hasura · rikinsk · Apr 23, 2020 · Apr 21, 2020 · Apr 21, 2020 · Apr 21, 2020
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -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)

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

@@ -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 on RASTER columns:**
-
-- ``_st_intersects_rast``
-
-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 ::
+.. _intersect_operators:
 
-   { _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 ::
+**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 <https://postgis.net/docs/RT_ST_Intersects.html>`__.)
 
 .. _CastExp:
 

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