From 53f35f638c5203d50bf63db0090fb224cb8fb2dc Mon Sep 17 00:00:00 2001 From: steve-chavez Date: Fri, 14 Feb 2020 14:14:32 -0500 Subject: [PATCH] Add on_conflict query parameter --- api.rst | 26 +++++++++++++++++++++++--- releases/upcoming.rst | 3 +++ 2 files changed, 26 insertions(+), 3 deletions(-) diff --git a/api.rst b/api.rst index 17960fa48..fb478dc12 100644 --- a/api.rst +++ b/api.rst @@ -1218,7 +1218,7 @@ 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. -Upsert +UPSERT ------ You can make an UPSERT with :code:`POST` and the :code:`Prefer: resolution=merge-duplicates` header: @@ -1234,11 +1234,31 @@ You can make an UPSERT with :code:`POST` and the :code:`Prefer: resolution=merge { "id": 3, "name": "New employee 3", "salary": 50000 } ] -UPSERT operates based on the primary key columns, you must specify all of them. You can also choose to ignore the duplicates with :code:`Prefer: resolution=ignore-duplicates`. UPSERT works best when the primary key is natural, but it's also possible to use it if the primary key is surrogate (example: "id serial primary key"). For more details read `this issue `_. +By default, UPSERT operates based on the primary key columns, you must specify all of them. You can also choose to ignore the duplicates with :code:`Prefer: resolution=ignore-duplicates`. This works best when the primary key is natural, but it's also possible to use it if the primary key is surrogate (example: "id serial primary key"). For more details read `this issue `_. .. important:: After creating a table or changing its primary key, you must refresh PostgREST schema cache for UPSERT to work properly. To learn how to refresh the cache see :ref:`schema_reloading`. +.. _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. + +.. code-block:: http + + POST /employees?on_conflict=name HTTP/1.1 + Prefer: resolution=merge-duplicates + + [ + { "name": "Old employee 1", "salary": 40000 }, + { "name": "Old employee 2", "salary": 52000 }, + { "name": "New employee 3", "salary": 60000 } + ] + +PUT +~~~ A single row UPSERT can be done by using :code:`PUT` and filtering the primary key columns with :code:`eq`: @@ -1252,7 +1272,7 @@ All the columns must be specified in the request body, including the primary key .. note:: - This feature is only available starting from PostgreSQL 9.5 since it uses the `ON CONFLICT clause `_. + Upsert features are only available starting from PostgreSQL 9.5 since it uses the `ON CONFLICT clause `_. .. _delete: diff --git a/releases/upcoming.rst b/releases/upcoming.rst index de5e751cd..858861f46 100644 --- a/releases/upcoming.rst +++ b/releases/upcoming.rst @@ -10,6 +10,9 @@ These are changes yet unreleased. If you'd like to try them out before a new off Added ----- +* Support for the :ref:`on_conflict ` query parameter to UPSERT based on a unique constraint. + |br| -- `@ykst `_ + * Support for :ref:`planned_count` and :ref:`estimated_count`. |br| -- `@steve-chavez `_