Skip to content

Latest commit

 

History

History
752 lines (593 loc) · 17.2 KB

table-view.rst

File metadata and controls

752 lines (593 loc) · 17.2 KB
Raw

Metadata API Reference: Tables/Views

Table of contents

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 <schema_metadata_apis>.

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": {
     "table": "author",
     "source": "default",
     "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/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin

{
   "type": "pg_track_table",
   "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

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 <TableName> Name of the table
configuration false Table Config <table_config> Configuration for the table/view
source false SourceName <SourceName> Name of the source database of the table (default: default)

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 <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 <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 <create_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 <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 <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.

pg_set_table_custom_fields <set_table_custom_fields> has been deprecated in favour of this API.

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"
       },
       "custom_column_names": {
          "id": "authorId"
       }
     }
   }
}

Args syntax

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

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 <TableName> Name of the table
configuration false Table Config <table_config> Configuration for the table/view
source false SourceName <SourceName> Name of the source database of the table (default: default)

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 <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 <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.

mssql_set_table_custom_fields <set_table_custom_fields> has been deprecated in favour of this API.

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",
      },
      "custom_column_names": {
          "id": "authorId"
      }
    }
  }
}

Args syntax

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

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 <table_config> Configuration for the table/view
source false SourceName <SourceName> Name of the source database of the table (default: default)

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 <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",
      },
      "custom_column_names": {
          "id": "authorId"
      }
    }
  }
}

Args syntax

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