Docs: Add FAQs

PR-URL: https://github.com/hasura/graphql-engine-mono/pull/5371
Co-authored-by: Rob Dominguez <24390149+robertjdominguez@users.noreply.github.com>
GitOrigin-RevId: 08c5f9cf9926a97a200270065b05809d9e76be1f

docs/docs/faq.mdx

@@ -12,25 +12,48 @@ slug: faq/index
 
 # FAQs
 
-## What types of workloads and databases does Hasura support? {#faq-db}
+## What are some pain points in the development process which Hasura solves?
 
-Hasura supports the following databases:
+- Automatically exposes full-featured GraphQL [query, mutation, subscription](/getting-started/how-it-works/index.mdx)
+CRUD types for each table in your database.
+- Compiles client GraphQL into [optimized SQL queries](#faq-compiler-performance), providing unmatched speed and
+efficiency.
+- [Massively reduces time](#faq-hasura-timesaving) writing boilerplate database CRUD API's.
+- Replaces long, complex, unintuitive SQL queries with the
+[declarative simplicity and benefits of GraphQL](#faq-how-hasura-works).
+- Allows you to manually extend your GraphQL API with extra endpoints to deal with any
+[business logic](#faq-business-logic) you may need.
+- Supports adding the [authentication solution of your choice](#faq-hasura-auth).
+- Secures your data with user roles and [fine-grained row level permissions](#faq-authorization).
+- Replaces multiple data sources with a [single unified endpoint](#faq-data-federation) for your entire application.
+- Provides tools to [define relationships](#faq-data-federation) between disparate data.
+- [Tracks changes over time](#faq-version-control) allowing changes to be added to version control and synchronization
+with your codebase.
+- Provides an [optimized and massively scalable](#faq-scaling) Cloud and Enterprise solution with which to host projects
+with extra features.
 
-- PostgresQL (and the Postgres family of databases: Yugabyte, Timescale, Citus, Aurora)
-- SQL Server
-- Big Query
+## What databases does Hasura support? {#faq-db}
+
+Hasura supports the following databases natively:
+
+- PostgreSQL (and the Postgres family of compatible databases)
+- Microsoft SQL Server
+- Google Cloud BigQuery
+
+Check out the list of [compatible databases](/databases/index.mdx#supported-databases).
 
 ## How does Hasura work? {#faq-how-hasura-works}
 
-Although Hasura presents itself as a web service, Hasura is quite a JIT compiler. Hasura takes incoming GraphQL API
-calls over HTTP and then tries to achieve theoretically optimal performance while delegating the data fetches to
-downstream data sources. You can read more about Hasura’s design philosophy in this
-[blog post](https://hasura.io/blog/how-hasura-works/)
+Although Hasura presents itself as a web-service API, Hasura is essentially a JIT compiler. Hasura takes incoming
+GraphQL API calls over HTTP and then tries to achieve theoretically optimal performance while delegating the data
+fetches to downstream data sources. You can read more about
+[how Hasura works here](/getting-started/how-it-works/index.mdx) and our design philosophy in this
+[blog post](https://hasura.io/blog/how-hasura-works/).
 
 ## How much time & effort does Hasura save? {#faq-hasura-timesaving}
 
-Hasura cuts down development time by 50-80%. You can find out more from our case studies
-[here.](https://hasura.io/user-stories/)
+Hasura cuts development time by roughly at least 50-80%. You can find out more from our case studies
+[here](https://hasura.io/user-stories/).
 
 ## How do I use Hasura if I already have an existing application or API? {#faq-hasura-existing-app-api}
 
@@ -38,45 +61,116 @@ Hasura is designed for incremental adoption without having to rip-and-replace or
 incrementally migrate your application to Hasura. Use Hasura to first build any new features for your application using
 your existing data as well as a high-performance read layer for any read-heavy use-cases as this takes no time to set
 up. You can also use any business logic in your existing applications by delegating to them via Hasura Actions. This
-gives you the time to migrate over any legacy code or rewrite existing micro-services with Hasura.
+gives you the time to migrate over any legacy code or rewrite existing microservices with Hasura.
 
-## Where do I put business logic? {#faq-business-logic}
+## How can I get Hasura up-and-running quickly?
 
-Hasura exposes your domain’s data and logic over a high-performance flexible API. Hasura removes the need for writing
-any code required for external or internal authorization rules.
+The easiest and fastest way to get Hasura up and running quickly is by using our
+[Hasura Cloud](/getting-started/getting-started-cloud.mdx) platform. Hasura can be also deployed easily in a
+[Docker container](/getting-started/docker-simple.mdx).
 
-Hasura provides 4 ways for exposing existing or new business logic in your domain:
+## What does my first-time demo experience look like?
 
-**Event triggers:** Whenever there’s a change in the upstream database, Hasura can capture that change as an event and
-deliver that to an HTTP webhook that can process that data change event and react to it asynchronously. Apart from
-attaching specific pieces of logic to events, this is especially useful if you’re thinking about building end-to-end
-real-time and reactive applications.
+Using the Hasura Console, click on the Data tab and connect up a new Postgres database from our partner company
+[Neon](/databases/connect-db/cloud-databases/neon.mdx). Then create tables, insert some demo data and test out some
+queries and mutations using the GraphiQL interface in the API tab. Alternatively, from your connected database in the
+Data tab, try one of our demo templates from the Template Gallery which can demonstrate key Hasura features for you
+quickly. If you already have an existing database with tables and data you can also just have Hasura connect to it,
+track tables and relationships, and you can immediately start exploring your new GraphQL API.
 
-- Read more about this architecture at [https://3factor.app](https://3factor.app)
-- Read more about event triggers in the Hasura [docs.](/event-triggers/index.mdx)
-- Go through a quick tutorial on how to set event triggers up at [https://learn.hasura.io](https://learn.hasura.io)
+## What's so great about GraphQL?
 
-**REST APIs:** If you have new or existing REST APIs that serve domain data or logic, you can easily connect Hasura to
-them and extend the GraphQL schema that Hasura exposes. This is useful not just when you have legacy APIs that contain a
-lot of transactional or application logic, but also when you want to build and serve custom logic with cloud-native code
+GraphQL's declarative and efficient fetching paradigm allows your API consumers to easily specify exactly which data
+they want and get only what they need returned to them, saving multiple request round trips. GraphQL is also strongly
+typed which allows users to know exactly what is available and what the data will look like.
+
+## How do I manage my database once it's connected to Hasura?
+
+Your database is still manageable in exactly the same way as it was before. In addition, you can perform many database
+management functions from the Hasura Console or run SQL directly on your DB from the Console.
+
+## How do I model out my data in a relational way in Hasura?
+
+Hasura allows you to specify relationships between your data including one-to-one, one-to-many and relationships to
+remote schemas between remote databases.
+
+## Can I connect my existing API endpoints, databases / data sources, or GraphQL servers? {#faq-data-federation}
+
+Yes, you can use Hasura as a data federation solution to connect multiple disparate data source types and define
+relationships between them. [Read more here](/data-federation/data-federation-types.mdx).
+
+## Are the common models accounted for? Querying? Filtering? Pagination? Inserting records? Live Queries?
+
+Yes. Hasura automatically generates `query`, `insert`, `update`, `delete` and `subscription` abilities on your databases
+which include `where`, `order_by`, `limit`, `offset` and `on_conflict` arguments where applicable.
+
+[//]: # '## How can I test the permission / business logic which I’ve setup?'
+
+## How do I track changes to my Hasura instance and keep them in sync with my codebase? {#faq-version-control}
+
+When using the Hasura CLI to manage Hasura, all actions regarding the underlying databases and Hasura config (Metadata)
+are recorded and can be committed to version control to enable easy versioned backups and re-deployment of your setup.
+
+## How do I declaratively deploy Hasura?
+
+With GitHub deployment on Hasura Cloud you can link a GitHub repository to your Hasura Project to automatically deploy
+Metadata and Migrations from within a given directory to the linked project. Alternatively, you can use GitHub Actions
+or a similar CI/CD service to build a custom deployment pipeline for your Hasura instances.
+
+## How can I preview changes to my Hasura instance?
+
+With [Preview Apps](/deployment/hasura-cloud/preview-apps.mdx) on Hasura Cloud you can automatically create an app on
+Hasura Cloud for every pull request you make to your GitHub repo enabling quick and easy testing of changes as you work.
+
+## How would I work collaboratively with my team using Hasura?
+
+Using [Projects](/projects/index.mdx) in Hasura Cloud you are able to add collaborators and assign each different access
+permissions on your instance. Since the Hasura [Metadata and Migrations](/migrations-metadata-seeds/index.mdx) can be
+committed to version control, you can also use the user permissions systems of a version control host (eg: GitHub) in
+order to control how your team collaborates on your Hasura project.
+
+## How do I connect business logic or extend the GraphQL schema? {#faq-business-logic}
+
+Hasura provides ways to connect existing or new business logic and for extending the generated GraphQL schema with extra
+CRUD functionality, eg:
+
+### REST APIs via Hasura Actions:
+
+If you have new or existing REST APIs that serve domain data or logic, you can easily connect Hasura to them and extend
+the GraphQL schema that Hasura exposes. This is useful not just when you have legacy APIs that contain a lot of
+transactional or application logic, but also when you want to build and serve custom logic with cloud-native code
 deployed as containers or serverless functions.
 
-- Read more about [Hasura Actions](/actions/index.mdx)
+- Read more about [Hasura Actions](/actions/index.mdx).
 
-**GraphQL APIs:** If you have a new or existing GraphQL service that extends the schema, say with custom mutations that
-incorporate your custom logic, or if you’d like to extend your overall GraphQL API with a “sub graph” that comes from a
-service that you may not directly own, you can use “Remote Schemas” in Hasura to bring in GraphQL services as data &
-logic providers to your GraphQL API.
+### Hasura Event Triggers:
 
-- Read more about [Remote Schemas](/remote-schemas/index.mdx)
+Whenever there’s a change in the upstream database, Hasura can capture that change as an event and deliver that to a
+HTTP webhook that can process that data change event and react to it asynchronously. Apart from attaching specific
+pieces of logic to events, this is especially useful if you’re thinking about building end-to-end real-time and reactive
+applications.
 
-**Stored procedures / custom functions in the database:** Stored procedures and custom functions are a common way to write and store
-high-performance business logic, or transactional logic, that's close to the data. As a part of the GraphQL API that
-Hasura exposes over databases, Hasura allows you to expose stored procedures or custom functions as fields in the GraphQL
-schema. This is a great way to bring in existing business logic that maybe in your database, or to write custom,
-high-performance logic if you’re familiar with databases!
+- Read more about this architecture at [https://3factor.app](https://3factor.app).
+- Read more about event triggers in the Hasura [docs](/event-triggers/index.mdx).
+- Go through a quick tutorial on how to set event triggers up at [https://learn.hasura.io](https://learn.hasura.io).
 
-- Read more about [custom functions](/schema/postgres/custom-functions.mdx)
+### GraphQL APIs via Hasura Remote Schemas:
+
+If you have a new or existing GraphQL service that extends the schema, say with custom mutations that incorporate your
+custom logic, or if you’d like to extend your overall GraphQL API with a “sub graph” that comes from a service that you
+may not directly own, you can use “Remote Schemas” in Hasura to bring in GraphQL services as data & logic providers to
+your GraphQL API.
+
+- Read more about [Remote Schemas](/remote-schemas/index.mdx).
+
+### Stored procedures / functions in the database:
+
+Stored procedures and functions are a common way to write and store high-performance business logic, or transactional
+logic, that's close to the data. As a part of the GraphQL API that Hasura exposes over databases, Hasura allows you to
+expose stored procedures or functions as fields in the GraphQL schema. This is a great way to bring in existing business
+logic that maybe in your database, or to write custom, high-performance logic if you’re familiar with databases!
+
+- Read more about [custom functions](/schema/postgres/custom-functions.mdx).
 
 Choose one or more of the methods above depending on where your existing business logic is; and where you want it to be
 in the future!
@@ -86,16 +180,16 @@ logic as reactive event triggers deployed as serverless functions (or lambdas) i
 
 ## Can I use REST instead of GraphQL APIs? {#faq-REST-api}
 
-Hasura 2.0 added support for REST APIs. Hasura 2.0 allows users to create idiomatic REST endpoints based on GraphQL
-templates. Read more [here.](/api-reference/restified.mdx)
+Yes. Hasura 2.0 added support for REST APIs and allows users to create idiomatic REST endpoints based on GraphQL
+templates. [Read more here](/api-reference/restified.mdx).
 
 ## Can Hasura integrate with my authentication system? {#faq-hasura-auth}
 
-Hasura believes authentication should not be restricted to a particular provider. Therefore, we make it easier for you
-to bring in your authentication system. The most favored mechanism is via JWT. Hasura can accept JWT tokens from any
-standard JWT provider. For extremely customized authentication systems, Hasura also supports auth webhook that allows
-you to read through cookies or tokens that might have a custom format. We have guides for some of the popular
-authentication providers. Read more [here.](/auth/authentication/index.mdx)
+Hasura believes authentication should not be restricted to a particular provider. Therefore, authentication is handled
+outside of Hasura and we make it easy for you to bring in your own authentication system. The most favored mechanism is
+via JWT. Hasura can accept JWT tokens from any standard JWT provider. For extremely customized authentication systems,
+Hasura also supports auth webhook that allows you to read through cookies or tokens that might have a custom format. We
+have guides for some of the popular authentication providers. Read more [here.](/auth/authentication/index.mdx)
 
 ## Does Hasura also automatically cache queries or data to improve performance? {#faq-hasura-query-caching}
 
@@ -103,28 +197,33 @@ Query response caching (available on Hasura Cloud & Hasura EE) can be enabled by
 the @cached directive. Read more about caching
 [here.](https://hasura.io/learn/graphql/hasura-advanced/performance/1-caching/)
 
-## How does Hasura handle ABAC, RBAC style authorization policies? {#faq-ABAC-RBAC}
+## How do I limit what data my users can see? {#faq-authorization}
 
-Hasura implements RBAC by automatically publishing a different GraphQL schema that represents the right queries, fields,
-and mutations that are available to that role.
+Hasura's authorization system allows the creation of user roles which can then be assigned fine-grained permission
+policies for each of the `insert`, `select`, `update`, and `delete` fields.
 
-For ABAC, session variables can be used as attributes, and permission rules can be created that can use any dynamic
-variable that is a property of the request.
+Hasura implements role-based access control (RBAC) by automatically publishing a different GraphQL schema that
+represents the right queries, fields, and mutations that are available to that role.
+
+For attribute-based access control (ABAC), session variables can be used as attributes, and permission rules can be
+created that can use any dynamic variable that is a property of the request.
+
+[Read more here](/auth/authorization/index.mdx).
 
 ## Does Hasura have other security features, specifically for GraphQL in production? {#faq-security}
 
-Hasura has multiple security features to best utilize the power of our GraphQL Engine. Features like service level
+Hasura has multiple security features to best utilize the power of our GraphQL Engine. Features like service-level
 security, authentication & authorization, allow lists, rate, and response limiting are present. Learn more about Hasura
-security [here.](https://hasura.io/learn/graphql/hasura-advanced/security/)
+security [here](https://hasura.io/learn/graphql/hasura-advanced/security/).
 
 ## How does the compiler approach provide superior performance? {#faq-compiler-performance}
 
-Typically when you think of GraphQL servers processing a query, you think of the number of resolvers involved in
+Typically, when you think of GraphQL servers processing a query, you think of the number of resolvers involved in
 fetching the data for the query. This approach can lead to multiple hits to the database with obvious constraints
 associated with it. Batching with data loader can improve the situation by reducing the number of calls.
 
-Internally Hasura parses a GraphQL query gets an internal representation of the GraphQL AST. GraphQL AST is then
-converted to a SQL AST. With necessary transformations and variables the final SQL is formed.
+Internally, Hasura parses a GraphQL query gets an internal representation of the GraphQL Abstract Syntax Tree (AST). The
+GraphQL AST is then converted to a SQL AST. With necessary transformations and variables the final SQL is formed.
 
 `GraphQL Parser -> GraphQL AST -> SQL AST -> SQL`
 
@@ -137,8 +236,10 @@ cores, memory, thresholds etc. You can keep increasing your number of concurrent
 Hasura Cloud will figure out the optimizations auto-magically. Hasura Cloud can load balance queries and subscriptions
 across read replicas while sending all mutations and metadata API calls to the master. Learn more about Horizontal
 scaling with Hasura, [here.](https://hasura.io/learn/graphql/hasura-advanced/performance/2-horizontal-scaling/)
+Additionally, Hasura Community Edition can be scaled horizontally by adding more Hasura instances to your deployment.
 
-## How can I improve the performance of slow running API calls? {#faq-slow-api-perf}
+[//]: # '## How does Hasura interact with other services (data layer, business intelligence tooling, etc.)?'
+[//]: # '## How can I improve the performance of slow running API calls? {#faq-slow-api-perf}'
 
 Hasura allows analyzing queries to identify the slow running calls and use Indexes to improve the performance. Learn
 more [here.](https://hasura.io/learn/graphql/hasura-advanced/performance/3-analyze-query-plans/)