hasura/graphql-engine
1
0
Fork 0
mirror of https://github.com/hasura/graphql-engine.git synced 2024-09-21 07:28:26 +03:00
Code Issues Projects Releases Wiki Activity

docs: add api reference for new metadata api endpoint

Browse Source 
GitOrigin-RevId: e86aa47899a030707adf14b1ea235644fc48d726
This commit is contained in:
Rikin Kachhia 2021-02-24 18:00:34 +05:30 committed by hasura-bot
parent 6dff6e97ab
commit 66fb02b51f
41 changed files with 6252 additions and 1702 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
docs/graphql/core/api-reference/index.rst
View File

@ -171,3 +171,4 @@ See details at :ref:`explain_api_reference`.
PG Dump API <pgdump>
Config API <config>
Explain API <explain>
Common syntax definitions <syntax-defs>

279
docs/graphql/core/api-reference/metadata-api/actions.rst Normal file
View File

@ -0,0 +1,279 @@
.. meta::
:description: Manage actions with the Hasura metadata API
:keywords: hasura, docs, metadata API, API reference, actions
.. _metadata_api_actions:
Metadata API Reference: Actions (v1.4 and above)
================================================
.. contents:: Table of contents
:backlinks: none
:depth: 1
:local:
Introduction
------------
**actions** are user defined mutations with custom business logic.
.. _metadata_create_action:
create_action
-------------
``create_action`` is used to define an action. There shouldn't be an existing action with the same name.
Create a synchronous action with name ``create_user``:
.. code-block:: http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type":"create_action",
"args":{
"name":"create_user",
"definition":{
"kind":"synchronous",
"arguments":[
{
"name":"username",
"type":"String!"
},
{
"name":"email",
"type":"String!"
}
],
"output_type":"User",
"handler":"https://action.my_app.com/create-user",
"timeout":60
},
"comment": "Custom action to create user"
}
}
.. _metadata_create_action_syntax:
Args syntax
^^^^^^^^^^^
.. list-table::
:header-rows: 1
* - Key
- Required
- Schema
- Description
* - name
- true
- :ref:`ActionName <ActionName>`
- Name of the action
* - definition
- true
- :ref:`ActionDefinition`
- Definition of the action
* - comment
- false
- text
- comment
.. note::
The ``GraphQL Types`` used in creating an action must be defined before via :ref:`Custom Types <metadata_api_custom_types>`
.. _metadata_drop_action:
drop_action
-----------
``drop_action`` is used to remove an action. Permissions defined on the actions are also dropped automatically.
Drop an action ``create_user``:
.. code-block:: http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type":"drop_action",
"args":{
"name":"create_user",
"clear_data": true
}
}
.. _metadata_drop_action_syntax:
Args syntax
^^^^^^^^^^^
.. list-table::
:header-rows: 1
* - Key
- Required
- Schema
- Description
* - name
- true
- :ref:`ActionName <ActionName>`
- Name of the action
* - clear_data
- false
- boolean
- If set to ``true`` and action kind is ``asynchronous``, related data is deleted from catalog. (default: ``true``)
.. _metadata_update_action:
update_action
-------------
``update_action`` is used to update the definition of the action. Definition thus provided is
replaced with existing one.
Update an action ``create_user`` by making it's kind to ``asynchronous``:
.. code-block:: http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type":"update_action",
"args":{
"name":"create_user",
"definition":{
"kind":"asynchronous",
"arguments":[
{
"name":"username",
"type":"String!"
},
{
"name":"email",
"type":"String!"
}
],
"output_type":"User",
"handler":"https://action.my_app.com/create-user"
}
}
}
.. _metadata_update_action_syntax:
Args syntax
^^^^^^^^^^^
.. list-table::
:header-rows: 1
* - Key
- Required
- Schema
- Description
* - name
- true
- :ref:`ActionName <ActionName>`
- Name of the action
* - definition
- true
- :ref:`ActionDefinition`
- Definition of the action to be replaced
.. _metadata_create_action_permission:
create_action_permission
------------------------
``create_action_permission`` is used to define a permission to make action visible for a role.
.. code-block:: http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type": "create_action_permission",
"args": {
"action": "create_user",
"role": "user"
}
}
.. _metadata_create_action_permission_syntax:
Args syntax
^^^^^^^^^^^
.. list-table::
:header-rows: 1
* - Key
- Required
- Schema
- Description
* - action
- true
- :ref:`ActionName <ActionName>`
- Name of the action
* - role
- true
- :ref:`RoleName <RoleName>`
- Name of the role
* - comment
- false
- text
- comment
.. _metadata_drop_action_permission:
drop_action_permission
----------------------
``drop_action_permission`` is used to drop a permission defined on an action.
.. code-block:: http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type": "drop_action_permission",
"args": {
"action": "create_user",
"role": "user"
}
}
.. _metadata_drop_action_permission_syntax:
Args syntax
^^^^^^^^^^^
.. list-table::
:header-rows: 1
* - Key
- Required
- Schema
- Description
* - name
- true
- :ref:`ActionName <ActionName>`
- Name of the action
* - role
- true
- :ref:`RoleName <RoleName>`
- Name of the role

154
docs/graphql/core/api-reference/metadata-api/computed-field.rst Normal file
View File

@ -0,0 +1,154 @@
.. meta::
:description: Manage computed fields with the Hasura metadata API
:keywords: hasura, docs, metadata API, API reference, computed field
.. _metadata_api_computed_field:
Metadata API Reference: Computed Fields (v1.4 and above)
========================================================
.. contents:: Table of contents
:backlinks: none
:depth: 1
:local:
Introduction
------------
**computed field** is an extra field added to a table, its value is
computed via an SQL function which has the table row type as an input argument.
Currenty, the Hasura GraphQL engine supports functions returning
`base types <https://www.postgresql.org/docs/current/extend-type-system.html#id-1.8.3.5.9>`__ or
`table row types <https://www.postgresql.org/docs/current/rowtypes.html#ROWTYPES-DECLARING>`__
as computed fields.
.. _pg_add_computed_field:
pg_add_computed_field
---------------------
``pg_add_computed_field`` is used to define a computed field in a table.
There cannot be an existing column or relationship or computed field with
the same name.
Create a ``computed field`` called ``full_name`` on an ``author`` *table*, using
an SQL function called ``author_full_name``:
.. code-block:: http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type":"pg_add_computed_field",
"args":{
"table":{
"name":"author",
"schema":"public"
},
"source": "default",
"name":"full_name",
"definition":{
"function":{
"name":"author_full_name",
"schema":"public"
},
"table_argument":"author_row"
}
}
}
.. _pg_add_computed_field_syntax:
Args syntax
^^^^^^^^^^^
.. list-table::
:header-rows: 1
* - Key
- Required
- Schema
- Description
* - table
- true
- :ref:`TableName <TableName>`
- Name of the table
* - name
- true
- :ref:`ComputedFieldName <ComputedFieldName>`
- Name of the new computed field
* - definition
- true
- :ref:`ComputedFieldDefinition`
- The computed field definition
* - comment
- false
- text
- comment
* - source
- false
- :ref:`SourceName <SourceName>`
- Name of the source database of the table (default: ``default``)
.. _pg_drop_computed_field:
pg_drop_computed_field
----------------------
``pg_drop_computed_field`` is used to drop a computed field of a table. If
there are other objects dependent on this computed field, like permissions, the request will fail and report the
dependencies unless ``cascade`` is set to ``true``. If ``cascade`` is set to ``true``, the dependent objects
are also dropped.
Drop a computed field ``full_name`` from a table ``author``:
.. code-block:: http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type":"pg_drop_computed_field",
"args":{
"table":{
"name":"author",
"schema":"public"
},
"source": "default",
"name":"full_name",
"cascade": false
}
}
.. _pg_drop_computed_field_syntax:
Args syntax
^^^^^^^^^^^
.. list-table::
:header-rows: 1
* - Key
- Required
- Schema
- Description
* - table
- true
- :ref:`TableName <TableName>`
- Name of the table
* - name
- true
- :ref:`ComputedFieldName <ComputedFieldName>`
- Name of the computed field
* - cascade
- false
- Boolean
- When set to ``true``, all the dependent items (if any) on this computed fields are also dropped
* - source
- false
- :ref:`SourceName <SourceName>`
- Name of the source database of the table (default: ``default``)

157
docs/graphql/core/api-reference/metadata-api/custom-functions.rst
View File

@ -4,8 +4,8 @@
.. _metadata_api_custom_functions:
Metadata API Reference: Custom Functions
========================================
Metadata API Reference: Custom Functions (v1.4 and above)
=========================================================
.. contents:: Table of contents
:backlinks: none
@ -19,7 +19,146 @@ Track/untrack a custom SQL function in the Hasura GraphQL engine.
Only tracked custom functions are available for querying/mutating/subscribing data over the GraphQL API.
.. TODO: add other existing APIs
.. _pg_track_function:
pg_track_function
-----------------
``pg_track_function`` is used to add a custom SQL function to the GraphQL schema.
It supports more configuration options than v1, and also supports tracking
functions as mutations.
Also refer a note :ref:`here <function_req_note>`.
Track an SQL function called ``search_articles`` with a Hasura session argument:
.. code-block:: http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type": "pg_track_function",
"args": {
"function": {
"schema": "public",
"name": "search_articles"
},
"source": "default",
"configuration": {
"session_argument": "hasura_session"
}
}
}
Track ``VOLATILE`` SQL function ``reset_widget`` as a mutation, so it appears
as a top-level field under the ``mutation`` root field:
.. code-block:: http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type": "pg_track_function",
"args": {
"function": {
"schema": "public",
"name": "reset_widget"
},
"configuration": {
"exposed_as": "mutation"
}
}
}
If ``exposed_as`` is omitted, the location in the schema to expose the function
will be inferred from the function's volatility, with ``VOLATILE`` functions
appearing under the ``mutation`` root, and others ending up under
``query/subscription``.
In most cases you will want ``VOLATILE`` functions to only be exposed as
mutations, and only ``STABLE`` and ``IMMUTABLE`` functions to be queries.
When tracking ``VOLATILE`` functions under the ``query`` root, the user needs
to guarantee that the field is idempotent and side-effect free, in the context
of the resulting GraphQL API.
One such use case might be a function that wraps a simple query and performs
some logging visible only to administrators.
.. note::
It's easy to accidentally give an SQL function the wrong volatility (or for a
function to end up with ``VOLATILE`` mistakenly, since it's the default).
.. _pg_track_function_syntax:
Args syntax
^^^^^^^^^^^
.. list-table::
:header-rows: 1
* - Key
- Required
- Schema
- Description
* - function
- true
- :ref:`FunctionName <FunctionName>`
- Name of the SQL function
* - configuration
- false
- :ref:`Function Configuration <function_configuration>`
- Configuration for the SQL function
* - source
- false
- :ref:`SourceName <SourceName>`
- Name of the source database of the function (default: ``default``)
.. _pg_untrack_function:
pg_untrack_function
-------------------
``pg_untrack_function`` is used to remove a SQL function from the GraphQL schema.
Remove an SQL function ``search_articles``:
.. code-block:: http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type": "pg_untrack_function",
"args": {
"schema": "public",
"name": "search_articles",
"source": "default"
}
}
Args syntax
^^^^^^^^^^^
.. list-table::
:header-rows: 1
* - Key
- Required
- Schema
- Description
* - table
- true
- :ref:`FunctionName <FunctionName>`
- Name of the SQL function
* - source
- false
- :ref:`SourceName <SourceName>`
- Name of the source database of the function (default: ``default``)
.. _pg_create_function_permission:
@ -40,11 +179,12 @@ target table of the function.
"type": "pg_create_function_permission",
"args": {
"function": "get_articles",
"source": "default",
"role": "user"
}
}
.. _pg_create_function_permission_args_syntax:
.. _pg_create_function_permission_syntax:
Args syntax
^^^^^^^^^^^
@ -67,7 +207,7 @@ Args syntax
* - source
- false
- Text
- Name of the source of the SQL function
- Name of the source database of the function (default: ``default``)
.. _pg_drop_function_permission:
@ -86,11 +226,12 @@ pg_drop_function_permission
"type": "pg_drop_function_permission",
"args": {
"function": "get_articles",
"role": "user"
"role": "user",
"source": "default"
}
}
.. _pg_drop_function_permission_args_syntax:
.. _pg_drop_function_permission_syntax:
Args syntax
^^^^^^^^^^^
@ -113,4 +254,4 @@ Args syntax
* - source
- false
- Text
- Name of the source of the SQL function
- Name of the source database of the function (default: ``default``)

106
docs/graphql/core/api-reference/metadata-api/custom-types.rst Normal file
View File

@ -0,0 +1,106 @@
.. meta::
:description: Define custom types with the Hasura metadata API
:keywords: hasura, docs, metadata API, API reference, custom types
.. _metadata_api_custom_types:
Metadata API Reference: Custom Types (v1.4 and above)
=====================================================
.. contents:: Table of contents
:backlinks: none
:depth: 1
:local:
Introduction
------------
**Custom Types** are user-defined GraphQL types which help to define :ref:`Actions <api_actions>`.
.. _metadata_set_custom_types:
set_custom_types
----------------
``set_custom_types`` is used to set user-defined GraphQL types. This API will replace the given types with existing ones.
.. code-block:: http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type": "set_custom_types",
"args": {
"scalars": [],
"enums": [],
"input_objects": [
{
"name": "User",
"fields": [
{
"name": "username",
"type": "String!"
},
{
"name": "password",
"type": "String!"
}
]
}
],
"objects": [
{
"name": "UserId",
"fields": [
{
"name": "id",
"type": "Int!"
}
],
"relationships": [
{
"name": "posts",
"type": "array",
"remote_table": "post",
"field_mapping": {
"id": "user_id"
}
}
]
}
]
}
}
.. _metadata_set_custom_types_syntax:
Args syntax
^^^^^^^^^^^
.. list-table::
:header-rows: 1
* - Key
- Required
- Schema
- Description
* - input_objects
- false
- Array of :ref:`InputObjectType`
- Set of GraphQL ``Input Object``
* - objects
- false
- Array of :ref:`ObjectType`
- Set of GraphQL ``Object``
* - scalars
- false
- Array of :ref:`ScalarType`
- Set of GraphQL ``Scalar``
* - enums
- false
- Array of :ref:`EnumType`
- Set of GraphQL ``Enum``

258
docs/graphql/core/api-reference/metadata-api/event-triggers.rst Normal file
View File

@ -0,0 +1,258 @@
.. meta::
:description: Manage event triggers with the Hasura metadata API
:keywords: hasura, docs, metadata API, API reference, event trigger
.. _metadata_api_event_triggers:
Metadata API Reference: Event Triggers (v1.4 and above)
=======================================================
.. contents:: Table of contents
:backlinks: none
:depth: 1
:local:
Introduction
------------
Event triggers are used to capture database changes and send them to a configured webhook.
.. _pg_create_event_trigger:
pg_create_event_trigger
-----------------------
``pg_create_event_trigger`` is used to create a new event trigger or replace an existing event trigger.
.. code-block:: http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type" : "pg_create_event_trigger",
"args" : {
"name": "sample_trigger",
"table": {
"name": "users",
"schema": "public"
},
"source": "default",
"webhook": "https://httpbin.org/post",
"insert": {
"columns": "*",
"payload": ["username"]
},
"update": {
"columns": ["username", "real_name"],
"payload": "*"
},
"delete": {
"columns": "*"
},
"headers":[
{
"name": "X-Hasura-From-Val",
"value": "myvalue"
},
{
"name": "X-Hasura-From-Env",
"value_from_env": "EVENT_WEBHOOK_HEADER"
}
],
"replace": false
}
}
.. _pg_create_event_trigger_syntax:
Args syntax
^^^^^^^^^^^
.. list-table::
:header-rows: 1
* - Key
- Required
- Schema
- Description
* - name
- true
- :ref:`TriggerName <TriggerName>`
- Name of the event trigger
* - table
- true
- :ref:`QualifiedTable <QualifiedTable>`
- Object with table name and schema
* - source
- false
- :ref:`SourceName <SourceName>`
- Name of the source database of the table (default: ``default``)
* - webhook
- false
- String
- Full url of webhook (*)
* - webhook_from_env
- false
- String
- Environment variable name of webhook (must exist at boot time) (*)
* - insert
- false
- :ref:`OperationSpec`
- Specification for insert operation
* - update
- false
- :ref:`OperationSpec`
- Specification for update operation
* - delete
- false
- :ref:`OperationSpec`
- Specification for delete operation
* - headers
- false
- [ :ref:`HeaderFromValue <HeaderFromValue>` | :ref:`HeaderFromEnv <HeaderFromEnv>` ]
- List of headers to be sent with the webhook
* - retry_conf
- false
- :ref:`RetryConf`
- Retry configuration if event delivery fails
* - replace
- false
- Boolean
- If set to true, the event trigger is replaced with the new definition
* - enable_manual
- false
- Boolean
- If set to true, the event trigger can be invoked manually
(*) Either ``webhook`` or ``webhook_from_env`` are required.
.. _pg_delete_event_trigger:
pg_delete_event_trigger
-----------------------
``pg_delete_event_trigger`` is used to delete an event trigger.
.. code-block:: http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type" : "pg_delete_event_trigger",
"args" : {
"name": "sample_trigger",
"source": "default"
}
}
.. _pg_delete_event_trigger_syntax:
Args syntax
^^^^^^^^^^^
.. list-table::
:header-rows: 1
* - Key
- Required
- Schema
- Description
* - name
- true
- :ref:`TriggerName <TriggerName>`
- Name of the event trigger
* - source
- false
- :ref:`SourceName <SourceName>`
- Name of the source database of the trigger (default: ``default``)
.. _pg_redeliver_event:
pg_redeliver_event
------------------
``redeliver_event`` is used to redeliver an existing event. For example, if an event is marked as error (
say it did not succeed after retries), you can redeliver it using this API. Note that this will reset the count of retries so far.
If the event fails to deliver, it will be retried automatically according to its ``retry_conf``.
.. code-block:: http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type" : "pg_redeliver_event",
"args" : {
"event_id": "ad4f698f-a14e-4a6d-a01b-38cd252dd8bf"
}
}
.. _pg_redeliver_event_syntax:
Args syntax
^^^^^^^^^^^
.. list-table::
:header-rows: 1
* - Key
- Required
- Schema
- Description
* - event_id
- true
- String
- UUID of the event
.. _pg_invoke_event_trigger:
pg_invoke_event_trigger
-----------------------
``invoke_event_trigger`` is used to invoke an event trigger with custom payload.
.. code-block:: http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type" : "pg_invoke_event_trigger",
"args" : {
"name": "sample_trigger",
"source": "default",
"payload": {}
}
}
.. _pg_invoke_event_trigger_syntax:
Args syntax
^^^^^^^^^^^
.. list-table::
:header-rows: 1
* - Key
- Required
- Schema
- Description
* - name
- true
- :ref:`TriggerName <TriggerName>`
- Name of the event trigger
* - payload
- true
- JSON
- Some JSON payload to send to trigger
* - source
- false
- :ref:`SourceName <SourceName>`
- Name of the source database of the trigger (default: ``default``)

437
docs/graphql/core/api-reference/metadata-api/index.rst
View File

@ -48,9 +48,9 @@ Request body
.. parsed-literal::
Query_
:ref:`Query <metadata_query>`
.. _Query:
.. _metadata_query:
Query
*****
@ -93,30 +93,342 @@ The various types of queries are listed in the following table:
- Synopsis
* - **bulk**
- :ref:`Query <Query>` array
- :ref:`Query <metadata_query>` array
- 1
- Execute multiple operations in a single query
* - :ref:`pg_create_function_permission`
- :ref:`pg_create_function_permission_args <pg_create_function_permission_args_syntax>`
* - :ref:`pg_add_source <pg_add_source>`
- :ref:`pg_add_source_args <pg_add_source_syntax>`
- 1
- Create a function permission
- Add a Postgres database
* - :ref:`pg_drop_source <pg_drop_source>`
- :ref:`pg_drop_source_args <pg_drop_source_syntax>`
- 1
- Remove a Postgres database
* - :ref:`pg_track_table <pg_track_table>`
- :ref:`pg_track_table_args <pg_track_table_syntax>`
- 1
- Add a Postgres table/view with configuration
* - :ref:`pg_untrack_table`
- :ref:`pg_untrack_table_args <pg_untrack_table_syntax>`
- 1
- Remove a Postgres table/view
* - :ref:`pg_set_table_customization <pg_set_table_customization>`
- :ref:`pg_set_table_customization_args <pg_set_table_customization_syntax>`
- 1
- Set table customization of an already tracked Postgres table
* - :ref:`pg_set_table_is_enum`
- :ref:`pg_set_table_is_enum_args <pg_set_table_is_enum_syntax>`
- 1
- Set a tracked Postgres table as an enum table
* - :ref:`pg_track_function`
- :ref:`pg_track_function_args <pg_track_function_syntax>`
- 1
- Add a Postgres SQL function with configuration
* - :ref:`pg_untrack_function`
- :ref:`FunctionName <FunctionName>`
- 1
- Remove a Postgres SQL function
* - :ref:`pg_create_function_permission`
- :ref:`pg_create_function_permission_args <pg_create_function_permission_syntax>`
- 1
- Create a Postgres function permission
* - :ref:`pg_drop_function_permission`
- :ref:`pg_drop_function_permission_args <pg_drop_function_permission_args_syntax>`
- :ref:`pg_drop_function_permission_args <pg_drop_function_permission_syntax>`
- 1
- Drop an existing function permission
- Drop an existing Postgres function permission
* - :ref:`export_metadata`
- :ref:`export_metadata_examples`
* - :ref:`pg_create_object_relationship`
- :ref:`pg_create_object_relationship_args <pg_create_object_relationship_syntax>`
- 1
- Define a new object relationship between Postgres tables/views
* - :ref:`pg_create_array_relationship`
- :ref:`pg_create_array_relationship_args <pg_create_array_relationship_syntax>`
- 1
- Define a new array relationship between Postgres tables/views
* - :ref:`pg_drop_relationship`
- :ref:`pg_drop_relationship_args <pg_drop_relationship_syntax>`
- 1
- Drop an existing Postgres relationship
* - :ref:`pg_rename_relationship`
- :ref:`pg_rename_relationship_args <pg_rename_relationship_syntax>`
- 1
- Modify name of an existing Postgres relationship
* - :ref:`pg_set_relationship_comment`
- :ref:`pg_set_relationship_comment_args <pg_set_relationship_comment_syntax>`
- 1
- Set comment on an existing Postgres relationship
* - :ref:`pg_add_computed_field`
- :ref:`pg_add_computed_field_args <pg_add_computed_field_syntax>`
- 1
- Add a computed field to a Postgres table/view
* - :ref:`pg_drop_computed_field`
- :ref:`pg_drop_computed_field_args <pg_drop_computed_field_syntax>`
- 1
- Drop a Postgres computed field
* - :ref:`pg_create_insert_permission`
- :ref:`pg_create_insert_permission_args <pg_create_insert_permission_syntax>`
- 1
- Specify insert permission for a Postgres table/view
* - :ref:`pg_drop_insert_permission`
- :ref:`pg_drop_insert_permission_args <pg_drop_insert_permission_syntax>`
- 1
- Remove existing insert permission for a Postgres table/view
* - :ref:`pg_create_select_permission`
- :ref:`pg_create_select_permission_args <pg_create_select_permission_syntax>`
- 1
- Specify select permission for a Postgres table/view
* - :ref:`pg_drop_select_permission`
- :ref:`pg_drop_select_permission_args <pg_drop_select_permission_syntax>`
- 1
- Remove existing select permission for a Postgres table/view
* - :ref:`pg_create_update_permission`
- :ref:`pg_create_update_permission_args <pg_create_update_permission_syntax>`
- 1
- Specify update permission for a Postgres table/view
* - :ref:`pg_drop_update_permission`
- :ref:`pg_drop_update_permission_args <pg_drop_update_permission_syntax>`
- 1
- Remove existing update permission for a Postgres table/view
* - :ref:`pg_create_delete_permission`
- :ref:`pg_create_delete_permission_args <pg_create_delete_permission_syntax>`
- 1
- Specify delete permission for a Postgres table/view
* - :ref:`pg_drop_delete_permission`
- :ref:`pg_drop_delete_permission_args <pg_drop_delete_permission_syntax>`
- 1
- Remove existing delete permission for a Postgres table/view
* - :ref:`pg_set_permission_comment`
- :ref:`pg_set_permission_comment_args <pg_set_permission_comment_syntax>`
- 1
- Set comment on an existing permission for a Postgres table/view
* - :ref:`pg_create_event_trigger`
- :ref:`pg_create_event_trigger_args <pg_create_event_trigger_syntax>`
- 1
- Create or replace an event trigger on a Postgres table
* - :ref:`pg_delete_event_trigger`
- :ref:`pg_delete_event_trigger_args <pg_delete_event_trigger_syntax>`
- 1
- Delete an existing event trigger on a Postgres table
* - :ref:`pg_redeliver_event`
- :ref:`pg_redeliver_event_args <pg_redeliver_event_syntax>`
- 1
- Redeliver an existing event on a Postgres table
* - :ref:`pg_invoke_event_trigger`
- :ref:`pg_invoke_event_trigger_args <pg_invoke_event_trigger_syntax>`
- 1
- Invoke a trigger with custom payload on a Postgres table
* - :ref:`metadata_create_cron_trigger`
- :ref:`create_cron_trigger_args <metadata_create_cron_trigger_syntax>`
- 1
- Create a cron trigger
* - :ref:`metadata_delete_cron_trigger`
- :ref:`delete_cron_trigger_args <metadata_delete_cron_trigger_syntax>`
- 1
- Delete an existing cron trigger
* - :ref:`metadata_create_scheduled_event`
- :ref:`create_scheduled_event_args <metadata_create_scheduled_event_syntax>`
- 1
- Create a new scheduled event
* - :ref:`metadata_add_remote_schema`
- :ref:`add_remote_schema_args <metadata_add_remote_schema_syntax>`
- 1
- Add a remote GraphQL server as a remote schema
* - :ref:`metadata_remove_remote_schema`
- :ref:`remove_remote_schema_args <metadata_remove_remote_schema_syntax>`
- 1
- Remove an existing remote schema
* - :ref:`metadata_reload_remote_schema`
- :ref:`reload_remote_schema_args <metadata_reload_remote_schema_syntax>`
- 1
- Reload schema of an existing remote schema
* - :ref:`metadata_add_remote_schema_permissions`
- :ref:`add_remote_schema_permissions <metadata_add_remote_schema_permissions_syntax>`
- 1
- Add permissions to a role of an existing remote schema
* - :ref:`metadata_drop_remote_schema_permissions`
- :ref:`drop_remote_schema_permissions <metadata_drop_remote_schema_permissions_syntax>`
- 1
- Drop existing permissions defined for a role for a remote schema
* - :ref:`metadata_create_remote_relationship`
- :ref:`create_remote_relationship_args <metadata_create_remote_relationship_syntax>`
- 1
- Create a remote relationship with an existing remote schema
* - :ref:`metadata_update_remote_relationship`
- :ref:`update_remote_relationship_args <metadata_update_remote_relationship_syntax>`
- 1
- Update an existing remote relationship
* - :ref:`metadata_delete_remote_relationship`
- :ref:`delete_remote_relationship_args <metadata_delete_remote_relationship_syntax>`
- 1
- Delete an existing remote relationship
* - :ref:`metadata_export_metadata`
- :ref:`Empty Object`
- 1
- Export the current metadata
* - :ref:`metadata_export_metadata`
- :ref:`Empty Object`
- 2
- Export existing metadata with resource version included.
* - :ref:`replace_metadata`
- :ref:`replace_metadata_examples`
* - :ref:`metadata_replace_metadata`
- :ref:`replace_metadata_args <metadata_replace_metadata_syntax>`
- 1
- Import and replace existing metadata
* - :ref:`metadata_replace_metadata`
- :ref:`replace_metadata_args <metadata_replace_metadata_syntax>`
- 2
- Replace existing metadata with check against current resource_version.
* - :ref:`metadata_reload_metadata`
- :ref:`Empty Object`
- 1
- Reload changes to the underlying Postgres DB
* - :ref:`metadata_clear_metadata`
- :ref:`Empty Object`
- 1
- Clear/wipe-out the current metadata state form server
* - :ref:`metadata_get_inconsistent_metadata`
- :ref:`Empty Object`
- 1
- List all inconsistent metadata objects
* - :ref:`metadata_drop_inconsistent_metadata`
- :ref:`Empty Object`
- 1
- Drop all inconsistent metadata objects
* - :ref:`metadata_create_query_collection`
- :ref:`create_query_collection_args <metadata_create_query_collection_syntax>`
- 1
- Create a query collection
* - :ref:`metadata_drop_query_collection`
- :ref:`drop_query_collection_args <metadata_drop_query_collection_syntax>`
- 1
- Drop a query collection
* - :ref:`metadata_add_query_to_collection`
- :ref:`add_query_to_collection_args <metadata_add_query_to_collection_syntax>`
- 1
- Add a query to a given collection
* - :ref:`metadata_drop_query_from_collection`
- :ref:`drop_query_from_collection_args <metadata_drop_query_from_collection_syntax>`
- 1
- Drop a query from a given collection
* - :ref:`metadata_add_collection_to_allowlist`
- :ref:`add_collection_to_allowlist_args <metadata_add_collection_to_allowlist_syntax>`
- 1
- Add a collection to the allow-list
* - :ref:`metadata_drop_collection_from_allowlist`
- :ref:`drop_collection_from_allowlist_args <metadata_drop_collection_from_allowlist_syntax>`
- 1
- Drop a collection from the allow-list
* - :ref:`metadata_set_custom_types`
- :ref:`set_custom_types_args <metadata_set_custom_types_syntax>`
- 1
- Set custom GraphQL types
* - :ref:`metadata_create_action`
- :ref:`create_action_args <metadata_create_action_syntax>`
- 1
- Create an action
* - :ref:`metadata_drop_action`
- :ref:`drop_action_args <metadata_drop_action_syntax>`
- 1
- Drop an action
* - :ref:`metadata_update_action`
- :ref:`update_action_args <metadata_update_action_syntax>`
- 1
- Update an action
* - :ref:`metadata_create_action_permission`
- :ref:`create_action_permission_args <metadata_create_action_permission_syntax>`
- 1
- Create an action permission
* - :ref:`metadata_drop_action_permission`
- :ref:`drop_action_permission_args <metadata_drop_action_permission_syntax>`
- 1
- Drop an action permission
* - :ref:`metadata_create_rest_endpoint`
- :ref:`create_rest_endpoint_args <metadata_create_rest_endpoint_syntax>`
- 1
- Create a RESTified GraphQL Endpoint
* - :ref:`metadata_drop_rest_endpoint`
- :ref:`drop_rest_endpoint_args <metadata_drop_rest_endpoint_syntax>`
- 1
- Drop a RESTified GraphQL Endpoint
**See:**
- :ref:`Tables/Views <metadata_api_tables_views>`
- :ref:`Custom SQL Functions <metadata_api_custom_functions>`
- :ref:`Relationships <metadata_api_relationship>`
- :ref:`Computed Fields <metadata_api_computed_field>`
- :ref:`Permissions <metadata_api_permission>`
- :ref:`Remote Schema Permissions <metadata_remote_schema_api_permission>`
- :ref:`Event Triggers <metadata_api_event_triggers>`
- :ref:`Remote Schemas <metadata_api_remote_schemas>`
- :ref:`Query Collections <metadata_api_query_collections>`
- :ref:`Custom Types <metadata_api_custom_types>`
- :ref:`Actions <metadata_api_actions>`
- :ref:`Manage Metadata <metadata_api_manage_metadata>`
Response structure
------------------
@ -191,86 +503,23 @@ The ``resource_version`` supplied must match the version returned otherwise a 40
The version is incremented on any operation that modified metadata as well as ``reload_metadata``.
.. toctree::
:maxdepth: 1
:hidden:
.. _export_metadata_examples:
Export Metadata Examples
------------------------
``export_metadata`` is used to export the current metadata from the server as a JSON file.
V1 Example: See :ref:`export_metadata`
V2 Example:
.. code-block:: http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type": "export_metadata",
"version": 2,
"args": {}
}
Response:
.. code-block:: json
{
"resource_version": 8,
"metadata": {
"version": 3,
"sources": [
{
"name": "default",
"tables": [
{
"table": {
.. _replace_metadata_examples:
Replace Metadata Examples
-------------------------
``replace_metadata`` is used to replace the current metadata with a JSON object.
V1 Example: See :ref:`replace_metadata_syntax_v1`
Version 2 example with inconsistencies and allow_inconsistent_metadata=true:
HTTP/1.1 200 OK
.. code-block:: json
{
"is_consistent": false,
"inconsistent_objects": [
{
"definition": {
"definition": {
"url": "http://localhost:5000/hello-graphql",
"forward_client_headers": false
},
"name": "test",
"permissions": [],
"comment": "testing replace metadata with remote schemas"
},
"reason": "HTTP exception occurred while sending the request to http://localhost:5000/hello-graphql",
"type": "remote_schema"
}, ...
Version 2 example with invalid ``resource_version``:
HTTP/1.1 409 Conflict
.. code-block:: json
{
"path": "$",
"error": "metadata resource version referenced (2) did not match current version",
"code": "conflict"
}
Databases <source>
Tables/Views <table-view>
Custom Functions <custom-functions>
Relationships <relationship>
Permissions <permission>
Remote Schema Permissions <remote-schema-permissions>
Computed Fields <computed-field>
Event Triggers <event-triggers>
Scheduled Triggers <scheduled-triggers>
Remote Schemas <remote-schemas>
Remote Relationships <remote-relationships>
Query Collections <query-collections>
RESTified GraphQL Endpoints <restified-endpoints>
Custom Types <custom-types>
Actions <actions>
Manage Metadata <manage-metadata>

241
docs/graphql/core/api-reference/metadata-api/manage-metadata.rst
View File

@ -4,8 +4,8 @@
.. _metadata_api_manage_metadata:
Metadata API Reference: Manage metadata
=======================================
Metadata API Reference: Manage metadata (v1.4 and above)
========================================================
.. contents:: Table of contents
:backlinks: none
@ -17,9 +17,62 @@ Introduction
APIs to manage Hasura metadata which is stored in ``hdb_catalog`` schema.
.. TODO: add other existing APIs
.. _metadata_export_metadata:
.. _replace_metadata_v2:
export_metadata
---------------
``export_metadata`` is used to export the current metadata from the server as a JSON file.
.. code-block:: none
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type" : "export_metadata",
"version": 1 | 2
"args": {}
}
Response:
The response JSON will be the metadata object. The structure of the metadata object
is just a JSON version of the :ref:`metadata files <metadata_format>` generated by
the CLI.
V2 Example:
.. code-block:: http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type": "export_metadata",
"version": 2,
"args": {}
}
Response:
.. code-block:: none
{
"resource_version": 8,
"metadata": {
"version": 3,
"sources": [
{
"name": "default",
"tables": [
{
"table": {
...
.. _metadata_replace_metadata:
replace_metadata
----------------
@ -29,7 +82,7 @@ metadata will be replaced with the new one.
.. code-block:: none
POST /v1/query HTTP/1.1
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
@ -39,13 +92,14 @@ metadata will be replaced with the new one.
"args": <replace-metadata-args>
}
For version 1, this API corresponds to the legacy API documented under :ref:`replace_metadata` in the ``/v1/query`` endpoint.
.. _replace_metadata_syntax_v2:
.. _metadata_replace_metadata_syntax:
Args syntax
^^^^^^^^^^^
If version is set to 1, then args should be the JSON object which is same as
the output of :ref:`metadata_export_metadata`.
For version 2, the following structure is used:
.. code-block:: none
@ -68,7 +122,7 @@ For version 2, the following structure is used:
- If set to ``true``, metadata will be replaced with a warning in the response indicating which items are inconsistent (default: ``false``)
* - metadata
- true
- :ref:`export_metadata`
- :ref:`metadata_export_metadata`
- The metadata that will replace the current metadata.
If the version is not specified, then it is inferred from the format of ``args``.
@ -119,3 +173,172 @@ Version 2 example with inconsistencies and allow_inconsistent_metadata=true incl
}, ...
]
}
Version 2 example with inconsistencies and allow_inconsistent_metadata=true:
.. code-block:: none
HTTP/1.1 200 OK
{
"is_consistent": false,
"inconsistent_objects": [
{
"definition": {
"definition": {
"url": "http://localhost:5000/hello-graphql",
"forward_client_headers": false
},
"name": "test",
"permissions": [],
"comment": "testing replace metadata with remote schemas"
},
"reason": "HTTP exception occurred while sending the request to http://localhost:5000/hello-graphql",
"type": "remote_schema"
}, ...
Version 2 example with invalid ``resource_version``:
.. code-block:: http
HTTP/1.1 409 Conflict
{
"path": "$",
"error": "metadata resource version referenced (2) did not match current version",
"code": "conflict"
}
.. _metadata_reload_metadata:
reload_metadata
---------------
``reload_metadata`` should be used when there is a change in underlying Postgres
database that Hasura should be aware of. Example: a new column is added to a
table using ``psql`` and this column should now be added to the GraphQL schema.
.. code-block:: http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type" : "reload_metadata",
"args": {
"reload_remote_schemas": true
}
}
.. _metadata_reload_metadata_syntax:
Args syntax
^^^^^^^^^^^
.. list-table::
:header-rows: 1
* - Key
- Required
- Schema
- Description
* - reload_remote_schemas
- false
- Boolean
- If set to ``true``, all remote schemas' (including inconsistent ones) cached GraphQL schemas are refreshed (default: ``false``)
.. _metadata_clear_metadata:
clear_metadata
--------------
``clear_metadata`` can be used to reset the state of Hasura -- clean the current
state by forgetting the tables tracked, relationships, permissions, event
triggers etc.
.. code-block:: http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type" : "clear_metadata",
"args": {}
}
.. _metadata_get_inconsistent_metadata:
get_inconsistent_metadata
-------------------------
``get_inconsistent_metadata`` can be used to fetch all inconsistent metadata objects.
.. code-block:: http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type": "get_inconsistent_metadata",
"args": {}
}
Response:
.. code-block:: json
[
{
"definition": {
"using": {
"foreign_key_constraint_on": {
"column": "author_id",
"table": "article"
}
},
"name": "articles",
"comment": null,
"table": "author"
},
"reason": "table \"article\" does not exist",
"type": "array_relation"
},
{
"definition": {
"using": {
"foreign_key_constraint_on": "author_id"
},
"name": "author",
"comment": null,
"table": "article"
},
"reason": "table \"article\" does not exist",
"type": "object_relation"
},
{
"definition": "article",
"reason": "no such table/view exists in postgres : \"article\"",
"type": "table"
}
]
.. _metadata_drop_inconsistent_metadata:
drop_inconsistent_metadata
--------------------------
``drop_inconsistent_metadata`` can be used to purge all inconsistent objects from the metadata.
.. code-block:: http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type": "drop_inconsistent_metadata",
"args": {}
}

636
docs/graphql/core/api-reference/metadata-api/permission.rst Normal file
View File

@ -0,0 +1,636 @@
.. meta::
:description: Manage permissions with the Hasura metadata API
:keywords: hasura, docs, metadata API, API reference, permission
.. _metadata_api_permission:
Metadata API Reference: Permissions (v1.4 and above)
====================================================
.. contents:: Table of contents
:backlinks: none
:depth: 1
:local:
Introduction
------------
The permission layer is designed to restrict the operations that can be
performed by various users. Permissions can be defined on various operations
(insert/select/update/delete) at a role level granularity. By default, the ``admin``
role has unrestricted access to all operations.
.. admonition:: Variables in rules
All ``X-Hasura-*`` header values can be used in the permission rules. These
values can come with the request and can be validated using webhook or can be
sent with the JWT token.
.. _pg_create_insert_permission:
pg_create_insert_permission
---------------------------
An insert permission is used to enforce constraints on the data that is being
inserted.
Let's look at an example, a permission for the ``user`` role to insert into the
``article`` table. What is the constraint that we would like to enforce here? *A
user can only insert articles for themselves* .
.. code-block:: http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type" : "pg_create_insert_permission",
"args" : {
"table" : "article",
"source": "default",
"role" : "user",
"permission" : {
"check" : {
"author_id" : "X-HASURA-USER-ID"
},
"set":{
"id":"X-HASURA-USER-ID"
},
"columns":["name","author_id"]
}
}
}
This reads as follows - for the ``user`` role:
* For every row that is being inserted into the *article* table, allow insert only if the ``check`` passes i.e. that the ``author_id`` column value is the same as the value in the request header ``X-HASURA-USER-ID``".
* If the above ``check`` passes, then access for insert will be limited to columns ``name`` and ``author_id`` only.
* When this insert happens, the value of the column ``id`` will be automatically ``set`` to the value of the resolved session variable ``X-HASURA-USER-ID``.
The argument for ``check`` is a boolean expression which has the same syntax as the ``where`` clause in the ``select`` query, making it extremely expressive.
An example:
.. code-block:: http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type" : "pg_create_insert_permission",
"args" : {
"table" : "article",
"source": "default",
"role" : "user",
"permission" : {
"check" : {
"author_id" : "X-HASURA-USER-ID",
"$or" : [
{
"category" : "editorial",
"is_reviewed" : false
},
{
"category" : { "$neq" : "editorial"}
}
]
}
}
}
}
In the above definition, the row is allowed to be inserted if the ``author_id``
is the same as the request's user id and ``is_reviewed`` is ``false`` when the
``category`` is "editorial".
.. _pg_create_insert_permission_syntax:
Args syntax
^^^^^^^^^^^
.. list-table::
:header-rows: 1
* - Key
- Required
- Schema
- Description
* - table
- true
- :ref:`TableName`
- Name of the table
* - role
- true
- :ref:`RoleName`
- Role
* - permission
- true
- :ref:`InsertPermission`
- The permission definition
* - comment
- false
- text
- Comment
* - source
- false
- :ref:`SourceName <SourceName>`
- Name of the source database of the table (default: ``default``)
.. _pg_drop_insert_permission:
pg_drop_insert_permission
-------------------------
The ``pg_drop_insert_permission`` API is used to drop an existing insert permission for a role on a table.
An example:
.. code-block:: http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type" : "pg_drop_insert_permission",
"args" : {
"table" : "article",
"source": "default",
"role" : "user"
}
}
.. _pg_drop_insert_permission_syntax:
Args syntax
^^^^^^^^^^^
.. list-table::
:header-rows: 1
* - Key
- Required
- Schema
- Description
* - table
- true
- :ref:`TableName`
- Name of the table
* - role
- true
- :ref:`RoleName`
- Role
* - source
- false
- :ref:`SourceName <SourceName>`
- Name of the source database of the table (default: ``default``)
.. _pg_create_select_permission:
pg_create_select_permission
---------------------------
A select permission is used to restrict access to only the specified columns and rows.
Let's look at an example, a permission for the ``user`` role to select from the
``article`` table: all columns can be read, as well as the rows that have been published or
authored by the user themselves.
.. code-block:: http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type" : "pg_create_select_permission",
"args" : {
"table" : "article",
"role" : "user",
"source": "default",
"permission" : {
"columns" : "*",
"filter" : {
"$or" : [
{ "author_id" : "X-HASURA-USER-ID" },
{ "is_published" : true }
]
},
"limit": 10,
"allow_aggregations": true
}
}
}
This reads as follows - For the ``user`` role:
* Allow selecting rows where the ``check`` passes i.e. ``is_published`` is ``true`` or the ``author_id`` matches the value of the session variable ``X-HASURA-USER-ID``.
* Allow selecting all columns (because the ``columns`` key is set to ``*``).
* ``limit`` the numbers of rows returned by a query to the ``article`` table by the ``user`` role to a maximum of 10.
* Allow aggregate queries.
.. _pg_create_select_permission_syntax:
Args syntax
^^^^^^^^^^^
.. list-table::
:header-rows: 1
* - Key
- Required
- Schema
- Description
* - table
- true
- :ref:`TableName`
- Name of the table
* - role
- true
- :ref:`RoleName`
- Role
* - permission
- true
- :ref:`SelectPermission`
- The permission definition
* - comment
- false
- text
- Comment
* - source
- false
- :ref:`SourceName <SourceName>`
- Name of the source database of the table (default: ``default``)
.. _pg_drop_select_permission:
pg_drop_select_permission
-------------------------
The ``pg_drop_select_permission`` is used to drop an existing select permission for a role on a table.
An example:
.. code-block:: http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type" : "pg_drop_select_permission",
"args" : {
"table" : "article",
"role" : "user",
"source": "default"
}
}
.. _pg_drop_select_permission_syntax:
Args syntax
^^^^^^^^^^^
.. list-table::
:header-rows: 1
* - Key
- Required
- Schema
- Description
* - table
- true
- :ref:`TableName`
- Name of the table
* - role
- true
- :ref:`RoleName`
- Role
* - source
- false
- :ref:`SourceName <SourceName>`
- Name of the source database of the table (default: ``default``)
.. _pg_create_update_permission:
pg_create_update_permission
---------------------------
An update permission is used to restrict the columns and rows that can be
updated. Its structure is quite similar to the select permission.
An example:
.. code-block:: http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type" : "pg_create_update_permission",
"args" : {
"table" : "article",
"source": "default",
"role" : "user",
"permission" : {
"columns" : ["title", "content", "category"],
"filter" : {
"author_id" : "X-HASURA-USER-ID"
},
"check" : {
"content" : {
"_ne": ""
}
},
"set":{
"updated_at" : "NOW()"
}
}
}
}
This reads as follows - for the ``user`` role:
* Allow updating only those rows where the ``filter`` passes i.e. the value of the ``author_id`` column of a row matches the value of the session variable ``X-HASURA-USER-ID``.
* If the above ``filter`` passes for a given row, allow updating only the ``title``, ``content`` and ``category`` columns (*as specified in the* ``columns`` *key*).
* After the update happens, verify that the ``check`` condition holds for the updated row i.e. that the value in the ``content`` column is not empty.
* When this update happens, the value of the column ``updated_at`` will be automatically ``set`` to the current timestamp.
.. note::
It is important to deny updates to columns that will determine the row
ownership. In the above example, the ``author_id`` column determines the
ownership of a row in the ``article`` table. Columns such as this should
never be allowed to be updated.
.. _pg_create_update_permission_syntax:
Args syntax
^^^^^^^^^^^
.. list-table::
:header-rows: 1
* - Key
- Required
- Schema
- Description
* - table
- true
- :ref:`TableName`
- Name of the table
* - role
- true
- :ref:`RoleName`
- Role
* - permission
- true
- :ref:`UpdatePermission`
- The permission definition
* - comment
- false
- text
- Comment
* - source
- false
- :ref:`SourceName <SourceName>`
- Name of the source database of the table (default: ``default``)
.. _pg_drop_update_permission:
pg_drop_update_permission
-------------------------
The ``pg_drop_update_permission`` API is used to drop an existing update permission for a role on a table.
An example:
.. code-block:: http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type" : "pg_drop_update_permission",
"args" : {
"table" : "article",
"source": "default",
"role" : "user"
}
}
.. _pg_drop_update_permission_syntax:
Args syntax
^^^^^^^^^^^
.. list-table::
:header-rows: 1
* - Key
- Required
- Schema
- Description
* - table
- true
- :ref:`TableName`
- Name of the table
* - role
- true
- :ref:`RoleName`
- Role
* - source
- false
- :ref:`SourceName <SourceName>`
- Name of the source database of the table (default: ``default``)
.. _pg_create_delete_permission:
pg_create_delete_permission
---------------------------
A delete permission is used to restrict the rows that can be deleted.
An example:
.. code-block:: http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type" : "pg_create_delete_permission",
"args" : {
"table" : "article",
"source": "default",
"role" : "user",
"permission" : {
"filter" : {
"author_id" : "X-HASURA-USER-ID"
}
}
}
}
This reads as follows:
"``delete`` for the ``user`` role on the ``article`` table is allowed on rows where
``author_id`` is the same as the request header ``X-HASURA-USER-ID`` value."
.. _pg_create_delete_permission_syntax:
Args syntax
^^^^^^^^^^^
.. list-table::
:header-rows: 1
* - Key
- Required
- Schema
- Description
* - table
- true
- :ref:`TableName`
- Name of the table
* - role
- true
- :ref:`RoleName`
- Role
* - permission
- true
- :ref:`DeletePermission`
- The permission definition
* - comment
- false
- text
- Comment
* - source
- false
- :ref:`SourceName <SourceName>`
- Name of the source database of the table (default: ``default``)
.. _pg_drop_delete_permission:
pg_drop_delete_permission
-------------------------
The ``pg_drop_delete_permission`` API is used to drop an existing delete permission for a role on a table.
An example:
.. code-block:: http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type" : "pg_drop_delete_permission",
"args" : {
"table" : "article",
"role" : "user",
"source": "default"
}
}
.. _pg_drop_delete_permission_syntax:
Args syntax
^^^^^^^^^^^
.. list-table::
:header-rows: 1
* - Key
- Required
- Schema
- Description
* - table
- true
- :ref:`TableName`
- Name of the table
* - role
- true
- :ref:`RoleName`
- Role
* - source
- false
- :ref:`SourceName <SourceName>`
- Name of the source database of the table (default: ``default``)
.. _pg_set_permission_comment:
pg_set_permission_comment
-------------------------
``pg_set_permission_comment`` is used to set/update the comment on a permission.
Setting the comment to ``null`` removes it.
An example:
.. code-block:: http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
Authorization: Bearer <auth-token> # optional if cookie is set
X-Hasura-Role: admin
{
"type": "pg_set_permission_comment",
"args": {
"table": "article",
"source": "default",
"role": "user",
"type" : "update",
"comment" : "can only modify his/her own rows"
}
}
.. _pg_set_permission_comment_syntax:
Args syntax
^^^^^^^^^^^
.. list-table::
:header-rows: 1
* - Key
- Required
- Schema
- Description
* - table
- true
- :ref:`TableName`
- Name of the table
* - role
- true
- :ref:`RoleName`
- The role in the permission
* - type
- true
- permission type (one of select/update/delete/insert)
- The type of the permission
* - comment
- false
- Text
- Comment
* - source
- false
- :ref:`SourceName <SourceName>`
- Name of the source database of the table (default: ``default``)

277
docs/graphql/core/api-reference/metadata-api/query-collections.rst Normal file
View File

@ -0,0 +1,277 @@
.. meta::
:description: Manage query collections with the Hasura metadata API
:keywords: hasura, docs, metadata API, API reference, query collection
.. _metadata_api_query_collections:
Metadata API Reference: Query collections (v1.4 and above)
==========================================================
.. contents:: Table of contents
:backlinks: none
:depth: 1
:local:
Introduction
------------
Group queries using query collections.
Create/drop query collections and add/drop a query to a collection using the following query types.
.. _metadata_create_query_collection:
create_query_collection
-----------------------
``create_query_collection`` is used to define a collection.
.. code-block:: http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type" : "create_query_collection",
"args": {
"name": "my_collection",
"comment": "an optional comment",
"definition": {
"queries": [
{"name": "query_1", "query": "query { test {id name}}"}
]
}
}
}
.. _metadata_create_query_collection_syntax:
Args Syntax
^^^^^^^^^^^
.. list-table::
:header-rows: 1
* - Key
- Required
- Schema
- Description
* - name
- true
- :ref:`CollectionName`
- Name of the query collection
* - definition
- true
- :ref:`CollectionQuery` array
- List of queries
* - comment
- false
- text
- Optional comment
.. _metadata_drop_query_collection:
drop_query_collection
---------------------
``drop_query_collection`` is used to drop a collection
.. code-block:: http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type" : "drop_query_collection",
"args": {
"collection": "my_collection",
"cascade": false
}
}
.. _metadata_drop_query_collection_syntax:
Args syntax
^^^^^^^^^^^
.. list-table::
:header-rows: 1
* - Key
- Required
- Schema
- Description
* - collection
- true
- :ref:`CollectionName`
- Name of the query collection
* - cascade
- true
- boolean
- When set to ``true``, the collection (if present) is removed from the allowlist
.. _metadata_add_query_to_collection:
add_query_to_collection
-----------------------
``add_query_to_collection`` is used to add a query to a given collection.
.. code-block:: http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type" : "add_query_to_collection",
"args": {
"collection_name": "my_collection",
"query_name": "query_2",
"query": "query {test {name}}"
}
}
.. _metadata_add_query_to_collection_syntax:
Args Syntax
^^^^^^^^^^^
.. list-table::
:header-rows: 1
* - Key
- Required
- Schema
- Description
* - collection_name
- true
- :ref:`CollectionName`
- Name of the query collection
* - query_name
- true
- :ref:`QueryName`
- Name of the query
* - query
- true
- text
- The GraphQL query text
.. _metadata_drop_query_from_collection:
drop_query_from_collection
--------------------------
``drop_query_from_collection`` is used to remove a query from a given collection.
.. code-block:: http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type" : "drop_query_from_collection",
"args": {
"collection_name": "my_collection",
"query_name": "query_2"
}
}
.. _metadata_drop_query_from_collection_syntax:
Args Syntax
^^^^^^^^^^^
.. list-table::
:header-rows: 1
* - Key
- Required
- Schema
- Description
* - collection_name
- true
- :ref:`CollectionName`
- Name of the query collection
* - query_name
- true
- :ref:`QueryName`
- Name of the query
.. _metadata_add_collection_to_allowlist:
add_collection_to_allowlist
---------------------------
``add_collection_to_allowlist`` is used to add a collection to the allow-list.
.. code-block:: http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type" : "add_collection_to_allowlist",
"args": {
"collection": "my_collection"
}
}
.. _metadata_add_collection_to_allowlist_syntax:
Args Syntax
^^^^^^^^^^^
.. list-table::
:header-rows: 1
* - Key
- Required
- Schema
- Description
* - collection
- true
- :ref:`CollectionName`
- Name of a query collection to be added to the allow-list
.. _metadata_drop_collection_from_allowlist:
drop_collection_from_allowlist
------------------------------
``drop_collection_from_allowlist`` is used to remove a collection from the allow-list.
.. code-block:: http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type" : "drop_collection_from_allowlist",
"args": {
"collection": "my_collection_1"
}
}
.. _metadata_drop_collection_from_allowlist_syntax:
Args Syntax
^^^^^^^^^^^
.. list-table::
:header-rows: 1
* - Key
- Required
- Schema
- Description
* - collection
- true
- :ref:`CollectionName`
- Name of a query collection to be removed from the allow-list

436
docs/graphql/core/api-reference/metadata-api/relationship.rst Normal file
View File

@ -0,0 +1,436 @@
.. meta::
:description: Use relationships with the Hasura metadata API
:keywords: hasura, docs, metadata API, API reference, relationship
.. _metadata_api_relationship:
Metadata API Reference: Relationships (v1.4 and above)
======================================================
.. contents:: Table of contents
:backlinks: none
:depth: 1
:local:
Introduction
------------
When retrieving data from tables, it is very helpful if we can also
fetch the related data alongside the columns. This is where relationships come
in. They can be considered as pseudo columns for a table to access the related
data.
For a simple ``article/author`` schema, the following relationships exist:
- ``author`` of an ``article``
- ``articles`` of an ``author``
There are two kinds of relationships:
- one-to-one or ``object relationships`` (e.g. ``author``).
- one-to-many or ``array relationships`` (e.g. ``articles``).
.. _pg_create_object_relationship:
pg_create_object_relationship
-----------------------------
``create_object_relationship`` is used to create an object relationship on a
table. There cannot be an existing column or relationship with the same name.
There are 2 ways in which you can create an object relationship.
1. Using foreign key constraint on a column
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Create an ``object relationship`` ``author`` on ``article`` *table*, *using* the
*foreign_key_constraint_on* the ``author_id`` column:
.. code-block:: http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type": "pg_create_object_relationship",
"args": {
"table": "article",
"name": "author",
"source": "default",
"using": {
"foreign_key_constraint_on" : "author_id"
}
}
}
.. _pg_manual_obj_relationship:
2. Manual configuration
^^^^^^^^^^^^^^^^^^^^^^^
This is an advanced feature which is mostly used to define relationships on or
to views. We cannot rely on foreign key constraints as they are not valid to or
from views. So, when using manual configuration, we have to specify the remote
table and how columns in this table are mapped to the columns of the
remote table.
Let's say we have a view called ``article_detail`` which has three columns
``article_id`` and ``view_count`` and ``average_rating``. We can now define an
object relationship called ``article_detail`` on the ``article`` table as
follows:
.. code-block:: http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type": "pg_create_object_relationship",
"args": {
"table": "article",
"name": "article_detail",
"source": "default",
"using": {
"manual_configuration" : {
"remote_table" : "article_detail",
"column_mapping" : {
"id" : "article_id"
}
}
}
}
}
.. note::
It is easy to make mistakes while using ``manual_configuration``.
One simple check is to ensure that foreign key constraint semantics are valid
on the columns being used in ``column_mapping``. In the previous example, if
it was allowed, a foreign key constraint could have been defined on
``article`` table's ``id`` column to ``article_detail`` view's ``article_id``
column.
.. _pg_create_object_relationship_syntax:
Args syntax
^^^^^^^^^^^
.. list-table::
:header-rows: 1
* - Key
- Required
- Schema
- Description
* - table
- true
- :ref:`TableName <TableName>`
- Name of the table
* - name
- true
- :ref:`RelationshipName <RelationshipName>`
- Name of the new relationship
* - using
- true
- :ref:`ObjRelUsing`
- Use one of the available ways to define an object relationship
* - comment
- false
- text
- comment
* - source
- false
- :ref:`SourceName <SourceName>`
- Name of the source database of the table (default: ``default``)
.. _pg_create_array_relationship:
pg_create_array_relationship
----------------------------
``create_array_relationship`` is used to create an array relationship on a
table. There cannot be an existing column or relationship with the same name.
There are 2 ways in which you can create an array relationship.
1. Using foreign key constraint on a column
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Create an ``array relationship`` ``articles`` on ``author`` *table*, *using* the
*foreign_key_constraint_on* the ``author_id`` column of the ``article`` table:
.. code-block:: http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type": "pg_create_array_relationship",
"args": {
"table": "author",
"name": "articles",
"source": "default",
"using": {
"foreign_key_constraint_on" : {
"table" : "article",
"column" : "author_id"
}
}
}
}
2. Manual configuration
^^^^^^^^^^^^^^^^^^^^^^^
This is an advanced feature which is mostly used to define relationships on or
to views. We cannot rely on foreign key constraints as they are not valid to or
from views. So, when using manual configuration, we have to specify the remote
table and how columns in this table are mapped to the columns of the
remote table.
Let's say we have a view called ``article_detail`` which has four columns
``author_id``, ``article_id``, ``view_count`` and ``average_rating``. We can now define an
array relationship called ``article_details`` on the ``author`` table as
follows:
.. code-block:: http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type": "pg_create_array_relationship",
"args": {
"table": "author",
"name": "article_details",
"source": "default",
"using": {
"manual_configuration" : {
"remote_table" : "article_detail",
"column_mapping" : {
"id" : "author_id"
}
}
}
}
}
.. note::
It is easy to make mistakes while using ``manual_configuration``.
One simple check is to ensure that foreign key constraint semantics are valid
on the columns being used in ``column_mapping``. In the previous example, if
it was allowed, a foreign key constraint could have been defined on the
``author`` table's ``id`` column to ``article_detail`` view's ``author_id``
column.
.. _pg_create_array_relationship_syntax:
Args syntax
^^^^^^^^^^^
.. list-table::
:header-rows: 1
* - Key
- Required
- Schema
- Description
* - table
- true
- :ref:`TableName`
- Name of the table
* - name
- true
- :ref:`RelationshipName`
- Name of the new relationship
* - using
- true
- :ref:`ArrRelUsing`
- Use one of the available ways to define an array relationship
* - comment
- false
- text
- comment
* - source
- false
- :ref:`SourceName <SourceName>`
- Name of the source database of the table (default: ``default``)
.. _pg_drop_relationship:
pg_drop_relationship
--------------------
``pg_drop_relationship`` is used to drop a relationship (both object and array) on
a table. If there are other objects dependent on this relationship like
permissions and query templates, etc., the request will fail and report the dependencies
unless ``cascade`` is set to ``true``. If ``cascade`` is set to ``true``, the
dependent objects are also dropped.
An example:
.. code-block:: http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type": "pg_drop_relationship",
"args": {
"table": "article",
"source": "default",
"relationship": "article_detail"
}
}
.. _pg_drop_relationship_syntax:
Args syntax
^^^^^^^^^^^
.. list-table::
:header-rows: 1
* - Key
- Required
- Schema
- Description
* - table
- true
- :ref:`TableName`
- Name of the table
* - relationship
- true
- :ref:`RelationshipName`
- Name of the relationship that needs to be dropped
* - cascade
- false
- Boolean
- When set to ``true``, all the dependent items on this relationship are also dropped
* - source
- false
- :ref:`SourceName <SourceName>`
- Name of the source database of the table (default: ``default``)
.. note::
Be careful when using ``cascade``. First, try running the request without
``cascade`` or ``cascade`` set to ``false``.
.. _pg_set_relationship_comment:
pg_set_relationship_comment
---------------------------
``pg_set_relationship_comment`` is used to set/update the comment on a
relationship. Setting the comment to ``null`` removes it.
An example:
.. code-block:: http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type": "pg_set_relationship_comment",
"args": {
"table": "article",
"source": "default",
"name": "article_detail",
"comment" : "has extra information about an article like count etc."
}
}
.. _pg_set_relationship_comment_syntax:
Args syntax
^^^^^^^^^^^
.. list-table::
:header-rows: 1
* - Key
- Required
- Schema
- Description
* - table
- true
- :ref:`TableName`
- Name of the table
* - relationship
- true
- :ref:`RelationshipName`
- The relationship
* - comment
- false
- Text
- Comment
* - source
- false
- :ref:`SourceName <SourceName>`
- Name of the source database of the table (default: ``default``)
.. _pg_rename_relationship:
pg_rename_relationship
----------------------
``pg_rename_relationship`` is used to modify the name of an existing relationship.
An example:
.. code-block:: http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type": "pg_rename_relationship",
"args": {
"table": "article",
"name": "article_details",
"source": "default",
"new_name": "article_detail"
}
}
.. _pg_rename_relationship_syntax:
Args syntax
^^^^^^^^^^^
.. list-table::
:header-rows: 1
* - Key
- Required
- Schema
- Description
* - table
- true
- :ref:`TableName`
- Name of the table
* - name
- true
- :ref:`RelationshipName`
- The relationship
* - new_name
- true
- :ref:`RelationshipName`
- New relationship name
* - source
- false
- :ref:`SourceName <SourceName>`
- Name of the source database of the table (default: ``default``)

190
docs/graphql/core/api-reference/metadata-api/remote-relationships.rst Normal file
View File

@ -0,0 +1,190 @@
.. meta::
:description: Manage remote relationships with the Hasura metadata API
:keywords: hasura, docs, metadata API, API reference, remote joins, remote relationships
Metadata API Reference: Remote Relationships (v1.4 and above)
=============================================================
.. contents:: Table of contents
:backlinks: none
:depth: 1
:local:
Introduction
------------
Remote Relationships allow you to join tables with remote schemas.
.. _metadata_create_remote_relationship:
create_remote_relationship
--------------------------
``create_remote_relationship`` is used to create a new remote relationship with an existing remote schema.
.. code-block:: http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type":"create_remote_relationship",
"args":{
"name": "sample_remote_relationship",
"table": "users",
"hasura_fields": ["id"],
"remote_schema": "my-remote-schema",
"remote_field": {
"messages": {
"arguments": {
"id":"$id"
}
}
}
}
}
.. _metadata_create_remote_relationship_syntax:
Args syntax
^^^^^^^^^^^
.. list-table::
:header-rows: 1
* - Key
- Required
- Schema
- Description
* - name
- true
- :ref:`RemoteRelationshipName`
- Name of the remote relationship
* - table
- true
- :ref:`QualifiedTable <QualifiedTable>`
- Object with table name and schema
* - hasura_fields
- true
- [:ref:`PGColumn <PGColumn>`]
- Column(s) in the table that is used for joining with remote schema field. All join keys in ``remote_field`` must appear here.
* - remote_schema
- true
- :ref:`RemoteSchemaName <RemoteSchemaName>`
- Name of the remote schema to join with
* - remote_field
- true
- :ref:`RemoteField`
- The schema tree ending at the field in remote schema which needs to be joined with.
.. _metadata_update_remote_relationship:
update_remote_relationship
--------------------------
``update_remote_relationship`` is used to update an existing remote relationship.
.. code-block:: http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type": "update_remote_relationship",
"args": {
"name": "sample_remote_relationship",
"table": "users",
"hasura_fields": ["id"],
"remote_schema": "my-remote-schema",
"remote_field": {
"posts": {
"arguments": {
"id": "$id",
"likes": {
"lte":"1000"
}
}
}
}
}
}
.. _metadata_update_remote_relationship_syntax:
Args syntax
^^^^^^^^^^^
.. list-table::
:header-rows: 1
* - Key
- Required
- Schema
- Description
* - name
- true
- :ref:`RemoteRelationshipName`
- Name of the remote relationship
* - table
- true
- :ref:`QualifiedTable <QualifiedTable>`
- Object with table name and schema
* - hasura_fields
- true
- [:ref:`PGColumn <PGColumn>`]
- Column(s) in the table that is used for joining with remote schema field. All join keys in ``remote_field`` must appear here.
* - remote_schema
- true
- :ref:`RemoteSchemaName <RemoteSchemaName>`
- Name of the remote schema to join with
* - remote_field
- true
- :ref:`RemoteField`
- The schema tree ending at the field in remote schema which needs to be joined with.
.. _metadata_delete_remote_relationship:
delete_remote_relationship
--------------------------
``delete_remote_relationship`` is used to delete an existing remote relationship.
.. code-block:: http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type" : "delete_remote_relationship",
"args" : {
"table":{
"name":"users",
"schema":"public"
},
"name":"sample_remote_relationship"
}
}
.. _metadata_delete_remote_relationship_syntax:
Args syntax
^^^^^^^^^^^
.. list-table::
:header-rows: 1
* - Key
- Required
- Schema
- Description
* - table
- true
- :ref:`QualifiedTable <QualifiedTable>`
- Object with table name and schema
* - name
- true
- :ref:`RemoteRelationshipName`
- Name of the remote relationship

385
docs/graphql/core/api-reference/metadata-api/remote-schema-permissions.rst Normal file
View File

@ -0,0 +1,385 @@
.. meta::
:description: Manage remote schema permissions with the Hasura metadata API
:keywords: hasura, docs, metadata API, API reference, remote schema permissions, permission
.. _metadata_remote_schema_api_permission:
Metadata API Reference: Remote Schema Permissions (v1.4 and above)
==================================================================
.. contents:: Table of contents
:backlinks: none
:depth: 1
:local:
Introduction
------------
Remote schema permissions can be defined to:
1. Expose only certain parts of the remote schema to a role
2. Preset arguments with static values or session variables for any field.
By default, the ``admin`` role has unrestricted access to
the remote schema.
.. _metadata_add_remote_schema_permissions:
add_remote_schema_permissions
-----------------------------
This API takes the schema `(GraphQL IDL format) <http://spec.graphql.org/June2018/#sec-Type-System>`__
which should be a subset of the remote schema and the role for which this restricted schema is exposed.
The schema also accepts a custom ``@preset`` directive for setting argument presets.
Suppose the following is the schema document of the remote.
.. code-block:: graphql
type User {
user_id: Int
name: String
phone: String
userMessages(whered: MessageWhereInpObj, includes: IncludeInpObj): [Message]
}
interface Communication {
id: Int!
msg: String!
}
type Message implements Communication {
id: Int!
name: String!
msg: String!
errorMsg: String
}
input MessageWhereInpObj {
id: IntCompareObj
name: StringCompareObj
}
input IntCompareObj {
eq : Int
gt : Int
lt : Int
}
input StringCompareObj {
eq : String
}
input IncludeInpObj {
id: [Int]
name: [String]
}
type Query {
hello: String
messages(where: MessageWhereInpObj, includes: IncludeInpObj): [Message]
user(user_id: Int!): User
users(user_ids: [Int]!): [User]
message(id: Int!) : Message
}
type mutation_root {
insert_user: (name: String!, phone: String!): User
}
schema {
query: Query
mutation: mutation_root
}
Let's say we want to impose some restrictions on the ``user`` role:
1. Expose only the ``user_id``, ``name`` and the ``user_messages`` field in the ``User`` object.
2. Add a preset value to the ``user_id`` argument of the ``user`` field defined in the ``Query`` object.
We want the value of the preset to come from a session variable called ``x-hasura-user-id``.
3. Allow filtering of the messages only by ``name`` in the ``where`` argument
of the ``user_messages`` field.
4. Allow only the fields ``hello``, ``messages`` and the ``user`` top level node in the ``Query`` object.
5. Expose only the ``query_root`` and not allow mutations for the role.
The schema document, implementing the above restrictions will look like:
.. code-block:: graphql
type User {
user_id: Int
name: String
userMessages(where: MessageWhereInpObj, includes: IncludeInpObj): [Message]
}
interface Communication {
id: Int!
msg: String!
}
type Message implements Communication {
id: Int!
name: String!
msg: String!
errorMsg: String
}
input MessageWhereInpObj {
name: StringCompareObj
}
input IntCompareObj {
eq : Int
gt : Int
lt : Int
}
input StringCompareObj {
eq : String
}
input IncludeInpObj {
id: [Int]
name: [String]
}
type Query {
hello: String
messages(where: MessageWhereInpObj, includes: IncludeInpObj): [Message]
user(user_id: Int! @preset(value: "x-hasura-user-id")): User
}
schema {
query: Query
}
To add the remote schema permission for the role ``user``, the following
API should be called with the schema document.
.. code-block:: http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type" : "add_remote_schema_permissions",
"args" : {
"remote_schema" : "user_messages",
"role" : "user",
"definition" : {
"schema" : "type User { user_id: Int name: String userMessages(where: MessageWhereInpObj, includes: IncludeInpObj): [Message] } interface Communication { id: Int! msg: String! } type Message implements Communication { id: Int! name: String! msg: String! errorMsg: String } input MessageWhereInpObj { name: StringCompareObj } input IntCompareObj { eq : Int gt : Int lt : Int } input StringCompareObj { eq : String } input IncludeInpObj { id: [Int] name: [String] } type Query { hello: String messages(where: MessageWhereInpObj, includes: IncludeInpObj): [Message] user(user_id: Int! @preset(value: \"x-hasura-user-id\")): User } schema { query: Query }"
},
"comment":"remote schema permissions for role: user"
}
}
Argument Presets
^^^^^^^^^^^^^^^^
Argument presets can be used to automatically inject input values for fields
during execution. This way the field is executed with limited input values. Argument
presets are of two types:
1. Static Value
2. :ref:`Session Variable <dynamic_session_variables>`
A preset value can be added to an input value via the ``@preset`` directive.
.. code-block:: graphql
type User {
name String
id Int
}
type Query {
user(user_id: Int! @preset(value: 1))
}
When an input field has a preset defined, it will be removed from the exposed schema. So, following
the above example, the user won't be able to specify the ``user_id`` argument while querying
the ``user`` field and whenever the role executes the ``user`` field, the preset value will
get added before querying the remote schema.
A preset value can also reference a session variable. When the preset value has a
session variable, then its value is resolved and then added before querying the remote schema.
.. note::
By default, if the input value preset contains a :ref:`session variable value <dynamic_session_variables>`,
then its value will be resolved when the query is executed. To treat the session
variable value as a literal value (avoiding resolving of the session variable
value) can be done by specifying ``static`` as ``true`` while defining the preset.
For example:
.. code-block:: graphql
type Query {
hello(text: String! @preset(value: "x-hasura-hello", static: true))
}
In this case, ``"x-hasura-hello"`` will be the argument to the ``hello`` field
whenever it's queried.
Remote Relationship Permissions
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Permissions for remote relationships are derived from the role's remote schema permissions.
When permissions for a given remote relationship cannot be derived from the remote schema
permissions of a given role, that remote relationship will not be accessible to that role.
Cases when the remote relationship cannot be derived are:
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1. There are no remote schema permissions configured for the role for the remote join's remote schema.
2. The remote join field is not accessible to the role.
3. Any of the type (both output and input types) used in the remote join field is not accessible to the role.
When a remote field's argument contains a preset and the same argument
is used for creating a remote relationship, then the **remote presets will be
overridden by the remote join configuration**. For example:
Let's say we have a table called ``customer`` and we have a remote schema called
``payments`` and we have a remote relationship ``customer_transactions_history`` defined
which joins ``customer`` to ``transactions`` field of the ``payments`` field.
Suppose, the ``payments`` remote schema is defined in the following way:
.. code-block:: graphql
type Transaction {
customer_id Int!
amount Int!
time String!
merchant String!
}
type Query {
transactions(customer_id: String!, limit: Int): [Transaction]
}
And, the ``customer`` table is defined in the following manner.
.. code-block:: sql
CREATE TABLE customer (
id SERIAL PRIMARY KEY,
name TEXT NOT NULL
);
The remote relationship is defined to join the ``id`` field from the
``customer`` table to the ``customer_id`` argument of the ``transactions``
field.
We only allow the ``user`` role to access the ``amount`` and ``time`` fiels of
the ``Transaction`` object, and introduce a preset for the ``limit`` argument
of the ``transaction`` field, resulting in the following schema being presented.
.. code-block:: graphql
type Transaction {
amount Int!
time String!
}
type Query {
transactions(customer_id: String!, limit: Int @preset(value: 10)): [Transaction]
}
Two changes have been made for the ``user`` role:
1. The ``merchant`` and ``customer_id`` fields are not accessible in the ``Transaction`` object.
2. The ``limit`` argument has a preset of 10.
Now, consider the following query:
.. code-block:: graphql
query {
customer {
name
customer_transactions_history {
amount
time
}
}
}
The ``user`` role won't be able to provide the value for the ``limit`` argument in
the ``customer_transactions_history`` field because the ``limit`` has a preset set
and the value will be added by the graphql-engine before it queries the remote schema.
.. _metadata_add_remote_schema_permissions_syntax:
Args syntax
^^^^^^^^^^^
.. list-table::
:header-rows: 1
* - Key
- Required
- Schema
- Description
* - remote_schema
- true
- :ref:`RemoteSchemaName`
- Name of the remote schema
* - role
- true
- :ref:`RoleName`
- Role
* - definition
- true
- :ref:`RemoteSchemaPermission`
- The remote schema permission definition
* - comment
- false
- text
- Comment
.. _metadata_drop_remote_schema_permissions:
drop_remote_schema_permissions
------------------------------
The ``drop_remote_schema_permissions`` API is used to drop an existing delete permission for a role on a remote schema.
An example:
.. code-block:: http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type" : "drop_remote_schema_permissions",
"args" : {
"remote_schema" : "user_messages",
"role" : "user"
}
}
.. _metadata_drop_remote_schema_permissions_syntax:
Args syntax
^^^^^^^^^^^
.. list-table::
:header-rows: 1
* - Key
- Required
- Schema
- Description
* - table
- true
- :ref:`RemoteSchemaName`
- Name of the remote schema
* - role
- true
- :ref:`RoleName`
- Role

142
docs/graphql/core/api-reference/metadata-api/remote-schemas.rst Normal file
View File

@ -0,0 +1,142 @@
.. meta::
:description: Manage remote schemas with the Hasura metadata API
:keywords: hasura, docs, metadata API, API reference, remote schema
.. _metadata_api_remote_schemas:
Metadata API Reference: Remote schemas (v1.4 and above)
=======================================================
.. contents:: Table of contents
:backlinks: none
:depth: 1
:local:
Introduction
------------
Add/Remove a remote GraphQL server as remote schema in Hasura GraphQL engine.
.. _metadata_add_remote_schema:
add_remote_schema
-----------------
``add_remote_schema`` is used to add a remote GraphQL server as remote schema. GraphQL engine stitches it's schema with existing.
An example request as follows:
.. code-block:: http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type": "add_remote_schema",
"args": {
"name": "my remote schema",
"definition": {
"url": "https://remote-server.com/graphql",
"headers": [{"name": "X-Server-Request-From", "value": "Hasura"}],
"forward_client_headers": false,
"timeout_seconds": 60
},
"comment": "some optional comment"
}
}
.. _metadata_add_remote_schema_syntax:
.. list-table::
:header-rows: 1
* - Key
- Required
- Schema
- Description
* - name
- true
- :ref:`RemoteSchemaName`
- Name of the remote schema
* - definition
- true
- :ref:`RemoteSchemaDef`
- Definition for the remote schema
* - comment
- false
- Text
- comment
.. _metadata_remove_remote_schema:
remove_remote_schema
--------------------
``remove_remote_schema`` is used to delete a remote schema. GraphQL engine de-stitches it's schema.
An example request as follows:
.. code-block:: http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type": "remove_remote_schema",
"args": {
"name": "my remote schema"
}
}
.. _metadata_remove_remote_schema_syntax:
.. list-table::
:header-rows: 1
* - Key
- Required
- Schema
- Description
* - name
- true
- :ref:`RemoteSchemaName`
- Name of the remote schema
.. _metadata_reload_remote_schema:
reload_remote_schema
--------------------
``reload_remote_schema`` is used to refresh schema of the remote server. GraphQL engine refetches schema from server and stitches.
An example request as follows:
.. code-block:: http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type": "reload_remote_schema",
"args": {
"name": "my remote schema"
}
}
.. _metadata_reload_remote_schema_syntax:
.. list-table::
:header-rows: 1
* - Key
- Required
- Schema
- Description
* - name
- true
- :ref:`RemoteSchemaName`
- Name of the remote schema

116
docs/graphql/core/api-reference/metadata-api/restified-endpoints.rst Normal file
View File

@ -0,0 +1,116 @@
.. meta::
:description: Manage RESTified endpoints with the Hasura metadata API
:keywords: hasura, docs, metadata API, API reference, RESTified endpoints
.. _metadata_api_restified_endpoints:
Metadata API Reference: RESTified GraphQL Endpoints (v1.4 and above)
====================================================================
.. contents:: Table of contents
:backlinks: none
:depth: 1
:local:
Introduction
------------
Add/Remove a RESTified GraphQL endpoint to Hasura GraphQL engine.
.. _metadata_create_rest_endpoint:
create_rest_endpoint
--------------------
``create_rest_endpoint`` is used to associate a URL template with a query.
An example request as follows:
.. code-block:: http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type": "create_rest_endpoint",
"args": {
"name": "example-name",
"url": "example",
"methods": ["POST","PUT","PATCH"],
"definition": {
"query": {
"query_name": "example_mutation",
"collection_name": "test_collection"
}
},
"comment": "some optional comment"
}
}
.. _metadata_create_rest_endpoint_syntax:
.. list-table::
:header-rows: 1
* - Key
- Required
- Schema
- Description
* - name
- true
- Text
- A unique identifier for the endpoint
* - url
- true
- :ref:`EndpointUrl`
- URL of the REST endpoint
* - methods
- true
- :ref:`EndpointMethods`
- Non-Empty case sensitive list of supported HTTP Methods
* - definition
- true
- :ref:`EndpointDef`
- Definition for the REST endpoint
* - comment
- false
- Text
- comment
.. _metadata_drop_rest_endpoint:
drop_rest_endpoint
------------------
``drop_rest_endpoint`` is used to delete an existing RESTified GraphQL Endpoint.
An example request as follows:
.. code-block:: http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type": "drop_rest_endpoint",
"args": {
"url": "my simple rest endpoint"
}
}
.. _metadata_drop_rest_endpoint_syntax:
.. list-table::
:header-rows: 1
* - Key
- Required
- Schema
- Description
* - url
- true
- :ref:`EndpointUrl`
- URL of the RESTified endpoint

201
docs/graphql/core/api-reference/metadata-api/scheduled-triggers.rst Normal file
View File

@ -0,0 +1,201 @@
.. meta::
:description: Manage scheduled triggers with the Hasura metadata API
:keywords: hasura, docs, metadata API, API reference, scheduled trigger
Metadata API Reference: Scheduled Triggers (v1.4 and above)
===========================================================
.. contents:: Table of contents
:backlinks: none
:depth: 1
:local:
Introduction
------------
Scheduled triggers are used to invoke webhooks based on a timestamp or cron.
.. _metadata_create_cron_trigger:
create_cron_trigger
-------------------
``create_cron_trigger`` is used to create a new cron trigger.
.. code-block:: http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type" : "create_cron_trigger",
"args" : {
"name": "sample_cron",
"webhook": "https://httpbin.org/post",
"schedule": "* * * * *",
"payload": {
"key1": "value1",
"key2": "value2"
},
"include_in_metadata":false,
"comment":"sample_cron commment"
}
}
.. _metadata_create_cron_trigger_syntax:
Args syntax
^^^^^^^^^^^
.. list-table::
:header-rows: 1
* - Key
- Required
- Schema
- Description
* - name
- true
- :ref:`TriggerName <TriggerName>`
- Name of the cron trigger
* - webhook
- true
- :ref:`WebhookURL <WebhookURL>`
- URL of the webhook
* - schedule
- true
- Cron Expression
- Cron expression at which the trigger should be invoked.
* - payload
- false
- JSON
- Any JSON payload which will be sent when the webhook is invoked.
* - headers
- false
- [ :ref:`HeaderFromValue <HeaderFromValue>` | :ref:`HeaderFromEnv <HeaderFromEnv>` ]
- List of headers to be sent with the webhook
* - retry_conf
- false
- :ref:`RetryConfST`
- Retry configuration if scheduled invocation delivery fails
* - include_in_metadata
- true
- Boolean
- Flag to indicate whether a trigger should be included in the metadata. When a cron
trigger is included in the metadata, the user will be able to export it when the
metadata of the graphql-engine is exported.
* - comment
- false
- Text
- Custom comment.
* - replace
- false
- Bool
- When replace is set to ``true``, the cron trigger will be updated(if exists) and when it's ``false`` or the
field is omitted, then a new cron trigger will be created.
.. _metadata_delete_cron_trigger:
delete_cron_trigger
-------------------
``delete_cron_trigger`` is used to delete an existing cron trigger. The scheduled events associated with the cron trigger will also be deleted.
.. code-block:: http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type" : "delete_cron_trigger",
"args" : {
"name": "sample_cron"
}
}
.. _metadata_delete_cron_trigger_syntax:
Args syntax
^^^^^^^^^^^
.. list-table::
:header-rows: 1
* - Key
- Required
- Schema
- Description
* - name
- true
- :ref:`TriggerName <TriggerName>`
- Name of the cron trigger
.. _metadata_create_scheduled_event:
create_scheduled_event
----------------------
``create_scheduled_event`` is used to create a scheduled event.
.. code-block:: http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type" : "create_scheduled_event",
"args" : {
"webhook": "https://httpbin.org/post",
"schedule_at": "2019-09-09T22:00:00Z",
"payload": {
"key1": "value1",
"key2": "value2"
},
"headers" : [{
"name":"header-key",
"value":"header-value"
}],
"comment":"sample scheduled event comment"
}
}
.. _metadata_create_scheduled_event_syntax:
Args syntax
^^^^^^^^^^^
.. list-table::
:header-rows: 1
* - Key
- Required
- Schema
- Description
* - webhook
- true
- :ref:`WebhookURL <WebhookURL>`
- URL of the webhook
* - schedule_at
- true
- Timestamp (ISO8601 format)
- The time at which the invocation should be invoked.
* - payload
- false
- JSON
- Any JSON payload which will be sent when the webhook is invoked.
* - headers
- false
- [ :ref:`HeaderFromValue <HeaderFromValue>` | :ref:`HeaderFromEnv <HeaderFromEnv>` ]
- List of headers to be sent with the webhook
* - retry_conf
- false
- :ref:`RetryConfST`
- Retry configuration if scheduled event delivery fails
* - comment
- false
- Text
- Custom comment.

113
docs/graphql/core/api-reference/metadata-api/source.rst Normal file
View File

@ -0,0 +1,113 @@
.. meta::
:description: Manage databases with the Hasura metadata API
:keywords: hasura, docs, metadata API, API reference, database, source
.. _metadata_api_sources:
Metadata API Reference: Databases (v1.4 and above)
==================================================
.. contents:: Table of contents
:backlinks: none
:depth: 1
:local:
Introduction
------------
Add/remove databases in Hasura GraphQL engine.
.. _pg_add_source:
pg_add_source
-------------
``pg_add_source`` is used to connect a Postgres database to Hasura.
Add a database with name ``pg1``:
.. code-block:: http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type": "pg_add_source",
"args": {
"name": "pg1",
"configuration": {
"connection_info": {
"database_url": "<db-connection-string>",
"pool_settings": {
"max_connections": 50,
"idle_timeout": 180,
"retries": 1
}
}
}
}
}
.. _pg_add_source_syntax:
Args syntax
^^^^^^^^^^^
.. list-table::
:header-rows: 1
* - Key
- Required
- Schema
- Description
* - name
- true
- :ref:`SourceName <SourceName>`
- Name of the Postgres database
* - configuration
- true
- :ref:`PGConfiguration <PGConfiguration>`
- Database connection configuration
.. TODO: add pgconfiguration spec
.. _pg_drop_source:
pg_drop_source
--------------
``pg_drop_source`` is used to remove a Postgres database from Hasura.
Remove a database with name ``pg1``:
.. code-block:: http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type": "pg_drop_source",
"args": {
"name": "pg1"
}
}
.. _pg_drop_source_syntax:
Args syntax
^^^^^^^^^^^
.. list-table::
:header-rows: 1
* - Key
- Required
- Schema
- Description
* - name
- true
- :ref:`SourceName <SourceName>`
- Name of the Postgres database

300
docs/graphql/core/api-reference/metadata-api/table-view.rst Normal file
View File

@ -0,0 +1,300 @@
.. meta::
:description: Manage tables and views with the Hasura metadata API
:keywords: hasura, docs, metadata API, API reference, table, view
.. _metadata_api_tables_views:
Metadata API Reference: Tables/Views (v1.4 and above)
=====================================================
.. contents:: Table of contents
:backlinks: none
:depth: 1
:local:
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.
.. _pg_track_table:
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``:
.. code-block:: http
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.
.. code-block:: http
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 <https://spec.graphql.org/June2018/#sec-Names>`__ in order to be able to track it.
.. _pg_track_table_syntax:
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
* - source
- false
- :ref:`SourceName <SourceName>`
- Name of the source database of the table (default: ``default``)
.. _pg_untrack_table:
pg_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/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
}
}
.. _pg_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)
* - source
- false
- :ref:`SourceName <SourceName>`
- Name of the source database of the table (default: ``default``)
.. _pg_set_table_is_enum:
pg_set_table_is_enum
--------------------
``pg_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/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
}
}
.. _pg_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>`.
* - source
- false
- :ref:`SourceName <SourceName>`
- Name of the source database of the table (default: ``default``)
.. _pg_set_table_customization:
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.
:ref:`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``:
.. code-block:: http
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"
}
}
}
}
.. _pg_set_table_customization_syntax:
Args syntax
^^^^^^^^^^^
.. list-table::
:header-rows: 1
* - Key
- Required
- Schema
- Description
* - table
- true
- :ref:`TableName <TableName>`
- Name of the table
* - configuration
- false
- :ref:`TableConfig <table_config>`
- Configuration for the table/view
* - source
- false
- :ref:`SourceName <SourceName>`
- Name of the source database of the table (default: ``default``)

18
docs/graphql/core/api-reference/schema-api/index.rst
View File

@ -47,9 +47,9 @@ Request body
.. parsed-literal::
Query_
:ref:`Query <schema_query>`
.. _Query_:
.. _schema_query:
Query
*****
@ -88,12 +88,12 @@ The various types of queries are listed in the following table:
- Synopsis
* - **bulk**
- :ref:`Query <Query>` array
- :ref:`Query <schema_query>` array
- 1
- Execute multiple operations in a single query
* - :ref:`run_sql`
- :ref:`run_sql_args <run_sql_syntax>`
* - :ref:`schema_run_sql`
- :ref:`run_sql_args <schema_run_sql_syntax>`
- 1
- Run SQL directly on Postgres
@ -155,4 +155,10 @@ to explicitly state that this API is not enabled i.e. remove it from the list of
--enabled-apis="graphql"
HASURA_GRAPHQL_ENABLED_APIS="graphql"
See :ref:`server_flag_reference` for info on setting the above flag/env var.
See :ref:`server_flag_reference` for info on setting the above flag/env var.
.. toctree::
:maxdepth: 1
:hidden:
Run SQL <run-sql>

319
docs/graphql/core/api-reference/schema-api/run-sql.rst Normal file
View File

@ -0,0 +1,319 @@
.. meta::
:description: Execute SQL with the Hasura schema/metadata API
:keywords: hasura, docs, schema/metadata API, API reference, run_sql
.. _schema_api_run_sql:
Schema API Reference: Run SQL
=============================
.. contents:: Table of contents
:backlinks: none
:depth: 2
:local:
.. _schema_run_sql:
run_sql
-------
``run_sql`` can be used to run arbitrary SQL statements.
Multiple SQL statements can be separated by a ``;``, however, only the result of the last SQL statement will be
returned.
.. admonition:: Admin-only
This is an admin-only request, i.e. the request can only be executed with ``X-Hasura-Role: admin``. This can be set by passing
``X-Hasura-Admin-Secret`` or by setting the right role in webhook/JWT
authorization mode.
This is deliberate as it is hard to enforce any sort of permissions on arbitrary SQL. If
you find yourself in the need of using ``run_sql`` to run custom DML requests,
consider creating a view. You can now define permissions on that particular view
for various roles.
Use cases
^^^^^^^^^
1. To execute DDL operations that are not supported by the console (e.g. managing indexes).
2. Run custom DML requests from backend microservices instead of installing libraries to speak to Postgres.
An example:
.. code-block:: http
POST /v2/query HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type": "run_sql",
"args": {
"source": "default",
"sql": "CREATE UNIQUE INDEX ON films (title);"
}
}
While ``run_sql`` lets you run any SQL, it tries to ensure that the Hasura GraphQL engine's
state (relationships, permissions etc.) is consistent i.e. you
cannot drop a column on which any metadata is dependent on (say a permission or
a relationship). The effects, however, can be cascaded.
Example: If we were to drop the 'bio' column from the author table (let's say
the column is used in some permission), you would see an error.
.. code-block:: http
POST /v2/query HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type": "run_sql",
"args": {
"source": "default",
"sql": "ALTER TABLE author DROP COLUMN name"
}
}
.. code-block:: http
HTTP/1.1 400 BAD REQUEST
Content-Type: application/json
{
"path": "$.args",
"error": "cannot drop due to the following dependent objects : permission author.user.select"
}
We can however, cascade these changes.
.. code-block:: http
:emphasize-lines: 9
POST /v2/query HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type": "run_sql",
"args": {
"source": "default",
"sql": "ALTER TABLE author DROP COLUMN bio",
"cascade" : true
}
}
.. code-block:: http
HTTP/1.1 200 OK
Content-Type: application/json
{
"result_type": "CommandOk"
}
With the above request, the dependent permission is also dropped.
Example: If we were to drop a foreign key constraint from the article table
(let's say the column involved in the foreign key is used to define a relationship),
you would see an error.
.. code-block:: http
POST /v2/query HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type": "run_sql",
"args": {
"source": "default",
"sql": "ALTER TABLE article DROP CONSTRAINT article_author_id_fkey"
}
}
.. code-block:: http
HTTP/1.1 400 BAD REQUEST
Content-Type: application/json
{
"path": "$.args",
"error": "cannot drop due to the following dependent objects : constraint article.article_author_id_fkey"
}
We can however, cascade these changes.
.. code-block:: http
:emphasize-lines: 9
POST /v2/query HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type": "run_sql",
"args": {
"source": "default",
"sql": "ALTER TABLE article DROP CONSTRAINT article_author_id_fkey",
"cascade" : true
}
}
.. code-block:: http
HTTP/1.1 200 OK
Content-Type: application/json
{
"result_type": "CommandOk"
}
With the above request, the dependent permission is also dropped.
In general, the SQL operations that will affect Hasura metadata are:
1. Dropping columns
2. Dropping tables
3. Dropping foreign keys
4. Altering types of columns
5. Dropping SQL functions
6. Overloading SQL functions
In case of 1, 2 and 3 the dependent objects (if any) can be dropped using ``cascade``.
However, when altering type of columns, if any objects are affected, the change
cannot be cascaded. So, those dependent objects have to be manually dropped before
executing the SQL statement. Dropping SQL functions will cascade the functions in
metadata even without using ``cascade`` since no other objects depend on them.
Overloading tracked SQL functions is not allowed.
Set ``check_metadata_consistency`` field to ``false`` to force the server to not consider metadata dependencies.
.. _schema_run_sql_syntax:
Args syntax
^^^^^^^^^^^
.. list-table::
:header-rows: 1
* - Key
- Required
- Schema
- Description
* - sql
- true
- String
- The sql to be executed
* - source
- false
- String
- The database on which the sql is to be executed (default: 'default' database)
* - cascade
- false
- Boolean
- When set to ``true``, the effect (if possible) is cascaded to any hasuradb dependent objects (relationships, permissions, templates).
* - check_metadata_consistency
- false
- Boolean
- When set to ``false``, the sql is executed without checking metadata dependencies.
* - read_only
- false
- Boolean
- When set to ``true``, the request will be run in ``READ ONLY`` transaction access mode which means only ``select`` queries will be successful. This flag ensures that the GraphQL schema is not modified and is hence highly performant.
Response
^^^^^^^^
The response is a JSON Object with the following structure.
.. list-table::
:header-rows: 1
* - Key
- Always present
- Schema
- Description
* - result_type
- true
- String
- One of "CommandOk" or "TuplesOk"
* - result
- false
- ``[[Text]]`` (An array of rows, each row an array of columns)
- This is present only when the ``result_type`` is "TuplesOk"
.. note::
The first row in the ``result`` (when present) will be the names of the columns.
Some examples
^^^^^^^^^^^^^
An SQL query returning results.
.. code-block:: http
POST /v2/query HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type": "run_sql",
"args": {
"source": "default",
"sql": "select user_id, first_name from author limit 2;"
}
}
.. code-block:: http
HTTP/1.1 200 OK
Content-Type: application/json
{
"result_type": "TuplesOk",
"result": [
[
"user_id",
"first_name"
],
[
"1",
"andre"
],
[
"2",
"angela"
]
]
}
An SQL query to create a table:
.. code-block:: http
POST /v2/query HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type":"run_sql",
"args": {
"source": "default",
"sql": "create table item ( id serial, name text, category text, primary key (id))",
"check_metadata_consistency": false
}
}
.. code-block:: http
HTTP/1.1 200 OK
Content-Type: application/json
{
"result_type": "CommandOk",
"result": null
}

76
docs/graphql/core/api-reference/schema-metadata-api/actions.rst
View File

@ -75,85 +75,13 @@ Args syntax
- Name of the action
* - definition
- true
- ActionDefinition_
- :ref:`ActionDefinition`
- Definition of the action
* - comment
- false
- text
- comment
.. _ActionDefinition:
ActionDefinition
&&&&&&&&&&&&&&&&
.. list-table::
:header-rows: 1
* - Key
- Required
- Schema
- Description
* - arguments
- false
- Array of InputArgument_
- Input arguments
* - output_type
- true
- :ref:`GraphQLType <GraphQLType>`
- The output type of the action. Only object and list of objects are allowed.
* - kind
- false
- [ ``synchronous`` | ``asynchronous`` ]
- The kind of the mutation action (default: ``synchronous``). If the type of
the action is ``query`` then the ``kind`` field should be omitted.
* - headers
- false
- [ :ref:`HeaderFromValue <HeaderFromValue>` | :ref:`HeaderFromEnv <HeaderFromEnv>` ]
- List of defined headers to be sent to the handler
* - forward_client_headers
- false
- boolean
- If set to ``true`` the client headers are forwarded to the webhook handler (default: ``false``)
* - handler
- true
- :ref:`WebhookURL <WebhookURL>`
- The action's webhook URL
* - type
- false
- [ ``mutation`` | ``query`` ]
- The type of the action (default: ``mutation``)
* - timeout
- false
- Integer
- Number of seconds to wait for response before timing out. Default: 30
.. _InputArgument:
InputArgument
&&&&&&&&&&&&&
.. list-table::
:header-rows: 1
* - Key
- Required
- Schema
- Description
* - name
- true
- text
- Name of the argument
* - type
- true
- :ref:`GraphQLType <GraphQLType>`
- Type of the argument
.. note::
The ``GraphQL Types`` used in creating an action must be defined before via :ref:`Custom Types <api_custom_types>`
.. _drop_action:
drop_action
@ -255,7 +183,7 @@ Args syntax
- Name of the action
* - definition
- true
- ActionDefinition_
- :ref:`ActionDefinition`
- Definition of the action to be replaced
.. _create_action_permission:

30
docs/graphql/core/api-reference/schema-metadata-api/computed-field.rst
View File

@ -80,41 +80,13 @@ Args syntax
- Name of the new computed field
* - definition
- true
- ComputedFieldDefinition_
- :ref:`ComputedFieldDefinition`
- The computed field definition
* - comment
- false
- text
- comment
.. _ComputedFieldDefinition:
ComputedFieldDefinition
&&&&&&&&&&&&&&&&&&&&&&&
.. list-table::
:header-rows: 1
* - Key
- Required
- Schema
- Description
* - function
- true
- :ref:`FunctionName <FunctionName>`
- The SQL function
* - table_argument
- false
- String
- Name of the argument which accepts a table row type. If omitted, the first
argument is considered a table argument
* - session_argument
- false
- String
- Name of the argument which accepts the Hasura session object as
a JSON/JSONB value. If omitted, the Hasura session object is
not passed to the function
.. _drop_computed_field:
drop_computed_field

36
docs/graphql/core/api-reference/schema-metadata-api/custom-functions.rst
View File

@ -25,7 +25,7 @@ track_function
--------------
``track_function`` is used to add a custom SQL function to the ``query`` root field of the GraphQL schema.
Also refer a note :ref:`here <note>`.
Also refer a note :ref:`here <function_req_note>`.
Add an SQL function ``search_articles``:
@ -51,7 +51,7 @@ track_function v2
Version 2 of ``track_function`` is used to add a custom SQL function to the GraphQL schema.
It supports more configuration options than v1, and also supports tracking
functions as mutations.
Also refer a note :ref:`here <note>`.
Also refer a note :ref:`here <function_req_note>`.
Track an SQL function called ``search_articles`` with a Hasura session argument:
@ -138,38 +138,6 @@ Args syntax
- :ref:`Function Configuration <function_configuration>`
- Configuration for the SQL function
.. _function_configuration:
Function Configuration
^^^^^^^^^^^^^^^^^^^^^^
.. list-table::
:header-rows: 1
* - Key
- Required
- Schema
- Description
* - session_argument
- false
- `String`
- Function argument which accepts session info JSON
* - exposed_as
- false
- `String`
- In which part of the schema should we expose this function? Either "mutation" or "query".
.. _note:
.. note::
Currently, only functions which satisfy the following constraints can be exposed over the GraphQL API
(*terminology from* `Postgres docs <https://www.postgresql.org/docs/current/sql-createfunction.html>`__):
- **Function behaviour**: ``STABLE`` or ``IMMUTABLE`` functions may *only* be exposed as queries (i.e. with ``exposed_as: query``)
- **Return type**: MUST be ``SETOF <table-name>`` OR ``<table_name>`` where ``<table-name>`` is already tracked
- **Argument modes**: ONLY ``IN``
.. _untrack_function:
untrack_function

223
docs/graphql/core/api-reference/schema-metadata-api/custom-types.rst
View File

@ -90,230 +90,17 @@ Args syntax
- Description
* - input_objects
- false
- Array of InputObjectType_
- Array of :ref:`InputObjectType`
- Set of GraphQL ``Input Object``
* - objects
- false
- Array of ObjectType_
- Array of :ref:`ObjectType`
- Set of GraphQL ``Object``
* - scalars
- false
- Array of ScalarType_
- Array of :ref:`ScalarType`
- Set of GraphQL ``Scalar``
* - enums
- false
- Array of EnumType_
- Set of GraphQL ``Enum``
.. _InputObjectType:
InputObjectType
&&&&&&&&&&&&&&&
A simple JSON object to define `GraphQL Input Object <https://spec.graphql.org/June2018/#sec-Input-Objects>`__
.. list-table::
:header-rows: 1
* - Key
- Required
- Schema
- Description
* - name
- true
- :ref:`GraphQLName`
- Name of the Input object type
* - description
- false
- String
- Description of the Input object type
* - fields
- true
- Array of InputObjectField_
- Fields of the Input object type
.. _InputObjectField:
InputObjectField
****************
.. list-table::
:header-rows: 1
* - Key
- Required
- Schema
- Description
* - name
- true
- :ref:`GraphQLName`
- Name of the Input object field
* - description
- false
- String
- Description of the Input object field
* - type
- true
- :ref:`GraphQLType <GraphQLType>`
- GraphQL ype of the input object field
.. _ObjectType:
ObjectType
&&&&&&&&&&
A simple JSON object to define `GraphQL Object <https://spec.graphql.org/June2018/#sec-Objects>`__
.. list-table::
:header-rows: 1
* - Key
- Required
- Schema
- Description
* - name
- true
- :ref:`GraphQLName`
- Name of the Object type
* - description
- false
- String
- Description of the Object type
* - fields
- true
- Array of ObjectField_
- Fields of the Object type
* - relationships
- false
- Array of ObjectRelationship_
- Relationships of the Object type to tables
.. _ObjectField:
ObjectField
***********
.. list-table::
:header-rows: 1
* - Key
- Required
- Schema
- Description
* - name
- true
- :ref:`GraphQLName`
- Name of the Input object field
* - description
- false
- String
- Description of the Input object field
* - type
- true
- :ref:`GraphQLType <GraphQLType>`
- GraphQL type of the input object field
.. _ObjectRelationship:
ObjectRelationship
******************
.. list-table::
:header-rows: 1
* - Key
- Required
- Schema
- Description
* - name
- true
- :ref:`RelationshipName`
- Name of the relationship, shouldn't conflict with existing field names
* - type
- true
- [ ``object`` | ``array`` ]
- Type of the relationship
* - remote_table
- true
- :ref:`TableName`
- The table to which relationship is defined
* - field_mapping
- true
- Object (ObjectField_ name : Remote table's :ref:`PGColumn`)
- Mapping of fields of object type to columns of remote table
.. _ScalarType:
ScalarType
&&&&&&&&&&
A simple JSON object to define `GraphQL Scalar <https://spec.graphql.org/June2018/#sec-Scalars>`__
.. list-table::
:header-rows: 1
* - Key
- Required
- Schema
- Description
* - name
- true
- :ref:`GraphQLName`
- Name of the Scalar type
* - description
- false
- String
- Description of the Scalar type
.. _EnumType:
EnumType
&&&&&&&&
A simple JSON object to define `GraphQL Enum <https://spec.graphql.org/June2018/#sec-Enums>`__
.. list-table::
:header-rows: 1
* - Key
- Required
- Schema
- Description
* - name
- true
- :ref:`GraphQLName`
- Name of the Enum type
* - description
- false
- String
- Description of the Enum type
* - values
- true
- Array of EnumValue_
- Values of the Enum type
.. _EnumValue:
EnumValue
*********
.. list-table::
:header-rows: 1
* - Key
- Required
- Schema
- Description
* - value
- true
- :ref:`GraphQLName`
- Value of the Enum type
* - description
- false
- String
- Description of the value
* - is_deprecated
- false
- Boolean
- If set to ``true``, the enum value is marked as deprecated
- Array of :ref:`EnumType`
- Set of GraphQL ``Enum``

75
docs/graphql/core/api-reference/schema-metadata-api/event-triggers.rst
View File

@ -94,15 +94,15 @@ Args syntax
- Environment variable name of webhook (must exist at boot time) (*)
* - insert
- false
- OperationSpec_
- :ref:`OperationSpec`
- Specification for insert operation
* - update
- false
- OperationSpec_
- :ref:`OperationSpec`
- Specification for update operation
* - delete
- false
- OperationSpec_
- :ref:`OperationSpec`
- Specification for delete operation
* - headers
- false
@ -110,7 +110,7 @@ Args syntax
- List of headers to be sent with the webhook
* - retry_conf
- false
- RetryConf_
- :ref:`RetryConf`
- Retry configuration if event delivery fails
* - replace
- false
@ -241,69 +241,4 @@ Args syntax
* - payload
- true
- JSON
- Some JSON payload to send to trigger
.. _TriggerName:
TriggerName
&&&&&&&&&&&
.. parsed-literal::
String
.. _OperationSpec:
OperationSpec
&&&&&&&&&&&&&
.. list-table::
:header-rows: 1
* - Key
- Required
- Schema
- Description
* - columns
- true
- EventTriggerColumns_
- List of columns or "*" to listen to changes
* - payload
- false
- EventTriggerColumns_
- List of columns or "*" to send as part of webhook payload
.. _EventTriggerColumns:
EventTriggerColumns
&&&&&&&&&&&&&&&&&&&
.. parsed-literal::
:class: haskell-pre
"*" | [:ref:`PGColumn`]
.. _RetryConf:
RetryConf
&&&&&&&&&
.. list-table::
:header-rows: 1
* - Key
- required
- Schema
- Description
* - num_retries
- false
- Integer
- Number of times to retry delivery. Default: 0
* - interval_sec
- false
- Integer
- Number of seconds to wait between each retry. Default: 10
* - timeout_sec
- false
- Integer
- Number of seconds to wait for response before timing out. Default: 60
- Some JSON payload to send to trigger

17
docs/graphql/core/api-reference/schema-metadata-api/index.rst
View File

@ -44,9 +44,9 @@ Request body
.. parsed-literal::
Query_
:ref:`Query <api_query>`
.. _Query:
.. _api_query:
Query
*****
@ -85,7 +85,7 @@ The various types of queries are listed in the following table:
- Synopsis
* - **bulk**
- :ref:`Query <Query>` array
- :ref:`Query <api_query>` array
- 1
- Execute multiple operations in a single query
@ -119,6 +119,11 @@ The various types of queries are listed in the following table:
- 1
- Remove a table/view
* - :ref:`set_table_is_enum`
- :ref:`set_table_is_enum_args <set_table_is_enum_syntax>`
- 1
- Set a tracked table as an enum table
* - :ref:`track_function`
- :ref:`FunctionName <FunctionName>`
- 1
@ -289,14 +294,13 @@ The various types of queries are listed in the following table:
- 1
- Delete an existing remote relationship
* - :ref:`export_metadata`
- :ref:`Empty Object`
- 1
- Export the current metadata
* - :ref:`replace_metadata_v1`
- :ref:`replace_metadata_args <replace_metadata_syntax_v1>`
* - :ref:`replace_metadata`
- :ref:`replace_metadata_args <replace_metadata_syntax>`
- 1
- Import and replace existing metadata
@ -495,4 +499,3 @@ See :ref:`server_flag_reference` for info on setting the above flag/env var.
Custom Types <custom-types>
Actions <actions>
Manage Metadata <manage-metadata>
Common syntax definitions <syntax-defs>

2
docs/graphql/core/api-reference/schema-metadata-api/manage-metadata.rst
View File

@ -62,7 +62,7 @@ metadata will be replaced with the new one.
"args": <replace-metadata-args>
}
.. _replace_metadata_syntax_v1:
.. _replace_metadata_syntax:
Args syntax
^^^^^^^^^^^

119
docs/graphql/core/api-reference/schema-metadata-api/permission.rst
View File

@ -128,44 +128,13 @@ Args syntax
- Role
* - permission
- true
- InsertPermission_
- :ref:`InsertPermission`
- The permission definition
* - comment
- false
- text
- Comment
.. _InsertPermission:
InsertPermission
&&&&&&&&&&&&&&&&
.. list-table::
:header-rows: 1
* - Key
- Required
- Schema
- Description
* - check
- true
- :ref:`BoolExp`
- This expression has to hold true for every new row that is inserted
* - set
- false
- :ref:`ColumnPresetExp`
- Preset values for columns that can be sourced from session variables or static values
* - columns
- false
- :ref:`PGColumn` array (or) ``'*'``
- Can insert into only these columns (or all when ``'*'`` is specified)
* - backend_only
- false
- Boolean
- When set to ``true`` the mutation is accessible only if ``x-hasura-use-backend-only-permissions``
session variable exists and is set to ``true`` and request is made with ``x-hasura-admin-secret``
set if any auth is configured
.. _drop_insert_permission:
drop_insert_permission
@ -278,46 +247,13 @@ Args syntax
- Role
* - permission
- true
- SelectPermission_
- :ref:`SelectPermission`
- The permission definition
* - comment
- false
- text
- Comment
.. _SelectPermission:
SelectPermission
&&&&&&&&&&&&&&&&
.. list-table::
:header-rows: 1
* - Key
- Required
- Schema
- Description
* - columns
- true
- :ref:`PGColumn` array (or) ``'*'``
- Only these columns are selectable (or all when ``'*'`` is specified)
* - computed_fields
- false
- :ref:`ComputedFieldName` array
- Only these computed fields are selectable
* - filter
- true
- :ref:`BoolExp`
- Only the rows where this expression holds true are selectable
* - limit
- false
- ``Integer``
- The maximum number of rows that can be returned
* - allow_aggregations
- false
- ``Boolean``
- Toggle allowing aggregate queries
.. _drop_select_permission:
drop_select_permission
@ -440,43 +376,13 @@ Args syntax
- Role
* - permission
- true
- UpdatePermission_
- :ref:`UpdatePermission`
- The permission definition
* - comment
- false
- text
- Comment
.. _UpdatePermission:
UpdatePermission
&&&&&&&&&&&&&&&&
.. list-table::
:header-rows: 1
* - Key
- Required
- Schema
- Description
* - columns
- true
- :ref:`PGColumn` array (or) ``'*'``
- Only these columns are selectable (or all when ``'*'`` is specified)
* - filter
- true
- :ref:`BoolExp`
- Only the rows where this precondition holds true are updatable
* - check
- false
- :ref:`BoolExp`
- Postcondition which must be satisfied by rows which have been updated
* - set
- false
- :ref:`ColumnPresetExp`
- Preset values for columns that can be sourced from session variables or static values.
.. _drop_update_permission:
drop_update_permission
@ -576,30 +482,13 @@ Args syntax
- Role
* - permission
- true
- DeletePermission_
- :ref:`DeletePermission`
- The permission definition
* - comment
- false
- text
- Comment
.. _DeletePermission:
DeletePermission
&&&&&&&&&&&&&&&&
.. list-table::
:header-rows: 1
* - Key
- Required
- Schema
- Description
* - filter
- true
- :ref:`BoolExp`
- Only the rows where this expression holds true are deletable
.. _drop_delete_permission:
drop_delete_permission

4
docs/graphql/core/api-reference/schema-metadata-api/query-collections.rst
View File

@ -205,7 +205,7 @@ Args Syntax
.. _add_collection_to_allowlist:
add_collection_to_allowlist
----------------------------
---------------------------
``add_collection_to_allowlist`` is used to add a collection to the allow-list.
@ -242,7 +242,7 @@ Args Syntax
.. _drop_collection_from_allowlist:
drop_collection_from_allowlist
-------------------------------
------------------------------
``drop_collection_from_allowlist`` is used to remove a collection from the allow-list.

109
docs/graphql/core/api-reference/schema-metadata-api/relationship.rst
View File

@ -133,59 +133,13 @@ Args syntax
- Name of the new relationship
* - using
- true
- ObjRelUsing_
- :ref:`ObjRelUsing`
- Use one of the available ways to define an object relationship
* - comment
- false
- text
- comment
.. _ObjRelUsing:
ObjRelUsing
&&&&&&&&&&&
.. list-table::
:header-rows: 1
* - Key
- Required
- Schema
- Description
* - foreign_key_constraint_on
- false
- :ref:`PGColumn <PGColumn>`
- The column with foreign key constraint
* - manual_configuration
- false
- ObjRelUsingManualMapping_
- Manual mapping of table and columns
.. note::
There has to be at least one and only one of ``foreign_key_constraint_on``
and ``manual_configuration``.
ObjRelUsingManualMapping
&&&&&&&&&&&&&&&&&&&&&&&&
.. list-table::
:header-rows: 1
* - Key
- Required
- Schema
- Description
* - remote_table
- true
- :ref:`TableName`
- The table to which the relationship has to be established
* - column_mapping
- true
- Object (:ref:`PGColumn` : :ref:`PGColumn`)
- Mapping of columns from current table to remote table
.. _create_array_relationship:
create_array_relationship
@ -290,72 +244,13 @@ Args syntax
- Name of the new relationship
* - using
- true
- ArrRelUsing_
- :ref:`ArrRelUsing`
- Use one of the available ways to define an array relationship
* - comment
- false
- text
- comment
.. _ArrRelUsing:
ArrRelUsing
&&&&&&&&&&&
.. list-table::
:header-rows: 1
* - Key
- Required
- Schema
- Description
* - foreign_key_constraint_on
- false
- ArrRelUsingFKeyOn_
- The column with foreign key constraint
* - manual_configuration
- false
- ArrRelUsingManualMapping_
- Manual mapping of table and columns
ArrRelUsingFKeyOn
&&&&&&&&&&&&&&&&&
.. list-table::
:header-rows: 1
* - Key
- Required
- Schema
- Description
* - table
- true
- :ref:`TableName`
- Name of the table
* - column
- true
- :ref:`PGColumn`
- Name of the column with foreign key constraint
ArrRelUsingManualMapping
&&&&&&&&&&&&&&&&&&&&&&&&
.. list-table::
:header-rows: 1
* - Key
- Required
- Schema
- Description
* - remote_table
- true
- :ref:`TableName`
- The table to which the relationship has to be established
* - column_mapping
- true
- Object (:ref:`PGColumn` : :ref:`PGColumn`)
- Mapping of columns from current table to remote table
.. _drop_relationship:
drop_relationship

87
docs/graphql/core/api-reference/schema-metadata-api/remote-relationships.rst
View File

@ -59,7 +59,7 @@ Args syntax
- Description
* - name
- true
- RemoteRelationshipName_
- :ref:`RemoteRelationshipName`
- Name of the remote relationship
* - table
- true
@ -75,7 +75,7 @@ Args syntax
- Name of the remote schema to join with
* - remote_field
- true
- RemoteField_
- :ref:`RemoteField`
- The schema tree ending at the field in remote schema which needs to be joined with.
.. _update_remote_relationship:
@ -125,7 +125,7 @@ Args syntax
- Description
* - name
- true
- RemoteRelationshipName_
- :ref:`RemoteRelationshipName`
- Name of the remote relationship
* - table
- true
@ -141,7 +141,7 @@ Args syntax
- Name of the remote schema to join with
* - remote_field
- true
- RemoteField_
- :ref:`RemoteField`
- The schema tree ending at the field in remote schema which needs to be joined with.
.. _delete_remote_relationship:
@ -186,80 +186,5 @@ Args syntax
- Object with table name and schema
* - name
- true
- RemoteRelationshipName_
- Name of the remote relationship
.. _RemoteRelationshipName:
RemoteRelationshipName
&&&&&&&&&&&&&&&&&&&&&&
.. parsed-literal::
String
RemoteField
&&&&&&&&&&&
.. parsed-literal::
:class: haskell-pre
{
FieldName: {
"arguments": InputArguments
"field": RemoteField # optional
}
}
``RemoteField`` is a recursive tree structure that points to the field in the remote schema that needs to be joined with. It is recursive because the remote field maybe nested deeply in the remote schema.
Examples:
.. code-block:: http
POST /v1/query HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"message": {
"arguments":{
"message_id":"$id"
}
}
}
.. code-block:: http
POST /v1/query HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"messages": {
"arguments": {
"limit": 100
},
"field": {
"private": {
"arguments": {
"id" : "$id"
}
}
}
}
}
InputArguments
&&&&&&&&&&&&&&
.. parsed-literal::
:class: haskell-pre
{
InputField : $PGColumn | Scalar
}
Table columns can be referred by prefixing ``$`` e.g ``$id``.
- :ref:`RemoteRelationshipName`
- Name of the remote relationship

21
docs/graphql/core/api-reference/schema-metadata-api/remote-schema-permissions.rst
View File

@ -334,35 +334,20 @@ Args syntax
- Role
* - definition
- true
- RemoteSchemaPermission_
- :ref:`RemoteSchemaPermission`
- The remote schema permission definition
* - comment
- false
- text
- Comment
.. _RemoteSchemaPermission:
RemoteSchemaPermission
""""""""""""""""""""""
.. list-table::
:header-rows: 1
* - Key
- Required
- Schema
- Description
* - schema
- true
- GraphQL SDL
- GraphQL SDL defining the role based schema
.. note::
``add_remote_schema_permissions`` will only work when the graphql-engine has enabled remote
schema permissions. Remote schema permissions can be enabled by running the graphql-engine
with the ``--enable-remote-schema-permissions`` server flag or by setting the ``HASURA_GRAPHQL_ENABLE_REMOTE_SCHEMA_PERMISSIONS`` environment variable.
.. _drop_remote_schema_permissions:
drop_remote_schema_permissions

50
docs/graphql/core/api-reference/schema-metadata-api/scheduled-triggers.rst
View File

@ -77,7 +77,7 @@ Args syntax
- List of headers to be sent with the webhook
* - retry_conf
- false
- RetryConfST_
- :ref:`RetryConfST`
- Retry configuration if scheduled invocation delivery fails
* - include_in_metadata
- true
@ -193,53 +193,9 @@ Args syntax
- List of headers to be sent with the webhook
* - retry_conf
- false
- RetryConfST_
- :ref:`RetryConfST`
- Retry configuration if scheduled event delivery fails
* - comment
- false
- Text
- Custom comment.
UrlFromEnv
&&&&&&&&&&
.. list-table::
:header-rows: 1
* - Key
- required
- Schema
- Description
* - from_env
- true
- String
- Name of the environment variable which has the URL
.. _RetryConfST:
RetryConfST
&&&&&&&&&&&
.. list-table::
:header-rows: 1
* - Key
- required
- Schema
- Description
* - num_retries
- false
- Integer
- Number of times to retry delivery. Default: 0
* - retry_interval_seconds
- false
- Integer
- Number of seconds to wait between each retry. Default: 10
* - timeout_seconds
- false
- Integer
- Number of seconds to wait for response before timing out. Default: 60
* - tolerance_seconds
- false
- Integer
- Number of seconds between scheduled time and actual delivery time that is acceptable. If the time difference is more than this, then the event is dropped. Default: 21600 (6 hours)
- Custom comment.

699
docs/graphql/core/api-reference/schema-metadata-api/syntax-defs.rst
View File

@ -1,699 +0,0 @@
.. meta::
:description: Common syntax definitions for the Hasura schema/metadata API
:keywords: hasura, docs, schema/metadata API, API reference, syntax definitions
.. _api_metadata_syntax_defs:
Schema/Metadata API Reference: Common syntax definitions
========================================================
.. contents:: Table of contents
:backlinks: none
:depth: 1
:local:
.. _TableName:
TableName
^^^^^^^^^
.. parsed-literal::
:class: haskell-pre
String | QualifiedTable_
.. _QualifiedTable:
QualifiedTable
^^^^^^^^^^^^^^
.. parsed-literal::
:class: haskell-pre
{
"name": String,
"schema": String
}
.. _FunctionName:
FunctionName
^^^^^^^^^^^^
.. parsed-literal::
:class: haskell-pre
String | QualifiedFunction_
QualifiedFunction
^^^^^^^^^^^^^^^^^
.. parsed-literal::
:class: haskell-pre
{
"name": String,
"schema": String
}
.. _RoleName:
RoleName
^^^^^^^^
.. parsed-literal::
String
.. _ComputedFieldName:
ComputedFieldName
^^^^^^^^^^^^^^^^^^
.. parsed-literal::
String
.. _PGColumnType:
PGColumnType
^^^^^^^^^^^^
.. parsed-literal::
String
1. Numeric types
.. list-table::
:widths: 12 10 20
:header-rows: 1
* - Type
- Alias
- Description
* - ``serial``
-
- autoincrementing integer
* - ``bigserial``
-
- autoincrementing bigint
* - ``integer``
-
- 4 bytes, typical choice for integer
* - ``smallint``
-
- 2 bytes
* - ``bigint``
-
- 8 bytes
* - ``real``
- ``float4``
- 6 decimal digits precision, inexact
* - ``double precision``
- ``float8``
- 15 decimal digits precision, inexact
* - ``numeric``
- ``decimal``
- arbitrary precision, exact
2. Character types
.. list-table::
:widths: 8 6 20
:header-rows: 1
* - Type
- Alias
- Description
* - ``varchar``
- ``text``
- typical choice for storing string types
3. Date/Time types
.. list-table::
:widths: 8 6 20
:header-rows: 1
* - Type
- Alias
- Description
* - ``timestamp with time zone``
- ``timestamptz``
- both date and time, with time zone. Allowed values should be of ISO8601 format. E.g. 2016-07-20T17:30:15Z, 2016-07-20T17:30:15+05:30, 2016-07-20T17:30:15.234890+05:30
* - ``time with time zone``
- ``timetz``
- time of day only, with time zone. Allowed values should be of ISO8601 format. E.g. 17:30:15Z, 17:30:15+05:30, 17:30:15.234890+05:30
* - ``date``
-
- date (no time of day). Allowed values are yyyy-mm-dd
4. Boolean type
.. list-table::
:widths: 8 6 20
:header-rows: 1
* - Type
- Alias
- Description
* - ``boolean``
-
- state of true or false
5. JSON types
.. list-table::
:widths: 8 6 20
:header-rows: 1
* - Type
- Alias
- Description
* - ``json``
-
- Stored as plain text
* - ``jsonb``
-
- Stored in a binary format and can be indexed
.. _PGColumn:
PGColumn
^^^^^^^^
.. parsed-literal::
String
.. _RelationshipName:
RelationshipName
^^^^^^^^^^^^^^^^
.. parsed-literal::
String
.. _BoolExp:
BoolExp
^^^^^^^
.. parsed-literal::
:class: haskell-pre
AndExp_ | OrExp_ | NotExp_ | ExistsExp_ | TrueExp_ | ColumnExp_
AndExp
^^^^^^
.. parsed-literal::
:class: haskell-pre
{
"$and" : [BoolExp_],
}
OrExp
^^^^^
.. parsed-literal::
:class: haskell-pre
{
"$or" : [BoolExp_],
}
NotExp
^^^^^^
.. parsed-literal::
:class: haskell-pre
{
"$not" : BoolExp_
}
ExistsExp
^^^^^^^^^
.. parsed-literal::
:class: haskell-pre
{
"$exists" : {
"_table": TableName_,
"_where": BoolExp_
}
}
TrueExp
^^^^^^^
.. parsed-literal::
:class: haskell-pre
{}
ColumnExp
^^^^^^^^^
.. parsed-literal::
:class: haskell-pre
{
PGColumn_ : { Operator_ : Value }
}
.. _MetadataOperator:
Operator
^^^^^^^^
**Generic operators (all column types except json, jsonb) :**
.. list-table::
:header-rows: 1
* - Operator
- PostgreSQL equivalent
* - ``"$eq"``
- ``=``
* - ``"$ne"``
- ``<>``
* - ``"$gt"``
- ``>``
* - ``"$lt"``
- ``<``
* - ``"$gte"``
- ``>=``
* - ``"$lte"``
- ``<=``
* - ``"$in"``
- ``IN``
* - ``"$nin"``
- ``NOT IN``
(For more details, refer to the Postgres docs for `comparison operators <https://www.postgresql.org/docs/current/functions-comparison.html>`__ and `list based search operators <https://www.postgresql.org/docs/current/functions-comparisons.html>`__.)
**Text related operators :**
.. list-table::
:header-rows: 1
* - Operator
- PostgreSQL equivalent
* - ``"$like"``
- ``LIKE``
* - ``"$nlike"``
- ``NOT LIKE``
* - ``"$ilike"``
- ``ILIKE``
* - ``"$nilike"``
- ``NOT ILIKE``
* - ``"$similar"``
- ``SIMILAR TO``
* - ``"$nsimilar"``
- ``NOT SIMILAR TO``
* - ``$regex``
- ``~``
* - ``$iregex``
- ``~*``
* - ``$nregex``
- ``!~``
* - ``$niregex``
- ``!~*``
(For more details on text related operators, refer to the `Postgres docs <https://www.postgresql.org/docs/current/functions-matching.html>`__.)
**Operators for comparing columns (all column types except json, jsonb):**
.. list-table::
:header-rows: 1
* - Operator
- PostgreSQL equivalent
* - ``"$ceq"``
- ``=``
* - ``"$cne"``
- ``<>``
* - ``"$cgt"``
- ``>``
* - ``"$clt"``
- ``<``
* - ``"$cgte"``
- ``>=``
* - ``"$clte"``
- ``<=``
(For more details on comparison operators, refer to the `Postgres docs <https://www.postgresql.org/docs/current/functions-comparison.html>`__.)
**Checking for NULL values :**
.. list-table::
:header-rows: 1
* - Operator
- PostgreSQL equivalent
* - ``_is_null`` (takes true/false as values)
- ``IS NULL``
(For more details on the ``IS NULL`` expression, refer to the `Postgres docs <https://www.postgresql.org/docs/current/functions-comparison.html>`__.)
**JSONB operators :**
.. list-table::
:header-rows: 1
* - Operator
- PostgreSQL equivalent
* - ``_contains``
- ``@>``
* - ``_contained_in``
- ``<@``
* - ``_has_key``
- ``?``
* - ``_has_keys_any``
- ``?!``
* - ``_has_keys_all``
- ``?&``
(For more details on JSONB operators, refer to the `Postgres docs <https://www.postgresql.org/docs/current/static/functions-json.html#FUNCTIONS-JSONB-OP-TABLE>`__.)
**PostGIS related operators on GEOMETRY columns:**
.. list-table::
:header-rows: 1
* - Operator
- PostGIS equivalent
* - ``_st_contains``
- ``ST_Contains(column, input)``
* - ``_st_crosses``
- ``ST_Crosses(column, input)``
* - ``_st_equals``
- ``ST_Equals(column, input)``
* - ``_st_intersects``
- ``ST_Intersects(column, input)``
* - ``_st_overlaps``
- ``ST_Overlaps(column, input)``
* - ``_st_touches``
- ``ST_Touches(column, input)``
* - ``_st_within``
- ``ST_Within(column, input)``
* - ``_st_d_within``
- ``ST_DWithin(column, input)``
(For more details on spatial relationship operators, refer to the `PostGIS docs <http://postgis.net/workshops/postgis-intro/spatial_relationships.html>`__.)
.. note::
- All operators take a JSON representation of ``geometry/geography`` values as input value.
- The input value for ``_st_d_within`` operator is an object:
.. parsed-literal::
{
field-name : {_st_d_within: {distance: Float, from: Value} }
}
.. _Object:
Object
^^^^^^
A JSONObject_
.. parsed-literal::
:class: haskell-pre
{
"k1" : v1,
"k2" : v2,
..
}
.. _JSONObject: https://tools.ietf.org/html/rfc7159
.. _Empty Object:
Empty Object
^^^^^^^^^^^^
An empty JSONObject_
.. code-block:: json
{}
.. _ColumnPresetExp:
ColumnPresetsExp
^^^^^^^^^^^^^^^^
A JSONObject_ of a Postgres column name to value mapping, where the value can be static or derived from a session variable.
.. parsed-literal::
:class: haskell-pre
{
"column1" : colVal1,
"column2" : colVal2,
..
}
E.g. where ``id`` is derived from a session variable and ``city`` is a static value.
.. code-block:: json
{
"id" : "x-hasura-User-Id",
"city" : "San Francisco"
}
.. note::
If the value of any key begins with "x-hasura-" (*case-insensitive*), the value of the column specified in the key will be derived from a session variable of the same name.
.. _RemoteSchemaName:
RemoteSchemaName
^^^^^^^^^^^^^^^^
.. parsed-literal::
String
.. _RemoteSchemaDef:
RemoteSchemaDef
^^^^^^^^^^^^^^^
.. parsed-literal::
:class: haskell-pre
{
"url" : url-string,
"url_from_env" : env-var-string,
"headers": [
{ "name": header-name-string,
"value": header-value-string,
"value_from_env": env-var-string
}
],
"forward_client_headers": boolean,
"timeout_seconds": integer
}
.. _CollectionName:
CollectionName
^^^^^^^^^^^^^^
.. parsed-literal::
String
.. _QueryName:
QueryName
^^^^^^^^^
.. parsed-literal::
String
.. _CollectionQuery:
CollectionQuery
^^^^^^^^^^^^^^^
.. parsed-literal::
:class: haskell-pre
{
"name": String,
"query": String
}
.. _EndpointUrl:
EndpointUrl
^^^^^^^^^^^
.. parsed-literal::
String
.. _EndpointMethods:
EndpointMethods
^^^^^^^^^^^^^^^
.. parsed-literal::
[String]
.. _EndpointDef:
EndpointDefinition
^^^^^^^^^^^^^^^^^^
.. parsed-literal::
:class: haskell-pre
{
"query": {
"query_name : String,
"collection_name" : CollectionName
}
}
.. _CustomColumnNames:
CustomColumnNames
^^^^^^^^^^^^^^^^^^
A JSONObject_ of Postgres column name to GraphQL name mapping
.. parsed-literal::
:class: haskell-pre
{
"column1" : String,
"column2" : String,
..
}
.. _ActionName:
ActionName
^^^^^^^^^^
.. parsed-literal::
:class: haskell-pre
String
.. _WebhookURL:
WebhookURL
^^^^^^^^^^
A String value which supports templating environment variables enclosed in ``{{`` and ``}}``.
.. parsed-literal::
:class: haskell-pre
String
Template example: ``https://{{ACTION_API_DOMAIN}}/create-user``
.. _HeaderFromValue:
HeaderFromValue
^^^^^^^^^^^^^^^
.. list-table::
:header-rows: 1
* - Key
- required
- Schema
- Description
* - name
- true
- String
- Name of the header
* - value
- true
- String
- Value of the header
.. _HeaderFromEnv:
HeaderFromEnv
^^^^^^^^^^^^^
.. list-table::
:header-rows: 1
* - Key
- required
- Schema
- Description
* - name
- true
- String
- Name of the header
* - value_from_env
- true
- String
- Name of the environment variable which holds the value of the header
.. _GraphQLType:
GraphQLType
^^^^^^^^^^^
A GraphQL `Type Reference <https://spec.graphql.org/June2018/#sec-Type-References>`__ string.
.. parsed-literal::
:class: haskell-pre
String
Example: ``String!`` for non-nullable String type and ``[String]`` for array of String types
.. _GraphQLName:
GraphQLName
^^^^^^^^^^^
A string literal that conform to `GraphQL spec <https://spec.graphql.org/June2018/#Name>`__.
.. parsed-literal::
:class: haskell-pre
String

77
docs/graphql/core/api-reference/schema-metadata-api/table-view.rst
View File

@ -209,81 +209,6 @@ Args syntax
- :ref:`Table Config <table_config>`
- Configuration for the table/view
.. _table_config:
Table Config
^^^^^^^^^^^^
.. list-table::
:header-rows: 1
* - Key
- Required
- Schema
- Description
* - custom_name
- false
- ``String``
- Customise the ``<table-name>`` with the provided custom name value.
The GraphQL nodes for the table will be generated according to the custom name.
* - 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
* - insert_one
- false
- ``String``
- Customise the ``insert_<table-name>_one`` root field
* - update
- false
- ``String``
- Customise the ``update_<table-name>`` root field
* - update_by_pk
- false
- ``String``
- Customise the ``update_<table-name>_by_pk`` root field
* - delete
- false
- ``String``
- Customise the ``delete_<table-name>`` root field
* - delete_by_pk
- false
- ``String``
- Customise the ``delete_<table-name>_by_pk`` root field
.. _set_table_custom_fields:
set_table_custom_fields (deprecated)
@ -297,8 +222,6 @@ table fields.
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

1551
docs/graphql/core/api-reference/syntax-defs.rst Normal file
View File

File diff suppressed because it is too large Load Diff

2
docs/graphql/core/getting-started/docker-simple.rst
View File

@ -52,7 +52,7 @@ contains all installation manifests required to deploy Hasura anywhere. Get the
# or run
curl https://raw.githubusercontent.com/hasura/graphql-engine/master/install-manifests/docker-compose-v2.0.0/docker-compose.yaml -o docker-compose.yml
See `changelog <https://github.com/hasura/graphql-engine/releases/tag/v2.0.0-alpha.1>`__
Step 2: Run Hasura GraphQL engine & Postgres
--------------------------------------------

2
docs/graphql/core/migrations/config-v1/reference/migration-file-format.rst
View File

@ -68,7 +68,7 @@ actions, which is represented with a ``-`` in YAML. Here is an example file:
Each one of the actions in these files are actually Hasura metadata API calls,
which are executed in **sequence** when the migration is applied. You can find
all the metadata actions that are available in the :ref:`API reference <Query>`.
all the metadata actions that are available in the :ref:`API reference <api_query>`.
SQL Files

4
docs/graphql/core/migrations/index.rst
View File

@ -78,8 +78,8 @@ Reference documentation
-----------------------
- :ref:`migrations_how_it_works`
- :ref:`Migration file format <migration_file_format_v3>`
- :ref:`Metadata format <metadata_format_v3>`
- :ref:`Migration file format <migration_file_format>`
- :ref:`Metadata format <metadata_format>`
.. toctree::
:maxdepth: 1

2
docs/graphql/core/migrations/reference/metadata-format.rst
View File

@ -2,7 +2,7 @@
:description: Hasura Metadata file format reference
:keywords: hasura, docs, metadata, file format
.. _metadata_format_v3:
.. _metadata_format:
Metadata format reference
=========================

2
docs/graphql/core/migrations/reference/migration-file-format.rst
View File

@ -2,7 +2,7 @@
:description: Hasura Migration file format reference
:keywords: hasura, docs, migration, file format
.. _migration_file_format_v3:
.. _migration_file_format:
Migration file format reference
===============================