From 78d9880607907a35639aa5ae11c27c3ec5bbb054 Mon Sep 17 00:00:00 2001 From: steve-chavez Date: Thu, 10 Aug 2023 02:11:41 -0500 Subject: [PATCH] add nulls=stripped --- .../api/resource_representation.rst | 37 +++++++++++++++++++ 1 file changed, 37 insertions(+) diff --git a/docs/references/api/resource_representation.rst b/docs/references/api/resource_representation.rst index 8a1f80529..76c0c5511 100644 --- a/docs/references/api/resource_representation.rst +++ b/docs/references/api/resource_representation.rst @@ -85,6 +85,43 @@ When a singular response is requested but no entries are found, the server respo Admittedly PostgREST could detect when there is an equality condition holding on all columns constituting the primary key and automatically convert to singular. However this could lead to a surprising change of format that breaks unwary client code just by filtering on an extra column. Instead we allow manually specifying singular vs plural to decouple that choice from the URL format. +Stripped Nulls +-------------- + +By default PostgREST returns all JSON null values. For example, requesting ``/projects?id=gt.10`` returns + +.. code:: json + + [ + { "id": 11, "name": "OSX", "client_id": 1, "another_col": "val" }, + { "id": 12, "name": "ProjectX", "client_id": null, "another_col": null }, + { "id": 13, "name": "Y", "client_id": null, "another_col": null } + ] + +On large result sets, the unused keys with ``null`` values can waste bandwith unnecessarily. To remove them, specify ``nulls=stripped`` as a parameter of ``application/vnd.pgrst.array``: + +.. tabs:: + + .. code-tab:: http + + GET /projects?id=gt.10 HTTP/1.1 + Accept: application/vnd.pgrst.array+json;nulls=stripped + + .. code-tab:: bash Curl + + curl "http://localhost:3000/projects?id=gt.10" \ + -H "Accept: application/vnd.pgrst.array+json;nulls=stripped" + +This returns + +.. code:: json + + [ + { "id": 11, "name": "OSX", "client_id": 1, "another_col": "val" }, + { "id": 12, "name": "ProjectX" }, + { "id": 13, "name": "Y"} + ] + .. _scalar_return_formats: Scalar Function Response Format