From 6afed0b30dcf7254cf3288cce41d96705bbecdc9 Mon Sep 17 00:00:00 2001
From: steve-chavez <stevechavezast@gmail.com>
Date: Sat, 28 Sep 2019 15:40:31 -0500
Subject: [PATCH] Add reference for stored proc embedding

---
 api.rst               | 32 ++++++++++++++++++++++++++++++++
 releases/upcoming.rst |  2 ++
 2 files changed, 34 insertions(+)

diff --git a/api.rst b/api.rst
index 19a7d8518..71948cc59 100644
--- a/api.rst
+++ b/api.rst
@@ -681,6 +681,38 @@ It's also possible to embed `Materialized Views <https://www.postgresql.org/docs
 
   If view definitions change you must refresh PostgREST's schema cache for this to work properly. See the section :ref:`schema_reloading`.
 
+.. _s_proc_embed:
+
+Embedding on Stored Procedures
+------------------------------
+
+If you have a :ref:`Stored Procedure <s_procs>` that returns a table type, you can embed its related tables.
+
+Here's a sample function(notice the ``RETURNS SETOF films``).
+
+.. code-block:: plpgsql
+
+  CREATE FUNCTION getallfilms() RETURNS SETOF films AS $$
+    SELECT * FROM films;
+  $$ LANGUAGE SQL IMMUTABLE;
+
+A request with ``directors`` embedded:
+
+.. code-block:: http
+
+   GET /rpc/getallfilms?select=title,directors(id,last_name)&title=like.*Workers* HTTP/1.1
+
+.. code-block:: json
+
+   [
+     { "title": "Workers Leaving The Lumière Factory In Lyon",
+       "directors": {
+         "id": 2,
+         "last_name": "Lumière"
+       }
+     }
+   ]
+
 .. _custom_queries:
 
 Custom Queries
diff --git a/releases/upcoming.rst b/releases/upcoming.rst
index 886c4449b..3085f0a92 100644
--- a/releases/upcoming.rst
+++ b/releases/upcoming.rst
@@ -16,6 +16,8 @@ Added
 * Support for :ref:`planned_count` and :ref:`estimated_count`.
   |br| -- `@steve-chavez <https://github.com/steve-chavez>`_
 
+* Documentation reference for :ref:`s_proc_embed`.
+
 Changed
 -------