mirror of
https://github.com/hasura/graphql-engine.git
synced 2024-12-17 12:31:52 +03:00
9bd5826020
* allow customizing GraphQL root field names, close #981 * document v2 track_table API in reference * support customising column field names in GraphQL schema * [docs] add custom column fields doc in API reference * add tests * rename 'ColField' to 'ColumnField' * embed column's graphql field in 'PGColumnInfo' -> Value constructor of 'PGCol' is not exposed -> Using 'parseJSON' to construct 'PGCol' in 'FromJSON' instances * avoid using 'Maybe TableConfig' * refactors & 'custom_column_fields' -> 'custom_column_names' * cli-test: add configuration field in metadata export test * update expected keys in `FromJSON` instance of `TableMeta` * use `buildSchemaCacheFor` to update configuration in v2 track_table * remove 'GraphQLName' type and use 'isValidName' exposed from parser lib * point graphql-parser-hs library git repo to hasura * support 'set_table_custom_fields' query API & added docs and tests
328 lines
6.4 KiB
ReStructuredText
328 lines
6.4 KiB
ReStructuredText
Schema/Metadata API Reference: Tables/Views
|
|
===========================================
|
|
|
|
.. contents:: Table of contents
|
|
:backlinks: none
|
|
:depth: 1
|
|
:local:
|
|
|
|
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
|
|
-----------
|
|
|
|
``track_table`` is used to add a table/view to the GraphQL schema.
|
|
|
|
Add a table/view ``author``:
|
|
|
|
.. code-block:: http
|
|
|
|
POST /v1/query HTTP/1.1
|
|
Content-Type: application/json
|
|
X-Hasura-Role: admin
|
|
|
|
{
|
|
"type": "track_table",
|
|
"args": {
|
|
"schema": "public",
|
|
"name": "author"
|
|
}
|
|
}
|
|
|
|
.. _track_table_syntax:
|
|
|
|
Args syntax
|
|
^^^^^^^^^^^
|
|
|
|
.. list-table::
|
|
:header-rows: 1
|
|
|
|
* - Key
|
|
- Required
|
|
- Schema
|
|
- Description
|
|
* - table
|
|
- true
|
|
- :ref:`TableName <TableName>`
|
|
- Name of the table
|
|
* - is_enum
|
|
- false
|
|
- Boolean
|
|
- When set to ``true``, creates the table as an :ref:`enum table <create_enum_table>`.
|
|
|
|
.. _set_table_is_enum:
|
|
|
|
set_table_is_enum
|
|
-----------------
|
|
|
|
``set_table_is_enum`` sets whether an already-tracked table should be used as an :ref:`enum table <create_enum_table>`.
|
|
|
|
Use table ``user_role`` as an enum table:
|
|
|
|
.. code-block:: http
|
|
|
|
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
|
|
}
|
|
}
|
|
|
|
.. _set_table_is_enum_syntax:
|
|
|
|
Args syntax
|
|
^^^^^^^^^^^
|
|
|
|
.. list-table::
|
|
:header-rows: 1
|
|
|
|
* - Key
|
|
- Required
|
|
- Schema
|
|
- Description
|
|
* - table
|
|
- true
|
|
- :ref:`TableName <TableName>`
|
|
- Name of the table
|
|
* - is_enum
|
|
- true
|
|
- Boolean
|
|
- Whether or not the table should be used as an :ref:`enum table <enum table>`.
|
|
|
|
.. _track_table_v2:
|
|
|
|
track_table v2
|
|
--------------
|
|
|
|
Version 2 of ``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``:
|
|
|
|
.. code-block:: http
|
|
|
|
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",
|
|
"update": "UpdateAuthors",
|
|
"delete": "DeleteAuthors"
|
|
},
|
|
"custom_column_names": {
|
|
"id": "authorId"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
|
|
.. _track_table_args_syntax_v2:
|
|
|
|
Args syntax
|
|
^^^^^^^^^^^
|
|
|
|
.. list-table::
|
|
:header-rows: 1
|
|
|
|
* - Key
|
|
- Required
|
|
- Schema
|
|
- Description
|
|
* - table
|
|
- true
|
|
- :ref:`TableName <TableName>`
|
|
- Name of the table
|
|
* - configuration
|
|
- false
|
|
- :ref:`Table Config <table_config>`
|
|
- Configuration for the table/view
|
|
|
|
.. _table_config:
|
|
|
|
Table Config
|
|
^^^^^^^^^^^^
|
|
|
|
.. list-table::
|
|
:header-rows: 1
|
|
|
|
* - Key
|
|
- Required
|
|
- Schema
|
|
- Description
|
|
* - custom_root_fields
|
|
- false
|
|
- :ref:`Custom Root Fields <custom_root_fields>`
|
|
- Customise the root fields
|
|
* - custom_column_names
|
|
- false
|
|
- :ref:`CustomColumnNames`
|
|
- Customise the column fields
|
|
|
|
.. _custom_root_fields:
|
|
|
|
Custom Root Fields
|
|
^^^^^^^^^^^^^^^^^^
|
|
|
|
.. list-table::
|
|
:header-rows: 1
|
|
|
|
* - Key
|
|
- Required
|
|
- Schema
|
|
- Description
|
|
* - select
|
|
- false
|
|
- `String`
|
|
- Customise the ``<table-name>`` root field
|
|
* - select_by_pk
|
|
- false
|
|
- `String`
|
|
- Customise the ``<table-name>_by_pk`` root field
|
|
* - select_aggregate
|
|
- false
|
|
- `String`
|
|
- Customise the ``<table-name>_aggregete`` root field
|
|
* - insert
|
|
- false
|
|
- `String`
|
|
- Customise the ``insert_<table-name>`` root field
|
|
* - update
|
|
- false
|
|
- `String`
|
|
- Customise the ``update_<table-name>`` root field
|
|
* - delete
|
|
- false
|
|
- `String`
|
|
- Customise the ``delete_<table-name>`` root field
|
|
|
|
.. _set_table_custom_fields:
|
|
|
|
set_table_custom_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``:
|
|
|
|
.. code-block:: http
|
|
|
|
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",
|
|
"update": "UpdateAuthors",
|
|
"delete": "DeleteAuthors"
|
|
},
|
|
"custom_column_names": {
|
|
"id": "authorId"
|
|
}
|
|
}
|
|
}
|
|
|
|
.. _set_table_custom_fields_args_syntax:
|
|
|
|
Args syntax
|
|
^^^^^^^^^^^
|
|
|
|
.. list-table::
|
|
:header-rows: 1
|
|
|
|
* - Key
|
|
- Required
|
|
- Schema
|
|
- Description
|
|
* - table
|
|
- true
|
|
- :ref:`TableName <TableName>`
|
|
- Name of the table
|
|
* - custom_root_fields
|
|
- false
|
|
- :ref:`Custom Root Fields <custom_root_fields>`
|
|
- Customise the root fields
|
|
* - custom_column_names
|
|
- false
|
|
- :ref:`CustomColumnNames`
|
|
- Customise the column fields
|
|
|
|
|
|
.. _untrack_table:
|
|
|
|
untrack_table
|
|
-------------
|
|
|
|
``untrack_table`` is used to remove a table/view from the GraphQL schema.
|
|
|
|
Remove a table/view ``author``:
|
|
|
|
.. code-block:: http
|
|
|
|
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
|
|
}
|
|
}
|
|
|
|
|
|
.. _untrack_table_syntax:
|
|
|
|
Args syntax
|
|
^^^^^^^^^^^
|
|
|
|
.. list-table::
|
|
:header-rows: 1
|
|
|
|
* - Key
|
|
- Required
|
|
- Schema
|
|
- Description
|
|
* - table
|
|
- true
|
|
- :ref:`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)
|