diff --git a/docs/how-tos/working-with-postgresql-data-types.rst b/docs/how-tos/working-with-postgresql-data-types.rst new file mode 100644 index 000000000..7cba0a979 --- /dev/null +++ b/docs/how-tos/working-with-postgresql-data-types.rst @@ -0,0 +1,80 @@ +.. _working_with_types: + +Working with PostgreSQL data types +================================== + +PostgREST makes use of PostgreSQL string representations to work with data types. Thanks to this, you can use special values, such as ``now`` for timestamps, ``yes`` for booleans or time values including the time zones. This page describes how you can take advantage of these string representations to perform operations on different PostgreSQL data types. + +Timestamps +---------- + +You can use the **time zone** to filter or send data if needed. Let's use this table as an example: + +.. code-block:: postgres + + create table reports ( + id int primary key + , due_date timestamptz + ); + +Suppose you are located in Sydney and want create a report with the date in the local time zone. Your request should look like this: + +.. tabs:: + + .. code-tab:: http + + POST /reports HTTP/1.1 + Content-Type: application/json + + [{ "id": 1, "due_date": "2022-02-24 11:10:15 Australia/Sydney" }, + { "id": 2, "due_date": "2022-02-27 22:00:00 Australia/Sydney" }] + + .. code-tab:: bash Curl + + curl "http://localhost:3000/reports" \ + -X POST -H "Content-Type: application/json" \ + -d '[{ "id": 1, "due_date": "2022-02-24 11:10:15 Australia/Sydney" },{ "id": 2, "due_date": "2022-02-27 22:00:00 Australia/Sydney" }]' + +Someone located in Cairo can retrieve the data using their local time, too: + +.. tabs:: + + .. code-tab:: http + + GET /reports?due_date=eq.2022-02-24+02:10:15+Africa/Cairo HTTP/1.1 + + .. code-tab:: bash Curl + + curl "http://localhost:3000/reports?due_date=eq.2022-02-24+02:10:15+Africa/Cairo" + +.. code-block:: json + + [ + { + "id": 1, + "due_date": "2022-02-23T19:10:15-05:00" + } + ] + +The response has the date in the time zone configured by the server: ``UTC -05:00``. + +You can use other comparative filters and also `PostgreSQL special date/time input values `_. For instance, to get the reports that are due after today you would do: + +.. tabs:: + + .. code-tab:: http + + GET /reports?due_date=gt.today HTTP/1.1 + + .. code-tab:: bash Curl + + curl "http://localhost:3000/reports?due_date=gt.today" + +.. code-block:: json + + [ + { + "id": 2, + "due_date": "2022-02-27T06:00:00-05:00" + } + ] diff --git a/docs/index.rst b/docs/index.rst index 3d522585d..8fa7b04f7 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -201,6 +201,7 @@ These are recipes that'll help you address specific use-cases. - :doc:`how-tos/embedding-table-from-another-schema` - :doc:`how-tos/providing-images-for-img` - `How PostgreSQL triggers work when called with a PostgREST PATCH HTTP request `_ +- :doc:`how-tos/working-with-postgresql-data-types` Ecosystem --------- diff --git a/postgrest.dict b/postgrest.dict index 60c7055c1..1ac2dd976 100644 --- a/postgrest.dict +++ b/postgrest.dict @@ -11,6 +11,7 @@ authenticator backoff balancer Beles +booleans Bouscal buildpack Cardano