Metadata Format Reference

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:

📂 metadata
├─ 📂 databases
│  ├─ 📄 databases.yaml
│  └─ 📂 default
│     ├─ 📂 tables
│     │  ├─ 📄 public_author.yaml
│     │  ├─ 📄 public_article.yaml
│     │  └─ 📄 tables.yaml
│     └─ 📂 functions
│        ├─ 📄 public_search_author.yaml
│        └─ 📄 functions.yaml
├─ 📄 actions.graphql
├─ 📄 actions.yaml
├─ 📄 allow_list.yaml
├─ 📄 api_limits.yaml
├─ 📄 cron_triggers.yaml
├─ 📄 graphql_schema_introspection.yaml
├─ 📄 inherited_roles.yaml
├─ 📄 network.yaml
├─ 📄 query_collections.yaml
├─ 📄 remote_schemas.yaml
├─ 📄 rest_endpoints.yaml
└─ 📄 version.yaml

Internally in Hasura Server, Metadata is maintained as a JSON blob in the hdb_metadata table of the Metadata database.

note

For config v2, see Metadata format reference (config v2).

Metadata directory format

The following files will be generated in the metadata/ directory of your project:

Note

The output of the export_metadata Metadata API is a JSON version of the Metadata files.

databases

📂 databases
├─ 📄 databases.yaml
└─ 📂 default
  ├─ 📂 tables
  │  ├─ 📄 public_author.yaml
  │  ├─ 📄 public_article.yaml
  │  └─ 📄 tables.yaml
  └─ 📂 functions
     ├─ 📄 public_search_author.yaml
     └─ 📄 functions.yaml

databases.yaml

- name: default
  kind: postgres
  configuration:
    connection_info:
      use_prepared_statements: false
      database_url:
        from_env: PG_DATABASE_URL
      isolation_level: read-committed
  tables: '!include default/tables/tables.yaml'

Note

database_url can be set as a string literal by omitting the from_env property.

[database-name]

Directory with metadata related to a database.

📂 default
├─ 📂 tables
│  ├─ 📄 public_author.yaml
│  ├─ 📄 public_article.yaml
│  └─ 📄 tables.yaml
└─ 📂 functions
   ├─ 📄 public_search_author.yaml
   └─ 📄 functions.yaml

tables

Directory with metadata related to a database's tables and views.

📂 tables
├─ 📄 public_author.yaml
├─ 📄 public_article.yaml
└─ 📄 tables.yaml

tables.yaml

The tables.yaml file contains a list of all further database table yaml files which need to be included in the metadata.

Example: A tables.yaml file which specifies further author and article table files

- '!include public_author.yaml'
- '!include public_article.yaml'

[table-name].yaml

The specific files for each database table contain all the metadata information regarding each database table.

These files can contain information relating to the table for:

• Relationships including object and array relationships
• Remote relationships including those to remote schemas and remote databases
• Operation permissions per role
• Event Triggers
• Computed fields
• Whether the table is an enum table
• GraphQL field customization

Example: A public_author.yaml table metadata file specifying some of the above.

table:
  name: author
  schema: public
array_relationships:
  - name: articles
    using:
      foreign_key_constraint_on:
        column: author_id
        table:
          name: article
          schema: public
insert_permissions:
  - role: user
    permission:
      check:
        id:
          _eq: X-Hasura-User-Id
      set:
        id: x-hasura-user-id
      columns:
        - name
select_permissions:
  - role: user
    permission:
      columns:
        - id
        - name
      filter:
        id:
          _eq: X-Hasura-User-Id
      allow_aggregations: true
      query_root_fields:
        - select
        - select_by_pk
      subscription_root_fields:
        - select
        - select_by_pk
delete_permissions:
  - role: user
    permission:
      backend_only: true
      filter: {}
event_triggers:
  - name: author_created
    definition:
      enable_manual: false
      insert:
        columns: '*'
    retry_conf:
      interval_sec: 10
      num_retries: 0
      timeout_sec: 60
    webhook: http://httpbin.org/post

functions

Directory with metadata related to a database's functions tracked to be exposed as top-level GraphQL fields.

📂 functions
├─ 📄 public_search_author.yaml
└─ 📄 functions.yaml

functions.yaml

The functions.yaml file contains a list of all further database function yaml files which need to be included in the metadata to be exposed as top-level GraphQL fields.

Example: A functions.yaml file which specifies further search_author function file

- '!include public_search_author.yaml'

[function-name].yaml

The specific files for each database function contain all the metadata information regarding exposing the database function as a top-level GraphQL field.

Example: A public_search_author.yaml function metadata file

function:
  name: search_author
  schema: public
permissions:
  - role: user

actions.graphql

The actions.graphql file contains all the GraphQL Actions and their custom type definitions.

Example: A query action called greet and two custom types called SampleInput and SampleOutput

type Query {
  greet(arg1: SampleInput!): SampleOutput
}
input SampleInput {
  username: String!
}
type SampleOutput {
  greetings: String!
}

actions.yaml

The actions.yaml file contains Metadata related to actions.

Example: An action called greet with the handler set to <base_url>/greet and two custom types called SampleInput and SampleOutput

actions:
  - name: greet
    definition:
      kind: ''
      handler: <base_url>/greet
      forward_client_headers: true
      headers:
        - value: application/json
          name: Content-Type
custom_types:
  enums: []
  input_objects:
    - name: SampleInput
  objects:
    - name: SampleOutput
  scalars: []

Example: Same example as above but with the base URL of the handler passed as an environment variable

actions:
  - name: greet
    definition:
      kind: ''
      handler: '{{ACTION_BASE_URL}}/greet'
      forward_client_headers: true
      headers:
        - value: application/json
          name: Content-Type
custom_types:
  enums: []
  input_objects:
    - name: SampleInput
  objects:
    - name: SampleOutput
  scalars: []

allow_list.yaml

The allow_list.yaml file contains the Metadata related to the allow list.

Example: A query collection called allowed-queries set as the allow-list

- collection: allowed-queries

api_limits.yaml

For Hasura Cloud and Hasura Enterprise the api_limits.yaml file contains the Metadata related to api limits.

Example: An api limit setting with global limits and a specific limit for a customer role

depth_limit:
  global: 10
  per_role:
    customer: 5
disabled: false
node_limit:
  global: 10
  per_role:
    customer: 5
rate_limit:
  global:
    max_reqs_per_min: 100
    unique_params: null
  per_role:
    customer:
      max_reqs_per_min: 60
      unique_params: null
time_limit:
  global: 10
  per_role:
    customer: 5

cron_triggers.yaml

The cron_triggers.yaml file contains Metadata related to cron triggers. The webhook can be an HTTP endpoint or an environment variable containing the HTTP endpoint.

Example: A cron trigger called test-trigger

- name: test-trigger
webhook: <webhook-url>
schedule: 0 12 * * 1-5
include_in_metadata: true
payload: {}
retry_conf:
  num_retries: 1
  timeout_seconds: 60
  tolerance_seconds: 21600
  retry_interval_seconds: 10

Note

The Metadata about a cron trigger will not be stored if Include this trigger in Hasura Metadata is disabled in the advanced option of events on the console or include_in_metadata is passed as false via the API.

graphql_schema_introspection.yaml

For Hasura Cloud and Hasura Enterprise the graphql_schema_introspection.yaml file enables disabling of GraphQL introspection for specified roles.

Example: Disabling introspection for roles customer and user

disabled_for_roles:
  - customer
  - user

inherited_roles.yaml

The inherited_roles.yaml file contains Metadata related to inherited roles.

Example: An inherited role of manager which inherits from user and customer

- role_name: manager
  role_set:
    - user
    - customer

network.yaml

The network.yaml file contains Metadata related to network options.

Example: A TLS Allowlist to represent a set of services that are permitted to use self-signed certificates

tls_allowlist:
  - host: graphql.hasura.io
    permissions:
      - self-signed
    suffix: core.graphql

query_collections.yaml

The query_collections.yaml file contains Metadata information about query collections.

Example: A query collection called sample-collection which contains two queries test and test2

- name: sample-collection
  definition:
    queries:
      - name: test
        query: |-
          query test {
            books {
              id
              author_id
              title
            }
          }
      - name: test2
        query: |-
          query test2 {
              authors{
                  id
                  author_name
              }
          }

remote_schemas.yaml

The remote_schemas.yaml file contains the Metadata related to remote schemas.

Example: A remote schema called my-remote-schema with the URL <remote-schema-url>

- name: my-remote-schema
  definition:
    url: <remote-schema-url>
    timeout_seconds: 40

Example: A remote schema called my-remote-schema with the URL passed as environment variable

- name: my-remote-schema
  definition:
    url_from_env: REMOTE_SCHEMA
    timeout_seconds: 40

rest_endpoints.yaml

The rest_endpoints.yaml file contains the Metadata related to REST endpoints.

Example: An example of a defined restified endpoint which gets an author based on their id

- comment: Get an author based on their id
  definition:
    query:
      collection_name: allowed-queries
      query_name: Author by Id
  methods:
    - GET
  name: Author by Id
  url: author/:id

version.yaml

The version.yaml file contains the Metadata format version.

version: 3