Documentation Source Text

<li><p>
Compile the ext/misc/json1.c source file separately using the
additional -DSQLITE_CORE compile-time option.  Then link the
resulting json1.o object file with the application.

<li><p>
Append the ext/misc/json1.c source file onto the end of a standard
[amalgamation|sqlite3.c amalagamation] source file and compile them
together.  No -DSQLITE_CORE compile-time option is needed in this
case since the SQLITE_CORE C preprocessor macro is defined 
by the code in sqlite3.c.
</ol>

<p>
In both cases, one can add the -DSQLITE_ENABLE_JSON1 compile-time
................................................................................
'$' character followed by zero or more instances
of ".<i>objectlabel</i>" or "&#91<i>arrayindex</i>&#93".

<h3>2.3 VALUE arguments</h3>

<p>
For functions that accept "<i>value</i>" arguments (also shown as
"<i>value1</i>" and "<i>value2</i>") that are used to
construct or modify a JSON string, those arguments is usually understood
to be a literal strings and are quoted to become primitive JSON string values
in the result.  Even if the input <i>value</i> strings looks like 
well-formed JSON, they are still interpreted as literal strings in the
result.

<p>
However, if a <i>value</i> argument come from the output of another
json function, then the argument is understood to be actual JSON and
the complete JSON is inserted rather than a quoted string.

<p>
For example, in the following call to json_object(), the first <i>value</i>
argument looks like a well-formed JSON array.  But because it is just an
ordinary SQL text value it is interpreted as a literal string and added to the
result as a quoted string:
................................................................................

<tcl>
jexample {json_object('ex','[52,3.14159]')} {'{"ex":"[52,3.14159]"}'}
</tcl>

<p>
But if the <i>value</i> argument in the outer json_object() call is the
result of another json function like [json()] or [json_array()], then
the value is understood to be actual JSON and is inserted as such:

<tcl>
jexample \
  {json_object('ex',json('[52,3.14159]'))} {'{"ex":[52,3.14159]}'}  \
  {json_object('ex',json_array(52,3.14159))} {'{"ex":[52,3.14159]}'}
</tcl>







<h3>2.4 Compatibility</h3>

<p>
The json1 extension uses the [sqlite3_value_subtype()] and
[sqlite3_result_subtype()] interfaces that were introduced with
SQLite version 3.8.12.  Therefore the json1 extension will not work
in earlier versions of SQLite.
................................................................................
<blockquote><pre>
SELECT big.rowid, fullkey, atom
  FROM big, json_tree(big.json)
 WHERE atom IS NOT NULL;
</pre></blockquote>

<p>Suppose each entry in the BIG table is a JSON object 
with a '$.id' field that is a unique indentifier
and a '$.partlist' field that can be a deeply nested object.
You want to find the id of every entry that contains one
or more references to uuid '6fa5181e-5721-11e5-a04e-57f3d7b32808' anywhere
in its '$.partlist'.

<blockquote><pre>
SELECT DISTINCT json_extract(big.json,'$.id')
  FROM big, json_tree(big.json, '$.partlist')
 WHERE json_tree.key='uuid'
   AND json_tree.value='6fa5181e-5721-11e5-a04e-57f3d7b32808';
</pre></blockquote>

<li><p>
Compile the ext/misc/json1.c source file separately using the
additional -DSQLITE_CORE compile-time option.  Then link the
resulting json1.o object file with the application.

<li><p>
Append the ext/misc/json1.c source file onto the end of a standard
[amalgamation|sqlite3.c amalgamation] source file and compile them
together.  No -DSQLITE_CORE compile-time option is needed in this
case since the SQLITE_CORE C preprocessor macro is defined 
by the code in sqlite3.c.
</ol>

<p>
In both cases, one can add the -DSQLITE_ENABLE_JSON1 compile-time
................................................................................
'$' character followed by zero or more instances
of ".<i>objectlabel</i>" or "&#91<i>arrayindex</i>&#93".

<h3>2.3 VALUE arguments</h3>

<p>
For functions that accept "<i>value</i>" arguments (also shown as
"<i>value1</i>" and "<i>value2</i>"),
those arguments is usually understood
to be a literal strings that are quoted and becomes JSON string values
in the result.  Even if the input <i>value</i> strings looks like 
well-formed JSON, they are still interpreted as literal strings in the
result.

<p>
However, if a <i>value</i> argument come directly from the result of another
json1 function, then the argument is understood to be actual JSON and
the complete JSON is inserted rather than a quoted string.

<p>
For example, in the following call to json_object(), the first <i>value</i>
argument looks like a well-formed JSON array.  But because it is just an
ordinary SQL text value it is interpreted as a literal string and added to the
result as a quoted string:
................................................................................

<tcl>
jexample {json_object('ex','[52,3.14159]')} {'{"ex":"[52,3.14159]"}'}
</tcl>

<p>
But if the <i>value</i> argument in the outer json_object() call is the
result of another json1 function like [json()] or [json_array()], then
the value is understood to be actual JSON and is inserted as such:

<tcl>
jexample \
  {json_object('ex',json('[52,3.14159]'))} {'{"ex":[52,3.14159]}'}  \
  {json_object('ex',json_array(52,3.14159))} {'{"ex":[52,3.14159]}'}
</tcl>

<p>
To be clear: "<i>json</i>" arguments are always interpreted as JSON
regardless of where the value for that argument comes from.  But
"<i>value</i>" arguments are only interpreted as JSON if those arguments
come directly from another json1 function.

<h3>2.4 Compatibility</h3>

<p>
The json1 extension uses the [sqlite3_value_subtype()] and
[sqlite3_result_subtype()] interfaces that were introduced with
SQLite version 3.8.12.  Therefore the json1 extension will not work
in earlier versions of SQLite.
................................................................................
<blockquote><pre>
SELECT big.rowid, fullkey, atom
  FROM big, json_tree(big.json)
 WHERE atom IS NOT NULL;
</pre></blockquote>

<p>Suppose each entry in the BIG table is a JSON object 
with a '$.id' field that is a unique identifier
and a '$.partlist' field that can be a deeply nested object.
You want to find the id of every entry that contains one
or more references to uuid '6fa5181e-5721-11e5-a04e-57f3d7b32808' anywhere
in its '$.partlist'.

<blockquote><pre>
SELECT DISTINCT json_extract(big.json,'$.id')
  FROM big, json_tree(big.json, '$.partlist')
 WHERE json_tree.key='uuid'
   AND json_tree.value='6fa5181e-5721-11e5-a04e-57f3d7b32808';
</pre></blockquote>