From 6aeb5065f8f901888e325400fca93a31e70fa023 Mon Sep 17 00:00:00 2001 From: Wolfgang Walther Date: Thu, 3 Feb 2022 08:06:01 +0100 Subject: [PATCH] Add docs about accessing array items and fields of composite types with JSON operators. Added in https://github.com/PostgREST/postgrest/pull/2145 Signed-off-by: Wolfgang Walther --- docs/api.rst | 21 +++++++++++++++------ 1 file changed, 15 insertions(+), 6 deletions(-) diff --git a/docs/api.rst b/docs/api.rst index a95f1118c..2cac9c2a2 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -269,10 +269,10 @@ Casting the columns is possible by suffixing them with the double colon ``::`` p .. _json_columns: -JSON Columns ------------- +Array / Composite / JSON Columns +-------------------------------- -You can specify a path for a ``json`` or ``jsonb`` column using the arrow operators(``->`` or ``->>``) as per the `PostgreSQL docs `_. +You can specify a path for a ``json`` or ``jsonb`` column using the arrow operators(``->`` or ``->>``) as per the `PostgreSQL docs `_. This also works for array items and fields of composite types. .. tabs:: @@ -348,10 +348,19 @@ Note that ``->>`` is used to compare ``blood_type`` as ``text``. To compare with { "id": 15, "age": 35 } ] + +.. important:: + + When using the ``->`` and ``->>`` operators, PostgREST uses a query like ``to_jsonb()->'field'``. To make filtering and ordering on those nested fields use an index, the index needs to be created on the same expression, including the ``to_jsonb(...)`` call: + + .. code-block:: postgres + + CREATE INDEX ON mytable ((to_jsonb(data) -> 'identification' ->> 'registration_number')); + .. _computed_cols: -Computed Columns ----------------- +Computed / Virtual Columns +-------------------------- Filters may be applied to computed columns(**a.k.a. virtual columns**) as well as actual table/view columns, even though the computed columns will not appear in the output. For example, to search first and last names at once we can create a computed column that will not appear in the output but can be used in a filter: @@ -537,7 +546,7 @@ If you care where nulls are sorted, add ``nullsfirst`` or ``nullslast``: curl "http://localhost:3000/people?order=age.desc.nullslast" -You can also use :ref:`computed_cols` to order the results, even though the computed columns will not appear in the output. +You can also use :ref:`computed_cols` to order the results, even though the computed columns will not appear in the output. You can sort by nested fields of :ref:`json_columns` with the JSON operators. .. _limits: