Documentation Source Text

Check-in [5cc19499aa]
Login

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:Update the json1 documentation to describe the new "path" column of json_tree().
Downloads: Tarball | ZIP archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1: 5cc19499aa16c92f01c4dc39ed75704f2d5a51a4
User & Date: drh 2015-09-10 17:21:32.398
Context
2015-09-10
18:21
Add a how-to-compile section to the json1 documentation. And fix many typos. (check-in: aafe027cf0 user: drh tags: trunk)
17:21
Update the json1 documentation to describe the new "path" column of json_tree(). (check-in: 5cc19499aa user: drh tags: trunk)
03:43
Improvements and clarification for the json1 documentation. (check-in: 4793854de9 user: drh tags: trunk)
Changes
Unified Diff Ignore Whitespace Patch
Changes to pages/json1.in.
444
445
446
447
448
449
450

451
452
453
454
455
456
457
458
459
    key ANY,             -- key for current element relative to its parent
    value ANY,           -- value for the current element
    type TEXT,           -- 'object','array','string','integer', etc.
    atom ANY,            -- value for primitive types, null for array & object
    id INTEGER           -- integer ID for this element
    parent INTEGER,      -- integer ID for the parent of this element
    fullkey TEXT,        -- full path describing the current element

    json JSON HIDDEN,    -- 1st input parameter: the raw JSON
    path TEXT HIDDEN     -- 2nd input parameter: the PATH at which to start
);
</pre></blockquote>

<p>
The "key" column is the integer array index for elements of a JSON array 
and the text label for elements of a JSON object.  The key column is
NULL in all other cases.







>

|







444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
    key ANY,             -- key for current element relative to its parent
    value ANY,           -- value for the current element
    type TEXT,           -- 'object','array','string','integer', etc.
    atom ANY,            -- value for primitive types, null for array & object
    id INTEGER           -- integer ID for this element
    parent INTEGER,      -- integer ID for the parent of this element
    fullkey TEXT,        -- full path describing the current element
    path TEXT,           -- path to the container of the current row
    json JSON HIDDEN,    -- 1st input parameter: the raw JSON
    root TEXT HIDDEN     -- 2nd input parameter: the PATH at which to start
);
</pre></blockquote>

<p>
The "key" column is the integer array index for elements of a JSON array 
and the text label for elements of a JSON object.  The key column is
NULL in all other cases.
477
478
479
480
481
482
483
484
485
486
487
488
489
490






491
492
493
494
495
496
497
only guarantee is that the "id" column will be different for every row.

<p>
The "parent" column is always NULL for json_each().
For json_tree(),
the "parent" column is the "id" integer for the parent of the current
element, or NULL for the top-level JSON element or the element identified
by the path in the second argument.

<p>
The "fullkey" column is a text path that uniquely identifies the current
row element within the original JSON string.  The complete key to the
true top-level element is returned even if an alternative starting point
is provided by the path argument.







<h4>2.9.1 Examples using json_each() and json_tree()</h4>

<p>Suppose the table "CREATE TABLE user(name,phone)" stores zero or
more phone numbers as a JSON array object in the user.phone field.
To find all users who have any phone number with a 704 area code:








|





|
>
>
>
>
>
>







478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
only guarantee is that the "id" column will be different for every row.

<p>
The "parent" column is always NULL for json_each().
For json_tree(),
the "parent" column is the "id" integer for the parent of the current
element, or NULL for the top-level JSON element or the element identified
by the root path in the second argument.

<p>
The "fullkey" column is a text path that uniquely identifies the current
row element within the original JSON string.  The complete key to the
true top-level element is returned even if an alternative starting point
is provided by the "root" argument.

<p>
The "path" column is the path to the array or object container the holds 
the current row, or the path to the current row in the case where the 
iteration starts on a primitive type and thus only provides a single
row of output.

<h4>2.9.1 Examples using json_each() and json_tree()</h4>

<p>Suppose the table "CREATE TABLE user(name,phone)" stores zero or
more phone numbers as a JSON array object in the user.phone field.
To find all users who have any phone number with a 704 area code: