From 4cd05681dd84abb6616f02920330ef6d9f0ca3e5 Mon Sep 17 00:00:00 2001 From: Steve Chavez Date: Mon, 6 Jan 2020 09:43:54 -0500 Subject: [PATCH] Add embedding disambiguation section (#290) --- _static/orders.png | Bin 0 -> 17892 bytes api.rst | 104 +++++++++++++++++++++++++++++++++++++++++++++ erd/README.md | 7 +++ erd/orders.er | 15 +++++++ 4 files changed, 126 insertions(+) create mode 100644 _static/orders.png create mode 100644 erd/README.md create mode 100644 erd/orders.er diff --git a/_static/orders.png b/_static/orders.png new file mode 100644 index 0000000000000000000000000000000000000000..db709c873da885c3c73b42678bbcc279f582c836 GIT binary patch literal 17892 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 b5BqQ>)q({)hfXjsFfe$!`njxgN@xNAx&3r# literal 0 HcmV?d00001 diff --git a/api.rst b/api.rst index 06082c2f7..2910f7e3a 100644 --- a/api.rst +++ b/api.rst @@ -746,6 +746,110 @@ Response: } } +.. _embed_disamb: + +Embedding Disambiguation +------------------------ + +For doing resource embedding, PostgREST infers the relationship between two tables based on a foreign key between them. +However, in cases where there's more than one foreign key between two tables, it's not possible to infer the relationship unambiguosly +by just specifying the tables names. + +Target Disambiguation +~~~~~~~~~~~~~~~~~~~~~ + +For example, suppose you have the following ``orders`` and ``addresses`` tables: + +.. image:: _static/orders.png + +And you try to embed ``orders`` with ``addresses`` (this is the **target**): + +.. code-block:: http + + GET /orders?select=*,addresses(*) HTTP/1.1 + +Since the ``orders`` table has two foreign keys to the ``addresses`` table — an order has a billing address and a shipping address — +the request is ambiguous and PostgREST will respond with an error: + +.. code-block:: http + + HTTP/1.1 300 Multiple Choices + +If this happens, you need to disambiguate the request by adding precision to the **target**. +Instead of the **table name**, you can specify the **foreign key constraint name** or the **column name** that is part of the foreign key. + +Let's try first with the **foreign key constraint name**. To make it clearer we can name it: + +.. code-block:: postgresql + + ALTER TABLE orders + ADD CONSTRAINT billing_address foreign key (billing_address_id) references addresses(id), + ADD CONSTRAINT shipping_address foreign key (shipping_address_id) references addresses(id); + + -- Or if the constraints names were already generated by PostgreSQL we can rename them + -- ALTER TABLE orders + -- RENAME CONSTRAINT orders_billing_address_id_fkey TO billing_address, + -- RENAME CONSTRAINT orders_shipping_address_id_fkey TO shipping_address; + +Now we can unambiguously embed the billing address by specifying the ``billing_address`` foreign key constraint as the **target**. + +.. code-block:: http + + GET /orders?select=name,billing_address(name) HTTP/1.1 + + [ + { + "name": "Personal Water Filter", + "billing_address": { + "name": "32 Glenlake Dr.Dearborn, MI 48124" + } + } + ] + +Alternatively, you can specify the **column name** of the foreign key constraint as the **target**. This can be aliased to make +the result more clear. + +.. code-block:: http + + GET /orders?select=name,billing_address:billing_address_id(name) HTTP/1.1 + + [ + { + "name": "Personal Water Filter", + "billing_address": { + "name": "32 Glenlake Dr.Dearborn, MI 48124" + } + } + ] + +Hint Disambiguation +~~~~~~~~~~~~~~~~~~~ + +If specifying the **target** is not enough for unambiguous embedding, you can add a **hint**. For example, let's assume we create +two VIEWs of ``addresses``: ``central_addresses`` and ``eastern_addresses``. + +Since PostgREST supports :ref:`embedding_views` by detecting **source foreign keys** in the views, embedding with the foreign key +as the **target** will not be enough for an unambiguous embed: + +.. code-block:: http + + GET /orders?select=*,billing_address(*) HTTP/1.1 + + HTTP/1.1 300 Multiple Choices + +For solving this case, in addition to the **target**, we can add a **hint**. +Here we specify ``central_addresses`` as the **target** and the ``billing_address`` foreign key as the **hint**: + +.. code-block:: http + + GET /orders?select=*,central_addresses!billing_address(*) HTTP/1.1 + + HTTP/1.1 200 OK + + [ ... ] + +Similarly to the **target**, the **hint** can be a **table name**, **foreign key constraint name** or **column name**. + .. _custom_queries: Custom Queries diff --git a/erd/README.md b/erd/README.md new file mode 100644 index 000000000..d71e8e263 --- /dev/null +++ b/erd/README.md @@ -0,0 +1,7 @@ +This files were created with https://github.com/BurntSushi/erd/. + +You can go download erd from https://github.com/BurntSushi/erd/releases and then do: + +```bash +./erd_static-x86-64 -i erd/film.er -o _static/film.png +``` diff --git a/erd/orders.er b/erd/orders.er new file mode 100644 index 000000000..bdd93de2e --- /dev/null +++ b/erd/orders.er @@ -0,0 +1,15 @@ +[Addresses] +*id +name +city +state +postal_code + +[Orders] +*id +name ++billing_address_id ++shipping_address_id + +Orders *--1 Addresses +Orders *--1 Addresses