hasura/graphql-engine
1
0
Fork 0
mirror of https://github.com/hasura/graphql-engine.git synced 2024-12-15 01:12:56 +03:00
Code Issues Projects Releases Wiki Activity

update query/mutation docs pages (#1426)

Browse Source
This commit is contained in:
Rikin Kachhia 2019-01-21 14:50:14 +05:30 committed by GitHub
parent 2e72760852
commit 6ec47a94c8
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
7 changed files with 96 additions and 82 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

15
docs/graphql/manual/api-reference/query.rst
View File

@ -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 <https://www.postgresql.org/docs/current/static/functions-json.html#FUNCTIONS-JSONB-OP-TABLE>`__.)
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 <http://postgis.net/workshops/postgis-intro/spatial_relationships.html>`__.)
.. 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::

8
docs/graphql/manual/mutations/delete.rst
View File

@ -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_<schema_name>_<table_name>``.
Delete based on an object's fields
----------------------------------
**Example:** Delete all articles rated less than 3:

11
docs/graphql/manual/mutations/index.rst
View File

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

8
docs/graphql/manual/mutations/insert.rst
View File

@ -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 <upsert>`
- 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_<schema_name>_<table_name>``.
Insert a single object
----------------------
**Example:** Insert a new ``article`` object and return the inserted article object in the response

10
docs/graphql/manual/mutations/update.rst
View File

@ -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_<schema_name>_<table_name>``.
Update based on an object's fields
----------------------------------

12
docs/graphql/manual/queries/index.rst
View File

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

114
docs/graphql/manual/queries/query-filters.rst
View File

@ -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 <Operator>` that can be used in the ``where`` argument to filter on
equality.
Here ``_eq`` and ``_gt`` are examples of :ref:`comparison operators <Operator>` 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 <http://postgis.net/workshops/postgis-intro/spatial_relationships.html>`__.
Use ``json`` (`GeoJSON <https://tools.ietf.org/html/rfc7946>`_) representation of ``geometry`` values in ``variables`` as shown in the following examples
Use ``json`` (`GeoJSON <https://tools.ietf.org/html/rfc7946>`_) 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,