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="article" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="d0e1"></a>Grammar of JSON Queries</h2></div></div><hr></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="#d0e28">Introduction</a></span></dt><dt><span class="sect1"><a href="#d0e65">Primitives</a></span></dt><dt><span class="sect1"><a href="#d0e194">Query</a></span></dt></dl></div><p>
4 <span class="author"><span class="firstname">Scott</span> <span class="surname">McKellar</span></span>
7 </p><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e28"></a>Introduction</h2></div></div></div><p> The format of this grammar approximates Extended Backus-Naur notation. However it is
8 intended as input to human beings, not to parser generators such as Lex or Yacc. Do not
9 expect formal rigor. Sometimes narrative text will explain things that are clumsy to
10 express in formal notation. More often, the text will restate or summarize the formal
11 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
12 for the name. The name identifies a grammatical construct that can appear on the
13 right side of another production.</p></li><li><p>Literals (including punctuation) are enclosed in 'single quotes', or in
14 "double quotes" if case is not significant.</p></li><li><p>A single quotation mark within a literal is escaped with a preceding
15 backslash: 'dog\'s tail'.</p></li><li><p>If a construct can be defined more than one way, then the alternatives may
16 appear in separate productions; or, they may appear in the same production,
17 separated by pipe symbols. The choice between these representations is of only
18 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
19 times.</p></li><li><p>JSON allows arbitrary white space between tokens. To avoid ugly clutter, this
20 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
21 pairs, separated by commas. Since the order of these name/value pairs is not
22 significant, the grammar will not try to show all the possible sequences. In
23 general it will present the required pairs first, if any, followed by any
24 optional elements.</p></li></ol></div><p> Since both EBNF and JSON use curly braces and square brackets, pay close attention to
25 whether these characters are in single quotes. If they're in single quotes, they are
26 literal elements of the JSON notation. Otherwise they are elements of the EBNF notation.
27 </p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e65"></a>Primitives</h2></div></div></div><p> We'll start by defining some primitives, to get them out of the way. They're mostly
28 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%"> </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
29 escaped according to JSON rules </td><td align="left" valign="top" width="30%"> </td></tr><tr><td align="left" valign="top" width="3%">[3]</td><td align="right" valign="top" width="10%"><a name="ebnf.int_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%"> </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%"> </td></tr><tr><td align="left" valign="top" width="3%">[5]</td><td align="right" valign="top" width="10%"><a name="ebnf.digits"></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%"> </td></tr><tr><td align="left" valign="top" width="3%">[6]</td><td align="right" valign="top" width="10%"><a name="ebnf.int_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%"> </td></tr><tr><td align="left" valign="top" width="3%">[7]</td><td align="right" valign="top" width="10%"><a name="ebnf.int"></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%"> </td></tr><tr><td align="left" valign="top" width="3%">[8]</td><td align="right" valign="top" width="10%"><a name="ebnf.num"></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%"> </td></tr></table></td></tr></table><p> When json_query requires an integral value, it will usually accept a quoted string
30 and convert it to an integer by brute force – to zero if necessary. Likewise it may
31 truncate a floating point number to an integral value. Scientific notation will be
32 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.bool"></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%"> </td></tr></table></td></tr></table><p> The preferred way to encode a boolean is with the JSON reserved word true or false,
33 in lower case without quotation marks. The string <code class="literal">true</code>, in upper,
34 lower, or mixed case, is another way to encode true. Any other string evaluates to
35 false. </p><p> As an accommodation to perl, numbers may be used as booleans. A numeric value of 1
36 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
37 interpreted as false. </p><p> The last couple of primitives aren't really very primitive, but we introduce them
38 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.classname"></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%"> </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
39 IDL. The class may refer either to a database table or to a source_definition, which is
40 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%"> </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
41 defined by the IDL. A field_name is also a column name for the table corresponding to
42 the relevant class. </p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e194"></a>Query</h2></div></div></div><p> The following production applies not only to the main query but also to most
43 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
44 ]<br> [ ',' '"where"' ':' where_condition ]<br> [ ',' '"having"' ':'
45 where_condition ]<br> [ ',' '"order_by"' ':' order_by_list ]<br> [ ','
46 '"limit"' ':' integer ]<br> [ ',' '"offset"' ':' integer ]<br> [ ','
47 '"distinct"' ':' boolean ]<br> [ ',' '"no_i18n"' ':' boolean ]<br> '}'
48 </td><td align="left" valign="top" width="30%"> </td></tr></table></td></tr></table><p> Except for the <code class="literal">"distinct"</code> and <code class="literal">no_i18n</code> entries,
49 each name/value pair represents a major clause of the SELECT statement. The name/value
50 pairs may appear in any order. </p><p> There is no name/value pair for the GROUP BY clause, because json_query generates it
51 automatically according to information encoded elsewhere. </p><p> The <code class="literal">"distinct"</code> entry, if present and true, tells json_query that
52 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
53 suppress internationalization. If not present, it defaults to false. (Note that
54 <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
55 arguments of the LIMIT and OFFSET clauses, respectively, of the SQL statement. Each
56 value should be non-negative, if present, or else the SQL won't work. </p></div></div></body></html>
projects / Evergreen.git / blob