hasura/graphql-engine
1
0
Fork 0
mirror of https://github.com/hasura/graphql-engine.git synced 2024-09-20 06:58:39 +03:00
Code Issues Projects Releases Wiki Activity

docs: add mapping of hasura operators - pg operators (close #4056) (#4502)

Browse Source
This commit is contained in:
Marion Schleifer 2020-04-23 14:06:54 +02:00 committed by GitHub
parent f3558d5278
commit b3d814e56f
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
5 changed files with 208 additions and 95 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

7
CHANGELOG.md
View File

@ -23,6 +23,13 @@ Along with the check for filtering rows that can be updated, you can now set a p
(close #4142) (#4313)
### docs: map Postgres operators to corresponding Hasura operators
Map Postgres operators to corresponding Hasura operators at various places in docs and link to PG documentation for reference.
For example, see [here](https://hasura.io/docs/1.0/graphql/manual/api-reference/schema-metadata-api/syntax-defs.html#operator).
(#4502) (close #4056)
### Bug fixes and improvements
- server: add support for `_inc` on `real`, `double`, `numeric` and `money` (fix #3573)

5
docs/CONTRIBUTING.md
View File

@ -107,6 +107,11 @@ syntax in which case you'll have to set the language type to `none` to avoid war
- Use `:ref:` instead of `:doc:` to link to pages to avoid having to set the relative path and chances of broken links
while moving pages
### Reference links
- For external links, add a double `_` in the end to avoid `Duplicate explicit target name` warnings , e.g. \``Google <https://www.google.com/>__`\`
- If you link to an external resource, make sure to link to the most current version of the same, e.g. `https://www.postgresql.org/docs/current/intro-whatis.html` rather than `https://www.postgresql.org/docs/9.6/intro-whatis.html`
### Pre-commit checks
- Just before committing your changes, delete your local `_build` folder completely and then build docs again. Scan
the output and look for any syntax warnings (e.g. title underline too short, could not lex literal block, etc.).

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

@ -422,33 +422,88 @@ ColumnExp
Operator
########
.. _generic_operators:
**Generic operators (all column types except json, jsonb):**
- ``_eq``
- ``_neq``
- ``_in``
- ``_nin``
- ``_gt``
- ``_lt``
- ``_gte``
- ``_lte``
.. list-table::
:header-rows: 1
* - Operator
- PostgreSQL equivalent
* - ``_eq``
- ``=``
* - ``_neq``
- ``<>``
* - ``_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_operators:
**Text related operators:**
- ``_like``
- ``_nlike``
- ``_ilike``
- ``_nilike``
- ``_similar``
- ``_nsimilar``
.. 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>`__.)
.. _null_expression:
**Checking for NULL values:**
- ``_is_null`` (takes true/false as 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>`__.)
.. _type_casting:
**Type casting:**
- ``_cast`` (takes a CastExp_ as a value)
.. list-table::
:header-rows: 1
* - Operator
- PostgreSQL equivalent
* - ``_cast`` (takes a CastExp_ as a value)
- ``::``
(For more details on type casting, refer to the `Postgres docs <https://www.postgresql.org/docs/current/sql-createcast.html>`__.)
.. _jsonb_operators:
**JSONB operators:**
@ -464,11 +519,13 @@ Operator
* - ``_has_key``
- ``?``
* - ``_has_keys_any``
- ``?|``
- ``?!``
* - ``_has_keys_all``
- ``?&``
(For more details on what these operators do, refer to the `Postgres docs <https://www.postgresql.org/docs/current/static/functions-json.html#FUNCTIONS-JSONB-OP-TABLE>`__).
(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>`__.)
.. _geometry_operators:
**PostGIS related operators on GEOMETRY columns:**
@ -478,23 +535,23 @@ Operator
* - Operator
- PostGIS equivalent
* - ``_st_contains``
- ``ST_Contains``
- ``ST_Contains(column, input)``
* - ``_st_crosses``
- ``ST_Crosses``
- ``ST_Crosses(column, input)``
* - ``_st_equals``
- ``ST_Equals``
- ``ST_Equals(column, input)``
* - ``_st_intersects``
- ``ST_Intersects``
- ``ST_Intersects(column, input)``
* - ``_st_overlaps``
- ``ST_Overlaps``
- ``ST_Overlaps(column, input)``
* - ``_st_touches``
- ``ST_Touches``
- ``ST_Touches(column, input)``
* - ``_st_within``
- ``ST_Within``
- ``ST_Within(column, input)``
* - ``_st_d_within``
- ``ST_DWithin``
- ``ST_DWithin(column, input)``
(For more details on what these operators do, refer to the `PostGIS docs <http://postgis.net/workshops/postgis-intro/spatial_relationships.html>`__).
(For more details on spatial relationship operators, refer to the `PostGIS docs <http://postgis.net/workshops/postgis-intro/spatial_relationships.html>`__.)
.. note::
@ -507,39 +564,27 @@ Operator
field-name : {_st_d_within: {distance: Float, from: Value} }
}
.. _intersect_operators:
**Intersect Operators on RASTER columns:**
- ``_st_intersects_rast``
.. list-table::
:header-rows: 1
Executes ``boolean ST_Intersects( raster <raster-column> , raster <input-raster> )``
.. parsed-literal ::
{ _st_intersects_rast: raster }
- ``_st_intersects_nband_geom``
Executes ``boolean ST_Intersects( raster <raster-column> , integer nband , geometry geommin )``
This accepts ``st_intersects_nband_geom_input`` input object
.. parsed-literal ::
{ _st_intersects_nband_geom: {nband: Integer! geommin: geometry!}
- ``_st_intersects_geom_nband``
Executes ``boolean ST_Intersects( raster <raster-column> , geometry geommin , integer nband = NULL )``
This accepts ``st_intersects_geom_nband_input`` input object
.. parsed-literal ::
{ _st_intersects_geom_nband: {geommin: geometry! nband: Integer }
* - Operator
- PostgreSQL equivalent
- Input object
* - ``_st_intersects_rast``
- ``ST_Intersects(column, value)``
- ``{ _st_intersects_rast: raster }``
* - ``_st_intersects_nband_geom``
- ``ST_Intersects(column, nband, geommin)``
- ``{ _st_intersects_nband_geom: {nband: Integer! geommin: geometry!}``
* - ``_st_intersects_geom_nband``
- ``ST_Intersects(column, geommin, nband)``
- ``{ _st_intersects_geom_nband: {geommin: geometry! nband: Integer }``
(For more details on intersect operators on ``raster`` columns refer to the `PostGIS docs <https://postgis.net/docs/RT_ST_Intersects.html>`__.)
.. _CastExp:

113
docs/graphql/manual/api-reference/schema-metadata-api/syntax-defs.rst
View File

@ -290,36 +290,85 @@ Operator
**Generic operators (all column types except json, jsonb) :**
- ``"$eq"``
- ``"$ne"``
- ``"$in"``
- ``"$nin"``
- ``"$gt"``
- ``"$lt"``
- ``"$gte"``
- ``"$lte"``
.. 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 :**
- ``"$like"``
- ``"$nlike"``
- ``"$ilike"``
- ``"$nilike"``
- ``"$similar"``
- ``"$nsimilar"``
.. 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):**
- ``"$ceq"``
- ``"$cne"``
- ``"$cgt"``
- ``"$clt"``
- ``"$cgte"``
- ``"$clte"``
.. 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 :**
- ``_is_null`` (takes true/false as 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 :**
@ -335,11 +384,11 @@ Operator
* - ``_has_key``
- ``?``
* - ``_has_keys_any``
- ``?|``
- ``?!``
* - ``_has_keys_all``
- ``?&``
(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>`__.)
(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:**
@ -349,23 +398,23 @@ Operator
* - Operator
- PostGIS equivalent
* - ``_st_contains``
- ``ST_Contains``
- ``ST_Contains(column, input)``
* - ``_st_crosses``
- ``ST_Crosses``
- ``ST_Crosses(column, input)``
* - ``_st_equals``
- ``ST_Equals``
- ``ST_Equals(column, input)``
* - ``_st_intersects``
- ``ST_Intersects``
- ``ST_Intersects(column, input)``
* - ``_st_overlaps``
- ``ST_Overlaps``
- ``ST_Overlaps(column, input)``
* - ``_st_touches``
- ``ST_Touches``
- ``ST_Touches(column, input)``
* - ``_st_within``
- ``ST_Within``
- ``ST_Within(column, input)``
* - ``_st_d_within``
- ``ST_DWithin``
- ``ST_DWithin(column, input)``
(For more details on what these operators do, refer to `PostGIS docs <http://postgis.net/workshops/postgis-intro/spatial_relationships.html>`__).
(For more details on spatial relationship operators, refer to the `PostGIS docs <http://postgis.net/workshops/postgis-intro/spatial_relationships.html>`__.)
.. note::

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

@ -69,6 +69,8 @@ The ``_eq`` (equal to) or the ``_neq`` (not equal to) operators are compatible w
``json`` or ``jsonB`` (like ``Integer``, ``Float``, ``Double``, ``Text``, ``Boolean``,
``Date``/``Time``/``Timestamp``, etc.).
For more details on equality operators and Postgres equivalents, refer to the :ref:`API reference <generic_operators>`.
The following are examples of using the equality operators on different types.
**Example: Integer (works with Double, Float, Numeric, etc.)**
@ -206,6 +208,8 @@ The ``_gt`` (greater than), ``_lt`` (less than), ``_gte`` (greater than or equal
``_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.).
For more details on greater than or less than operators and Postgres equivalents, refer to the :ref:`API reference <generic_operators>`.
The following are examples of using these operators on different types:
@ -331,6 +335,8 @@ The ``_in`` (in a list) and ``_nin`` (not in list) operators are used to compare
They are compatible with any Postgres type other than ``json`` or ``jsonB`` (like ``Integer``, ``Float``, ``Double``,
``Text``, ``Boolean``, ``Date``/``Time``/``Timestamp``, etc.).
For more details on list based search operators and Postgres equivalents, refer to the :ref:`API reference <generic_operators>`.
The following are examples of using these operators on different types:
**Example: Integer (works with Double, Float, etc.)**
@ -422,7 +428,7 @@ Text search or pattern matching operators (_like, _similar, etc.)
The ``_like``, ``_nlike``, ``_ilike``, ``_nilike``, ``_similar``, ``_nsimilar`` operators are used for
pattern matching on string/text fields.
These operators behave exactly like their `SQL counterparts <https://www.postgresql.org/docs/current/static/functions-matching.html>`__
For more details on text search operators and Postgres equivalents, refer to the :ref:`API reference <text_operators>`.
**Example: _like**
@ -511,7 +517,7 @@ JSONB operators (_contains, _has_key, etc.)
The ``_contains``, ``_contained_in``, ``_has_key``, ``_has_keys_any`` and ``_has_keys_all`` operators are used to filter
based on ``JSONB`` columns.
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>`__.
For more details on JSONB operators and Postgres equivalents, refer to the :ref:`API reference <jsonb_operators>`.
**Example: _contains**
@ -602,8 +608,7 @@ The ``_st_contains``, ``_st_crosses``, ``_st_equals``, ``_st_intersects``, ``_st
``_st_d_within`` and ``_st_intersects`` can be used on ``geography`` columns also.
For more details on what these operators do, refer to
`PostGIS spatial relationship docs <http://postgis.net/workshops/postgis-intro/spatial_relationships.html>`_.
For more details on spatial relationship operators and Postgres equivalents, refer to the :ref:`API reference <geometry_operators>`.
Use JSON representation (see `GeoJSON <https://tools.ietf.org/html/rfc7946>`_) of ``geometry`` and ``geography`` values in
``variables`` as shown in the following examples:
@ -712,6 +717,8 @@ Filter or check for null values (_is_null)
Checking for null values can be achieved using the ``_is_null`` operator.
For more details on the ``_is_null`` operator and Postgres equivalent, refer to the :ref:`API reference <null_expression>`.
**Example: Filter null values in a field**
Fetch a list of articles that have a value in the ``published_on`` field:
@ -760,8 +767,9 @@ Intersect operators on RASTER columns (_st_intersects_rast, etc)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Intersect operators on columns with ``raster`` type are supported.
Refer to `Postgis docs <https://postgis.net/docs/RT_ST_Intersects.html>`__ to know more about intersect functions on ``raster`` columns.
Please submit a feature request via `github <https://github.com/hasura/graphql-engine>`__ if you want support for more functions.
Please submit a feature request via `GitHub <https://github.com/hasura/graphql-engine>`__ if you want support for more functions.
For more details on intersect operators on raster columns and Postgres equivalents, refer to the :ref:`API reference <intersect_operators>`.
**Example: _st_intersects_rast**
@ -975,7 +983,6 @@ Using multiple filters in the same query (_and, _or)
You can group multiple parameters in the same ``where`` argument using the ``_and`` or the ``_or`` operators to filter
results based on more than one criteria.
.. note::
You can use the ``_or`` and ``_and`` operators along with the ``_not`` operator to create arbitrarily complex boolean
expressions involving multiple filtering criteria.