[open-ils-commits] [GIT] Evergreen ILS branch rel_3_1 updated. 567218dbf48afe306707e6e776a4c360e47e74e5

[Evergreen Git]

This is an automated email from the git hooks/post-receive script. It was
generated because a ref change was pushed to the repository containing
the project "Evergreen ILS".

The branch, rel_3_1 has been updated
       via  567218dbf48afe306707e6e776a4c360e47e74e5 (commit)
      from  4a7750ddb61b3d7c0811aea19a448ebbe467ff7c (commit)

Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.

- Log -----------------------------------------------------------------
commit 567218dbf48afe306707e6e776a4c360e47e74e5
Author: Remington Steed <rjs7 at calvin.edu>
Date:   Mon Nov 26 14:10:36 2018 -0500

    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 at calvin.edu>

diff --git a/docs/TechRef/JSONTutorial.xml b/docs/TechRef/JSONTutorial.xml
index 5ea28c3..f91678d 100644
--- a/docs/TechRef/JSONTutorial.xml
+++ b/docs/TechRef/JSONTutorial.xml
@@ -2194,6 +2194,82 @@
 		</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
 				a JSON query. </para>

-----------------------------------------------------------------------

Summary of changes:
 docs/TechRef/JSONTutorial.xml |   76 +++++++++++++++++++++++++++++++++++++++++
 1 files changed, 76 insertions(+), 0 deletions(-)


hooks/post-receive
-- 
Evergreen ILS