Metadata API Reference: Tables/Views

Introduction

Track/untrack a table/view in Hasura GraphQL engine.

Only tracked tables/views are available for querying/mutating/subscribing data over the GraphQL API.

Supported from

The metadata API is supported for versions v2.0.0 and above and replaces the older schema/metadata API.

pg_track_table

pg_track_table is used to add a table/view to the GraphQL schema with configuration. You can customise the root field names.

Add a table/view author:

POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin

{
  "type": "pg_track_table",
  "args": {
    "source": "default",
    "table": "author",
    "configuration": {
      "custom_root_fields": {
        "select": "Authors",
        "select_by_pk": "Author",
        "select_aggregate": "AuthorAggregate",
        "insert": "AddAuthors",
        "insert_one":"AddAuthor",
        "update": "UpdateAuthors",
        "update_by_pk": "UpdateAuthor",
        "delete": "DeleteAuthors",
        "delete_by_pk": "DeleteAuthor"
      },
      "column_config": {
        "id": {
          "custom_name": "authorId",
          "comment": "The ID of the Author"
        }
      },
      "comment": "Authors of books"
    },
    "apollo_federation_config": {
      "enable": "v1"
    }
  }
}

A table can be tracked with a custom name. This can be useful when a table name is not GraphQL compliant, like Users Address. A custom name like users_address will complement the "Users Address" table, so that it can be added to the GraphQL schema.

POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin

{
   "type": "pg_track_table",
   "args": {
     "source": "default",
     "table": "Author Details",
     "configuration": {
        "custom_name": "author_details"
     }
   }
}

The GraphQL nodes and typenames that are generated will be according to the identifier. For example, in this case, the nodes generated will be:

• users_address
• users_address_one
• users_address_aggregate
• insert_users_address
• insert_users_address_one
• update_users_address
• update_users_address_by_pk
• delete_users_address
• delete_users_address_by_pk

Note

Hasura GraphQL engine requires the constraint names (if any) of a table to be GraphQL compliant in order to be able to track it.

Args syntax

Key	Required	Schema	Description
table	true	TableName	Name of the table
configuration	false	Table Config	Configuration for the table/view
source	false	SourceName	Name of the source database of the table (default: default)
apollo_federation_config	false	ApolloFederationConfig	Apollo federation configuration for the table

pg_untrack_table

untrack_table is used to remove a table/view from the GraphQL schema.

Remove a table/view author:

POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin

{
    "type": "pg_untrack_table",
    "args": {
        "table": {
            "schema": "public",
            "name": "author"
         },
        "source": "default",
        "cascade": true
    }
}

Args syntax

Key	Required	Schema	Description
table	true	TableName	Name of the table
cascade	false	Boolean	When set to true, the effect (if possible) is cascaded to any metadata dependent objects (relationships, permissions, templates)
source	false	SourceName	Name of the source database of the table (default: default)

pg_set_table_is_enum

pg_set_table_is_enum sets whether an already-tracked table should be used as an enum table.

Use table user_role as an enum table:

POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin

{
  "type": "pg_set_table_is_enum",
  "args": {
    "table": {
      "schema": "public",
      "name": "user_role"
    },
    "source": "default",
    "is_enum": true
  }
}

Args syntax

Key	Required	Schema	Description
table	true	TableName	Name of the table
is_enum	true	Boolean	Whether or not the table should be used as an enum table <enum table>.
source	false	SourceName	Name of the source database of the table (default: default)

pg_set_table_customization

pg_set_table_customization allows you to customize any given table with a custom name, custom root fields and custom column names of an already tracked table. This will replace the already present customization.

Set the configuration for a table/view called author:

POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin

{
  "type": "pg_set_table_customization",
  "args": {
    "table": "author_details",
    "source": "default",
    "configuration": {
      "identifier": "author",
      "custom_root_fields": {
        "select": "Authors",
        "select_by_pk": "Author",
        "select_aggregate": "AuthorAggregate",
        "insert": "AddAuthors",
        "insert_one":"AddAuthor",
        "update": "UpdateAuthors",
        "update_by_pk": "UpdateAuthor",
        "delete": "DeleteAuthors",
        "delete_by_pk": "DeleteAuthor"
      },
      "column_config": {
        "id": {
          "custom_name": "authorId",
          "comment": "The ID of the Author"
        }
      }
    }
  }
}

Args syntax

Key	Required	Schema	Description
table	true	TableName	Name of the table
configuration	false	TableConfig	Configuration for the table/view
source	false	SourceName	Name of the source database of the table (default: default)

pg_set_apollo_federation_config

pg_set_apollo_federation_config allows you to set apollo federation configuration for an already tracked postgres table. Enabling Apollo Federation will allow you to use the table type generated by Hasura in other subgraphs.

Set the Apollo Federation configuration for a postgres table called author:

POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin

{
  "type": "pg_set_apollo_federation_config",
  "args": {
    "table": "author_details",
    "source": "default",
    "apollo_federation_config": {
      "enable": "v1"
    }
  }
}

Args syntax

Key	Required	Schema	Description
table	true	TableName	Name of the table
source	false	SourceName	Name of the source database of the table (default: default)
apollo_federation_config	false	ApolloFederationConfig	Configuration for the table/view

Note

Setting apollo_federation_config to null will disable Apollo Federation support on the table.

mssql_track_table

mssql_track_table is used to add a table/view to the GraphQL schema with configuration. You can customise the root field names.

Add a table/view author:

POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin

{
    "type": "mssql_track_table",
    "args": {
      "table": "author",
      "source": "default"
    }
}

Note

Hasura GraphQL engine requires the constraint names (if any) of a table to be GraphQL compliant in order to be able to track it.

Args syntax

Key	Required	Schema	Description
table	true	TableName	Name of the table
configuration	false	Table Config	Configuration for the table/view
source	false	SourceName	Name of the source database of the table (default: default)
apollo_federation_config	false	ApolloFederationConfig	Apollo federation configuration for the table

mssql_untrack_table

untrack_table is used to remove a table/view from the GraphQL schema.

Remove a table/view author:

POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin

{
    "type": "mssql_untrack_table",
    "args": {
        "table": {
            "schema": "dbo",
            "name": "author"
          },
        "source": "default",
        "cascade": true
    }
}

Args syntax

Key	Required	Schema	Description
table	true	TableName	Name of the table
cascade	false	Boolean	When set to true, the effect (if possible) is cascaded to any metadata dependent objects (relationships, permissions, templates)
source	false	SourceName	Name of the source database of the table (default: default)

mssql_set_table_customization

mssql_set_table_customization allows you to customize any given table with a custom name, custom root fields and custom column names of an already tracked table. This will replace the already present customization.

Set the configuration for a table/view called author:

POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin

{
  "type": "mssql_set_table_customization",
  "args": {
    "table": "author_details",
    "source": "default",
    "configuration": {
      "identifier": "author",
      "custom_root_fields": {
        "select": "Authors",
        "select_aggregate": "AuthorAggregate",
      },
      "column_config": {
        "id": {
          "custom_name": "authorId",
          "comment": "The ID of the Author"
        }
      }
    }
  }
}

Args syntax

Key	Required	Schema	Description
table	true	TableName	Name of the table
configuration	false	TableConfig	Configuration for the table/view
source	false	SourceName	Name of the source database of the table (default: default)

mssql_set_apollo_federation_config

mssql_set_apollo_federation_config allows you to set apollo federation configuration for an already tracked mssql table. Enabling Apollo Federation will allow you to use the table type generated by Hasura in other subgraphs.

Set the Apollo Federation configuration for a mssql table called author:

POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin

{
  "type": "mssql_set_apollo_federation_config",
  "args": {
    "table": "author_details",
    "source": "default",
    "apollo_federation_config": {
      "enable": "v1"
    }
  }
}

Args syntax

Key	Required	Schema	Description
table	true	TableName	Name of the table
source	false	SourceName	Name of the source database of the table (default: default)
apollo_federation_config	false	ApolloFederationConfig	Configuration for the table/view

Note

Setting apollo_federation_config to null will disable Apollo Federation support on the table.

bigquery_track_table

bigquery_track_table is used to add a table/view to the GraphQL schema with configuration. You can customise the root field names.

Add a table/view author:

POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin

{
    "type": "bigquery_track_table",
    "args": {
      "table": {
        "dataset": "hasura",
        "name": "author",
      },
      "source": "default"
    }
}

In the case of BigQuery, dataset names are prefixed to table/view names to form a unique root field name, such that the above example will result in the root field name being hasura_author.

Note

Hasura GraphQL engine requires the constraint names (if any) of a table to be GraphQL compliant in order to be able to track it.

Args syntax

Key	Required	Schema	Description
table	true	{"dataset":_, "name":_}	Name of the table
configuration	false	Table Config	Configuration for the table/view
source	false	SourceName	Name of the source database of the table (default: default)
apollo_federation_config	false	ApolloFederationConfig	Apollo federation configuration for the table

bigquery_untrack_table

bigquery_untrack_table is used to remove a table/view from the GraphQL schema.

Remove a table/view author:

POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin

{
    "type": "bigquery_untrack_table",
    "args": {
        "table": {
            "dataset": "hasura",
            "name": "author"
          },
        "source": "default",
        "cascade": true
    }
}

Args syntax

Key	Required	Schema	Description
table	true	{"dataset":_, "name":_}	Name of the table
cascade	false	Boolean	When set to true, the effect (if possible) is cascaded to any metadata dependent objects (relationships, permissions, templates)
source	false	SourceName	Name of the source database of the table (default: default)

bigquery_set_table_customization

bigquery_set_table_customization allows you to customize any given table with a custom name, custom root fields and custom column names of an already tracked table. This will replace the already present customization.

Set the configuration for a table/view called hasura_author_details to author:

POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin

{
  "type": "bigquery_set_table_customization",
  "args": {
    "table": {
      "dataset": "hasura",
      "name": "author_details",
    },
    "source": "default",
    "configuration": {
      "custom_name": "author",
      "custom_root_fields": {
        "select": "Authors",
        "select_aggregate": "AuthorAggregate",
      },
      "column_config": {
        "id": {
          "custom_name": "authorId",
          "comment": "The ID of the Author"
        }
      }
    }
  }
}

Args syntax

Key	Required	Schema	Description
table	true	{"dataset":_, "name":_}	Name of the table
configuration	false	TableConfig	Configuration for the table/view
source	false	SourceName	Name of the source database of the table (default: default)

bigquery_set_apollo_federation_config

bigquery_set_apollo_federation_config allows you to set apollo federation configuration for an already tracked bigquery table. Enabling Apollo Federation will allow you to use the table type generated by Hasura in other subgraphs.

Set the Apollo Federation configuration for a bigquery table called author:

POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin

{
  "type": "bigquery_set_apollo_federation_config",
  "args": {
    "table": "author_details",
    "source": "default",
    "apollo_federation_config": {
      "enable": "v1"
    }
  }
}

Args syntax

Key	Required	Schema	Description
table	true	TableName	Name of the table
source	false	SourceName	Name of the source database of the table (default: default)
apollo_federation_config	false	ApolloFederationConfig	Configuration for the table/view

Note

Setting apollo_federation_config to null will disable Apollo Federation support on the table.