Add reference for filtering on json column

Fixes https://github.com/PostgREST/postgrest-docs/issues/266

api.rst

@@ -190,6 +190,8 @@ Casting the columns is possible by suffixing them with the double colon ``::`` p
     {"full_name": "Jane Doe", "salary": "120000.00"}
   ]
 
+.. _json_columns:
+
 JSON Columns
 ~~~~~~~~~~~~
 
@@ -204,7 +206,16 @@ You can specify a path for a ``json`` or ``jsonb`` column using the arrow operat
     { "id": 2, "blood_type": "O+", "phones": [{"country_code": "43", "number": "512-446-4988"}, {"country_code": "43", "number": "213-891-5979"}] }
   ]
 
-That also works with filters:
+.. code-block:: http
+
+  GET /people?select=id,json_data->phones->0->>number HTTP/1.1
+
+  [
+    { "id": 1, "number": "917-929-5745"},
+    { "id": 2, "number": "512-446-4988"}
+  ]
+
+This also works with filters:
 
 .. code-block:: http
 
@@ -216,6 +227,18 @@ That also works with filters:
     { "id": 7, "blood_type": "A-" }
   ]
 
+Note that ``->>`` is used to compare ``blood_type`` as ``text``. To compare with an integer value use ``->``:
+
+.. code-block:: http
+
+  GET /people?select=id,json_data->age&json_data->age=gt.20 HTTP/1.1
+
+  [
+    { "id": 11, "age": 25 },
+    { "id": 12, "age": 30 },
+    { "id": 15, "age": 35 }
+  ]
+
 .. _computed_cols:
 
 Computed Columns

releases/upcoming.rst

@@ -30,9 +30,11 @@ Added
    + Allow overriding provided headers(Content-Type, Location, etc) by :ref:`guc_resp_hdrs`
    + Access to the ``Authorization`` header value through ``request.header.authorization``
 
-* Documentation reference for :ref:`s_proc_embed`.
+* Documentation improvements
 
-* Documentation reference for :ref:`mutation_embed`.
+  + Reference for :ref:`s_proc_embed`.
+  + Reference for :ref:`mutation_embed`.
+  + Reference for filters on :ref:`json_columns`.
 
 Fixed
 -----