Docs: Add ##Introduction where appropriate

PR-URL: https://github.com/hasura/graphql-engine-mono/pull/10132
GitOrigin-RevId: 3b89a304c7c66d2a520b6c02478b4f6698d7bb1f
This commit is contained in:
Sean Park-Ross 2023-08-17 15:58:49 +02:00 committed by hasura-bot
parent 15ac52ded4
commit ed8eeec59d
77 changed files with 118 additions and 43 deletions

View File

@ -11,6 +11,8 @@ keywords:
# Async Actions
## Introduction
Sometimes you may not want to wait for an action to complete before
sending a response back to the client (say if the business logic takes a
long time). In such cases you can create an **asynchronous** action,

View File

@ -14,6 +14,8 @@ import GraphiQLIDE from '@site/src/components/GraphiQLIDE';
# Debugging Actions
## Introduction
While you're developing Actions for your application, to debug faster
you may want to see the exact details of the webhook call for the Action
as well.

View File

@ -19,7 +19,7 @@ import Player from '@site/src/components/Player';
<ProductBadge ce free standard pro ee self />
## Overview
## Introduction
The most common use case for Actions is to expose an existing API as a GraphQL query. To make this easier, we have added
the ability to import an Action from an [OpenAPI spec](https://swagger.io/specification/). OpenAPI is a widely used

View File

@ -14,6 +14,8 @@ import Thumbnail from '@site/src/components/Thumbnail';
# Admin Access
## Introduction
Hasura will bypass permissions and allow all queries, mutations and subscriptions when you include your
`X-Hasura-Admin-Secret` header without other session variables on your request. You can also specify the `admin`
role in your authenticated requests to [bypass permissions](#admin-role).

View File

@ -13,7 +13,7 @@ import Thumbnail from '@site/src/components/Thumbnail';
# Authentication
## Overview
## Introduction
**Authentication verifies the identity of a user.**

View File

@ -13,6 +13,8 @@ sidebar_position: 40
# Unauthenticated / Public Access
## Introduction
It is a common requirement to have requests which are accessible to all users without the need for authentication or
logging in.

View File

@ -15,6 +15,8 @@ import ProductBadge from '@site/src/components/ProductBadge';
# Authentication Using a Webhook
## Introduction
You can configure the Hasura Engine to use webhook mode in order to authenticate incoming requests.
This process of using webhook mode for authentication with Hasura requires specifying a URL - which Hasura calls with

View File

@ -13,7 +13,7 @@ import Thumbnail from '@site/src/components/Thumbnail';
# Authorization
## Overview
## Introduction
**Authorization determines what a verified user can access.**

View File

@ -16,6 +16,8 @@ import GraphiQLIDE from '@site/src/components/GraphiQLIDE';
# Inherited Roles
## Introduction
An inherited role is a way to create a new role which inherits permissions from two or more roles.
Once an inherited role is created, it can be treated as any other role i.e. it can be provided in the `X-Hasura-Role`

View File

@ -15,6 +15,8 @@ import TabItem from '@theme/TabItem';
# Aggregation permissions
## Introduction
You can enable access to [aggregation queries](/queries/postgres/aggregation-queries.mdx) for a given role on `select`
operations.

View File

@ -15,6 +15,8 @@ import TabItem from '@theme/TabItem';
# Backend Only Mutations
## Introduction
If a mutation permission is marked as "backend only", it is accessible to the given role only if the
`x-hasura-use-backend-only-permissions` session variable exists on the request and is set to `true`. The
`x-hasura-admin-secret` must also be present if any auth is configured.

View File

@ -15,6 +15,8 @@ import TabItem from '@theme/TabItem';
# Column Permissions
## Introduction
Column permissions determine which columns are accessible in the rows which are accessible.
<Tabs className="api-tabs">

View File

@ -16,6 +16,8 @@ import TabItem from '@theme/TabItem';
# Column Presets
## Introduction
[//]: # (TODO delete http://localhost:3000/docs/latest/schema/postgres/default-values/column-presets/ and redirect it
here)
While this is not strictly a permission configuration, defining role-based column presets for `insert` and `update`

View File

@ -13,6 +13,8 @@ import Thumbnail from '@site/src/components/Thumbnail';
# Permissions Examples
## Introduction
This is a guide to help you set up a basic authorization architecture for your GraphQL fields. It is recommended that
you first check out [Roles & Session variables](/auth/authorization/roles-variables.mdx) and other pages in
[configuring permission rules](/auth/authorization/permissions/index.mdx) which will be referred to throughout this

View File

@ -16,6 +16,8 @@ import TabItem from '@theme/TabItem';
# Root Field Visibility
## Introduction
Sometimes you may want a role to only have access to certain root fields of a table or have the table only be
accessible through a [relationship](/schema/postgres/table-relationships/index.mdx).

View File

@ -12,6 +12,8 @@ import Thumbnail from '@site/src/components/Thumbnail';
# Configuring Permission Rules
## Introduction
Permissions in Hasura are defined with table, role and operation (_insert, update, select, delete_) level granularity:
<Thumbnail src='/img/auth/permission-rule-granularity_2.16.1.png' alt='Defining permissions in Hasura' width='1000px' />

View File

@ -13,9 +13,10 @@ import Thumbnail from '@site/src/components/Thumbnail';
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
# Row Fetch Limit
## Introduction
Limit the number of rows returned in a response on `select` operations.
<Tabs groupId="user-preference" className="api-tabs">

View File

@ -15,6 +15,8 @@ import TabItem from '@theme/TabItem';
# Configure Row Permissions {#row-level-permissions}
## Introduction
Row permissions are powerful boolean expressions that help you restrict access to database rows for each database
operation and user role.

View File

@ -1,6 +1,4 @@
---
description: How caching works
title: How it works
keywords:
- caching
- queries
@ -9,7 +7,9 @@ keywords:
sidebar_position: 3
---
## What is cached exactly?
# How Caching Works
## Introduction
Hasura Caching is a type of response caching that helps you store results of a given query in order to serve it more
quickly to your users. Hasura will cache the response of a given query under a cache key, and when another request

View File

@ -17,7 +17,7 @@ import Thumbnail from '@site/src/components/Thumbnail';
# Hasura GraphQL Federation Architectures
## Overview
## Introduction
In GraphQL, a supergraph is a unified and coherent schema that combines multiple sub-graphs, each representing a
distinct part of the overall data model. The distinctions between supergraphs and a sub-graphs is largely academic and

View File

@ -20,7 +20,7 @@ import ProductBadge from '@site/src/components/ProductBadge';
<ProductBadge standard free standard pro />
## Overview
## Introduction
The Schema Registry, as the name suggests, is a registry which stores all the GraphQL schemas that have existed on your
Hasura project. It is aimed at making your Hasura GraphQL schema changes more reliable, prevent breaking changes in the

View File

@ -15,7 +15,7 @@ import Thumbnail from '@site/src/components/Thumbnail';
# Get Started with Hasura Cloud and Amazon Athena
## Try it out
## Introduction
### Step 1: Create an account on Hasura Cloud and create a new Hasura Project

View File

@ -15,6 +15,8 @@ import Thumbnail from '@site/src/components/Thumbnail';
# Get Started with Docker and Amazon Athena
## Introduction
Currently, testing continues on the Amazon Athena connector for use in self-hosted environments. Our suggested
installation method is to use Docker Compose to deploy a working deployment of Hasura with the Amazon Athena connector
enabled.

View File

@ -12,6 +12,8 @@ sidebar_position: 3
# Hasura GraphQL Data Connector SDK
## Introduction
The Data Connector SDK serves as a pack of documentation and resources for understanding, building, and testing Data
Connector Agent implementations to ensure that they are complete, correct, idiomatic and can be developed rapidly and
with confidence. The workflow that the SDK supports out of the box is powered by Docker Compose in order to reduce the

View File

@ -15,7 +15,7 @@ import Thumbnail from '@site/src/components/Thumbnail';
# Get Started with Hasura Cloud & MS SQL Server
## Try it out
## Introduction
### Step 1: Create an account on Hasura Cloud and create a new Hasura Project

View File

@ -15,7 +15,7 @@ import Thumbnail from '@site/src/components/Thumbnail';
# Get Started with Docker (Hasura & MS SQL Server)
## Try it out
## Introduction
### Pre-requisites

View File

@ -14,7 +14,7 @@ import Thumbnail from '@site/src/components/Thumbnail';
# Get Started with Hasura Cloud & Citus - Hyperscale
## Try it out
## Introduction
### Step 1: Create an account on Hasura Cloud and create a new Hasura Project

View File

@ -14,7 +14,7 @@ import Thumbnail from '@site/src/components/Thumbnail';
# Get Started with Docker (Hasura & Citus - Hyperscale)
## Try it out
## Introduction
### Pre-requisites

View File

@ -14,7 +14,7 @@ import Thumbnail from '@site/src/components/Thumbnail';
# Get Started with Hasura Cloud & CockroachDB
## Try it out
## Introduction
### Step 1: Create an account on Hasura Cloud and create a new Hasura Project

View File

@ -14,7 +14,7 @@ import Thumbnail from '@site/src/components/Thumbnail';
# Get Started with Hasura (Docker) & CockroachDB
## Try it out
## Introduction
### Pre-requisites

View File

@ -14,6 +14,8 @@ import Thumbnail from '@site/src/components/Thumbnail';
# Get Started with Docker (Hasura & Snowflake)
## Introduction
Testing is currently underway on the Snowflake connector for use in self-hosted environments. Our suggested
installation method is to use Docker Compose to deploy a working deployment of Hasura with the Snowflake Connector
enabled.

View File

@ -15,6 +15,8 @@ import Thumbnail from '@site/src/components/Thumbnail';
# Connect Hasura to Weaviate
## Introduction
[Weaviate](https://weaviate.io/) is a cloud-native, modular, real-time vector search engine that allows you to build
intelligent applications by using machine learning models as the data layer. It is open-source and can be deployed
on-premise or in the cloud.

View File

@ -12,7 +12,7 @@ sidebar_position: 10
# Healthz Check
## Overview
## Introduction
Hasura provides a Health Check endpoint to monitor the status of the GraphQL API. This is available under the
`/healthz` endpoint for all Hasura Projects (including the OSS GraphQL Engine).

View File

@ -21,7 +21,7 @@ import ProductBadge from '@site/src/components/ProductBadge';
<ProductBadge free standard ee self />
## Overview
## Introduction
Hasura enables users to check the health of connected data sources via the Health Check API.
[API reference here](/api-reference/source-health.mdx).

View File

@ -12,6 +12,8 @@ sidebar_label: Performance tuning
# Tune Hasura Performance
## Introduction
This page serves as a reference for suggestions on fine tuning the performance of your Hasura GraphQL Engine instance.
We cover database configurations, scaling, observability, and software architecture to help you get the most out of your
set up.

View File

@ -21,7 +21,7 @@ import Thumbnail from '@site/src/components/Thumbnail';
<div className="badge badge--primary heading-badge">Available on: Self-hosted Enterprise</div>
## Overview
## Introduction
SSO can be configured with ADFS SAML by setting up [Dex](https://dexidp.io/docs/) as an OAuth2 proxy. Access can be
configured for all users of a domain or only for members of certain groups.

View File

@ -19,7 +19,7 @@ import Thumbnail from '@site/src/components/Thumbnail';
<div className="badge badge--primary heading-badge">Available on: Self-hosted Enterprise</div>
## Overview
## Introduction
Auth0 is a rapidly integrable authentication and authorization service. You can use it easily to manage admin users,
integrate SSO with Hasura GraphQL Engine or act as middleware to connect non-OAuth compliant identity providers (IdP).

View File

@ -21,7 +21,7 @@ import Thumbnail from '@site/src/components/Thumbnail';
<div className="badge badge--primary heading-badge">Available on: Self-hosted Enterprise</div>
## Overview
## Introduction
SSO can be configured with Google Workspace OAuth2 by setting up [Dex](https://dexidp.io/docs/) as an OAuth2 proxy.
Access can be configured for all users of a domain or just for members of certain groups.

View File

@ -19,7 +19,7 @@ import Thumbnail from '@site/src/components/Thumbnail';
<div className="badge badge--primary heading-badge">Available on: Self-hosted Enterprise</div>
## Overview
## Introduction
SSO can be configured with LDAP by setting up [Dex](https://dexidp.io/docs/) as an OAuth2 proxy. Access can be
configured for all users of a domain or only for members of certain groups.

View File

@ -19,7 +19,7 @@ import ProductBadge from '@site/src/components/ProductBadge';
<ProductBadge self />
## Overview
## Introduction
Trying and evaluating Hasura Enterprise features with your current Hasura setup is now easier and self-serve. Starting
with Hasura GraphQL Engine version `v2.23.0`, you can get started with your 30-day Enterprise Edition Trial in

View File

@ -15,7 +15,7 @@ import ProductBadge from '@site/src/components/ProductBadge';
<ProductBadge self />
## Overview
## Introduction
Starting from Hasura GraphQL Engine version `v2.12.0`, we have included both open-source and commercial components in
the `hasura/graphql-engine` container image. The open-source portions are licensed under the [Apache License, Version 2.0](https://www.apache.org/licenses/LICENSE-2.0). The proprietary components include features for Hasura Enterprise and they can be enabled through a free trial or with a license key provided by the Hasura team.

View File

@ -17,7 +17,7 @@ import Player from '@site/src/components/Player';
# Build an API gateway
## Overview
## Introduction
This guide, and the others contained in this directory, are intended to be a step-by-step resource to build an
application using Hasura. If you arrived here from the Hasura Cloud Console, you'll have already created a project and

View File

@ -17,7 +17,7 @@ import Player from '@site/src/components/Player';
# Build a Data Access Layer
## Overview
## Introduction
This guide, and the others contained in this directory, are intended to be a step-by-step resource to build an
application using Hasura. If you arrived here from the Hasura Cloud Console, you'll have already created a project and

View File

@ -17,7 +17,7 @@ import Player from '@site/src/components/Player';
# Build a GraphQL Backend
## Overview
## Introduction
This guide, and the others contained in this directory, are intended to be a step-by-step resource to build an
application using Hasura. If you arrived here from the Hasura Cloud Console, you'll have already created a project and

View File

@ -19,7 +19,7 @@ import HeadingIcon from '@site/src/components/HeadingIcon';
# Hasura Cloud Data Usage Calculation
### How do we calculate data usage?
## How do we calculate data usage?
Hasura Cloud projects are billed based on the amount of data that passes through Hasura Cloud. This data corresponds to
the operations that are performed by you, your apps, or your clients.

View File

@ -19,7 +19,7 @@ import ProductBadge from '@site/src/components/ProductBadge';
<ProductBadge ee />
## Overview
## Introduction
Hasura allows you to pay for Hasura Cloud Enterprise via private offers in the
[AWS Marketplace](https://aws.amazon.com/marketplace/pp/prodview-h7qmhw3draxh4?sr=0-1&ref_=beagle&applicationId=AWSMPContessa)

View File

@ -15,7 +15,7 @@ import ProductBadge from '@site/src/components/ProductBadge';
<ProductBadge ee />
## Overview
## Introduction
If you're designing your system to be fault tolerant enough to account for a full region-wide outage, we recommend
enabling a backup region on Hasura Cloud too.

View File

@ -14,7 +14,7 @@ import ProductBadge from '@site/src/components/ProductBadge';
<ProductBadge standard pro ee />
## Overview
## Introduction
Hasura Cloud supports high-availability (HA) configurations for Cloud Enterprise projects.

View File

@ -16,7 +16,7 @@ import ProductBadge from '@site/src/components/ProductBadge';
<ProductBadge free standard pro ee />
## Overview
## Introduction
[Hasura Cloud](https://cloud.hasura.io) offers three plans: Hasura Cloud Free, Hasura Cloud Professional, and Hasura
Cloud Enterprise.

View File

@ -12,6 +12,8 @@ import Thumbnail from '@site/src/components/Thumbnail';
# Manage Migrations
## Introduction
Hasura will create pure SQL files representing every change made to tracked databases made while using the Console
served by the Hasura CLI.

View File

@ -10,6 +10,8 @@ sidebar_position: 11
# Metadata Best Practices
## Introduction
Proper Metadata management ensures the Hasura GraphQL Engine operates appropriately and as expected. You can use several
different patterns to manage Metadata successfully. However, the below do's, and don'ts have been gathered through
real-world practices, user experiences, and challenges when managing enterprise-scale Hasura ecosystems.

View File

@ -11,6 +11,8 @@ toc_max_heading_level: 6
# Metadata Format Reference
## Introduction
With Metadata config `v3`, the Metadata that is exported from the server by the CLI is a directory of multiple files and
directories as per the example below:

View File

@ -19,7 +19,7 @@ import ProductBadge from '@site/src/components/ProductBadge';
<ProductBadge free standard pro ee />
## Overview
## Introduction
Troubleshoot errors quickly with powerful analytical tools and filters:

View File

@ -12,6 +12,8 @@ slug: index
# Built-in Monitoring in Hasura Cloud
## Introduction
Observability is a critical aspect of any application, and Hasura Cloud provides developers with a powerful set of tools
to monitor and debug their applications. In this document, we'll explore the observability features available in Hasura
Cloud and how they can help you build better applications.

View File

@ -18,7 +18,7 @@ import ProductBadge from '@site/src/components/ProductBadge';
<ProductBadge standard pro ee />
## Overview
## Introduction
Subscription workers offer a subscription-worker-specific version of usage statistics:

View File

@ -19,7 +19,7 @@ import ProductBadge from '@site/src/components/ProductBadge';
<ProductBadge standard pro ee />
## Overview
## Introduction
Learn about usage with aggregate summaries and filtering tools:

View File

@ -23,7 +23,7 @@ import ProductBadge from '@site/src/components/ProductBadge';
<ProductBadge standard pro ee />
## Overview
## Introduction
To be able to effectively monitor, diagnose and troubleshoot your application stack in production, Hasura Cloud will
export metrics, logs and traces to observability tools / APM vendors.

View File

@ -13,6 +13,8 @@ sidebar_position: 7
# Database Observability
## Introduction
The purpose of this document is to provide an overview of how to configure database observability. The scope covers
configuring the observability tools for the database host and database. While the specifics of this guide may vary
depending on the host, database, and other aspects of your deployment, we have used Hasura Cloud and a self-hosted

View File

@ -23,7 +23,7 @@ import ProductBadge from '@site/src/components/ProductBadge';
<ProductBadge standard pro ee />
## Overview
## Introduction
To be able to effectively monitor, diagnose and troubleshoot your application stack in production, Hasura Enterprise
Edition will export metrics, logs and traces to observability tools / APM vendors.

View File

@ -26,7 +26,7 @@ import Thumbnail from '@site/src/components/Thumbnail';
<ProductBadge self />
## Overview
## Introduction
This guide will help you set up a basic observability dashboard for Hasura using Prometheus and Grafana. We have two
approaches depending on your use case:

View File

@ -10,6 +10,8 @@ sidebar_position: 2
# Observability Best Practices
## Introduction
The purpose of this document is to provide an overview of some of the best practices to follow when you configure
observability for your Hasura-driven product. We will cover the fundamentals of observability and provides general
recommendations on what Hasura considers as observability best practices.

View File

@ -11,7 +11,7 @@ sidebar_class_name: cloud-and-enterprise-icon
# Data Privacy and Access at Hasura
## Overview
## Introduction
We take privacy and security very seriously at Hasura and take all measures to protect your data. This document outlines
the measures we take to ensure that your data is secure and private.

View File

@ -16,7 +16,7 @@ import ProductBadge from '@site/src/components/ProductBadge';
<ProductBadge standard pro ee />
## Overview
## Introduction
This document describes the Service Level Agreement (SLA) calculation and crediting process for Hasura Cloud. The SLA
applies to paid tiers in Hasura Cloud.

View File

@ -15,7 +15,7 @@ import GraphiQLIDE from '@site/src/components/GraphiQLIDE';
# Postgres: Filter Query Results / Search Queries
## Overview
## Introduction
Hasura provides a powerful yet simple syntax to filter query results on Postgres. This is useful for building search
queries or filtering data based on some criteria. You can utilize arguments and operators to filter results based on

View File

@ -14,6 +14,8 @@ slug: tutorials/index
# Tutorials
## Introduction
The tutorials listed below are a great way to start learning Hasura, GraphQL, and even front-end or full-stack
development. Each link will take you directly to a particular tutorial on our Learn site, or you can
[head there directly](https://hasura.io/learn/) and peruse through our offerings.

View File

@ -14,6 +14,8 @@ sidebar_label: VS Code integration
# Guides: Visual Studio Code Setup
## Introduction
If you use [Visual Studio code](https://code.visualstudio.com/), the
[Apollo GraphQL plugin](https://marketplace.visualstudio.com/items?itemName=apollographql.vscode-apollo) can improve
your development experience significantly by enabling a lot of cool features like syntax highlighting for GraphQL, auto

View File

@ -17,6 +17,8 @@ import GraphiQLIDE from '@site/src/components/GraphiQLIDE';
# Create a RESTified Endpoint
## Introduction
There are two methods to create a RESTified endpoint in Hasura Cloud and EE.
:::info Data source availability

View File

@ -15,6 +15,8 @@ import GraphiQLIDE from '@site/src/components/GraphiQLIDE';
# RESTified Endpoint Config
## Introduction
In this document, we cover the RESTified endpoint configuration options. We will also cover how to use the RESTified
endpoint to query and mutate data in your database.

View File

@ -15,7 +15,9 @@ sidebar_position: 3
import Thumbnail from '@site/src/components/Thumbnail';
import GraphiQLIDE from '@site/src/components/GraphiQLIDE';
# How It Works: Scheduled Triggers
# Scheduled Triggers
## Introduction
Hasura Scheduled Triggers is a powerful feature that allows you to schedule tasks or events in your application based on
specific time intervals. It is a trigger-based system that executes tasks at predefined intervals, specified in a

View File

@ -17,6 +17,8 @@ import Thumbnail from '@site/src/components/Thumbnail';
# Send an Abandoned Cart Reminder Email using Scheduled Triggers
## Introduction
Scheduled Triggers allow you to schedule business logic to occur at specific times or intervals.
In this guide, we'll show how to use Scheduled Triggers to send an email reminder to a customer who has added products

View File

@ -18,6 +18,8 @@ import Thumbnail from '@site/src/components/Thumbnail';
# Send a Coupon Expiration Reminder Email
## Introduction
Scheduled Triggers allows you to schedule business, or other logic to occur at specific times or intervals. In this
guide, we'll walk through how to use Scheduled Triggers on an e-commerce type application to send a reminder email to users when their coupon is about to expire. Nudges like this can help increase conversion rates and improve the overall user experience.

View File

@ -19,6 +19,8 @@ import Thumbnail from '@site/src/components/Thumbnail';
# Send a Daily Summary Email
## Introduction
Scheduled Triggers allows you to schedule business, or other logic to occur at specific times or intervals. In this
guide, we'll explore how to use Scheduled Triggers to send each user a daily summary of recent notifications which they
have received. We'll do this by executing this trigger every morning and seeing what new notifications have come through

View File

@ -12,6 +12,8 @@ slug: index
# Recipes
## Introduction
This section contains recipes for common use cases of **Scheduled Triggers**. Each recipe is a succinct, tested, and
reusable piece of code that can be used to solve a common use case. However, these recipes are not exhaustive and you
can use them as a starting point to build your own custom logic.

View File

@ -19,6 +19,8 @@ import Thumbnail from '@site/src/components/Thumbnail';
# Send a Product Review Request Email
## Introduction
Scheduled Triggers allows you to schedule business, or other logic to occur at specific times or intervals. In this
guide, we'll explore how to use Scheduled Triggers to send a review request email for a product seven days after the
order is delivered. We'll do this by executing this trigger every day at midnight to check whether it has been seven

View File

@ -14,7 +14,7 @@ import GraphiQLIDE from '@site/src/components/GraphiQLIDE';
# Setting up Soft Deletes for Data
## Overview
## Introduction
For some projects you may require records to be "soft deleted", i.e. items should not actually be removed from the
database, but should be marked with a timestamp to indicate when they were deleted.

View File

@ -10,6 +10,8 @@ keywords:
# MS SQL Server
## Introduction
The Hasura GraphQL Engine automatically generates your GraphQL schema and resolvers based on your tables/views in MS SQL
Server. **You don't need to write a GraphQL schema or resolvers.** See
[How Hasura GraphQL Engine works](/getting-started/how-it-works/index.mdx) for more details.

View File

@ -18,6 +18,8 @@ sidebar_position: 6
import Thumbnail from '@site/src/components/Thumbnail';
import ProductBadge from '@site/src/components/ProductBadge';
# Observability & Performance Tuning
## Subscription Execution
For serving subscription requests, Hasura optimizes the subscription execution to ensure it is as fast as possible while