From 60d4f47bb00bafb6b52b9c980f24ebbeee96eb10 Mon Sep 17 00:00:00 2001
From: Remington Steed <rjs7@calvin.edu>
Date: Mon, 26 Nov 2018 14:10:36 -0500
Subject: [PATCH] Docs: LP#1731048: Update json_query documentation for new
 join syntax

This commit simply adds the text from the related commit message (see
LP#1527731) to the original DocBook file. NOTE: This documentation is
also available on the wiki, and has been updated there as well:

https://wiki.evergreen-ils.org/doku.php?id=documentation:tutorials:json_query

Signed-off-by: Remington Steed <rjs7@calvin.edu>
---
 docs/TechRef/JSONTutorial.xml | 76 +++++++++++++++++++++++++++++++++++
 1 file changed, 76 insertions(+)

diff --git a/docs/TechRef/JSONTutorial.xml b/docs/TechRef/JSONTutorial.xml
index 5ea28c38b9..f91678d09b 100644
--- a/docs/TechRef/JSONTutorial.xml
+++ b/docs/TechRef/JSONTutorial.xml
@@ -2193,6 +2193,82 @@
 				different ways (see the next subsection). </para>
 		</sect3>
 
+		<sect3>
+			<title>Choosing the Order of JOINs</title>
+			<para>As of Evergreen 3.0.2, we support user-defined join order in cstore and friends.
+				Previously, because the join structure of oils_sql beyond the specification of
+				a single table was only allowed to be represented as a JSON object, it was
+				subject to potential hash key reordering. By supporting an
+				intervening array layer, one can now specify the exact join order of the
+				tables in a join tree.
+
+				For example, given the following JSON object passing through a modern Perl 5
+				interpreter as a nested hash: </para>
+
+			<informalexample>
+				<programlisting language="JSON">
+    {select : {acp:['id'],
+                 acn:['record'],
+                 acpl:['name']
+                },
+      from : {acp:
+                    {acn:{filter:{record:12345}},
+                     acpl:null
+                    }
+                }
+    }
+				</programlisting>
+			</informalexample>
+
+			<para> the FROM clause of the query may end up as: </para>
+
+			<informalexample>
+				<programlisting language="SQL">
+				FROM acp
+					JOIN acn ON (acp.call_number = acn.id AND acn.record = 12345)
+					JOIN acpl ON (acp.location = acpl.id)
+				</programlisting>
+			</informalexample>
+
+			<para> Or as: </para>
+
+			<informalexample>
+				<programlisting language="SQL">
+				FROM acp
+					JOIN acpl ON (acp.location = acpl.id)
+					JOIN acn ON (acp.call_number = acn.id AND acn.record = 12345)
+				</programlisting>
+			</informalexample>
+
+			<para> In some situations, the join order will matter either to the semantics of the
+			query plan, or to its performance. The following example of the newly
+			supported syntax illustrates how to specify join order: </para>
+
+			<informalexample>
+				<programlisting language="JSON">
+    {select : {acp:['id'],
+                 acn:['record'],
+                 acpl:['name']
+                },
+      from : {acp:[
+                    {acn:{filter:{record:12345}}},
+                     'acpl'
+                ]}
+    }
+				</programlisting>
+			</informalexample>
+
+			<para> And the only FROM clause the can be generated is: </para>
+
+			<informalexample>
+				<programlisting language="SQL">
+				FROM acp
+					JOIN acn ON (acp.call_number = acn.id AND acn.record = 12345)
+					JOIN acpl ON (acp.location = acpl.id)
+				</programlisting>
+			</informalexample>
+		</sect3>
+
 		<sect3>
 			<title>Things You Can't Do</title>
 			<para> In a JOIN, as with other SQL constructs, there are some things that you can't do with
-- 
2.43.2