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
│  ├─ 📂 default
│  │  └─ 📂 tables
│  │     ├─ 📄 public_author.yaml
│  │     ├─ 📄 public_article.yaml
│  │     └─ 📄 tables.yaml
│  └── 📄 databases.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

📂 metadata
├─ 📂 databases
│  ├─ 📂 default
│  │  └─ 📂 tables
│  │     ├─ 📄 public_author.yaml
│  │     ├─ 📄 public_article.yaml
│  │     └─ 📄 tables.yaml
│  └── 📄 databases.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.

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

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.

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

version.yaml

The version.yaml file contains the Metadata format version.

version: 3

public_t1.yaml OLD?

table:
name: t1
schema: public