Skip to main content
Version: v2.x

Schema/Metadata API Reference: Tables/Views (Deprecated)

Deprecation

In versions v2.0.0 and above, the schema/Metadata API is deprecated in favour of the schema API and the Metadata API.

Though for backwards compatibility, the schema/Metadata APIs will continue to function.

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.

track_table

track_table is used to add a table/view to the GraphQL schema.

Add a table/view author:

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

{
"type": "track_table",
"args": {
"schema": "public",
"name": "author"
}
}

Args syntax

KeyRequiredSchemaDescription
tabletrueTableNameName of the table
is_enumfalseBooleanWhen set to true, creates the table as an enum table.
apollo_federation_configfalseApolloFederationConfigApollo federation configuration for the table

set_table_is_enum

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/query HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin

{
"type": "set_table_is_enum",
"args": {
"table": {
"schema": "public",
"name": "user_role"
},
"is_enum": true
}
}

Args syntax

KeyRequiredSchemaDescription
tabletrueTableNameName of the table
is_enumtrueBooleanWhether or not the table should be used as an enum table <enum table>.

track_table v2

Version 2 of track_table is used to add a table/view to the GraphQL schema with configuration. You can customize the root field names.

Add a table/view author:

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

{
"type": "track_table",
"version": 2,
"args": {
"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"
},
"custom_column_names": {
"id": "authorId"
}
}
}
}

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/query HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin

{
"type": "track_table",
"version": 2,
"args": {
"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

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

KeyRequiredSchemaDescription
tabletrueTableNameName of the table
configurationfalseTable ConfigConfiguration for the table/view
apollo_federation_configfalseApolloFederationConfigApollo federation configuration for the table

set_table_custom_fields (deprecated)

set_table_custom_fields has been deprecated. Use the set_table_customization API to set the custom table fields.

set_table_custom_fields in version 2 sets the custom root fields and custom column names of already tracked table. This will replace the already present custom fields configuration.

Set custom fields for table/view author:

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

{
"type": "set_table_custom_fields",
"version": 2,
"args": {
"table": "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"
},
"custom_column_names": {
"id": "authorId"
}
}
}

Args syntax

KeyRequiredSchemaDescription
tabletrueTableNameName of the table
custom_root_fieldsfalseCustom Root FieldsCustomize the root fields
custom_column_namesfalseCustomColumnNamesCustomize the column fields

set_table_customization

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_table_custom_fields has been deprecated in favour of this API.

Set the configuration for a table/view called author:

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

{
"type": "set_table_customization",
"args": {
"table": "author_details",
"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"
},
"custom_column_names": {
"id": "authorId"
}
}
}
}

Args syntax

KeyRequiredSchemaDescription
tabletrueTableNameName of the table
configurationfalseTableConfigConfiguration for the table/view

untrack_table

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

Remove a table/view author:

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

{
"type": "untrack_table",
"args": {
"table": {
"schema": "public",
"name": "author"
},
"cascade": true
}
}

Args syntax

KeyRequiredSchemaDescription
tabletrueTableNameName of the table
cascadefalseBooleanWhen set to true, the effect (if possible) is cascaded to any Metadata dependent objects (relationships, permissions, templates)