From 72bffddbf18eac309216323a524f8d56ef458d04 Mon Sep 17 00:00:00 2001 From: steve-chavez Date: Thu, 24 Mar 2022 18:21:13 +0100 Subject: [PATCH] Add limited updates/deletions Also move updates to its own section --- docs/api.rst | 101 ++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 71 insertions(+), 30 deletions(-) diff --git a/docs/api.rst b/docs/api.rst index 7ae36a41a..1b886af09 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -1479,10 +1479,10 @@ Hints also work alongside ``!inner`` if a top level filtering is needed. From th curl "http://localhost:3000/orders?select=*,central_addresses!billing_address!inner(*)¢ral_addresses.code=AB1000" -.. _insert_update: +.. _insert: -Insertions / Updates -==================== +Insertions +========== All tables and `auto-updatable views `_ can be modified through the API, subject to permissions of the requester's database role. @@ -1537,28 +1537,6 @@ URL encoded payloads can be posted with ``Content-Type: application/x-www-form-u Some JavaScript libraries will post the data incorrectly if you're not careful. For best results try one of the :ref:`clientside_libraries` built for PostgREST. -To update a row or rows in a table, use the PATCH verb. Use :ref:`h_filter` to specify which record(s) to update. Here is an example query setting the :code:`category` column to child for all people below a certain age. - -.. tabs:: - - .. code-tab:: http - - PATCH /people?age=lt.13 HTTP/1.1 - - { "category": "child" } - - .. code-tab:: bash Curl - - curl "http://localhost:3000/people?age=lt.13" \ - -X PATCH -H "Content-Type: application/json" \ - -d '{ "category": "child" }' - -Updates also support :code:`Prefer: return=representation` plus :ref:`v_filter`. - -.. warning:: - - Beware of accidentally updating every row in a table. To learn to prevent that see :ref:`block_fulltable`. - .. _bulk_insert: Bulk Insert @@ -1621,8 +1599,7 @@ To bulk insert JSON post an array of objects having all-matching keys Specifying Columns ------------------ -By using the :code:`columns` query parameter it's possible to specify the payload keys that will be inserted/updated -and ignore the rest of the payload. +By using the :code:`columns` query parameter it's possible to specify the payload keys that will be inserted and ignore the rest of the payload. .. tabs:: @@ -1662,10 +1639,37 @@ In this case, only **source**, **publication_date** and **figure** will be inser Using this also has the side-effect of being more efficient for :ref:`bulk_insert` since PostgREST will not process the JSON and it'll send it directly to PostgreSQL. +.. _update: + +Updates +======= + +To update a row or rows in a table, use the PATCH verb. Use :ref:`h_filter` to specify which record(s) to update. Here is an example query setting the :code:`category` column to child for all people below a certain age. + +.. tabs:: + + .. code-tab:: http + + PATCH /people?age=lt.13 HTTP/1.1 + + { "category": "child" } + + .. code-tab:: bash Curl + + curl "http://localhost:3000/people?age=lt.13" \ + -X PATCH -H "Content-Type: application/json" \ + -d '{ "category": "child" }' + +Updates also support :code:`Prefer: return=representation` plus :ref:`v_filter`. + +.. warning:: + + Beware of accidentally updating every row in a table. To learn to prevent that see :ref:`block_fulltable`. + .. _upsert: UPSERT ------- +====== You can make an UPSERT with :code:`POST` and the :code:`Prefer: resolution=merge-duplicates` header: @@ -1703,7 +1707,7 @@ By default, UPSERT operates based on the primary key columns, you must specify a .. _on_conflict: On Conflict -~~~~~~~~~~~ +----------- By specifying the ``on_conflict`` query parameter, you can make UPSERT work on a column(s) that has a UNIQUE constraint. @@ -1736,7 +1740,7 @@ By specifying the ``on_conflict`` query parameter, you can make UPSERT work on a .. _upsert_put: PUT -~~~ +--- A single row UPSERT can be done by using :code:`PUT` and filtering the primary key columns with :code:`eq`: @@ -1795,6 +1799,43 @@ Deletions also support :code:`Prefer: return=representation` plus :ref:`v_filter Beware of accidentally deleting all rows in a table. To learn to prevent that see :ref:`block_fulltable`. +Limited Updates/Deletions +========================= + +You can limit the amount of affected rows by :ref:`update` or :ref:`delete` with the ``limit`` query parameter. For this, you must add an explicit ``order`` on a unique column(s). + +.. tabs:: + + .. code-tab:: http + + PATCH /users?limit=10&order=id&last_login=lt.2017-01-01 HTTP/1.1 + + { "status": "inactive" } + + .. code-tab:: bash Curl + + curl -X PATCH "/users?limit=10&order=id&last_login=lt.2020-01-01" \ + -H "Content-Type: application/json" \ + -d '{ "status": "inactive" }' + +.. tabs:: + + .. code-tab:: http + + DELETE /users?limit=10&order=id&status=eq.inactive HTTP/1.1 + + .. code-tab:: bash Curl + + curl -X DELETE "http://localhost:3000/users?limit=10&order=id&status=eq.inactive" + +If your table has no unique columns, you can use the `ctid `_ system column. + +Using ``offset`` to target a different subset of rows is also possible. + +.. note:: + + There is no native ``UPDATE...LIMIT`` or ``DELETE...LIMIT`` support in PostgreSQL; the generated query simulates that behavior and is based on `this Crunchy Data blog post `_. + .. _custom_queries: Custom Queries