docs/TechRef/JSONGrammar.html

   1 <html><head>
   2       <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
   3    <title>Grammar of JSON Queries</title><meta name="generator" content="DocBook XSL-NS Stylesheets V1.74.3-pre"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e1"></a>Grammar of JSON Queries</h2></div></div><hr></div><p>
   4                 <span class="author"><span class="firstname">Scott</span> <span class="surname">McKellar</span></span>
   5         </p><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e19"></a>Introduction</h3></div></div></div><p> The format of this grammar approximates Extended Backus-Naur notation. However it is
   6                         intended as input to human beings, not to parser generators such as Lex or Yacc. Do not
   7                         expect formal rigor. Sometimes narrative text will explain things that are clumsy to
   8                         express in formal notation. More often, the text will restate or summarize the formal
   9                         productions. </p><p> Conventions: </p><div class="orderedlist"><ol type="1"><li><p>The grammar is a series of productions.</p></li><li><p>A production consists of a name, followed by "::=", followed by a definition
  10                                         for the name. The name identifies a grammatical construct that can appear on the
  11                                         right side of another production.</p></li><li><p>Literals (including punctuation) are enclosed in 'single quotes', or in
  12                                         "double quotes" if case is not significant.</p></li><li><p>A single quotation mark within a literal is escaped with a preceding
  13                                         backslash: 'dog\'s tail'.</p></li><li><p>If a construct can be defined more than one way, then the alternatives may
  14                                         appear in separate productions; or, they may appear in the same production,
  15                                         separated by pipe symbols. The choice between these representations is of only
  16                                         cosmetic significance.</p></li><li><p>A construct enclosed within square brackets is optional.</p></li><li><p>A construct enclosed within curly braces may be repeated zero or more
  17                                         times.</p></li><li><p>JSON allows arbitrary white space between tokens. To avoid ugly clutter, this
  18                                         grammar ignores the optional white space. </p></li><li><p>In many cases a production defines a JSON object, i.e. a list of name-value
  19                                         pairs, separated by commas. Since the order of these name/value pairs is not
  20                                         significant, the grammar will not try to show all the possible sequences. In
  21                                         general it will present the required pairs first, if any, followed by any
  22                                         optional elements.</p></li></ol></div><p> Since both EBNF and JSON use curly braces and square brackets, pay close attention to
  23                         whether these characters are in single quotes. If they're in single quotes, they are
  24                         literal elements of the JSON notation. Otherwise they are elements of the EBNF notation.
  25                 </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e56"></a>Primitives</h3></div></div></div><p> We'll start by defining some primitives, to get them out of the way. They're mostly
  26                         just what you would expect. </p><table width="100%" cellpadding="5" bgcolor="#F5DCB3" border="1" class="productionset" summary="EBNF"><tr><td><table border="0" width="99%" cellpadding="0" bgcolor="#F5DCB3" class="productionset" summary="EBNF productions"><tr><td align="left" valign="top" width="3%">[1]</td><td align="right" valign="top" width="10%"><a name="ebnf.string"></a> string </td><td valign="top" width="5%" align="center"><code>::=</code></td><td valign="top" width="52%"> '"' chars '"' </td><td align="left" valign="top" width="30%">&nbsp;</td></tr><tr><td align="left" valign="top" width="3%">[2]</td><td align="right" valign="top" width="10%"><a name="ebnf.chars"></a> chars </td><td valign="top" width="5%" align="center"><code>::=</code></td><td valign="top" width="52%"> any valid sequence of UTF-8 characters, with certain special characters
  27                                         escaped according to JSON rules </td><td align="left" valign="top" width="30%">&nbsp;</td></tr><tr><td align="left" valign="top" width="3%">[3]</td><td align="right" valign="top" width="10%"><a name="ebnf.integer_literal"></a> integer_literal </td><td valign="top" width="5%" align="center"><code>::=</code></td><td valign="top" width="52%"> [ sign ] digit { digit } </td><td align="left" valign="top" width="30%">&nbsp;</td></tr><tr><td align="left" valign="top" width="3%">[4]</td><td align="right" valign="top" width="10%"><a name="ebnf.sign"></a> sign </td><td valign="top" width="5%" align="center"><code>::=</code></td><td valign="top" width="52%"> '+' | '-' </td><td align="left" valign="top" width="30%">&nbsp;</td></tr><tr><td align="left" valign="top" width="3%">[5]</td><td align="right" valign="top" width="10%"><a name="ebnf.digit"></a> digit </td><td valign="top" width="5%" align="center"><code>::=</code></td><td valign="top" width="52%">digit = '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9'</td><td align="left" valign="top" width="30%">&nbsp;</td></tr><tr><td align="left" valign="top" width="3%">[6]</td><td align="right" valign="top" width="10%"><a name="ebnf.integer_string"></a> integer_string </td><td valign="top" width="5%" align="center"><code>::=</code></td><td valign="top" width="52%"> '"' integer_literal '"' </td><td align="left" valign="top" width="30%">&nbsp;</td></tr><tr><td align="left" valign="top" width="3%">[7]</td><td align="right" valign="top" width="10%"><a name="ebnf.integer"></a> integer </td><td valign="top" width="5%" align="center"><code>::=</code></td><td valign="top" width="52%"> integer_literal | integer_string </td><td align="left" valign="top" width="30%">&nbsp;</td></tr><tr><td align="left" valign="top" width="3%">[8]</td><td align="right" valign="top" width="10%"><a name="ebnf.number"></a> number </td><td valign="top" width="5%" align="center"><code>::=</code></td><td valign="top" width="52%"> any valid character sequence that is numeric according to JSON rules </td><td align="left" valign="top" width="30%">&nbsp;</td></tr></table></td></tr></table><p> When json_query requires an integral value, it will usually accept a quoted string
  28                         and convert it to an integer by brute force &#8211; to zero if necessary. Likewise it may
  29                         truncate a floating point number to an integral value. Scientific notation will be
  30                         accepted but may not give the intended results. </p><table width="100%" cellpadding="5" bgcolor="#F5DCB3" border="1" class="productionset" summary="EBNF"><tr><td><table border="0" width="99%" cellpadding="0" bgcolor="#F5DCB3" class="productionset" summary="EBNF productions"><tr><td align="left" valign="top" width="3%">[9]</td><td align="right" valign="top" width="10%"><a name="ebnf.boolean"></a> boolean </td><td valign="top" width="5%" align="center"><code>::=</code></td><td valign="top" width="52%"> 'true' | 'false' | string | number </td><td align="left" valign="top" width="30%">&nbsp;</td></tr></table></td></tr></table><p> The preferred way to encode a boolean is with the JSON reserved word true or false,
  31                         in lower case without quotation marks. The string <code class="literal">true</code>, in upper,
  32                         lower, or mixed case, is another way to encode true. Any other string evaluates to
  33                         false. </p><p> As an accommodation to perl, numbers may be used as booleans. A numeric value of 1
  34                         means true, and any other numeric value means false. </p><p> Any other valid JSON value, such as an array, will be accepted as a boolean but
  35                         interpreted as false. </p><p> The last couple of primitives aren't really very primitive, but we introduce them
  36                         here for convenience: </p><table width="100%" cellpadding="5" bgcolor="#F5DCB3" border="1" class="productionset" summary="EBNF"><tr><td><table border="0" width="99%" cellpadding="0" bgcolor="#F5DCB3" class="productionset" summary="EBNF productions"><tr><td align="left" valign="top" width="3%">[10]</td><td align="right" valign="top" width="10%"><a name="ebnf.class_name"></a> class_name </td><td valign="top" width="5%" align="center"><code>::=</code></td><td valign="top" width="52%"> string </td><td align="left" valign="top" width="30%">&nbsp;</td></tr></table></td></tr></table><p> A class_name is a special case of a string: the name of a class as defined by the
  37                         IDL. The class may refer either to a database table or to a source_definition, which is
  38                         a subquery. </p><table width="100%" cellpadding="5" bgcolor="#F5DCB3" border="1" class="productionset" summary="EBNF"><tr><td><table border="0" width="99%" cellpadding="0" bgcolor="#F5DCB3" class="productionset" summary="EBNF productions"><tr><td align="left" valign="top" width="3%">[11]</td><td align="right" valign="top" width="10%"><a name="ebnf.field_name"></a> field_name </td><td valign="top" width="5%" align="center"><code>::=</code></td><td valign="top" width="52%"> string </td><td align="left" valign="top" width="30%">&nbsp;</td></tr></table></td></tr></table><p> A field_name is another special case of a string: the name of a non-virtual field as
  39                         defined by the IDL. A field_name is also a column name for the table corresponding to
  40                         the relevant class. </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e185"></a>Query</h3></div></div></div><p> The following production applies not only to the main query but also to most
  41                         subqueries. </p><table width="100%" cellpadding="5" bgcolor="#F5DCB3" border="1" class="productionset" summary="EBNF"><tr><td><table border="0" width="99%" cellpadding="0" bgcolor="#F5DCB3" class="productionset" summary="EBNF productions"><tr><td align="left" valign="top" width="3%">[12]</td><td align="right" valign="top" width="10%"><a name="ebnf.query"></a> query </td><td valign="top" width="5%" align="center"><code>::=</code></td><td valign="top" width="52%"> '{'<br> '"from"' ':' from_list<br> [ ',' '"select"' ':' select_list
  42                                         ]<br> [ ',' '"where"' ':' where_condition ]<br> [ ',' '"having"' ':'
  43                                         where_condition ]<br> [ ',' '"order_by"' ':' order_by_list ]<br> [ ','
  44                                         '"limit"' ':' integer ]<br> [ ',' '"offset"' ':' integer ]<br> [ ','
  45                                         '"distinct"' ':' boolean ]<br> [ ',' '"no_i18n"' ':' boolean ]<br> '}'
  46                                 </td><td align="left" valign="top" width="30%">&nbsp;</td></tr></table></td></tr></table><p> Except for the <code class="literal">"distinct"</code> and <code class="literal">no_i18n</code> entries,
  47                         each name/value pair represents a major clause of the SELECT statement. The name/value
  48                         pairs may appear in any order. </p><p> There is no name/value pair for the GROUP BY clause, because json_query generates it
  49                         automatically according to information encoded elsewhere. </p><p> The <code class="literal">"distinct"</code> entry, if present and true, tells json_query that
  50                         it may have to create a GROUP BY clause. If not present, it defaults to false. </p><p> The <code class="literal">"no_i18n"</code> entry, if present and true, tells json_query to
  51                         suppress internationalization. If not present, it defaults to false. (Note that
  52                                 <code class="literal">"no_i18n"</code> contains the digit one, not the letter ell.) </p><p> The values for <code class="literal">limit</code> and <code class="literal">offset</code> provide the
  53                         arguments of the LIMIT and OFFSET clauses, respectively, of the SQL statement. Each
  54                         value should be non-negative, if present, or else the SQL won't work. </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e252"></a>FROM Clause</h3></div></div></div><p>
  55                         The object identified by <code class="literal">&#8220;from&#8221;</code> encodes the FROM clause of
  56                         the SQL.  The associated value may be a string, an array, or a JSON object.
  57                 </p><table width="100%" cellpadding="5" bgcolor="#F5DCB3" border="1" class="productionset" summary="EBNF"><tr><td><table border="0" width="99%" cellpadding="0" bgcolor="#F5DCB3" class="productionset" summary="EBNF productions"><tr><td align="left" valign="top" width="3%">[13]</td><td align="right" valign="top" width="10%"><a name="ebnf.from_list_0"></a> from_list </td><td valign="top" width="5%" align="center"><code>::=</code></td><td valign="top" width="52%"> class_name </td><td align="left" valign="top" width="30%">&nbsp;</td></tr></table></td></tr></table><p>
  58                         If <code class="literal">from_list</code> is a <code class="literal">class_name</code>, the
  59                         json_query inserts the corresponding table name or subquery into the FROM
  60                         clause, using the <code class="literal">class_name</code> as an alias for the table
  61                         or subquery.  The class must be defined as non-virtual in the IDL.
  62                 </p><table width="100%" cellpadding="5" bgcolor="#F5DCB3" border="1" class="productionset" summary="EBNF"><tr><td><table border="0" width="99%" cellpadding="0" bgcolor="#F5DCB3" class="productionset" summary="EBNF productions"><tr><td align="left" valign="top" width="3%">[14]</td><td align="right" valign="top" width="10%"><a name="ebnf.from_list_1"></a> from_list </td><td valign="top" width="5%" align="center"><code>::=</code></td><td valign="top" width="52%"> '['  string  {  ','  parameter  }  ']' </td><td align="left" valign="top" width="30%">&nbsp;</td></tr><tr><td align="left" valign="top" width="3%">[15]</td><td align="right" valign="top" width="10%"><a name="ebnf.parameter"></a> parameter </td><td valign="top" width="5%" align="center"><code>::=</code></td><td valign="top" width="52%"> string  |  number  |  'null' </td><td align="left" valign="top" width="30%">&nbsp;</td></tr></table></td></tr></table><p>
  63                         If from_list is a JSON array, then it represents a table-like function from
  64                         which the SQL statement will select rows, using a SELECT clause consisting
  65                         of &#8220;SELECT *&#8221; (regardless of the select_list supplied by the method parameter).
  66                 </p><p>
  67                         The first entry in the array is the name of the function.  It must be a string
  68                         naming a stored function.  Each subsequent entry is a function parameter.  If
  69                         it is a string or a number, json_query will insert it into a comma-separated
  70                         parameter list, enclosed in quotes, with any special characters escaped as needed.
  71                         If it is the JSON reserved word <code class="literal">null</code>, json_query will insert
  72                         it into the parameter list as a null value.
  73                 </p><p>
  74                         If <code class="literal">from_list</code> is a JSON object, it must contain exactly one entry.
  75                         The key of this entry must be the name of a non-virtual class defined in the IDL.
  76                         This class will be the top-level class of the FROM clause, the only one named
  77                         outside of a JOIN clause.
  78                 </p><table width="100%" cellpadding="5" bgcolor="#F5DCB3" border="1" class="productionset" summary="EBNF"><tr><td><table border="0" width="99%" cellpadding="0" bgcolor="#F5DCB3" class="productionset" summary="EBNF productions"><tr><td align="left" valign="top" width="3%">[16]</td><td align="right" valign="top" width="10%"><a name="ebnf.from_list_2"></a> from_list </td><td valign="top" width="5%" align="center"><code>::=</code></td><td valign="top" width="52%"> '{' class_name ':' join_list '}' </td><td align="left" valign="top" width="30%">&nbsp;</td></tr><tr><td align="left" valign="top" width="3%">[17]</td><td align="right" valign="top" width="10%"><a name="ebnf.join_list_0"></a> join_list </td><td valign="top" width="5%" align="center"><code>::=</code></td><td valign="top" width="52%"> class_name </td><td align="left" valign="top" width="30%">&nbsp;</td></tr><tr><td align="left" valign="top" width="3%">[18]</td><td align="right" valign="top" width="10%"><a name="ebnf.join_list_1"></a> join_list </td><td valign="top" width="5%" align="center"><code>::=</code></td><td valign="top" width="52%"> '{' join_def { ',' join_def } '}' </td><td align="left" valign="top" width="30%">&nbsp;</td></tr></table></td></tr></table><p>
  79                         If the associated data is a <code class="literal">class_name</code>, json_query will
  80                         construct an INNER JOIN clause joining the class to the top-level clause,
  81                         using the columns specified by the IDL for such a join.
  82                 </p><p>
  83                         Otherwise, the associated data must be a JSON object with one or more entries,
  84                         each entry defining a join:
  85                 </p><table width="100%" cellpadding="5" bgcolor="#F5DCB3" border="1" class="productionset" summary="EBNF"><tr><td><table border="0" width="99%" cellpadding="0" bgcolor="#F5DCB3" class="productionset" summary="EBNF productions"><tr><td align="left" valign="top" width="3%">[19]</td><td align="right" valign="top" width="10%"><a name="ebnf.join_def"></a> join_def </td><td valign="top" width="5%" align="center"><code>::=</code></td><td valign="top" width="52%">
  86                                         class_name  ':'<br>
  87                                         '{'<br>
  88                                         [  '&#8221;type&#8221;'      ':'  string      ]<br>
  89                                         [  '&#8221;field&#8221;'     ':'  field_name  ]<br>
  90                                         [  '&#8221;fkey&#8221;'      ':'  field_name  ]<br>
  91                                         [  '&#8221;filter&#8221;'    ':'  where_condition  ]<br>
  92                                         [  '&#8221;filter_op&#8221;' ':'  string      ]<br>
  93                                         [  '&#8221;join&#8221;'      ':'  join_list   ]<br>
  94                                         '}'
  95                                 </td><td align="left" valign="top" width="30%">&nbsp;</td></tr></table></td></tr></table><p>
  96                         The data portion of the <code class="literal">&#8220;join_type&#8221;</code> entry tells json_query
  97                         whether to use a left join, right join, full join, or inner join.  The values
  98                         <code class="literal">&#8220;left&#8221;</code>, <code class="literal">&#8220;right&#8221;</code>, and <code class="literal">&#8220;full&#8221;</code>,
  99                         in upper, lower, or mixed case, have the obvious meanings.  If the
 100                         <code class="literal">&#8220;join_type&#8221;</code> entry has any other value, or is not present,
 101                         json_query constructs an inner join.
 102                 </p><p>
 103                         The <code class="literal">&#8220;field&#8221;</code> and <code class="literal">&#8220;fkey&#8221;</code> attributes specify the
 104                         columns to be equated in the join condition.  The <code class="literal">&#8220;field&#8221;</code>
 105                         attribute refers to the column in the joined table, i.e. the one named by the
 106                         <code class="literal">join_def</code>.  The <code class="literal">&#8220;fkey&#8221;</code> attribute refers to the
 107                         corresponding column in the other table, i.e. the one named outside the
 108                         <code class="literal">join_def</code> &#8211; either the top-level table or a table named by some
 109                         other <code class="literal">join_def</code>.
 110                 </p><p>
 111                         It may be tempting to suppose that <code class="literal">&#8220;fkey&#8221;</code> stands for &#8220;foreign key&#8221;,
 112                         and therefore refers to a column in the child table that points to the key of a
 113                         parent table.  Resist the temptation; the labels are arbitrary.  The json_query
 114                         method doesn't care which table is the parent and which is the child.
 115                 </p><p>
 116                         These relationships are best explained with an example.  The following
 117                         <code class="literal">from_list</code>:
 118                 </p><div class="informalexample"><pre class="programlisting">
 119         {
 120             "aou": {
 121                 "asv": {
 122                     "type" : "left",
 123                     "fkey" : "id",
 124                     "field" : "owner"
 125                 }
 126             }
 127         }
 128                         </pre></div><p>
 129                         ...turns into the following FROM clause:
 130                 </p><div class="informalexample"><pre class="programlisting">
 131         FROM
 132             actor.org_unit AS "aou"
 133                 LEFT JOIN action.survey AS "asv"
 134                     ON ( "asv".owner = "aou".id )
 135                         </pre></div><p>
 136                         Note in this example that <code class="literal">&#8220;fkey&#8221;</code> refers to a column of the
 137                         class <code class="literal">&#8220;aou&#8221;</code>, and <code class="literal">&#8220;field&#8221;</code> refers to a
 138                         column of the class <code class="literal">&#8220;asv&#8221;</code>.
 139                 </p><p>
 140                         If you specify only one of the two columns, json_query will try to identify the
 141                         other one from the IDL. However, if you specify only the column from the parent
 142                         table, this attempt will probably fail.
 143                 </p><p>
 144                         If you specify both columns, json_query will use the column names you specify,
 145                         without verifying them with a lookup in the IDL.  By this means you can perform
 146                         a join using a linkage that the IDL doesn't define.  Of course, if the columns
 147                         don't exist in the database, the query will fail when json_query tries to execute it.
 148                 </p><p>
 149                         Using the columns specified, either explicitly or implicitly, the json_query
 150                         method constructs a join condition.  With raw SQL it is possible (though
 151                         rarely useful) to join two tables by an inequality.  However the json_query
 152                         method always uses a simple equality condition.
 153                 </p><p>
 154                         Using a <code class="literal">&#8220;filter&#8221;</code> entry in the join_def, you can apply one
 155                         or more additional conditions to the JOIN clause, typically to restrict the
 156                         join to certain rows of the joined table.  The data associated with the
 157                         <code class="literal">&#8220;filter&#8221;</code> key is the same sort of
 158                         <code class="literal">where_condition</code> that you use for a WHERE clause
 159                         (discussed below).
 160                 </p><p>
 161                         If the string associated with the <code class="literal">&#8220;filter_op&#8221;</code> entry is
 162                         <code class="literal">&#8220;OR&#8221;</code> in upper, lower, or mixed case, then the json_query
 163                         method uses OR to connect the standard join condition to any additional
 164                         conditions supplied by a <code class="literal">&#8220;filter&#8221;</code> entry.
 165                 </p><p>
 166                         (Note that if the <code class="literal">where_condition</code> supplies multiple
 167                         conditions, they will be connected by AND.  You will probably want to move
 168                         them down a layer &#8211; enclose them in parentheses, in effect &#8211; to avoid a
 169                         confusing mixture of ANDs and ORs.)
 170                 </p><p>
 171                         If the <code class="literal">&#8220;filter_op&#8221;</code> entry carries any other value, or if
 172                         it is absent, then the json_query method uses AND.  In the absence of a
 173                         <code class="literal">&#8220;filter&#8221;</code> entry, <code class="literal">&#8220;filter_op&#8221;</code> has no effect.
 174                 </p><p>
 175                         A <code class="literal">&#8220;join&#8221;</code> entry in a <code class="literal">join_def</code> specifies
 176                         another layer of join.  The class named in the subjoin is joined to the class
 177                         named by the <code class="literal">join_def</code> to which it is subordinate.  By this
 178                         means you can encode multiple joins in a hierarchy.
 179                 </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e504"></a>SELECT Clause</h3></div></div></div><p>
 180                         If a query does not contain an entry for <code class="literal">&#8220;select&#8221;</code>, json_query
 181                         will construct a default SELECT clause.  The default includes every non-virtual
 182                         field from the top-level class of the FROM clause, as defined by the IDL.  The
 183                         result is similar to SELECT *, except:
 184                 </p><div class="itemizedlist"><ul type="disc"><li><p>The default includes only the fields defined in the IDL.</p></li><li><p>The columns will appear in the same order in which they appear in the IDL,
 185                                 regardless of the order in which the database defines them.</p></li></ul></div><p>
 186                         There are other ways to specify a default SELECT list, as shown below.
 187                 </p><p>
 188                         If a <code class="literal">"select"</code> entry is present, the associated value must
 189                         be a JSON object, keyed on class names:
 190                 </p><table width="100%" cellpadding="5" bgcolor="#F5DCB3" border="1" class="productionset" summary="EBNF"><tr><td><table border="0" width="99%" cellpadding="0" bgcolor="#F5DCB3" class="productionset" summary="EBNF productions"><tr><td align="left" valign="top" width="3%">[20]</td><td align="right" valign="top" width="10%"><a name="ebnf.select_list"></a> select_list </td><td valign="top" width="5%" align="center"><code>::=</code></td><td valign="top" width="52%"> '{' class_name ':' field_list { ',' class_name ':' field_list } '}' </td><td align="left" valign="top" width="30%">&nbsp;</td></tr></table></td></tr></table><p>
 191                         The <code class="literal">class_name</code> must identify either the top-level class or
 192                         a class belonging to one of the joins.  Otherwise json_query will silently
 193                         ignore the <code class="literal">select_list</code>.
 194                 </p><table width="100%" cellpadding="5" bgcolor="#F5DCB3" border="1" class="productionset" summary="EBNF"><tr><td><table border="0" width="99%" cellpadding="0" bgcolor="#F5DCB3" class="productionset" summary="EBNF productions"><tr><td align="left" valign="top" width="3%">[21]</td><td align="right" valign="top" width="10%"><a name="ebnf.field_list_0"></a> field_list </td><td valign="top" width="5%" align="center"><code>::=</code></td><td valign="top" width="52%"> 'null'  |  '&#8221;*&#8221;' </td><td align="left" valign="top" width="30%">&nbsp;</td></tr></table></td></tr></table><p>
 195                         If a field_list is either the JSON reserved word <code class="literal">null</code>
 196                         (in lower case) or an asterisk in double quotes, json_query constructs a
 197                         default SELECT list &#8211; provided that the class is the top-level class of the
 198                         query.  If the class belongs to a join somewhere, json_query ignores the
 199                         <code class="literal">field_list</code>.
 200                 </p><p>
 201                         More commonly, the <code class="literal">field_list</code> is a JSON array of zero or
 202                         more field specifications:
 203                 </p><table width="100%" cellpadding="5" bgcolor="#F5DCB3" border="1" class="productionset" summary="EBNF"><tr><td><table border="0" width="99%" cellpadding="0" bgcolor="#F5DCB3" class="productionset" summary="EBNF productions"><tr><td align="left" valign="top" width="3%">[22]</td><td align="right" valign="top" width="10%"><a name="ebnf.field_list_1"></a> field_list </td><td valign="top" width="5%" align="center"><code>::=</code></td><td valign="top" width="52%"> '['  [  field_spec  {  ','  field_spec  }  ]  ']' </td><td align="left" valign="top" width="30%">&nbsp;</td></tr></table></td></tr></table><p>
 204                         If the array is empty, json_query will construct a default SELECT list for
 205                         the class &#8211; again, provided that the class is the top-level class in the query.
 206                 </p><p>
 207                         In the simplest case, a field specification may name a non-virtual field
 208                         defined in the IDL:
 209                 </p><table width="100%" cellpadding="5" bgcolor="#F5DCB3" border="1" class="productionset" summary="EBNF"><tr><td><table border="0" width="99%" cellpadding="0" bgcolor="#F5DCB3" class="productionset" summary="EBNF productions"><tr><td align="left" valign="top" width="3%">[23]</td><td align="right" valign="top" width="10%"><a name="ebnf.field_spec_0"></a> field_spec </td><td valign="top" width="5%" align="center"><code>::=</code></td><td valign="top" width="52%"> field_name </td><td align="left" valign="top" width="30%">&nbsp;</td></tr></table></td></tr></table><p>
 210                         In some cases json_query constructs a call to the
 211                         <code class="literal">oils_i18n_xlate</code> function to internationalize the value of the
 212                         selected column.  Specifically, it does so if all the following are true:
 213                 </p><div class="itemizedlist"><ul type="disc"><li><p>the settings file defines a locale;</p></li><li><p>in the field definition for the field in the IDL, the tag
 214                                 <code class="literal">&#8220;il8n&#8221;</code> is present and true;</p></li><li><p>the query does <span class="emphasis"><em>not</em></span> include the
 215                                 <code class="literal">"no_il8n"</code> tag (or includes it with a value of false).</p></li></ul></div><p>
 216                         A field specification may be a JSON object:
 217                 </p><table width="100%" cellpadding="5" bgcolor="#F5DCB3" border="1" class="productionset" summary="EBNF"><tr><td><table border="0" width="99%" cellpadding="0" bgcolor="#F5DCB3" class="productionset" summary="EBNF productions"><tr><td align="left" valign="top" width="3%">[24]</td><td align="right" valign="top" width="10%"><a name="ebnf.field_spec_1"></a> field_spec </td><td valign="top" width="5%" align="center"><code>::=</code></td><td valign="top" width="52%">
 218                                         '{'<br>
 219                                         '&#8221;column&#8221;'  ':'  <br>
 220                                         [ ',' '&#8221;alias&#8221;'  ':'  string  ]<br>
 221                                         [ ',' '&#8221;aggregate&#8221;'  ':'  boolean  ]<br>
 222                                         [ ',' transform_spec  ]<br>
 223                                         '}'
 224                                 </td><td align="left" valign="top" width="30%">&nbsp;</td></tr></table></td></tr></table><p>
 225                         The <code class="literal">&#8220;column&#8221;</code> entry provides the column name, which must
 226                         be defined as non-virtual in the IDL.
 227                 </p><p>
 228                         The <code class="literal">&#8220;alias&#8221;</code> entry provides a column alias.  If no alias
 229                         is specified, json_query uses the column name as its own alias.
 230                 </p><p>
 231                         The <code class="literal">&#8220;aggregate&#8221;</code> entry has no effect on the SELECT clause
 232                         itself.  Rather, it affects the construction of a GROUP BY class.  If there
 233                         is an <code class="literal">&#8220;aggregate&#8221;</code> entry for any field, then json_query builds
 234                         a GROUP BY clause listing every column that is <span class="emphasis"><em>not</em></span> tagged
 235                         for aggregation (or that carries an <code class="literal">&#8220;aggregate&#8221;</code> entry with
 236                         a value of false).  If <span class="emphasis"><em>all</em></span> columns are tagged for
 237                         aggregation, then json_query omits the GROUP BY clause.
 238                 </p><table width="100%" cellpadding="5" bgcolor="#F5DCB3" border="1" class="productionset" summary="EBNF"><tr><td><table border="0" width="99%" cellpadding="0" bgcolor="#F5DCB3" class="productionset" summary="EBNF productions"><tr><td align="left" valign="top" width="3%">[25]</td><td align="right" valign="top" width="10%"><a name="ebnf.transform_spec_0"></a> transform_spec </td><td valign="top" width="5%" align="center"><code>::=</code></td><td valign="top" width="52%">
 239                                         '&#8221;transform&#8221;'  ':'  string  ]<br>
 240                                         [ ',' '&#8221;result_field&#8221;  ':'  string  ]<br>
 241                                         [ ',' '&#8221;params&#8221;  ':' param_list  ]
 242                                 </td><td align="left" valign="top" width="30%">&nbsp;</td></tr></table></td></tr></table><p>
 243                         When a <code class="literal">transform_spec</code> is present, json_query selects the
 244                         return value of a function instead of selecting the column directly.  The entry
 245                         for <code class="literal">&#8220;transform&#8221;</code> provides the name of the function, and the
 246                         column name (as specified by the <code class="literal">&#8220;column&#8221;</code> tag), qualified by
 247                         the class name, is the argument to the function.  For example, you might use such
 248                         a function to format a date or time, or otherwise transform a column value.
 249                         You might also use an aggregate function such as SUM, COUNT, or MAX (possibly
 250                         together with the <code class="literal">&#8220;aggregate&#8221;</code> tag).
 251                 </p><p>
 252                         The <code class="literal">&#8220;result_field&#8221;</code> entry, when present, specifies a subcolumn
 253                         of the function's return value.  The resulting SQL encloses the function call
 254                         in parentheses, and follows it with a period and the subcolumn name.
 255                 </p><p>
 256                         The <code class="literal">&#8220;params&#8221;</code> entry, if present, provides a possibly empty
 257                         array of additional parameter values, either strings, numbers, or nulls:
 258                 </p><table width="100%" cellpadding="5" bgcolor="#F5DCB3" border="1" class="productionset" summary="EBNF"><tr><td><table border="0" width="99%" cellpadding="0" bgcolor="#F5DCB3" class="productionset" summary="EBNF productions"><tr><td align="left" valign="top" width="3%">[26]</td><td align="right" valign="top" width="10%"><a name="ebnf.param_list"></a> param_list </td><td valign="top" width="5%" align="center"><code>::=</code></td><td valign="top" width="52%"> '['  [  parameter  {  ','  parameter  }  ]  ']' </td><td align="left" valign="top" width="30%">&nbsp;</td></tr></table></td></tr></table><p>
 259                         Such parameter values are enclosed in single quotes, with any special characters
 260                         escaped as needed, and inserted after the column name as additional parameters
 261                         to the function.  You might, for example, use an additional parameter to provide
 262                         a format string for a reformatting function.
 263                 </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e721"></a>WHERE Clause</h3></div></div></div><p> There are two types of <code class="literal">where_condition</code>: objects and arrays.
 264                         Of these, the object type is the more fundamental, and occurs at some level in every
 265                         <code class="literal">where_condition</code>.  The array type is mainly a way of circumventing
 266                         a limitation of the object type. </p><p> The object type of <code class="literal">where_condition</code> is a comma-separated list
 267                         of one or more <code class="literal">conditions</code>: </p><table width="100%" cellpadding="5" bgcolor="#F5DCB3" border="1" class="productionset" summary="EBNF"><tr><td><table border="0" width="99%" cellpadding="0" bgcolor="#F5DCB3" class="productionset" summary="EBNF productions"><tr><td align="left" valign="top" width="3%">[27]</td><td align="right" valign="top" width="10%"><a name="ebnf.where_condition_0"></a> where_condition </td><td valign="top" width="5%" align="center"><code>::=</code></td><td valign="top" width="52%"> '{' condition { ',' condition } '}' </td><td align="left" valign="top" width="30%">&nbsp;</td></tr></table></td></tr></table><p> The generated SQL will include a code fragment for each <code class="literal">condition</code>,
 268                         joined by AND (or in some cases by OR, as described below). </p><p> As usual for entries in a JSON object, each <code class="literal">condition</code> consists
 269                         of a unique string to serve as a key, a colon, and an associated value. </p><p> The key string may be the name of a column belonging to the relevant table, or
 270                         it may be an operator string.  In order to distinguish it from any possible column
 271                         name, an operator string always begins with a plus sign or minus sign. </p><p> JSON requires that every key string be unique within an object.  This requirement
 272                         imposes some awkward limitations on a JSON query.  For example, you might want to
 273                         express two conditions for the same column: id &gt; 10 and id != 25.  Since each of
 274                         those conditions would have the same key string, namely &#8220;id&#8221;, you can't put them
 275                         into the same JSON object. </p><p> The solution is to put such conflicting conditions in separate JSON objects, and
 276                         put the objects into an array: </p><table width="100%" cellpadding="5" bgcolor="#F5DCB3" border="1" class="productionset" summary="EBNF"><tr><td><table border="0" width="99%" cellpadding="0" bgcolor="#F5DCB3" class="productionset" summary="EBNF productions"><tr><td align="left" valign="top" width="3%">[28]</td><td align="right" valign="top" width="10%"><a name="ebnf.where_condition_1"></a> where_condition </td><td valign="top" width="5%" align="center"><code>::=</code></td><td valign="top" width="52%"> '[' where_condition { ',' where_condition } ']' </td><td align="left" valign="top" width="30%">&nbsp;</td></tr></table></td></tr></table><p> The resulting SQL encloses each subordinate set of <code class="literal">conditions</code>
 277                         in parentheses, and connects the sets with AND (or in some cases OR, as described
 278                         below).  It's possible to put only a single <code class="literal">where_condition</code> in
 279                         the array; the result is to add a layer of parentheses around the condition. </p><p> There are two kinds of <code class="literal">condition</code> where the operator begins
 280                         with a plus sign.  In the simpler case, the associated data is simply a column name:
 281                 </p><table width="100%" cellpadding="5" bgcolor="#F5DCB3" border="1" class="productionset" summary="EBNF"><tr><td><table border="0" width="99%" cellpadding="0" bgcolor="#F5DCB3" class="productionset" summary="EBNF productions"><tr><td align="left" valign="top" width="3%">[29]</td><td align="right" valign="top" width="10%"><a name="ebnf.condition_0"></a> condition </td><td valign="top" width="5%" align="center"><code>::=</code></td><td valign="top" width="52%"> plus_class ':' field_name </td><td align="left" valign="top" width="30%">&nbsp;</td></tr></table></td></tr></table><p> A <code class="literal">plus_class</code> is a string that begins with a plus sign.
 282                         The rest of the string, after the plus sign, must be the class name for the table
 283                         to which the column belongs. </p><p> If the column is a boolean, then the resulting SQL uses it (as qualified by the
 284                         class name) as a stand-alone condition. </p><p> Otherwise, this kind of syntax provides a way to place a column on the right side
 285                         of a comparison operator.  For example: </p><div class="informalexample"><pre class="programlisting">
 286         {
 287             "from":"aou",
 288             "select": { "aou":[ "id", "name" ] },
 289             "where": {
 290                 "id": {
 291                     "&gt;": { "+aou":"parent_ou" }
 292                 }
 293             }
 294         }
 295                         </pre></div><p> The resulting SQL: </p><div class="informalexample"><pre class="programlisting">
 296         SELECT
 297             "aou".id AS "id",
 298             "aou".name AS "name"
 299         FROM
 300             actor.org_unit AS "aou"
 301         WHERE
 302             (
 303                 "aou".id &gt; (  "aou".parent_ou  )
 304             );
 305                         </pre></div><p> The other type of <code class="literal">condition</code> that uses a
 306                         <code class="literal">plus_class</code> applies a specified class name to a
 307                         <code class="literal">where_condition</code>: </p><table width="100%" cellpadding="5" bgcolor="#F5DCB3" border="1" class="productionset" summary="EBNF"><tr><td><table border="0" width="99%" cellpadding="0" bgcolor="#F5DCB3" class="productionset" summary="EBNF productions"><tr><td align="left" valign="top" width="3%">[30]</td><td align="right" valign="top" width="10%"><a name="ebnf.condition_1"></a> condition </td><td valign="top" width="5%" align="center"><code>::=</code></td><td valign="top" width="52%"> plus_class ':' where_condition </td><td align="left" valign="top" width="30%">&nbsp;</td></tr></table></td></tr></table><p> The resulting SQL is enclosed in parentheses, and qualifies the columns with
 308                         the specified class name.  This syntax provides a mechanism to shift the class
 309                         context &#8211; i.e. to refer to one class in a context that would otherwise refer to
 310                         a different class. </p><p> Ordinarily the class name must be a valid non-virtual class defined in the IDL,
 311                         and applicable to the associated <code class="literal">where_condition</code>.  There is at
 312                         least one peculiar exception.  The JSON fragment: </p><div class="informalexample"><pre class="programlisting">
 313         "+abc": { "+xyz":"frobozz" }
 314                         </pre></div><p> ...is rendered as: </p><div class="informalexample"><pre class="programlisting">
 315         (  "xyz".frobozz  )
 316                         </pre></div><p> ...even though neither <code class="literal">&#8220;abc&#8221;</code>, nor <code class="literal">&#8220;xyz&#8221;</code>,
 317                         nor <code class="literal">&#8220;frobozz&#8221;</code> is defined in the IDL.  The class name
 318                         <code class="literal">&#8220;abc&#8221;</code> isn't used at all because the <code class="literal">&#8220;+xyz&#8221;</code>
 319                         operator overrides it.  Such a query won't fail until json_query tries
 320                         to execute it in the database. </p><p> The other operators that may occur at this level all begin with a minus sign,
 321                         and they all represent familiar SQL operators.  For example, the
 322                         <code class="literal">&#8220;-or&#8221;</code> operator joins the conditions within a
 323                         <code class="literal">where_condition</code> by OR (instead of the default AND), and
 324                         encloses them all in parentheses: </p><table width="100%" cellpadding="5" bgcolor="#F5DCB3" border="1" class="productionset" summary="EBNF"><tr><td><table border="0" width="99%" cellpadding="0" bgcolor="#F5DCB3" class="productionset" summary="EBNF productions"><tr><td align="left" valign="top" width="3%">[31]</td><td align="right" valign="top" width="10%"><a name="ebnf.condition_2"></a> condition </td><td valign="top" width="5%" align="center"><code>::=</code></td><td valign="top" width="52%"> '&#8221;-or&#8221;' ':' where_condition </td><td align="left" valign="top" width="30%">&nbsp;</td></tr></table></td></tr></table><p> In fact the <code class="literal">&#8220;-or&#8221;</code> operator is the only way to get OR into
 325                         the WHERE clause. </p><p> The <code class="literal">&#8220;-and&#8221;</code> operator is similar, except that it uses AND: </p><table width="100%" cellpadding="5" bgcolor="#F5DCB3" border="1" class="productionset" summary="EBNF"><tr><td><table border="0" width="99%" cellpadding="0" bgcolor="#F5DCB3" class="productionset" summary="EBNF productions"><tr><td align="left" valign="top" width="3%">[32]</td><td align="right" valign="top" width="10%"><a name="ebnf.condition_3"></a> condition </td><td valign="top" width="5%" align="center"><code>::=</code></td><td valign="top" width="52%"> '&#8221;-and&#8221;' ':'  where_condition </td><td align="left" valign="top" width="30%">&nbsp;</td></tr></table></td></tr></table><p> Arguably the <code class="literal">&#8220;-and&#8221;</code> operator is redundant, because you can
 326                         get the same effect by wrapping the subordinate <code class="literal">where_condition</code>
 327                         in a JSON array.  Either technique merely adds a layer of parentheses, since AND
 328                         connects successive conditions by default. </p><p> The <code class="literal">&#8220;-not&#8221;</code> operator expands the subordinate
 329                         <code class="literal">where_condition</code> within parentheses, and prefaces the result
 330                         with NOT: </p><table width="100%" cellpadding="5" bgcolor="#F5DCB3" border="1" class="productionset" summary="EBNF"><tr><td><table border="0" width="99%" cellpadding="0" bgcolor="#F5DCB3" class="productionset" summary="EBNF productions"><tr><td align="left" valign="top" width="3%">[33]</td><td align="right" valign="top" width="10%"><a name="ebnf.condition_4"></a> condition </td><td valign="top" width="5%" align="center"><code>::=</code></td><td valign="top" width="52%"> '&#8221;-not&#8221;' ':'  where_condition </td><td align="left" valign="top" width="30%">&nbsp;</td></tr></table></td></tr></table><p> The <code class="literal">&#8220;-exists&#8221;</code> or <code class="literal">&#8220;-not-exists&#8221;</code> operator
 331                         constructs a subquery within an EXISTS  or NOT EXISTS clause, respectively: </p><table width="100%" cellpadding="5" bgcolor="#F5DCB3" border="1" class="productionset" summary="EBNF"><tr><td><table border="0" width="99%" cellpadding="0" bgcolor="#F5DCB3" class="productionset" summary="EBNF productions"><tr><td align="left" valign="top" width="3%">[34]</td><td align="right" valign="top" width="10%"><a name="ebnf.condition_5"></a> condition </td><td valign="top" width="5%" align="center"><code>::=</code></td><td valign="top" width="52%"> '&#8221;-exists&#8221;' ':' query </td><td align="left" valign="top" width="30%">&nbsp;</td></tr><tr><td align="left" valign="top" width="3%">[35]</td><td align="right" valign="top" width="10%"><a name="ebnf.condition_6"></a> condition </td><td valign="top" width="5%" align="center"><code>::=</code></td><td valign="top" width="52%"> '&#8221;-not-exists&#8221;' ':' query </td><td align="left" valign="top" width="30%">&nbsp;</td></tr></table></td></tr></table><p> The remaining kinds of <code class="literal">condition</code> all have a
 332                         <code class="literal">field_name</code> on the left and some kind of <code class="literal">predicate</code>
 333                         on the right.  A <code class="literal">predicate</code> places a constraint on the value of
 334                         the column &#8211; or, in some cases, on the value of the column as transformed by some
 335                         function call: </p><table width="100%" cellpadding="5" bgcolor="#F5DCB3" border="1" class="productionset" summary="EBNF"><tr><td><table border="0" width="99%" cellpadding="0" bgcolor="#F5DCB3" class="productionset" summary="EBNF productions"><tr><td align="left" valign="top" width="3%">[36]</td><td align="right" valign="top" width="10%"><a name="ebnf.condition_7"></a> condition </td><td valign="top" width="5%" align="center"><code>::=</code></td><td valign="top" width="52%"> field_name ':' predicate </td><td align="left" valign="top" width="30%">&nbsp;</td></tr></table></td></tr></table><p> The simplest such constraint is to require that the column have a specific value,
 336                         or be null: </p><table width="100%" cellpadding="5" bgcolor="#F5DCB3" border="1" class="productionset" summary="EBNF"><tr><td><table border="0" width="99%" cellpadding="0" bgcolor="#F5DCB3" class="productionset" summary="EBNF productions"><tr><td align="left" valign="top" width="3%">[37]</td><td align="right" valign="top" width="10%"><a name="ebnf.predicate_0"></a> predicate </td><td valign="top" width="5%" align="center"><code>::=</code></td><td valign="top" width="52%"> lit_value | 'null' </td><td align="left" valign="top" width="30%">&nbsp;</td></tr><tr><td align="left" valign="top" width="3%">[38]</td><td align="right" valign="top" width="10%"><a name="ebnf.lit_value"></a> lit_value </td><td valign="top" width="5%" align="center"><code>::=</code></td><td valign="top" width="52%"> string | number </td><td align="left" valign="top" width="30%">&nbsp;</td></tr></table></td></tr></table><p> You can also compare a column to a literal value using some kind of inequality.
 337                         However it's a bit more complicated because you have to specify what kind of comparison
 338                         to make: </p><table width="100%" cellpadding="5" bgcolor="#F5DCB3" border="1" class="productionset" summary="EBNF"><tr><td><table border="0" width="99%" cellpadding="0" bgcolor="#F5DCB3" class="productionset" summary="EBNF productions"><tr><td align="left" valign="top" width="3%">[39]</td><td align="right" valign="top" width="10%"><a name="ebnf.compare_op_0"></a> predicate </td><td valign="top" width="5%" align="center"><code>::=</code></td><td valign="top" width="52%"> '{' compare_op ':' lit_value '}' </td><td align="left" valign="top" width="30%">&nbsp;</td></tr><tr><td align="left" valign="top" width="3%">[40]</td><td align="right" valign="top" width="10%"><a name="ebnf.compare_op_1"></a> compare_op </td><td valign="top" width="5%" align="center"><code>::=</code></td><td valign="top" width="52%"> string </td><td align="left" valign="top" width="30%">&nbsp;</td></tr></table></td></tr></table><p> A <code class="literal">compare_op</code> is a string that defines a comparison operator.
 339                         Valid values include the following: </p><pre class="programlisting">
 340         =    &lt;&gt;   !=
 341         &lt;    &gt;    &lt;=   &gt;=
 342         ~    ~*   !~   !~*
 343         like      ilike
 344         similar to
 345                 </pre><p> Strictly speaking, json_query accepts any <code class="literal">compare_op</code>
 346                         that doesn't contain semicolons or white space (or
 347                         <code class="literal">&#8220;similar to&#8221;</code> as a special exception).  As a result, it
 348                         is possible &#8211; and potentially useful &#8211; to use a custom operator like
 349                         <code class="literal">&#8220;&gt;100*&#8221;</code> in order to insert an expression that would
 350                         otherwise be difficult or impossible to create through a JSON query.  The ban
 351                         on semicolons and white space prevents certain kinds of SQL injection. </p><p> Note that json_query does <span class="emphasis"><em>not</em></span> accept two operators that
 352                         PostgreSQL <span class="emphasis"><em>does</em></span> accept: <code class="literal">&#8220;is distinct from&#8221;</code>
 353                         and <code class="literal">&#8220;is not distinct from&#8221;</code>. </p><p> You can also compare a column to a null value: </p><table width="100%" cellpadding="5" bgcolor="#F5DCB3" border="1" class="productionset" summary="EBNF"><tr><td><table border="0" width="99%" cellpadding="0" bgcolor="#F5DCB3" class="productionset" summary="EBNF productions"><tr><td align="left" valign="top" width="3%">[41]</td><td align="right" valign="top" width="10%"><a name="ebnf.predicate_1"></a> predicate </td><td valign="top" width="5%" align="center"><code>::=</code></td><td valign="top" width="52%"> '{' compare_op ':' 'null' '}' </td><td align="left" valign="top" width="30%">&nbsp;</td></tr></table></td></tr></table><p> The equality operator <code class="literal">&#8220;=&#8221;</code> turns into IS NULL.  Any other
 354                         operator turns into IS NOT NULL. </p><p> When a <code class="literal">compare_op</code> is paired with an array, it defines a
 355                         function call: </p><table width="100%" cellpadding="5" bgcolor="#F5DCB3" border="1" class="productionset" summary="EBNF"><tr><td><table border="0" width="99%" cellpadding="0" bgcolor="#F5DCB3" class="productionset" summary="EBNF productions"><tr><td align="left" valign="top" width="3%">[42]</td><td align="right" valign="top" width="10%"><a name="ebnf.predicate_2"></a> predicate </td><td valign="top" width="5%" align="center"><code>::=</code></td><td valign="top" width="52%"> '{' compare_op ':' '[' string { ',' parameter } ']' '}' </td><td align="left" valign="top" width="30%">&nbsp;</td></tr></table></td></tr></table><p> The first entry in the array is the function's name.  Subsequent entries in
 356                         the array, if any, represent the parameters of the function call.  They may be
 357                         strings, numbers, or nulls.  In the generated SQL, the function call appears on
 358                         the right of the comparison. </p><p> The <code class="literal">&#8220;between&#8221;</code> operator creates a BETWEEN clause: </p><table width="100%" cellpadding="5" bgcolor="#F5DCB3" border="1" class="productionset" summary="EBNF"><tr><td><table border="0" width="99%" cellpadding="0" bgcolor="#F5DCB3" class="productionset" summary="EBNF productions"><tr><td align="left" valign="top" width="3%">[43]</td><td align="right" valign="top" width="10%"><a name="ebnf.predicate_3"></a> predicate </td><td valign="top" width="5%" align="center"><code>::=</code></td><td valign="top" width="52%"> '{'  &#8220;between&#8221;  ':'  '['  lit_value  ','  lit_value  ']'  '}' </td><td align="left" valign="top" width="30%">&nbsp;</td></tr></table></td></tr></table><p> Although PostgreSQL allows a null value in a BETWEEN clause, json_query
 359                         requires literal non-null values.  It isn't sensible to use null values in a
 360                         BETWEEN clause.  A few experiments show that the results of the comparison are
 361                         peculiar and erratic. </p><p> There are two ways to create an IN list of allowed values.  The simplest is
 362                         to put literal values into a JSON array: </p><table width="100%" cellpadding="5" bgcolor="#F5DCB3" border="1" class="productionset" summary="EBNF"><tr><td><table border="0" width="99%" cellpadding="0" bgcolor="#F5DCB3" class="productionset" summary="EBNF productions"><tr><td align="left" valign="top" width="3%">[44]</td><td align="right" valign="top" width="10%"><a name="ebnf.predicate_4"></a> predicate </td><td valign="top" width="5%" align="center"><code>::=</code></td><td valign="top" width="52%"> '[' lit_value { ',' lit_value }  ']' </td><td align="left" valign="top" width="30%">&nbsp;</td></tr></table></td></tr></table><p> As with BETWEEN clauses, json_query does not accept null values in an IN list,
 363                         even though PostgreSQL does allow them.  Nulls are not sensible in this context
 364                         because they never match anything. </p><p>  </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e1140"></a>Having Clause</h3></div></div></div><p>For the HAVING clause, json_query accepts exactly the same syntax as it accepts for
 365                         the WHERE clause.</p><p> The other way to create an IN list is to use an explicit
 366                         <code class="literal">&#8220;in&#8221;</code> operator with an array of literal values.  This format
 367                         also works for the <code class="literal">&#8220;not in&#8221;</code> operator: </p><table width="100%" cellpadding="5" bgcolor="#F5DCB3" border="1" class="productionset" summary="EBNF"><tr><td><table border="0" width="99%" cellpadding="0" bgcolor="#F5DCB3" class="productionset" summary="EBNF productions"><tr><td align="left" valign="top" width="3%">[45]</td><td align="right" valign="top" width="10%"><a name="ebnf.predicate_5"></a> predicate </td><td valign="top" width="5%" align="center"><code>::=</code></td><td valign="top" width="52%"> '{' in_operator ';'  '[' lit_value [ ',' lit_value ]  ']'  '}' </td><td align="left" valign="top" width="30%">&nbsp;</td></tr><tr><td align="left" valign="top" width="3%">[46]</td><td align="right" valign="top" width="10%"><a name="ebnf.in_operator"></a> in_operator </td><td valign="top" width="5%" align="center"><code>::=</code></td><td valign="top" width="52%"> &#8220;in&#8221;  |  &#8220;not in&#8221; </td><td align="left" valign="top" width="30%">&nbsp;</td></tr></table></td></tr></table><p> Another kind of IN or NOT IN clause uses a subquery instead of a list of
 368                         values: </p><table width="100%" cellpadding="5" bgcolor="#F5DCB3" border="1" class="productionset" summary="EBNF"><tr><td><table border="0" width="99%" cellpadding="0" bgcolor="#F5DCB3" class="productionset" summary="EBNF productions"><tr><td align="left" valign="top" width="3%">[47]</td><td align="right" valign="top" width="10%"><a name="ebnf.predicate_6"></a> predicate </td><td valign="top" width="5%" align="center"><code>::=</code></td><td valign="top" width="52%"> '{' in_operator ':'  query  '}' </td><td align="left" valign="top" width="30%">&nbsp;</td></tr></table></td></tr></table><p> The remaining types of <code class="literal">predicate</code> can put a function call on
 369                         the left of the comparison, by using a <code class="literal">transform_spec</code> together
 370                         with a <code class="literal">&#8220;value&#8221;</code> tag.   The <code class="literal">transform_spec</code> is
 371                         optional, and if you don't need it, the same SQL would in many cases be easier to
 372                         express by other means. </p><p> The <code class="literal">transform_spec</code> construct was described earlier in
 373                         connection with the SELECT clause, but here it is again: </p><table width="100%" cellpadding="5" bgcolor="#F5DCB3" border="1" class="productionset" summary="EBNF"><tr><td><table border="0" width="99%" cellpadding="0" bgcolor="#F5DCB3" class="productionset" summary="EBNF productions"><tr><td align="left" valign="top" width="3%">[48]</td><td align="right" valign="top" width="10%"><a name="ebnf.transform_spec_1"></a> transform_spec </td><td valign="top" width="5%" align="center"><code>::=</code></td><td valign="top" width="52%">
 374                                         '&#8221;transform&#8221;'  ':'  string  ]<br>
 375                                         [ ',' '&#8221;result_field&#8221;  ':'  string  ]<br>
 376                                         [ ',' '&#8221;params&#8221;  ':' param_list  ]
 377                                 </td><td align="left" valign="top" width="30%">&nbsp;</td></tr></table></td></tr></table><p> As in the SELECT clause, the <code class="literal">&#8220;transform&#8221;</code> string names the
 378                         function.  The first parameter is always the column identified by the field_name.
 379                         Additional parameters, if any, appear in the <code class="literal">param_list</code>.  The
 380                         <code class="literal">&#8220;result_field&#8221;</code> string, if present, identifies one column of a
 381                         multicolumn return value. </p><p> Here's a second way to compare a value to a literal value (but not to a null
 382                         value): </p><table width="100%" cellpadding="5" bgcolor="#F5DCB3" border="1" class="productionset" summary="EBNF"><tr><td><table border="0" width="99%" cellpadding="0" bgcolor="#F5DCB3" class="productionset" summary="EBNF productions"><tr><td align="left" valign="top" width="3%">[49]</td><td align="right" valign="top" width="10%"><a name="ebnf.predicate_7"></a> predicate </td><td valign="top" width="5%" align="center"><code>::=</code></td><td valign="top" width="52%"> '{' compare_op ':' '{' '&#8221;value&#8221;' ':' lit_value<br>
 383                                         [ transform_spec ] '}' '}' </td><td align="left" valign="top" width="30%">&nbsp;</td></tr></table></td></tr></table><p> ...and a way to compare a value to a boolean expression: </p><table width="100%" cellpadding="5" bgcolor="#F5DCB3" border="1" class="productionset" summary="EBNF"><tr><td><table border="0" width="99%" cellpadding="0" bgcolor="#F5DCB3" class="productionset" summary="EBNF productions"><tr><td align="left" valign="top" width="3%">[50]</td><td align="right" valign="top" width="10%"><a name="ebnf.predicate_8"></a> predicate </td><td valign="top" width="5%" align="center"><code>::=</code></td><td valign="top" width="52%"> '{' compare_op ':' '{' '&#8221;value&#8221;' ':' '{'<br>
 384                                         condition { ',' condition } [ transform_spec ] '}' '}' </td><td align="left" valign="top" width="30%">&nbsp;</td></tr></table></td></tr></table><p> The final predicate is another way to put a function call on the right side
 385                         of the comparison: </p><table width="100%" cellpadding="5" bgcolor="#F5DCB3" border="1" class="productionset" summary="EBNF"><tr><td><table border="0" width="99%" cellpadding="0" bgcolor="#F5DCB3" class="productionset" summary="EBNF productions"><tr><td align="left" valign="top" width="3%">[51]</td><td align="right" valign="top" width="10%"><a name="ebnf.predicate_9"></a> predicate </td><td valign="top" width="5%" align="center"><code>::=</code></td><td valign="top" width="52%"> '{' compare_op ':' '{' '&#8221;value&#8221;' ':' '['<br>
 386                                         string { ',' parameter } ']' [ transform_spec ] '}' '}' </td><td align="left" valign="top" width="30%">&nbsp;</td></tr></table></td></tr></table><p> This format is available for the sake of consistency, but offers no advantage
 387                         over the simpler version. </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e1278"></a>ORDER BY Clause</h3></div></div></div><p> There are two ways to encode an ORDER BY clause: as an array, or as a list.
 388                         Either may be empty, in which case the generated SQL will not include an ORDER BY
 389                         clause: </p><table width="100%" cellpadding="5" bgcolor="#F5DCB3" border="1" class="productionset" summary="EBNF"><tr><td><table border="0" width="99%" cellpadding="0" bgcolor="#F5DCB3" class="productionset" summary="EBNF productions"><tr><td align="left" valign="top" width="3%">[52]</td><td align="right" valign="top" width="10%"><a name="ebnf.order_by_list_0"></a> order_by_list </td><td valign="top" width="5%" align="center"><code>::=</code></td><td valign="top" width="52%"> '['  ']'  |  '{'  '}' </td><td align="left" valign="top" width="30%">&nbsp;</td></tr></table></td></tr></table><p> If not empty, the array contains one or more objects, each defining a sort
 390                         field: </p><table width="100%" cellpadding="5" bgcolor="#F5DCB3" border="1" class="productionset" summary="EBNF"><tr><td><table border="0" width="99%" cellpadding="0" bgcolor="#F5DCB3" class="productionset" summary="EBNF productions"><tr><td align="left" valign="top" width="3%">[53]</td><td align="right" valign="top" width="10%"><a name="ebnf.order_by_list_1"></a> order_by_list </td><td valign="top" width="5%" align="center"><code>::=</code></td><td valign="top" width="52%"> '{' sort_field_def  {  ','  sort_field_def }  '}' </td><td align="left" valign="top" width="30%">&nbsp;</td></tr><tr><td align="left" valign="top" width="3%">[54]</td><td align="right" valign="top" width="10%"><a name="ebnf.sort_field_def"></a> sort_field_def </td><td valign="top" width="5%" align="center"><code>::=</code></td><td valign="top" width="52%"> '{'<br>
 391                                         '&#8221;class&#8221;'  ':'  class_name<br>
 392                                         ','  '&#8221;field&#8221;'  ':'  field_name<br>
 393                                         [  ','  '&#8221;direction&#8221;'  ':'  lit_value  ]<br>
 394                                         [  ','  transform_spec  ]<br>
 395                                         '}' </td><td align="left" valign="top" width="30%">&nbsp;</td></tr></table></td></tr></table><p> The <code class="literal">&#8220;class&#8221;</code> and <code class="literal">&#8220;field&#8221;</code> entries are
 396                         required, and of course the field must belong to the class.  Furthermore, at
 397                         least one field from the class must appear in the SELECT clause. </p><p> The <code class="literal">&#8220;direction&#8221;</code> entry, if present, specifies whether the
 398                         sort will be ascending or descending for the column in question.  If the associated
 399                         value begins with &#8220;D&#8221; or &#8220;d&#8221;, the sort will be descending; otherwise the sort will
 400                         be ascending.  If the value is a number, it will be treated as a string that does not
 401                         start with &#8220;D&#8221; or &#8220;d&#8221;, resulting in an ascending sort. </p><p> In the absence of a <code class="literal">&#8220;direction&#8221;</code> entry, the sort will be
 402                         ascending. </p><p> The <code class="literal">transform_spec</code> works here the same way it works in the
 403                         SELECT clause and the WHERE clause, enabling you to pass the column through a
 404                         transforming function before the sort: </p><table width="100%" cellpadding="5" bgcolor="#F5DCB3" border="1" class="productionset" summary="EBNF"><tr><td><table border="0" width="99%" cellpadding="0" bgcolor="#F5DCB3" class="productionset" summary="EBNF productions"><tr><td align="left" valign="top" width="3%">[55]</td><td align="right" valign="top" width="10%"><a name="ebnf.transform_spec_2"></a> transform_spec </td><td valign="top" width="5%" align="center"><code>::=</code></td><td valign="top" width="52%">
 405                                         '&#8221;transform&#8221;'  ':'  string  ]<br>
 406                                         [ ',' '&#8221;result_field&#8221;  ':'  string  ]<br>
 407                                         [ ',' '&#8221;params&#8221;  ':' param_list  ]
 408                                 </td><td align="left" valign="top" width="30%">&nbsp;</td></tr></table></td></tr></table><p> When the <code class="literal">order_by_list</code> is an object instead of an array,
 409                         the syntax is less verbose, but also less flexible.  The keys for the object are
 410                         class names: </p><table width="100%" cellpadding="5" bgcolor="#F5DCB3" border="1" class="productionset" summary="EBNF"><tr><td><table border="0" width="99%" cellpadding="0" bgcolor="#F5DCB3" class="productionset" summary="EBNF productions"><tr><td align="left" valign="top" width="3%">[56]</td><td align="right" valign="top" width="10%"><a name="ebnf.order_by_list_2"></a> order_by_list </td><td valign="top" width="5%" align="center"><code>::=</code></td><td valign="top" width="52%"> '{' class_name ':' sort_class_def<br>
 411                                         { ',' class_name ':' sort_class_def } '}' </td><td align="left" valign="top" width="30%">&nbsp;</td></tr></table></td></tr></table><p> Each class must be referenced in the SELECT clause. </p><p> As in the SELECT clause, all the fields for a given class must be grouped
 412                         together.  You can't sort by a column from one table, then a column from a second
 413                         table, then another column from the first table. If you need this kind of sort,
 414                         you must encode the ORDER BY clause as an array instead of an object. </p><p> The data associated with a <code class="literal">class_name</code> may be either an array
 415                         or an object.  If an array, it's simply a list of field names, and each field must
 416                         belong to the class: </p><table width="100%" cellpadding="5" bgcolor="#F5DCB3" border="1" class="productionset" summary="EBNF"><tr><td><table border="0" width="99%" cellpadding="0" bgcolor="#F5DCB3" class="productionset" summary="EBNF productions"><tr><td align="left" valign="top" width="3%">[57]</td><td align="right" valign="top" width="10%"><a name="ebnf.sort_class_def_0"></a> sort_class_def </td><td valign="top" width="5%" align="center"><code>::=</code></td><td valign="top" width="52%"> '['  field_name  { ','  field_name }  ']' </td><td align="left" valign="top" width="30%">&nbsp;</td></tr></table></td></tr></table><p> With this syntax, the direction of sorting will always be ascending. </p><p> If the data is an object, the keys are field names, and as usual the fields
 417                         must belong to the class: </p><table width="100%" cellpadding="5" bgcolor="#F5DCB3" border="1" class="productionset" summary="EBNF"><tr><td><table border="0" width="99%" cellpadding="0" bgcolor="#F5DCB3" class="productionset" summary="EBNF productions"><tr><td align="left" valign="top" width="3%">[58]</td><td align="right" valign="top" width="10%"><a name="ebnf.sort_class_def_1"></a> sort_class_def </td><td valign="top" width="5%" align="center"><code>::=</code></td><td valign="top" width="52%"> '{'  field_name  ':' sort_class_subdef<br>
 418                                         { ','  field_name  ':' sort_class_subdef  }  '}' </td><td align="left" valign="top" width="30%">&nbsp;</td></tr></table></td></tr></table><p> Since the <code class="literal">field_name</code> is the key for the object, it cannot
 419                         appear more than once.  As a result, some kinds of sorts are not possible with this
 420                         syntax.  For example, one might want to sort by UPPER( family_name ), and then by
 421                         family_name with case unchanged, to make sure that &#8220;diBona&#8221; comes before &#8220;Dibona&#8221;.
 422                         For situations like this, you must encode the ORDER BY clause as an array rather
 423                         than an object. </p><p> The data associated with each <code class="literal">field_name</code> may take either of
 424                         two forms.  In the simplest case, it's a literal value to specify the direction
 425                         of sorting: </p><table width="100%" cellpadding="5" bgcolor="#F5DCB3" border="1" class="productionset" summary="EBNF"><tr><td><table border="0" width="99%" cellpadding="0" bgcolor="#F5DCB3" class="productionset" summary="EBNF productions"><tr><td align="left" valign="top" width="3%">[59]</td><td align="right" valign="top" width="10%"><a name="ebnf.sort_class_subdef_0"></a> sort_class_subdef </td><td valign="top" width="5%" align="center"><code>::=</code></td><td valign="top" width="52%"> lit_value </td><td align="left" valign="top" width="30%">&nbsp;</td></tr></table></td></tr></table><p> If the literal is a string starting with &#8220;D&#8221; or &#8220;d&#8221;, json_query sorts the field
 426                         in descending order.  Otherwise it sorts the field in ascending order. </p><p> In other cases, the <code class="literal">field_name</code> may be paired with an object
 427                         to specify more details: </p><table width="100%" cellpadding="5" bgcolor="#F5DCB3" border="1" class="productionset" summary="EBNF"><tr><td><table border="0" width="99%" cellpadding="0" bgcolor="#F5DCB3" class="productionset" summary="EBNF productions"><tr><td align="left" valign="top" width="3%">[60]</td><td align="right" valign="top" width="10%"><a name="ebnf.sort_class_subdef_1"></a> sort_class_subdef </td><td valign="top" width="5%" align="center"><code>::=</code></td><td valign="top" width="52%"> '{'<br>
 428                                         [  '&#8221;direction&#8221;'  ':'  lit_value ]<br>
 429                                         [  transform_spec  ]<br>
 430                                         '}' </td><td align="left" valign="top" width="30%">&nbsp;</td></tr></table></td></tr></table><p> As before, the value tagged as <code class="literal">&#8220;direction&#8221;</code> specifies the
 431                         direction of the sort, depending on the first character.  If not otherwise
 432                         specified, the sort direction defaults to ascending. </p><p> Also as before, the <code class="literal">transform_spec</code> may specify a function
 433                         through which to pass the column. </p><p> Since both the <code class="literal">&#8220;direction&#8221;</code> tag and the
 434                         <code class="literal">transform_spec</code> are optional, the object may be empty: </p><table width="100%" cellpadding="5" bgcolor="#F5DCB3" border="1" class="productionset" summary="EBNF"><tr><td><table border="0" width="99%" cellpadding="0" bgcolor="#F5DCB3" class="productionset" summary="EBNF productions"><tr><td align="left" valign="top" width="3%">[61]</td><td align="right" valign="top" width="10%"><a name="ebnf.sort_class_subdef_2"></a> sort_class_subdef </td><td valign="top" width="5%" align="center"><code>::=</code></td><td valign="top" width="52%"> '{'  '}' </td><td align="left" valign="top" width="30%">&nbsp;</td></tr></table></td></tr></table></div></div></body></html>