mirror of
https://github.com/hasura/graphql-engine.git
synced 2024-12-17 04:24:35 +03:00
657 lines
11 KiB
ReStructuredText
657 lines
11 KiB
ReStructuredText
.. 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``
|
|
|
|
(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
|
|
}
|
|
|
|
.. _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
|