diff --git a/docs/graphql/manual/api-reference/query.rst b/docs/graphql/manual/api-reference/query.rst index 0465a42eb3e..53b83ac5a49 100644 --- a/docs/graphql/manual/api-reference/query.rst +++ b/docs/graphql/manual/api-reference/query.rst @@ -317,7 +317,7 @@ ColumnExp Operator ######## -Generic operators (all column types except json, jsonb) : +**Generic operators (all column types except json, jsonb):** - ``_eq`` - ``_neq`` @@ -328,7 +328,7 @@ Generic operators (all column types except json, jsonb) : - ``_gte`` - ``_lte`` -JSONB operators: +**JSONB operators:** .. list-table:: :header-rows: 1 @@ -348,7 +348,7 @@ JSONB operators: (For more details on what these operators do, refer to `Postgres docs `__.) -Text related operators : +**Text related operators :** - ``_like`` - ``_nlike`` @@ -357,11 +357,11 @@ Text related operators : - ``_similar`` - ``_nsimilar`` -Checking for ``null`` values : +**Checking for NULL values:** - ``_is_null`` (takes true/false as values) -PostGIS related operators on GEOMETRY columns : +**PostGIS related operators on GEOMETRY columns:** .. list-table:: :header-rows: 1 @@ -387,8 +387,9 @@ PostGIS related operators on GEOMETRY columns : (For more details on what these operators do, refer to `PostGIS docs `__.) -.. Note:: - 1. All operators take a json representation of ``geometry/geography`` values. Also see :doc:`here <../queries/query-filters>` for more query examples on these operators +.. note:: + + 1. All operators take a ``json`` representation of ``geometry/geography`` values. 2. Input value for ``_st_d_within`` operator is an object:- .. parsed-literal:: diff --git a/docs/graphql/manual/mutations/delete.rst b/docs/graphql/manual/mutations/delete.rst index 2239be0cc0f..6ef3fe585ab 100644 --- a/docs/graphql/manual/mutations/delete.rst +++ b/docs/graphql/manual/mutations/delete.rst @@ -6,6 +6,9 @@ Delete mutation :depth: 1 :local: +Auto-generated delete mutation schema +------------------------------------- + Here’s the schema for the delete mutation field for a table ``article``: .. code-block:: graphql @@ -28,6 +31,11 @@ As you can see from the schema: for filtering options. Objects can be deleted based on filters on their own fields or those in their nested objects. - You can return the number of affected rows and the affected objects (with nested objects) in the response. +.. note:: + + If a table is not in the ``public`` Postgres schema, the delete mutation field will be of the format + ``delete__``. + Delete based on an object's fields ---------------------------------- **Example:** Delete all articles rated less than 3: diff --git a/docs/graphql/manual/mutations/index.rst b/docs/graphql/manual/mutations/index.rst index 2ba060ef2cb..22506fad1c5 100644 --- a/docs/graphql/manual/mutations/index.rst +++ b/docs/graphql/manual/mutations/index.rst @@ -6,13 +6,18 @@ Mutations :depth: 1 :local: -GraphQL mutations are used to modify server-side data (i.e. write, update or delete data). As with queries, mutation -fields are auto-generated based on the Postgres schema. +GraphQL mutations are used to modify data on the server (i.e. write, update or delete data). + +Hasura GraphQL engine auto-generates mutations as part of the GraphQL schema from your Postgres schema model. + +Data of all tables in the database tracked by the GraphQL engine can be modified over the GraphQL endpoint. +If you have a tracked table in your database, its insert/update/delete mutation fields are added as nested +fields under the ``mutation_root`` root level type. Types of mutation requests -------------------------- -Let's use this reference author/article schema to look at different types of mutations. +The following types of mutation requests are possible: .. toctree:: :maxdepth: 1 diff --git a/docs/graphql/manual/mutations/insert.rst b/docs/graphql/manual/mutations/insert.rst index 0c9ddfabb83..0c7dcdb9edf 100644 --- a/docs/graphql/manual/mutations/insert.rst +++ b/docs/graphql/manual/mutations/insert.rst @@ -6,6 +6,9 @@ Insert mutation :depth: 1 :local: +Auto-generated insert mutation schema +------------------------------------- + Here’s the schema for the insert mutation field for a table ``article``: .. code-block:: graphql @@ -29,6 +32,11 @@ As you can see from the schema: - You can pass an ``on_conflict`` argument to convert the mutation to an :doc:`upsert mutation ` - You can return the number of affected rows and the affected objects (with nested objects) in the response. +.. note:: + + If a table is not in the ``public`` Postgres schema, the insert mutation field will be of the format + ``insert__``. + Insert a single object ---------------------- **Example:** Insert a new ``article`` object and return the inserted article object in the response diff --git a/docs/graphql/manual/mutations/update.rst b/docs/graphql/manual/mutations/update.rst index d4b6faf59ae..64f45bcce77 100644 --- a/docs/graphql/manual/mutations/update.rst +++ b/docs/graphql/manual/mutations/update.rst @@ -6,6 +6,9 @@ Update mutation :depth: 1 :local: +Auto-generated update mutation schema +------------------------------------- + Here’s the schema for the update mutation field for a table ``article``: .. code-block:: graphql @@ -32,8 +35,11 @@ As you can see from the schema: .. note:: - At least any one of ``_set``, ``_inc`` operators or the jsonb operators ``_append``, ``_prepend``, ``_delete_key``, - ``_delete_elem``, ``_delete_at_path`` is required. + - At least any one of ``_set``, ``_inc`` operators or the jsonb operators ``_append``, ``_prepend``, ``_delete_key``, + ``_delete_elem``, ``_delete_at_path`` is required. + + - If a table is not in the ``public`` Postgres schema, the update mutation field will be of the format + ``update__``. Update based on an object's fields ---------------------------------- diff --git a/docs/graphql/manual/queries/index.rst b/docs/graphql/manual/queries/index.rst index ef520ee34ba..9d0813df034 100644 --- a/docs/graphql/manual/queries/index.rst +++ b/docs/graphql/manual/queries/index.rst @@ -6,13 +6,15 @@ Queries :depth: 1 :local: -Hasura GraphQL engine auto-generates queries and mutations as part of the GraphQL schema from your Postgres schema -model. It generates a range of possible queries and operators that also work with relationships defined in your SQL +GraphQL queries are used to fetch data from the server. + +Hasura GraphQL engine auto-generates queries as part of the GraphQL schema from your Postgres schema model. +It generates a range of possible queries and operators that also work with relationships defined in your SQL schema. -All tracked tables of the database can be queried and modified over the GraphQL endpoint. If you have a tracked table -in your database, a query and insert/update/delete mutations each are added as nested fields under the root level -types, ``query_root`` and ``mutation_root`` respectively. +All tables of the database tracked by the GraphQL engine can be queried over the GraphQL endpoint. +If you have a tracked table in your database, its query field is added as a nested +field under the ``query_root`` root level type. Auto-generated query schema --------------------------- diff --git a/docs/graphql/manual/queries/query-filters.rst b/docs/graphql/manual/queries/query-filters.rst index 259e6dd0b0a..b4783f180ec 100644 --- a/docs/graphql/manual/queries/query-filters.rst +++ b/docs/graphql/manual/queries/query-filters.rst @@ -43,16 +43,18 @@ For example, to fetch a list of authors who have articles with a rating greater } } -Here ``_eq`` and ``_gt`` are examples of :ref:`comparison operators ` that can be used in the ``where`` argument to filter on -equality. +Here ``_eq`` and ``_gt`` are examples of :ref:`comparison operators ` that can be used in the ``where`` +argument to filter on equality. Let’s take a look at different operators that can be used to filter results and other advanced use cases: Equality operators (_eq and _neq) --------------------------------- The ``_eq`` (equal to) or the ``_neq`` (not equal to) operators are compatible with any Postgres type other than -json or jsonB (like Integer, Float, Double, Text, Boolean, Date/Time/Timestamp, etc.). The following are examples of -using the equality operators on different types. +``json`` or ``jsonB`` (like ``Integer``, ``Float``, ``Double``, ``Text``, ``Boolean``, +``Date``/``Time``/``Timestamp``, etc.). + +The following are examples of using the equality operators on different types. Example: Integer (works with Double, Float, Numeric, etc.) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -185,9 +187,10 @@ Fetch a list of articles that were published on a certain date (``published_on`` Greater than or less than operators (_gt, _lt, _gte, _lte) ---------------------------------------------------------- The ``_gt`` (greater than), ``_lt`` (less than), ``_gte`` (greater than or equal to), -``_lte`` (less than or equal to) operators are compatible with any Postgres type other than json or jsonB -(like Integer, Float, Double, Text, Boolean, Date/Time/Timestamp, etc.). The following are examples of using these -operators on different types: +``_lte`` (less than or equal to) operators are compatible with any Postgres type other than ``json`` or ``jsonB`` +(like ``Integer``, ``Float``, ``Double``, ``Text``, ``Boolean``, ``Date``/``Time``/``Timestamp``, etc.). + +The following are examples of using these operators on different types: Example: Integer (works with Double, Float, etc.) @@ -308,8 +311,10 @@ Fetch a list of articles that were published on or after date "01/01/2018": List based search operators (_in, _nin) --------------------------------------- The ``_in`` (in a list) and ``_nin`` (not in list) operators are used to comparing field values to a list of values. -They are compatible with any Postgres type other than json or jsonB (like Integer, Float, Double, Text, Boolean, -Date/Time/Timestamp, etc.). The following are examples of using these operators on different types: +They are compatible with any Postgres type other than ``json`` or ``jsonB`` (like ``Integer``, ``Float``, ``Double``, +``Text``, ``Boolean``, ``Date``/``Time``/``Timestamp``, etc.). + +The following are examples of using these operators on different types: Example: Integer (works with Double, Float, etc.) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -475,22 +480,26 @@ Fetch a list of authors whose names begin with A or C (``similar`` is case-sensi PostGIS topology operators -------------------------- + The ``_st_contains``, ``_st_crosses``, ``_st_equals``, ``_st_intersects``, ``_st_overlaps``, ``_st_touches``, ``_st_within`` and ``_st_d_within`` operators are used to filter ``geometry`` like columns. For more details on what these operators do, refer to `PostGIS docs `__. -Use ``json`` (`GeoJSON `_) representation of ``geometry`` values in ``variables`` as shown in the following examples +Use ``json`` (`GeoJSON `_) representation of ``geometry`` values in +``variables`` as shown in the following examples: Example: _st_within -^^^^^^^^^^^^^^^^^^^^^ -Fetch a list of geometry values which are within the given ``polygon`` value +^^^^^^^^^^^^^^^^^^^ +Fetch a list of geometry values which are within the given ``polygon`` value: .. graphiql:: :view_only: :query: query geom_table($polygon: geometry){ - geom_table(where: {geom_col: {_st_within: $polygon}}){ + geom_table( + where: {geom_col: {_st_within: $polygon}} + ){ id geom_col } @@ -512,50 +521,33 @@ Fetch a list of geometry values which are within the given ``polygon`` value ] } } - -Variables for above query:- - -.. code-block:: json - - { - "polygon": { - "type": "Polygon", - "coordinates": [ - [ - [ - 0, - 0 - ], - [ - 0, - 2 - ], - [ - 2, - 2 - ], - [ - 2, - 0 - ], - [ - 0, - 0 - ] - ] - ] - } - } + :variables: + { + "polygon": { + "type": "Polygon", + "coordinates": [ + [ + [ 0, 0 ], + [ 0, 2 ], + [ 2, 2 ], + [ 2, 0 ], + [ 0, 0 ] + ] + ] + } + } Example: _st_d_within ^^^^^^^^^^^^^^^^^^^^^ -Fetch a list of geometry values which are 3 units from given ``point`` value +Fetch a list of geometry values which are 3 units from given ``point`` value: .. graphiql:: :view_only: :query: query geom_table($point: geometry){ - geom_table(where: {geom_col: {_st_d_within: {distance: 3, from: $point}}}){ + geom_table( + where: {geom_col: {_st_d_within: {distance: 3, from: $point}}} + ){ id geom_col } @@ -587,21 +579,13 @@ Fetch a list of geometry values which are 3 units from given ``point`` value ] } } - -Variables for above query:- - -.. code-block:: json - - { - "point": { + :variables: + { + "point": { "type": "Point", - "coordinates": [ - 0, - 0 - ] - } - } - + "coordinates": [ 0, 0 ] + } + } Filter or check for null values ------------------------------- @@ -1061,7 +1045,7 @@ Fetch if **all** of the nested objects defined via an array relationship satisfy ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ As by default a row is returned if any of the nested objects satisfy a condition, to achieve the above we need to frame -the ``where`` expression as ``{_not: {inverse-of-condition}}``. This reads as: fetch if not(any of the nested objects +the ``where`` expression as ``{_not: {inverse-of-condition}}``. This reads as: fetch if not (any of the nested objects satisfy the inverted condition) i.e. all of the nested objects satisfy the condition. For example, @@ -1162,7 +1146,7 @@ Fetch if **none** of the nested objects defined via an array relationship satisf ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ As by default a row is returned if any of the nested objects satisfy a condition, to achieve the above we need to frame -the ``where`` expression as ``{_not: {condition}}``. This reads as: fetch if not(any of the nested objects +the ``where`` expression as ``{_not: {condition}}``. This reads as: fetch if not (any of the nested objects satisfy the condition) i.e. none of the nested objects satisy the condition. For example,