From ae28ba5875c8b67686b0e7d6b4caf7afc8fb192e Mon Sep 17 00:00:00 2001 From: Marion Schleifer Date: Tue, 21 Apr 2020 12:03:02 +0200 Subject: [PATCH 01/22] add tables for operators --- .../schema-metadata-api/syntax-defs.rst | 84 ++++++++++++++----- 1 file changed, 63 insertions(+), 21 deletions(-) diff --git a/docs/graphql/manual/api-reference/schema-metadata-api/syntax-defs.rst b/docs/graphql/manual/api-reference/schema-metadata-api/syntax-defs.rst index e98e496a57974..d0f327fa2b8d1 100644 --- a/docs/graphql/manual/api-reference/schema-metadata-api/syntax-defs.rst +++ b/docs/graphql/manual/api-reference/schema-metadata-api/syntax-defs.rst @@ -290,36 +290,78 @@ 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"`` + - + * - ``"$in"`` + - + * - ``"$nin"`` + - + * - ``"$gt"`` + - + * - ``"$lt"`` + - + * - ``"$gte"`` + - + * - ``"$lte"`` + - **Text related operators :** -- ``"$like"`` -- ``"$nlike"`` -- ``"$ilike"`` -- ``"$nilike"`` -- ``"$similar"`` -- ``"$nsimilar"`` +.. list-table:: + :header-rows: 1 + + * - Operator + - PostgreSQL equivalent + * - ``"$like"`` + - + * - ``"$nlike"`` + - + * - ``"$ilike"`` + - + * - ``"$nilike"`` + - + * - ``"$similar"`` + - + * - ``"$nsimilar"`` + - + **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"`` + - **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) + - **JSONB operators :** From f905505edda9b6a24b6fae259d6b193dd80ee394 Mon Sep 17 00:00:00 2001 From: Marion Schleifer Date: Tue, 21 Apr 2020 13:21:01 +0200 Subject: [PATCH 02/22] more operators --- .../schema-metadata-api/syntax-defs.rst | 14 +- docs/graphql/manual/queries/query-filters.rst | 135 +++++++++++++++++- 2 files changed, 139 insertions(+), 10 deletions(-) diff --git a/docs/graphql/manual/api-reference/schema-metadata-api/syntax-defs.rst b/docs/graphql/manual/api-reference/schema-metadata-api/syntax-defs.rst index d0f327fa2b8d1..db43af334b133 100644 --- a/docs/graphql/manual/api-reference/schema-metadata-api/syntax-defs.rst +++ b/docs/graphql/manual/api-reference/schema-metadata-api/syntax-defs.rst @@ -320,17 +320,17 @@ Operator * - Operator - PostgreSQL equivalent * - ``"$like"`` - - + - ``like`` * - ``"$nlike"`` - - + - ``nlike`` * - ``"$ilike"`` - - + - ``ilike`` * - ``"$nilike"`` - - + - ``nilike`` * - ``"$similar"`` - - + - ``similar`` * - ``"$nsimilar"`` - - + - ``nsimilar`` **Operators for comparing columns (all column types except json, jsonb):** @@ -361,7 +361,7 @@ Operator * - Operator - PostgreSQL equivalent * - ``_is_null`` (takes true/false as values) - - + - ``NOT NULL`` **JSONB operators :** diff --git a/docs/graphql/manual/queries/query-filters.rst b/docs/graphql/manual/queries/query-filters.rst index 12bce60ec3865..8e37ff173fc93 100644 --- a/docs/graphql/manual/queries/query-filters.rst +++ b/docs/graphql/manual/queries/query-filters.rst @@ -69,6 +69,16 @@ 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.). +.. list-table:: + :header-rows: 1 + + * - Operator + - PostgreSQL equivalent + * - ``_eq`` + - ``=`` + * - ``_neq`` + - ``<>`` + The following are examples of using the equality operators on different types. **Example: Integer (works with Double, Float, Numeric, etc.)** @@ -206,6 +216,20 @@ 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.). +.. list-table:: + :header-rows: 1 + + * - Operator + - PostgreSQL equivalent + * - ``_gt`` + - ``>`` + * - ``_lt`` + - ``<`` + * - ``_gte`` + - ``>=`` + * - ``_lte`` + - ``<=`` + The following are examples of using these operators on different types: @@ -331,6 +355,16 @@ 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.). +.. list-table:: + :header-rows: 1 + + * - Operator + - PostgreSQL equivalent + * - ``_in`` + - + * - ``_nin`` + - ``!!=`` + The following are examples of using these operators on different types: **Example: Integer (works with Double, Float, etc.)** @@ -422,7 +456,25 @@ 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 `__ +.. list-table:: + :header-rows: 1 + + * - Operator + - PostgreSQL equivalent + * - ``_like`` + - ``_like`` + * - ``_nlike`` + - ``_nlike`` + * - ``_ilike`` + - ``_ilike`` + * - ``_nilike`` + - ``_nilike`` + * - ``_similar`` + - ``_similar`` + * - ``_nsimilar`` + - ``_nsimilar`` + +These operators behave exactly like their `SQL counterparts `__. **Example: _like** @@ -511,6 +563,22 @@ JSONB operators (_contains, _has_key, etc.) The ``_contains``, ``_contained_in``, ``_has_key``, ``_has_key_any`` and ``_has_key_all`` operators are used to filter based on ``JSONB`` columns. +.. list-table:: + :header-rows: 1 + + * - Operator + - PostgreSQL equivalent + * - ``_contains`` + - ``@>`` + * - ``_contained_in`` + - ``<@`` + * - ``_has_key`` + - ``?`` + * - ``_has_key_any`` + - ``?|`` + * - ``_has_key_all`` + - ``?&`` + For more details on what these operators do, refer to `Postgres docs `__. **Example: _contains** @@ -602,6 +670,28 @@ The ``_st_contains``, ``_st_crosses``, ``_st_equals``, ``_st_intersects``, ``_st ``_st_d_within`` and ``_st_intersects`` can be used on ``geography`` columns also. +.. list-table:: + :header-rows: 1 + + * - Operator + - PostGIS equivalent + * - ``_st_contains`` + - ``ST_Contains`` + * - ``_st_crosses`` + - ``ST_Crosses`` + * - ``_st_equals`` + - ``ST_Equals`` + * - ``_st_intersects`` + - ``ST_Intersect`` + * - ``_st_overlaps`` + - ``ST_Overlaps`` + * - ``_st_touches`` + - ``ST_Touches`` + * - ``_st_within`` + - ``ST_Within`` + * - ``_st_d_within`` + - ``ST_DWithin`` + For more details on what these operators do, refer to `PostGIS spatial relationship docs `_. @@ -712,6 +802,14 @@ Filter or check for null values (_is_null) Checking for null values can be achieved using the ``_is_null`` operator. +.. list-table:: + :header-rows: 1 + + * - Operator + - PostgreSQL equivalent + * - ``_is_null`` + - ``IS NULL`` + **Example: Filter null values in a field** Fetch a list of articles that have a value in the ``published_on`` field: @@ -760,8 +858,21 @@ Intersect operators on RASTER columns (_st_intersects_rast, etc) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Intersect operators on columns with ``raster`` type are supported. +Please submit a feature request via `GitHub `__ if you want support for more functions. + +.. list-table:: + :header-rows: 1 + + * - Operator + - PostgreSQL equivalent + * - ``_st_intersects_rast`` + - + * - ``_st_intersects_geom_nband`` + - + * - ``_st_intersects_nband_geom`` + - + Refer to `Postgis docs `__ to know more about intersect functions on ``raster`` columns. -Please submit a feature request via `github `__ if you want support for more functions. **Example: _st_intersects_rast** @@ -914,6 +1025,14 @@ Filter based on failure of some criteria (_not) The ``_not`` operator can be used to fetch results for which some condition does not hold true. i.e. to invert the filter set for a condition. +.. list-table:: + :header-rows: 1 + + * - Operator + - PostgreSQL equivalent + * - ``_not`` + - ``NOT`` + **Example: _not** Fetch all authors who don't have any published articles: @@ -970,11 +1089,21 @@ Fetch all authors who don't have any published articles: } 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. +.. list-table:: + :header-rows: 1 + + * - Operator + - PostgreSQL equivalent + * - ``_and`` + - ``AND`` + * - ``_or`` + - ``OR`` + .. note:: You can use the ``_or`` and ``_and`` operators along with the ``_not`` operator to create arbitrarily complex boolean From 4e09b9236639c453714c8b5575cab1f9e15e7563 Mon Sep 17 00:00:00 2001 From: Marion Schleifer Date: Tue, 21 Apr 2020 13:40:06 +0200 Subject: [PATCH 03/22] add links to postgres docs --- docs/graphql/manual/queries/query-filters.rst | 34 ++++++++++++++++--- 1 file changed, 29 insertions(+), 5 deletions(-) diff --git a/docs/graphql/manual/queries/query-filters.rst b/docs/graphql/manual/queries/query-filters.rst index 8e37ff173fc93..0affa23a990ce 100644 --- a/docs/graphql/manual/queries/query-filters.rst +++ b/docs/graphql/manual/queries/query-filters.rst @@ -79,6 +79,10 @@ The ``_eq`` (equal to) or the ``_neq`` (not equal to) operators are compatible w * - ``_neq`` - ``<>`` +.. note:: + + Please refer to the `Postgres documentation `_ for more details on these operators. + The following are examples of using the equality operators on different types. **Example: Integer (works with Double, Float, Numeric, etc.)** @@ -230,6 +234,10 @@ The ``_gt`` (greater than), ``_lt`` (less than), ``_gte`` (greater than or equal * - ``_lte`` - ``<=`` +.. note:: + + Please refer to the `Postgres documentation `_ for more details on these operators. + The following are examples of using these operators on different types: @@ -365,6 +373,10 @@ They are compatible with any Postgres type other than ``json`` or ``jsonB`` (lik * - ``_nin`` - ``!!=`` +.. note:: + + Please refer to the `Postgres documentation `_ for more details on search operators. + The following are examples of using these operators on different types: **Example: Integer (works with Double, Float, etc.)** @@ -474,7 +486,10 @@ pattern matching on string/text fields. * - ``_nsimilar`` - ``_nsimilar`` -These operators behave exactly like their `SQL counterparts `__. +.. note:: + + These operators behave exactly like their SQL counterparts. + Please refer to the `Postgres documentation `_ for more details on pattern matching operators. **Example: _like** @@ -579,7 +594,9 @@ based on ``JSONB`` columns. * - ``_has_key_all`` - ``?&`` -For more details on what these operators do, refer to `Postgres docs `__. +.. note:: + + Please refer to the `Postgres documentation `_ for more details on JSONB operators. **Example: _contains** @@ -692,8 +709,9 @@ The ``_st_contains``, ``_st_crosses``, ``_st_equals``, ``_st_intersects``, ``_st * - ``_st_d_within`` - ``ST_DWithin`` -For more details on what these operators do, refer to -`PostGIS spatial relationship docs `_. +.. note:: + + Please refer to the `Postgres documentation `_ for more details on spatial relationship operators. Use JSON representation (see `GeoJSON `_) of ``geometry`` and ``geography`` values in ``variables`` as shown in the following examples: @@ -810,6 +828,10 @@ Checking for null values can be achieved using the ``_is_null`` operator. * - ``_is_null`` - ``IS NULL`` +.. note:: + + Please refer to the `Postgres documentation `_ for more details on the ``_is_null`` operator. + **Example: Filter null values in a field** Fetch a list of articles that have a value in the ``published_on`` field: @@ -872,7 +894,9 @@ Please submit a feature request via `GitHub `__ to know more about intersect functions on ``raster`` columns. +.. note:: + + Please refer to the `Postgres documentation `_ for more details about intersect functions on ``raster`` columns. **Example: _st_intersects_rast** From f3edc5afa1909138fa3bed726eacff0f7d49b196 Mon Sep 17 00:00:00 2001 From: Marion Schleifer Date: Tue, 21 Apr 2020 13:50:30 +0200 Subject: [PATCH 04/22] misc fixes --- docs/graphql/manual/queries/query-filters.rst | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/docs/graphql/manual/queries/query-filters.rst b/docs/graphql/manual/queries/query-filters.rst index 0affa23a990ce..f79c9834e1bd6 100644 --- a/docs/graphql/manual/queries/query-filters.rst +++ b/docs/graphql/manual/queries/query-filters.rst @@ -77,11 +77,11 @@ The ``_eq`` (equal to) or the ``_neq`` (not equal to) operators are compatible w * - ``_eq`` - ``=`` * - ``_neq`` - - ``<>`` + - ``<>`` or ``!=`` .. note:: - Please refer to the `Postgres documentation `_ for more details on these operators. + Please refer to the `Postgres documentation `_ for more details on equality operators. The following are examples of using the equality operators on different types. @@ -236,7 +236,7 @@ The ``_gt`` (greater than), ``_lt`` (less than), ``_gte`` (greater than or equal .. note:: - Please refer to the `Postgres documentation `_ for more details on these operators. + Please refer to the `Postgres documentation `_ for more details on these operators. The following are examples of using these operators on different types: @@ -1057,6 +1057,10 @@ filter set for a condition. * - ``_not`` - ``NOT`` +.. note:: + + Please refer to the `Postgres documentation `_ for more details on the ``NOT`` operator. + **Example: _not** Fetch all authors who don't have any published articles: @@ -1128,6 +1132,9 @@ results based on more than one criteria. * - ``_or`` - ``OR`` +.. note:: + + Please refer to the `Postgres documentation `_ for more details on these operators. .. note:: You can use the ``_or`` and ``_and`` operators along with the ``_not`` operator to create arbitrarily complex boolean From 174a5a4bba7a9fd41e2fcb7a6fc062bf9b093ee3 Mon Sep 17 00:00:00 2001 From: Marion Schleifer Date: Tue, 21 Apr 2020 21:38:05 +0200 Subject: [PATCH 05/22] add to changelog --- CHANGELOG.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index c08c15be23713..bd6f6cbee0f60 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -22,6 +22,10 @@ The order, collapsed state of columns and page size is now persisted across page (close #3390) (#3753) +### Docs improvements + +- Map Postgres operators to corresponding Hasura operators in docs and link to PG documentation (close #4056) + ### Bug fixes and improvements - cli: set_table_is_enum metadata type for squashing migrations (close #4394) (#4395) @@ -49,7 +53,7 @@ The order, collapsed state of columns and page size is now persisted across page - server: `type` field is not required if `jwk_url` is provided in JWT config - server: add a new field `claims_namespace_path` which accepts a JSON Path for looking up hasura claim in the JWT token (#4349) - server: support reusing Postgres scalars in custom types (close #4125) - + ## `v1.2.0-beta.3` ### console: manage Postgres check constraints From f79283af391c4e565d5f732e9c84cb25514c9eb0 Mon Sep 17 00:00:00 2001 From: Marion Schleifer Date: Tue, 21 Apr 2020 21:40:37 +0200 Subject: [PATCH 06/22] add pr to changelog --- CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index bd6f6cbee0f60..78c2869215fb3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -24,7 +24,7 @@ The order, collapsed state of columns and page size is now persisted across page ### Docs improvements -- Map Postgres operators to corresponding Hasura operators in docs and link to PG documentation (close #4056) +- Map Postgres operators to corresponding Hasura operators in docs and link to PG documentation (#4502) (close #4056) ### Bug fixes and improvements From 0c39f447fc8c7778c41f21d7ee7eb287f48ae577 Mon Sep 17 00:00:00 2001 From: Marion Schleifer Date: Tue, 21 Apr 2020 21:50:46 +0200 Subject: [PATCH 07/22] small fix --- docs/graphql/manual/queries/query-filters.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/graphql/manual/queries/query-filters.rst b/docs/graphql/manual/queries/query-filters.rst index f79c9834e1bd6..d748ce7192b18 100644 --- a/docs/graphql/manual/queries/query-filters.rst +++ b/docs/graphql/manual/queries/query-filters.rst @@ -830,7 +830,7 @@ Checking for null values can be achieved using the ``_is_null`` operator. .. note:: - Please refer to the `Postgres documentation `_ for more details on the ``_is_null`` operator. + Please refer to the `Postgres documentation `_ for more details on the ``IS NULL`` construct. **Example: Filter null values in a field** From cc114e1ea58af722d017804df6dc654d5b3f0b91 Mon Sep 17 00:00:00 2001 From: Marion Schleifer Date: Wed, 22 Apr 2020 16:02:27 +0200 Subject: [PATCH 08/22] add rest of operators --- .../schema-metadata-api/syntax-defs.rst | 60 +++++++++---------- docs/graphql/manual/queries/query-filters.rst | 44 +++++++------- 2 files changed, 52 insertions(+), 52 deletions(-) diff --git a/docs/graphql/manual/api-reference/schema-metadata-api/syntax-defs.rst b/docs/graphql/manual/api-reference/schema-metadata-api/syntax-defs.rst index db43af334b133..139ebd87a232a 100644 --- a/docs/graphql/manual/api-reference/schema-metadata-api/syntax-defs.rst +++ b/docs/graphql/manual/api-reference/schema-metadata-api/syntax-defs.rst @@ -296,21 +296,21 @@ Operator * - Operator - PostgreSQL equivalent * - ``"$eq"`` - - + - ``=`` * - ``"$ne"`` - - + - ``<>`` * - ``"$in"`` - - + - ``IN`` * - ``"$nin"`` - - + - ``NOT IN`` * - ``"$gt"`` - - + - ``>`` * - ``"$lt"`` - - + - ``<`` * - ``"$gte"`` - - + - ``>=`` * - ``"$lte"`` - - + - ``<=`` **Text related operators :** @@ -320,17 +320,17 @@ Operator * - Operator - PostgreSQL equivalent * - ``"$like"`` - - ``like`` + - ``LIKE`` * - ``"$nlike"`` - - ``nlike`` + - ``NOT LIKE`` * - ``"$ilike"`` - - ``ilike`` + - ``ILIKE`` * - ``"$nilike"`` - - ``nilike`` + - ``NOT ILIKE`` * - ``"$similar"`` - - ``similar`` + - ``SIMILAR TO`` * - ``"$nsimilar"`` - - ``nsimilar`` + - ``NOT SIMILAR TO`` **Operators for comparing columns (all column types except json, jsonb):** @@ -341,17 +341,17 @@ Operator * - Operator - PostgreSQL equivalent * - ``"$ceq"`` - - + - ``=`` * - ``"$cne"`` - - + - ``<>`` * - ``"$cgt"`` - - + - ``>`` * - ``"$clt"`` - - + - ``<`` * - ``"$cgte"`` - - + - ``>=`` * - ``"$clte"`` - - + - ``<=`` **Checking for NULL values :** @@ -361,7 +361,7 @@ Operator * - Operator - PostgreSQL equivalent * - ``_is_null`` (takes true/false as values) - - ``NOT NULL`` + - ``IS NULL`` **JSONB operators :** @@ -377,7 +377,7 @@ Operator * - ``_has_key`` - ``?`` * - ``_has_keys_any`` - - ``?|`` + - ``?!`` * - ``_has_keys_all`` - ``?&`` @@ -391,21 +391,21 @@ Operator * - Operator - PostGIS equivalent * - ``_st_contains`` - - ``ST_Contains`` + - ``ST_Contains(lhs, val)`` * - ``_st_crosses`` - - ``ST_Crosses`` + - ``ST_Crosses(lhs, val)`` * - ``_st_equals`` - - ``ST_Equals`` + - ``ST_Equals(lhs, val)`` * - ``_st_intersects`` - - ``ST_Intersects`` + - ``ST_Intersects(lht, val)`` * - ``_st_overlaps`` - - ``ST_Overlaps`` + - ``ST_Overlaps(lhs, val)`` * - ``_st_touches`` - - ``ST_Touches`` + - ``ST_Touches(lhs, val)`` * - ``_st_within`` - - ``ST_Within`` + - ``ST_within(lhs, val)`` * - ``_st_d_within`` - - ``ST_DWithin`` + - ``ST_DWithin(lhs, val)`` (For more details on what these operators do, refer to `PostGIS docs `__). diff --git a/docs/graphql/manual/queries/query-filters.rst b/docs/graphql/manual/queries/query-filters.rst index d748ce7192b18..09575bc6fb481 100644 --- a/docs/graphql/manual/queries/query-filters.rst +++ b/docs/graphql/manual/queries/query-filters.rst @@ -77,7 +77,7 @@ The ``_eq`` (equal to) or the ``_neq`` (not equal to) operators are compatible w * - ``_eq`` - ``=`` * - ``_neq`` - - ``<>`` or ``!=`` + - ``<>`` .. note:: @@ -369,13 +369,13 @@ They are compatible with any Postgres type other than ``json`` or ``jsonB`` (lik * - Operator - PostgreSQL equivalent * - ``_in`` - - + - ``IN`` * - ``_nin`` - - ``!!=`` + - ``NOT IN`` .. note:: - Please refer to the `Postgres documentation `_ for more details on search operators. + Please refer to the `Postgres documentation `_ for more details on search operators. The following are examples of using these operators on different types: @@ -474,17 +474,17 @@ pattern matching on string/text fields. * - Operator - PostgreSQL equivalent * - ``_like`` - - ``_like`` + - ``LIKE`` * - ``_nlike`` - - ``_nlike`` + - ``NOT LIKE`` * - ``_ilike`` - - ``_ilike`` + - ``ILIKE`` * - ``_nilike`` - - ``_nilike`` + - ``NOT ILIKE`` * - ``_similar`` - - ``_similar`` + - ``SIMILAR TO`` * - ``_nsimilar`` - - ``_nsimilar`` + - ``NOT SIMILAR TO`` .. note:: @@ -590,7 +590,7 @@ based on ``JSONB`` columns. * - ``_has_key`` - ``?`` * - ``_has_key_any`` - - ``?|`` + - ``?!`` * - ``_has_key_all`` - ``?&`` @@ -693,21 +693,21 @@ The ``_st_contains``, ``_st_crosses``, ``_st_equals``, ``_st_intersects``, ``_st * - Operator - PostGIS equivalent * - ``_st_contains`` - - ``ST_Contains`` + - ``ST_Contains(lhs, val)`` * - ``_st_crosses`` - - ``ST_Crosses`` + - ``ST_Crosses(lhs, val)`` * - ``_st_equals`` - - ``ST_Equals`` + - ``ST_Equals(lhs, val)`` * - ``_st_intersects`` - - ``ST_Intersect`` + - ``ST_Intersect(lht, val)`` * - ``_st_overlaps`` - - ``ST_Overlaps`` + - ``ST_Overlaps(lhs, val)`` * - ``_st_touches`` - - ``ST_Touches`` + - ``ST_Touches(lhs, val)`` * - ``_st_within`` - - ``ST_Within`` + - ``ST_Within(lhs, val)`` * - ``_st_d_within`` - - ``ST_DWithin`` + - ``ST_DWithin(lhs, val)`` .. note:: @@ -888,11 +888,11 @@ Please submit a feature request via `GitHub Date: Wed, 22 Apr 2020 20:45:39 +0530 Subject: [PATCH 09/22] Update CHANGELOG.md --- CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 78c2869215fb3..98d4cf55bb5c3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -22,7 +22,7 @@ The order, collapsed state of columns and page size is now persisted across page (close #3390) (#3753) -### Docs improvements +### Docs - Map Postgres operators to corresponding Hasura operators in docs and link to PG documentation (#4502) (close #4056) From 25cd0daab0310c70dd5dc99416885ede98844e12 Mon Sep 17 00:00:00 2001 From: Tirumarai Selvan Date: Wed, 22 Apr 2020 20:46:43 +0530 Subject: [PATCH 10/22] Update CHANGELOG.md --- CHANGELOG.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 98d4cf55bb5c3..d386cede7a135 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,10 @@ ## Next release +### Docs + +- Map Postgres operators to corresponding Hasura operators in docs and link to PG documentation (#4502) (close #4056) + ### Bug fixes and improvements - server: add support for `_inc` on `real`, `double`, `numeric` and `money` (fix #3573) @@ -22,10 +26,6 @@ The order, collapsed state of columns and page size is now persisted across page (close #3390) (#3753) -### Docs - -- Map Postgres operators to corresponding Hasura operators in docs and link to PG documentation (#4502) (close #4056) - ### Bug fixes and improvements - cli: set_table_is_enum metadata type for squashing migrations (close #4394) (#4395) From 0d4216bcf3c89554ee8ff2a8374d490e66ec709d Mon Sep 17 00:00:00 2001 From: Marion Schleifer Date: Wed, 22 Apr 2020 19:41:07 +0200 Subject: [PATCH 11/22] add to graphql api and fixes --- .../api-reference/graphql-api/query.rst | 86 +++++++++++++------ .../schema-metadata-api/syntax-defs.rst | 16 ++-- docs/graphql/manual/queries/query-filters.rst | 42 ++++----- 3 files changed, 90 insertions(+), 54 deletions(-) diff --git a/docs/graphql/manual/api-reference/graphql-api/query.rst b/docs/graphql/manual/api-reference/graphql-api/query.rst index 05743aad2a728..4325a6dd76a7e 100644 --- a/docs/graphql/manual/api-reference/graphql-api/query.rst +++ b/docs/graphql/manual/api-reference/graphql-api/query.rst @@ -424,31 +424,67 @@ Operator ######## **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`` + - ``<>`` + * - ``_in`` + - ``IN`` + * - ``_nin`` + - ``NOT IN`` + * - ``_gt`` + - ``>`` + * - ``_lt`` + - ``<`` + * - ``_gte`` + - ``>=`` + * - ``_lte`` + - ``<=`` **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`` **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`` **Type casting:** -- ``_cast`` (takes a CastExp_ as a value) +.. list-table:: + :header-rows: 1 + + * - Operator + - PostgreSQL equivalent + * - ``_cast`` (takes a CastExp_ as a value) + - ``::`` **JSONB operators:** @@ -464,7 +500,7 @@ Operator * - ``_has_key`` - ``?`` * - ``_has_keys_any`` - - ``?|`` + - ``?!`` * - ``_has_keys_all`` - ``?&`` @@ -478,21 +514,21 @@ 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_Intersect(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 `__). diff --git a/docs/graphql/manual/api-reference/schema-metadata-api/syntax-defs.rst b/docs/graphql/manual/api-reference/schema-metadata-api/syntax-defs.rst index 139ebd87a232a..04831042a0d89 100644 --- a/docs/graphql/manual/api-reference/schema-metadata-api/syntax-defs.rst +++ b/docs/graphql/manual/api-reference/schema-metadata-api/syntax-defs.rst @@ -391,21 +391,21 @@ Operator * - Operator - PostGIS equivalent * - ``_st_contains`` - - ``ST_Contains(lhs, val)`` + - ``ST_Contains(column, input)`` * - ``_st_crosses`` - - ``ST_Crosses(lhs, val)`` + - ``ST_Crosses(column, input)`` * - ``_st_equals`` - - ``ST_Equals(lhs, val)`` + - ``ST_Equals(column, input)`` * - ``_st_intersects`` - - ``ST_Intersects(lht, val)`` + - ``ST_Intersects(column, input)`` * - ``_st_overlaps`` - - ``ST_Overlaps(lhs, val)`` + - ``ST_Overlaps(column, input)`` * - ``_st_touches`` - - ``ST_Touches(lhs, val)`` + - ``ST_Touches(column, input)`` * - ``_st_within`` - - ``ST_within(lhs, val)`` + - ``ST_within(column, input)`` * - ``_st_d_within`` - - ``ST_DWithin(lhs, val)`` + - ``ST_DWithin(column, input)`` (For more details on what these operators do, refer to `PostGIS docs `__). diff --git a/docs/graphql/manual/queries/query-filters.rst b/docs/graphql/manual/queries/query-filters.rst index 09575bc6fb481..df8e30262609b 100644 --- a/docs/graphql/manual/queries/query-filters.rst +++ b/docs/graphql/manual/queries/query-filters.rst @@ -81,7 +81,7 @@ The ``_eq`` (equal to) or the ``_neq`` (not equal to) operators are compatible w .. note:: - Please refer to the `Postgres documentation `_ for more details on equality operators. + Please refer to the `Postgres documentation `__ for more details on equality operators. The following are examples of using the equality operators on different types. @@ -236,7 +236,7 @@ The ``_gt`` (greater than), ``_lt`` (less than), ``_gte`` (greater than or equal .. note:: - Please refer to the `Postgres documentation `_ for more details on these operators. + Please refer to the `Postgres documentation `__ for more details on these operators. The following are examples of using these operators on different types: @@ -375,7 +375,7 @@ They are compatible with any Postgres type other than ``json`` or ``jsonB`` (lik .. note:: - Please refer to the `Postgres documentation `_ for more details on search operators. + Please refer to the `Postgres documentation `__ for more details on search operators. The following are examples of using these operators on different types: @@ -489,7 +489,7 @@ pattern matching on string/text fields. .. note:: These operators behave exactly like their SQL counterparts. - Please refer to the `Postgres documentation `_ for more details on pattern matching operators. + Please refer to the `Postgres documentation `__ for more details on pattern matching operators. **Example: _like** @@ -596,7 +596,7 @@ based on ``JSONB`` columns. .. note:: - Please refer to the `Postgres documentation `_ for more details on JSONB operators. + Please refer to the `Postgres documentation `__ for more details on JSONB operators. **Example: _contains** @@ -693,25 +693,25 @@ The ``_st_contains``, ``_st_crosses``, ``_st_equals``, ``_st_intersects``, ``_st * - Operator - PostGIS equivalent * - ``_st_contains`` - - ``ST_Contains(lhs, val)`` + - ``ST_Contains(column, input)`` * - ``_st_crosses`` - - ``ST_Crosses(lhs, val)`` + - ``ST_Crosses(column, input)`` * - ``_st_equals`` - - ``ST_Equals(lhs, val)`` + - ``ST_Equals(column, input)`` * - ``_st_intersects`` - - ``ST_Intersect(lht, val)`` + - ``ST_Intersect(column, input)`` * - ``_st_overlaps`` - - ``ST_Overlaps(lhs, val)`` + - ``ST_Overlaps(column, input)`` * - ``_st_touches`` - - ``ST_Touches(lhs, val)`` + - ``ST_Touches(column, input)`` * - ``_st_within`` - - ``ST_Within(lhs, val)`` + - ``ST_Within(column, input)`` * - ``_st_d_within`` - - ``ST_DWithin(lhs, val)`` + - ``ST_DWithin(column, input)`` .. note:: - Please refer to the `Postgres documentation `_ for more details on spatial relationship operators. + Please refer to the `Postgres documentation `__ for more details on spatial relationship operators. Use JSON representation (see `GeoJSON `_) of ``geometry`` and ``geography`` values in ``variables`` as shown in the following examples: @@ -830,7 +830,7 @@ Checking for null values can be achieved using the ``_is_null`` operator. .. note:: - Please refer to the `Postgres documentation `_ for more details on the ``IS NULL`` construct. + Please refer to the `Postgres documentation `__ for more details on the ``IS NULL`` construct. **Example: Filter null values in a field** @@ -888,15 +888,15 @@ Please submit a feature request via `GitHub `_ for more details about intersect functions on ``raster`` columns. + Please refer to the `Postgres documentation `__ for more details about intersect functions on ``raster`` columns. **Example: _st_intersects_rast** @@ -1059,7 +1059,7 @@ filter set for a condition. .. note:: - Please refer to the `Postgres documentation `_ for more details on the ``NOT`` operator. + Please refer to the `Postgres documentation `__ for more details on the ``NOT`` operator. **Example: _not** @@ -1134,7 +1134,7 @@ results based on more than one criteria. .. note:: - Please refer to the `Postgres documentation `_ for more details on these operators. + Please refer to the `Postgres documentation `__ for more details on these operators. .. note:: You can use the ``_or`` and ``_and`` operators along with the ``_not`` operator to create arbitrarily complex boolean From d3cb12f363deccbc74612eb27d0430162e4292af Mon Sep 17 00:00:00 2001 From: Marion Schleifer Date: Thu, 23 Apr 2020 11:20:17 +0200 Subject: [PATCH 12/22] review --- .../api-reference/graphql-api/query.rst | 73 +++++---- .../schema-metadata-api/syntax-defs.rst | 11 +- docs/graphql/manual/queries/query-filters.rst | 153 +----------------- 3 files changed, 58 insertions(+), 179 deletions(-) diff --git a/docs/graphql/manual/api-reference/graphql-api/query.rst b/docs/graphql/manual/api-reference/graphql-api/query.rst index 4325a6dd76a7e..12cc1977ce87f 100644 --- a/docs/graphql/manual/api-reference/graphql-api/query.rst +++ b/docs/graphql/manual/api-reference/graphql-api/query.rst @@ -422,6 +422,9 @@ ColumnExp Operator ######## + +.. _generic_operators: + **Generic operators (all column types except json, jsonb):** .. list-table:: @@ -446,6 +449,10 @@ Operator * - ``_lte`` - ``<=`` +(For more details on these operators, refer to the `Postgres docs `__.) + +.. _text_operators: + **Text related operators:** .. list-table:: @@ -466,6 +473,10 @@ Operator * - ``_nsimilar`` - ``NOT SIMILAR TO`` +(For more details on text related operators, refer to the `Postgres docs `__.) + +.. _null_expression: + **Checking for NULL values:** .. list-table:: @@ -476,6 +487,10 @@ Operator * - ``_is_null`` (takes true/false as values) - ``IS NULL`` +(For more details on the ``IS NULL`` expression, refer to the `Postgres docs `__.) + +.. _type_casting: + **Type casting:** .. list-table:: @@ -486,6 +501,10 @@ Operator * - ``_cast`` (takes a CastExp_ as a value) - ``::`` +(For more details on type casting, refer to the `Postgres docs `__.) + +.. _jsonb_operators: + **JSONB operators:** .. list-table:: @@ -504,7 +523,9 @@ Operator * - ``_has_keys_all`` - ``?&`` -(For more details on what these operators do, refer to the `Postgres docs `__). +(For more details on JSONB operators, refer to the `Postgres docs `__.) + +.. _geometry_operators: **PostGIS related operators on GEOMETRY columns:** @@ -530,7 +551,7 @@ Operator * - ``_st_d_within`` - ``ST_DWithin(column, input)`` -(For more details on what these operators do, refer to the `PostGIS docs `__). +(For more details on spatial relationship operators, refer to the `PostGIS docs `__.) .. note:: @@ -543,39 +564,27 @@ Operator field-name : {_st_d_within: {distance: Float, from: Value} } } -**Intersect Operators on RASTER columns:** - -- ``_st_intersects_rast`` - -Executes ``boolean ST_Intersects( raster , raster )`` - -.. parsed-literal :: - - { _st_intersects_rast: raster } - +.. _intersect_operators: -- ``_st_intersects_nband_geom`` - -Executes ``boolean ST_Intersects( raster , 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 , geometry geommin , integer nband = NULL )`` - -This accepts ``st_intersects_geom_nband_input`` input object - -.. parsed-literal :: +**Intersect Operators on RASTER columns:** - { _st_intersects_geom_nband: {geommin: geometry! nband: Integer } +.. list-table:: + :header-rows: 1 + * - 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 `__.) .. _CastExp: diff --git a/docs/graphql/manual/api-reference/schema-metadata-api/syntax-defs.rst b/docs/graphql/manual/api-reference/schema-metadata-api/syntax-defs.rst index 04831042a0d89..e84d6d06b036e 100644 --- a/docs/graphql/manual/api-reference/schema-metadata-api/syntax-defs.rst +++ b/docs/graphql/manual/api-reference/schema-metadata-api/syntax-defs.rst @@ -312,6 +312,8 @@ Operator * - ``"$lte"`` - ``<=`` +(For more details on these operators, refer to the `Postgres docs `__.) + **Text related operators :** .. list-table:: @@ -332,6 +334,7 @@ Operator * - ``"$nsimilar"`` - ``NOT SIMILAR TO`` +(For more details on text related operators, refer to the `Postgres docs `__.) **Operators for comparing columns (all column types except json, jsonb):** @@ -353,6 +356,8 @@ Operator * - ``"$clte"`` - ``<=`` +(For more details on comparison operators, refer to the `Postgres docs `__.) + **Checking for NULL values :** .. list-table:: @@ -363,6 +368,8 @@ Operator * - ``_is_null`` (takes true/false as values) - ``IS NULL`` +(For more details on the ``IS NULL`` expression, refer to the `Postgres docs `__.) + **JSONB operators :** .. list-table:: @@ -381,7 +388,7 @@ Operator * - ``_has_keys_all`` - ``?&`` -(For more details on what these operators do, refer to `Postgres docs `__.) +(For more details on JSONB operators, refer to the `Postgres docs `__.) **PostGIS related operators on GEOMETRY columns:** @@ -407,7 +414,7 @@ Operator * - ``_st_d_within`` - ``ST_DWithin(column, input)`` -(For more details on what these operators do, refer to `PostGIS docs `__). +(For more details on spatial relationship operators, refer to the `PostGIS docs `__.) .. note:: diff --git a/docs/graphql/manual/queries/query-filters.rst b/docs/graphql/manual/queries/query-filters.rst index a7f2ff0f47e7c..79b7439289265 100644 --- a/docs/graphql/manual/queries/query-filters.rst +++ b/docs/graphql/manual/queries/query-filters.rst @@ -69,19 +69,9 @@ 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.). -.. list-table:: - :header-rows: 1 - - * - Operator - - PostgreSQL equivalent - * - ``_eq`` - - ``=`` - * - ``_neq`` - - ``<>`` - .. note:: - Please refer to the `Postgres documentation `__ for more details on equality operators. + For more details on equality operators and Postgres equivalents, refer to the :ref:`API reference `. The following are examples of using the equality operators on different types. @@ -220,23 +210,9 @@ 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.). -.. list-table:: - :header-rows: 1 - - * - Operator - - PostgreSQL equivalent - * - ``_gt`` - - ``>`` - * - ``_lt`` - - ``<`` - * - ``_gte`` - - ``>=`` - * - ``_lte`` - - ``<=`` - .. note:: - Please refer to the `Postgres documentation `__ for more details on these operators. + For more details on greater than or less than operators and Postgres equivalents, refer to the :ref:`API reference `. The following are examples of using these operators on different types: @@ -363,19 +339,9 @@ 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.). -.. list-table:: - :header-rows: 1 - - * - Operator - - PostgreSQL equivalent - * - ``_in`` - - ``IN`` - * - ``_nin`` - - ``NOT IN`` - .. note:: - Please refer to the `Postgres documentation `__ for more details on search operators. + For more details on list based search operators and Postgres equivalents, refer to the :ref:`API reference `. The following are examples of using these operators on different types: @@ -468,28 +434,9 @@ 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. -.. 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`` - .. note:: - These operators behave exactly like their SQL counterparts. - Please refer to the `Postgres documentation `__ for more details on pattern matching operators. + For more details on search or pattern matching operators and Postgres equivalents, refer to the :ref:`API reference `. **Example: _like** @@ -578,25 +525,9 @@ 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. -.. list-table:: - :header-rows: 1 - - * - Operator - - PostgreSQL equivalent - * - ``_contains`` - - ``@>`` - * - ``_contained_in`` - - ``<@`` - * - ``_has_key`` - - ``?`` - * - ``_has_key_any`` - - ``?!`` - * - ``_has_key_all`` - - ``?&`` - .. note:: - Please refer to the `Postgres documentation `__ for more details on JSONB operators. + For more details on JSONB operators and Postgres equivalents, refer to the :ref:`API reference `. **Example: _contains** @@ -687,31 +618,9 @@ The ``_st_contains``, ``_st_crosses``, ``_st_equals``, ``_st_intersects``, ``_st ``_st_d_within`` and ``_st_intersects`` can be used on ``geography`` columns also. -.. 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_Intersect(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)`` - .. note:: - Please refer to the `Postgres documentation `__ for more details on spatial relationship operators. + For more details on spatial relationship operators and Postgres equivalents, refer to the :ref:`API reference `. Use JSON representation (see `GeoJSON `_) of ``geometry`` and ``geography`` values in ``variables`` as shown in the following examples: @@ -820,17 +729,9 @@ Filter or check for null values (_is_null) Checking for null values can be achieved using the ``_is_null`` operator. -.. list-table:: - :header-rows: 1 - - * - Operator - - PostgreSQL equivalent - * - ``_is_null`` - - ``IS NULL`` - .. note:: - Please refer to the `Postgres documentation `__ for more details on the ``IS NULL`` construct. + For more details on the ``_is_null`` operator and Postgres equivalent, refer to the :ref:`API reference `. **Example: Filter null values in a field** @@ -882,21 +783,9 @@ Intersect operators on RASTER columns (_st_intersects_rast, etc) Intersect operators on columns with ``raster`` type are supported. Please submit a feature request via `GitHub `__ if you want support for more functions. -.. list-table:: - :header-rows: 1 - - * - Operator - - PostgreSQL equivalent - * - ``_st_intersects_rast`` - - ``ST_Intersects(column, value)`` - * - ``_st_intersects_geom_nband`` - - ``ST_Intersects(column, geommin, nband)`` - * - ``_st_intersects_nband_geom`` - - ``ST_Intersects(column, nband, geommin)`` - .. note:: - Please refer to the `Postgres documentation `__ for more details about intersect functions on ``raster`` columns. + For more details on intersect operators on raster columns and Postgres equivalents, refer to the :ref:`API reference `. **Example: _st_intersects_rast** @@ -1049,18 +938,6 @@ Filter based on failure of some criteria (_not) The ``_not`` operator can be used to fetch results for which some condition does not hold true. i.e. to invert the filter set for a condition. -.. list-table:: - :header-rows: 1 - - * - Operator - - PostgreSQL equivalent - * - ``_not`` - - ``NOT`` - -.. note:: - - Please refer to the `Postgres documentation `__ for more details on the ``NOT`` operator. - **Example: _not** Fetch all authors who don't have any published articles: @@ -1122,20 +999,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. -.. list-table:: - :header-rows: 1 - - * - Operator - - PostgreSQL equivalent - * - ``_and`` - - ``AND`` - * - ``_or`` - - ``OR`` - -.. note:: - - Please refer to the `Postgres documentation `__ for more details on these operators. - .. note:: You can use the ``_or`` and ``_and`` operators along with the ``_not`` operator to create arbitrarily complex boolean expressions involving multiple filtering criteria. From 8971f2d48b45a5fe5b4c9681c5c0bf1b6868c38f Mon Sep 17 00:00:00 2001 From: Marion Schleifer Date: Thu, 23 Apr 2020 11:36:36 +0200 Subject: [PATCH 13/22] small fixes --- .../manual/api-reference/graphql-api/query.rst | 14 +++++++------- docs/graphql/manual/queries/query-filters.rst | 2 +- 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/graphql/manual/api-reference/graphql-api/query.rst b/docs/graphql/manual/api-reference/graphql-api/query.rst index 12cc1977ce87f..db2979530774d 100644 --- a/docs/graphql/manual/api-reference/graphql-api/query.rst +++ b/docs/graphql/manual/api-reference/graphql-api/query.rst @@ -436,10 +436,6 @@ Operator - ``=`` * - ``_neq`` - ``<>`` - * - ``_in`` - - ``IN`` - * - ``_nin`` - - ``NOT IN`` * - ``_gt`` - ``>`` * - ``_lt`` @@ -447,9 +443,13 @@ Operator * - ``_gte`` - ``>=`` * - ``_lte`` - - ``<=`` + - ``<=`` + * - ``_in`` + - ``IN`` + * - ``_nin`` + - ``NOT IN`` -(For more details on these operators, refer to the `Postgres docs `__.) +(For more details, refer to the Postgres docs for `comparison operators `__ and `list based search operators `_.) .. _text_operators: @@ -547,7 +547,7 @@ Operator * - ``_st_touches`` - ``ST_Touches(column, input)`` * - ``_st_within`` - - ``ST_Within(column, input)`` + - ``ST_Within(column, input)`` * - ``_st_d_within`` - ``ST_DWithin(column, input)`` diff --git a/docs/graphql/manual/queries/query-filters.rst b/docs/graphql/manual/queries/query-filters.rst index 79b7439289265..832511b292e28 100644 --- a/docs/graphql/manual/queries/query-filters.rst +++ b/docs/graphql/manual/queries/query-filters.rst @@ -436,7 +436,7 @@ pattern matching on string/text fields. .. note:: - For more details on search or pattern matching operators and Postgres equivalents, refer to the :ref:`API reference `. + These operators behave exactly like their SQL counterparts. For more details on these operators and Postgres equivalents, refer to the :ref:`API reference `. **Example: _like** From 454f77dd58394119416fa4718c41a701db34e5a7 Mon Sep 17 00:00:00 2001 From: Marion Schleifer Date: Thu, 23 Apr 2020 11:38:42 +0200 Subject: [PATCH 14/22] nitpick --- .../manual/api-reference/graphql-api/query.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/graphql/manual/api-reference/graphql-api/query.rst b/docs/graphql/manual/api-reference/graphql-api/query.rst index db2979530774d..0ae2adf63df09 100644 --- a/docs/graphql/manual/api-reference/graphql-api/query.rst +++ b/docs/graphql/manual/api-reference/graphql-api/query.rst @@ -449,7 +449,7 @@ Operator * - ``_nin`` - ``NOT IN`` -(For more details, refer to the Postgres docs for `comparison operators `__ and `list based search operators `_.) +(For more details, refer to the Postgres docs for `comparison operators `__ and `list based search operators `_). .. _text_operators: @@ -473,7 +473,7 @@ Operator * - ``_nsimilar`` - ``NOT SIMILAR TO`` -(For more details on text related operators, refer to the `Postgres docs `__.) +(For more details on text related operators, refer to the `Postgres docs `__). .. _null_expression: @@ -487,7 +487,7 @@ Operator * - ``_is_null`` (takes true/false as values) - ``IS NULL`` -(For more details on the ``IS NULL`` expression, refer to the `Postgres docs `__.) +(For more details on the ``IS NULL`` expression, refer to the `Postgres docs `__). .. _type_casting: @@ -501,7 +501,7 @@ Operator * - ``_cast`` (takes a CastExp_ as a value) - ``::`` -(For more details on type casting, refer to the `Postgres docs `__.) +(For more details on type casting, refer to the `Postgres docs `__). .. _jsonb_operators: @@ -523,7 +523,7 @@ Operator * - ``_has_keys_all`` - ``?&`` -(For more details on JSONB operators, refer to the `Postgres docs `__.) +(For more details on JSONB operators, refer to the `Postgres docs `__). .. _geometry_operators: @@ -551,7 +551,7 @@ Operator * - ``_st_d_within`` - ``ST_DWithin(column, input)`` -(For more details on spatial relationship operators, refer to the `PostGIS docs `__.) +(For more details on spatial relationship operators, refer to the `PostGIS docs `__). .. note:: From a20113cee6444fd0b3a0f1ec4daf776601076375 Mon Sep 17 00:00:00 2001 From: Marion Schleifer Date: Thu, 23 Apr 2020 11:40:05 +0200 Subject: [PATCH 15/22] revert nitpick --- .../manual/api-reference/graphql-api/query.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/graphql/manual/api-reference/graphql-api/query.rst b/docs/graphql/manual/api-reference/graphql-api/query.rst index 0ae2adf63df09..db2979530774d 100644 --- a/docs/graphql/manual/api-reference/graphql-api/query.rst +++ b/docs/graphql/manual/api-reference/graphql-api/query.rst @@ -449,7 +449,7 @@ Operator * - ``_nin`` - ``NOT IN`` -(For more details, refer to the Postgres docs for `comparison operators `__ and `list based search operators `_). +(For more details, refer to the Postgres docs for `comparison operators `__ and `list based search operators `_.) .. _text_operators: @@ -473,7 +473,7 @@ Operator * - ``_nsimilar`` - ``NOT SIMILAR TO`` -(For more details on text related operators, refer to the `Postgres docs `__). +(For more details on text related operators, refer to the `Postgres docs `__.) .. _null_expression: @@ -487,7 +487,7 @@ Operator * - ``_is_null`` (takes true/false as values) - ``IS NULL`` -(For more details on the ``IS NULL`` expression, refer to the `Postgres docs `__). +(For more details on the ``IS NULL`` expression, refer to the `Postgres docs `__.) .. _type_casting: @@ -501,7 +501,7 @@ Operator * - ``_cast`` (takes a CastExp_ as a value) - ``::`` -(For more details on type casting, refer to the `Postgres docs `__). +(For more details on type casting, refer to the `Postgres docs `__.) .. _jsonb_operators: @@ -523,7 +523,7 @@ Operator * - ``_has_keys_all`` - ``?&`` -(For more details on JSONB operators, refer to the `Postgres docs `__). +(For more details on JSONB operators, refer to the `Postgres docs `__.) .. _geometry_operators: @@ -551,7 +551,7 @@ Operator * - ``_st_d_within`` - ``ST_DWithin(column, input)`` -(For more details on spatial relationship operators, refer to the `PostGIS docs `__). +(For more details on spatial relationship operators, refer to the `PostGIS docs `__.) .. note:: From 15dff12d2c2c6f3e15a381ddedcbef1db31d9ea3 Mon Sep 17 00:00:00 2001 From: Marion Schleifer Date: Thu, 23 Apr 2020 11:43:13 +0200 Subject: [PATCH 16/22] tiny fixes --- docs/graphql/manual/api-reference/graphql-api/query.rst | 2 +- .../manual/api-reference/schema-metadata-api/syntax-defs.rst | 2 +- docs/graphql/manual/queries/query-filters.rst | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/graphql/manual/api-reference/graphql-api/query.rst b/docs/graphql/manual/api-reference/graphql-api/query.rst index db2979530774d..2604da6f2f345 100644 --- a/docs/graphql/manual/api-reference/graphql-api/query.rst +++ b/docs/graphql/manual/api-reference/graphql-api/query.rst @@ -541,7 +541,7 @@ Operator * - ``_st_equals`` - ``ST_Equals(column, input)`` * - ``_st_intersects`` - - ``ST_Intersect(column, input)`` + - ``ST_Intersects(column, input)`` * - ``_st_overlaps`` - ``ST_Overlaps(column, input)`` * - ``_st_touches`` diff --git a/docs/graphql/manual/api-reference/schema-metadata-api/syntax-defs.rst b/docs/graphql/manual/api-reference/schema-metadata-api/syntax-defs.rst index e84d6d06b036e..b4ac13b21ec15 100644 --- a/docs/graphql/manual/api-reference/schema-metadata-api/syntax-defs.rst +++ b/docs/graphql/manual/api-reference/schema-metadata-api/syntax-defs.rst @@ -410,7 +410,7 @@ Operator * - ``_st_touches`` - ``ST_Touches(column, input)`` * - ``_st_within`` - - ``ST_within(column, input)`` + - ``ST_Within(column, input)`` * - ``_st_d_within`` - ``ST_DWithin(column, input)`` diff --git a/docs/graphql/manual/queries/query-filters.rst b/docs/graphql/manual/queries/query-filters.rst index 832511b292e28..2953eacc5df8b 100644 --- a/docs/graphql/manual/queries/query-filters.rst +++ b/docs/graphql/manual/queries/query-filters.rst @@ -994,7 +994,7 @@ Fetch all authors who don't have any published articles: } 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. From 0daab92b312d30e299fd6b2f9472cba55d830d49 Mon Sep 17 00:00:00 2001 From: Marion Schleifer Date: Thu, 23 Apr 2020 11:48:59 +0200 Subject: [PATCH 17/22] fix link --- .../api-reference/schema-metadata-api/syntax-defs.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/graphql/manual/api-reference/schema-metadata-api/syntax-defs.rst b/docs/graphql/manual/api-reference/schema-metadata-api/syntax-defs.rst index b4ac13b21ec15..1f96251769e9c 100644 --- a/docs/graphql/manual/api-reference/schema-metadata-api/syntax-defs.rst +++ b/docs/graphql/manual/api-reference/schema-metadata-api/syntax-defs.rst @@ -299,10 +299,6 @@ Operator - ``=`` * - ``"$ne"`` - ``<>`` - * - ``"$in"`` - - ``IN`` - * - ``"$nin"`` - - ``NOT IN`` * - ``"$gt"`` - ``>`` * - ``"$lt"`` @@ -311,8 +307,12 @@ Operator - ``>=`` * - ``"$lte"`` - ``<=`` + * - ``"$in"`` + - ``IN`` + * - ``"$nin"`` + - ``NOT IN`` -(For more details on these operators, refer to the `Postgres docs `__.) +(For more details, refer to the Postgres docs for `comparison operators `__ and `list based search operators `_.) **Text related operators :** From f8a685883fd640cdaca3bf1a6dd1a34fc7390d42 Mon Sep 17 00:00:00 2001 From: Marion Schleifer Date: Thu, 23 Apr 2020 12:20:02 +0200 Subject: [PATCH 18/22] remove notes --- docs/graphql/manual/queries/query-filters.rst | 32 +++++-------------- 1 file changed, 8 insertions(+), 24 deletions(-) diff --git a/docs/graphql/manual/queries/query-filters.rst b/docs/graphql/manual/queries/query-filters.rst index 2953eacc5df8b..8553ff0c5e6e7 100644 --- a/docs/graphql/manual/queries/query-filters.rst +++ b/docs/graphql/manual/queries/query-filters.rst @@ -69,9 +69,7 @@ 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.). -.. note:: - - For more details on equality operators and Postgres equivalents, refer to the :ref:`API reference `. +For more details on equality operators and Postgres equivalents, refer to the :ref:`API reference `. The following are examples of using the equality operators on different types. @@ -210,9 +208,7 @@ 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.). -.. note:: - - For more details on greater than or less than operators and Postgres equivalents, refer to the :ref:`API reference `. +For more details on greater than or less than operators and Postgres equivalents, refer to the :ref:`API reference `. The following are examples of using these operators on different types: @@ -339,9 +335,7 @@ 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.). -.. note:: - - For more details on list based search operators and Postgres equivalents, refer to the :ref:`API reference `. +For more details on list based search operators and Postgres equivalents, refer to the :ref:`API reference `. The following are examples of using these operators on different types: @@ -434,9 +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. -.. note:: - - These operators behave exactly like their SQL counterparts. For more details on these operators and Postgres equivalents, refer to the :ref:`API reference `. +These operators behave exactly like their SQL counterparts. For more details on these operators and Postgres equivalents, refer to the :ref:`API reference `. **Example: _like** @@ -525,9 +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. -.. note:: - - For more details on JSONB operators and Postgres equivalents, refer to the :ref:`API reference `. +For more details on JSONB operators and Postgres equivalents, refer to the :ref:`API reference `. **Example: _contains** @@ -618,9 +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. -.. note:: - - For more details on spatial relationship operators and Postgres equivalents, refer to the :ref:`API reference `. +For more details on spatial relationship operators and Postgres equivalents, refer to the :ref:`API reference `. Use JSON representation (see `GeoJSON `_) of ``geometry`` and ``geography`` values in ``variables`` as shown in the following examples: @@ -729,9 +717,7 @@ Filter or check for null values (_is_null) Checking for null values can be achieved using the ``_is_null`` operator. -.. note:: - - For more details on the ``_is_null`` operator and Postgres equivalent, refer to the :ref:`API reference `. +For more details on the ``_is_null`` operator and Postgres equivalent, refer to the :ref:`API reference `. **Example: Filter null values in a field** @@ -783,9 +769,7 @@ Intersect operators on RASTER columns (_st_intersects_rast, etc) Intersect operators on columns with ``raster`` type are supported. Please submit a feature request via `GitHub `__ if you want support for more functions. -.. note:: - - For more details on intersect operators on raster columns and Postgres equivalents, refer to the :ref:`API reference `. +For more details on intersect operators on raster columns and Postgres equivalents, refer to the :ref:`API reference `. **Example: _st_intersects_rast** From d321da49d366cfc31c6ffa71b74fdb45f4cade86 Mon Sep 17 00:00:00 2001 From: Marion Schleifer Date: Thu, 23 Apr 2020 12:28:30 +0200 Subject: [PATCH 19/22] current links --- docs/graphql/manual/api-reference/graphql-api/query.rst | 6 +++--- .../api-reference/schema-metadata-api/syntax-defs.rst | 6 +++--- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/graphql/manual/api-reference/graphql-api/query.rst b/docs/graphql/manual/api-reference/graphql-api/query.rst index 2604da6f2f345..7bf0ce7f45206 100644 --- a/docs/graphql/manual/api-reference/graphql-api/query.rst +++ b/docs/graphql/manual/api-reference/graphql-api/query.rst @@ -449,7 +449,7 @@ Operator * - ``_nin`` - ``NOT IN`` -(For more details, refer to the Postgres docs for `comparison operators `__ and `list based search operators `_.) +(For more details, refer to the Postgres docs for `comparison operators `__ and `list based search operators `_.) .. _text_operators: @@ -487,7 +487,7 @@ Operator * - ``_is_null`` (takes true/false as values) - ``IS NULL`` -(For more details on the ``IS NULL`` expression, refer to the `Postgres docs `__.) +(For more details on the ``IS NULL`` expression, refer to the `Postgres docs `__.) .. _type_casting: @@ -501,7 +501,7 @@ Operator * - ``_cast`` (takes a CastExp_ as a value) - ``::`` -(For more details on type casting, refer to the `Postgres docs `__.) +(For more details on type casting, refer to the `Postgres docs `__.) .. _jsonb_operators: diff --git a/docs/graphql/manual/api-reference/schema-metadata-api/syntax-defs.rst b/docs/graphql/manual/api-reference/schema-metadata-api/syntax-defs.rst index 1f96251769e9c..80fb8fdb3091e 100644 --- a/docs/graphql/manual/api-reference/schema-metadata-api/syntax-defs.rst +++ b/docs/graphql/manual/api-reference/schema-metadata-api/syntax-defs.rst @@ -312,7 +312,7 @@ Operator * - ``"$nin"`` - ``NOT IN`` -(For more details, refer to the Postgres docs for `comparison operators `__ and `list based search operators `_.) +(For more details, refer to the Postgres docs for `comparison operators `__ and `list based search operators `_.) **Text related operators :** @@ -356,7 +356,7 @@ Operator * - ``"$clte"`` - ``<=`` -(For more details on comparison operators, refer to the `Postgres docs `__.) +(For more details on comparison operators, refer to the `Postgres docs `__.) **Checking for NULL values :** @@ -368,7 +368,7 @@ Operator * - ``_is_null`` (takes true/false as values) - ``IS NULL`` -(For more details on the ``IS NULL`` expression, refer to the `Postgres docs `__.) +(For more details on the ``IS NULL`` expression, refer to the `Postgres docs `__.) **JSONB operators :** From 46fdc026436c12789ee3963f5cca752a1f4bef0a Mon Sep 17 00:00:00 2001 From: Marion Schleifer Date: Thu, 23 Apr 2020 12:50:33 +0200 Subject: [PATCH 20/22] add to contributing guide --- docs/CONTRIBUTING.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index d1a4513006627..dc81c9274e30f 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -106,6 +106,11 @@ without losing any visible quality. syntax in which case you'll have to set the language type to `none` to avoid warnings during builds. - 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 +- For external links, add a double `_` in the end, e.g. \``Google __`\` + +### Reference links + +- 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/functions-comparison.html` rather than `https://www.postgresql.org/docs/8.3/functions-comparison.html` ### Pre-commit checks - Just before committing your changes, delete your local `_build` folder completely and then build docs again. Scan From 701b532809239ff9c4202a233c24ae066a3af483 Mon Sep 17 00:00:00 2001 From: Rikin Kachhia <54616969+rikinsk@users.noreply.github.com> Date: Thu, 23 Apr 2020 17:22:40 +0530 Subject: [PATCH 21/22] Update CONTRIBUTING.md --- docs/CONTRIBUTING.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index dc81c9274e30f..b20673631e306 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -106,11 +106,11 @@ without losing any visible quality. syntax in which case you'll have to set the language type to `none` to avoid warnings during builds. - 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 -- For external links, add a double `_` in the end, e.g. \``Google __`\` ### Reference links -- 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/functions-comparison.html` rather than `https://www.postgresql.org/docs/8.3/functions-comparison.html` +- For external links, add a double `_` in the end to avoid `Duplicate explicit target name` warnings , e.g. \``Google __`\` +- 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 From 4a2d1213189e495b46c7972467f5c5644c21ef9b Mon Sep 17 00:00:00 2001 From: Rikin Kachhia <54616969+rikinsk@users.noreply.github.com> Date: Thu, 23 Apr 2020 17:25:31 +0530 Subject: [PATCH 22/22] Update query-filters.rst --- docs/graphql/manual/queries/query-filters.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/graphql/manual/queries/query-filters.rst b/docs/graphql/manual/queries/query-filters.rst index 8553ff0c5e6e7..e1e58b972c7d2 100644 --- a/docs/graphql/manual/queries/query-filters.rst +++ b/docs/graphql/manual/queries/query-filters.rst @@ -428,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. For more details on these operators and Postgres equivalents, refer to the :ref:`API reference `. +For more details on text search operators and Postgres equivalents, refer to the :ref:`API reference `. **Example: _like**