update json_query documentation for new join syntax

Bug #1731048 reported by Galen Charlton on 2017-11-08
6
This bug affects 1 person
Affects Status Importance Assigned to Milestone
Evergreen
Medium
Unassigned
3.0
Medium
Unassigned
3.1
Undecided
Unassigned

Bug Description

The patch for bug 1527731 taught json_query how to specify that tables to joined in a particular order. From the commit message:

    With this commit we now 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 -- thanks, Perl. 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:

    {select : {acp:['id'],
                 acn:['record'],
                 acpl:['name']
                },
      from : {acp:
                    {acn:{filter:{record:12345}},
                     acpl:null
                    }
                }
    }

    the FROM clause of the query may end up as:

      FROM acp
            JOIN acn ON (acp.call_number = acn.id AND acn.record = 12345)
            JOIN acpl ON (acp.location = acpl.id)

    Or as:

      FROM acp
            JOIN acpl ON (acp.location = acpl.id)
            JOIN acn ON (acp.call_number = acn.id AND acn.record = 12345)

    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:

    {select : {acp:['id'],
                 acn:['record'],
                 acpl:['name']
                },
      from : {acp:[
                    {acn:{filter:{record:12345}}},
                     'acpl'
                ]}
    }

    And the only FROM clause the can be generated is:

      FROM acp
            JOIN acn ON (acp.call_number = acn.id AND acn.record = 12345)
            JOIN acpl ON (acp.location = acpl.id)

Technical documentation that should be updated includes docs/TechRef/JSONTutorial.xml

Galen Charlton (gmc) on 2017-11-08
tags: added: documentation
Changed in evergreen:
milestone: none → 3.0.2
importance: Undecided → Medium
Changed in evergreen:
milestone: 3.0.2 → 3.0.3
Changed in evergreen:
milestone: 3.0.3 → 3.0.4
Changed in evergreen:
milestone: 3.0.4 → 3.05
Changed in evergreen:
milestone: 3.0.5 → 3.0.6
Changed in evergreen:
milestone: 3.0.6 → 3.0.7
Changed in evergreen:
milestone: 3.0.7 → 3.0.8
Changed in evergreen:
milestone: 3.0.8 → 3.1.3
Changed in evergreen:
milestone: 3.1.3 → 3.1.4
Changed in evergreen:
milestone: 3.1.4 → 3.1.5
Changed in evergreen:
milestone: 3.1.5 → 3.1.6
Changed in evergreen:
milestone: 3.1.6 → 3.2.1
Changed in evergreen:
milestone: 3.2.1 → 3.2.2
Remington Steed (rjs7) wrote :

We should also update the wiki page (or make a plan for removing one of them, so there's a single source):

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

Remington Steed (rjs7) wrote :

I've updated the wiki page. And here's a branch with the updated TechRef doc file:

http://git.evergreen-ils.org/?p=working/Evergreen.git;a=shortlog;h=refs/heads/user/rsteed/lp1731048_update_docs_for_json_query_ordered_joins

NOTE: The TechRef doc (DocBook format) isn't currently included in the official documentation (docs.evergreen-ils.org, which is AsciiDoc format). (Format conversion is probably easy via pandoc.)

Let's choose either the wiki or the TechRef directory to be the canonical place for this information, and remove the other one. I'd vote for removing the TechRef and keeping the wiki page. Opinions?

tags: added: pullrequest
Changed in evergreen:
milestone: 3.2.2 → 3.2.3
Remington Steed (rjs7) wrote :

For now, I've pushed the branch with the TechRef file change to master, 3.2 and 3.1.

Changed in evergreen:
status: New → Fix Committed
To post a comment you must log in.
This report contains Public information  Edit
Everyone can see this information.

Other bug subscribers