Documentation Source Text

Hex Artifact Content
Login

Artifact 12715f352823ef9ba5a000bc0274832078044d82:


0000: 3c 74 69 74 6c 65 3e 54 68 65 20 4a 53 4f 4e 31  <title>The JSON1
0010: 20 45 78 74 65 6e 73 69 6f 6e 3c 2f 74 69 74 6c   Extension</titl
0020: 65 3e 0a 3c 74 63 6c 3e 68 64 5f 6b 65 79 77 6f  e>.<tcl>hd_keywo
0030: 72 64 73 20 6a 73 6f 6e 31 20 7b 74 68 65 20 6a  rds json1 {the j
0040: 73 6f 6e 31 20 65 78 74 65 6e 73 69 6f 6e 7d 20  son1 extension} 
0050: 7b 4a 53 4f 4e 20 53 51 4c 20 66 75 6e 63 74 69  {JSON SQL functi
0060: 6f 6e 73 7d 3c 2f 74 63 6c 3e 0a 3c 68 32 3e 54  ons}</tcl>.<h2>T
0070: 68 65 20 4a 53 4f 4e 31 20 45 78 74 65 6e 73 69  he JSON1 Extensi
0080: 6f 6e 3c 2f 68 32 3e 0a 0a 3c 70 3e 0a 54 68 65  on</h2>..<p>.The
0090: 20 3c 62 3e 6a 73 6f 6e 31 3c 2f 62 3e 20 65 78   <b>json1</b> ex
00a0: 74 65 6e 73 69 6f 6e 20 69 73 20 61 20 5b 6c 6f  tension is a [lo
00b0: 61 64 61 62 6c 65 20 65 78 74 65 6e 73 69 6f 6e  adable extension
00c0: 5d 20 74 68 61 74 0a 69 6d 70 6c 65 6d 65 6e 74  ] that.implement
00d0: 73 20 74 68 69 72 74 65 65 6e 20 5b 61 70 70 6c  s thirteen [appl
00e0: 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
00f0: 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 61  SQL functions] a
0100: 6e 64 0a 74 77 6f 20 5b 74 61 62 6c 65 2d 76 61  nd.two [table-va
0110: 6c 75 65 64 20 66 75 6e 63 74 69 6f 6e 73 5d 20  lued functions] 
0120: 74 68 61 74 20 61 72 65 20 75 73 65 66 75 6c 20  that are useful 
0130: 66 6f 72 0a 6d 61 6e 61 67 69 6e 67 20 5b 68 74  for.managing [ht
0140: 74 70 3a 2f 2f 6a 73 6f 6e 2e 6f 72 67 2f 20 7c  tp://json.org/ |
0150: 20 4a 53 4f 4e 5d 20 63 6f 6e 74 65 6e 74 20 73   JSON] content s
0160: 74 6f 72 65 64 20 69 6e 20 61 6e 20 53 51 4c 69  tored in an SQLi
0170: 74 65 20 64 61 74 61 62 61 73 65 2e 0a 54 68 65  te database..The
0180: 73 65 20 61 72 65 20 74 68 65 20 73 63 61 6c 61  se are the scala
0190: 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  r SQL functions 
01a0: 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79 20 6a  implemented by j
01b0: 73 6f 6e 31 3a 0a 0a 3c 62 6c 6f 63 6b 71 75 6f  son1:..<blockquo
01c0: 74 65 3e 0a 3c 63 65 6e 74 65 72 3e 3c 74 61 62  te>.<center><tab
01d0: 6c 65 20 62 6f 72 64 65 72 3d 30 20 63 65 6c 6c  le border=0 cell
01e0: 70 61 64 64 69 6e 67 3d 35 3e 0a 3c 74 63 6c 3e  padding=5>.<tcl>
01f0: 0a 73 65 74 20 74 61 62 63 6e 74 20 30 0a 70 72  .set tabcnt 0.pr
0200: 6f 63 20 74 61 62 65 6e 74 72 79 20 7b 66 78 20  oc tabentry {fx 
0210: 64 65 73 63 20 6c 6e 6b 7d 20 7b 0a 20 20 67 6c  desc lnk} {.  gl
0220: 6f 62 61 6c 20 74 61 62 63 6e 74 0a 20 20 69 6e  obal tabcnt.  in
0230: 63 72 20 74 61 62 63 6e 74 0a 20 20 68 64 5f 70  cr tabcnt.  hd_p
0240: 75 74 73 20 22 3c 74 72 3e 3c 74 64 20 77 69 64  uts "<tr><td wid
0250: 74 68 3d 33 30 20 76 61 6c 69 67 6e 3d 27 74 6f  th=30 valign='to
0260: 70 27 3e 24 74 61 62 63 6e 74 2e 3c 2f 74 64 3e  p'>$tabcnt.</td>
0270: 22 0a 20 20 68 64 5f 70 75 74 73 20 22 3c 74 64  ".  hd_puts "<td
0280: 20 76 61 6c 69 67 6e 3d 27 74 6f 70 27 20 77 69   valign='top' wi
0290: 64 74 68 3d 27 33 30 25 27 3e 5c 6e 22 0a 20 20  dth='30%'>\n".  
02a0: 73 65 74 20 66 78 20 5b 73 74 72 69 6e 67 20 74  set fx [string t
02b0: 72 69 6d 20 24 66 78 5d 0a 20 20 73 65 74 20 68  rim $fx].  set h
02c0: 6c 69 6e 6b 20 22 3c 61 20 68 72 65 66 3d 27 23  link "<a href='#
02d0: 24 6c 6e 6b 27 3e 22 0a 20 20 72 65 67 73 75 62  $lnk'>".  regsub
02e0: 20 2d 61 6c 6c 20 7b 5e 6a 73 6f 6e 5c 28 7d 20   -all {^json\(} 
02f0: 24 66 78 20 22 24 7b 68 6c 69 6e 6b 7d 6a 73 6f  $fx "${hlink}jso
0300: 6e 3c 2f 61 3e 28 22 20 66 78 0a 20 20 72 65 67  n</a>(" fx.  reg
0310: 73 75 62 20 2d 61 6c 6c 20 7b 28 6a 73 6f 6e 5f  sub -all {(json_
0320: 5b 61 2d 7a 5f 5d 2b 29 7d 20 24 66 78 20 22 24  [a-z_]+)} $fx "$
0330: 68 6c 69 6e 6b 5c 5c 31 3c 2f 61 3e 22 20 66 78  hlink\\1</a>" fx
0340: 0a 20 20 72 65 67 73 75 62 20 2d 61 6c 6c 20 7b  .  regsub -all {
0350: 28 76 61 6c 75 65 5b 31 2d 39 5d 3f 7c 70 61 74  (value[1-9]?|pat
0360: 68 7c 6c 61 62 65 6c 5b 31 2d 39 5d 3f 29 7d 20  h|label[1-9]?)} 
0370: 24 66 78 20 22 3c 69 3e 5c 5c 31 3c 2f 69 3e 22  $fx "<i>\\1</i>"
0380: 20 66 78 0a 20 20 72 65 67 73 75 62 20 2d 61 6c   fx.  regsub -al
0390: 6c 20 7b 5c 28 28 6a 73 6f 6e 29 7d 20 24 66 78  l {\((json)} $fx
03a0: 20 22 28 3c 69 3e 5c 5c 31 3c 2f 69 3e 22 20 66   "(<i>\\1</i>" f
03b0: 78 0a 20 20 68 64 5f 70 75 74 73 20 24 66 78 5c  x.  hd_puts $fx\
03c0: 6e 0a 20 20 68 64 5f 70 75 74 73 20 22 3c 2f 74  n.  hd_puts "</t
03d0: 64 3e 3c 74 64 20 76 61 6c 69 67 6e 3d 27 74 6f  d><td valign='to
03e0: 70 27 3e 5c 6e 22 0a 20 20 68 64 5f 70 75 74 73  p'>\n".  hd_puts
03f0: 20 5b 73 74 72 69 6e 67 20 74 72 69 6d 20 24 64   [string trim $d
0400: 65 73 63 5d 5c 6e 0a 20 20 68 64 5f 70 75 74 73  esc]\n.  hd_puts
0410: 20 22 3c 2f 74 64 3e 3c 2f 74 72 3e 5c 6e 5c 6e   "</td></tr>\n\n
0420: 22 0a 7d 0a 73 65 74 20 74 73 63 74 72 20 31 30  ".}.set tsctr 10
0430: 30 0a 70 72 6f 63 20 6a 65 78 61 6d 70 6c 65 20  0.proc jexample 
0440: 7b 61 72 67 73 7d 20 7b 0a 20 20 68 64 5f 70 75  {args} {.  hd_pu
0450: 74 73 20 22 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  ts "<blockquote>
0460: 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 30 20  <table border=0 
0470: 63 65 6c 6c 70 61 64 64 69 6e 67 3d 30 3e 5c 6e  cellpadding=0>\n
0480: 22 0a 20 20 66 6f 72 65 61 63 68 20 7b 73 71 6c  ".  foreach {sql
0490: 20 72 65 73 7d 20 24 61 72 67 73 20 7b 0a 20 20   res} $args {.  
04a0: 20 20 23 23 23 20 75 6e 63 6f 6d 6d 65 6e 74 20    ### uncomment 
04b0: 74 6f 20 67 65 6e 65 72 61 74 65 20 74 65 73 74  to generate test
04c0: 20 63 61 73 65 73 20 66 72 6f 6d 20 74 68 65 20   cases from the 
04d0: 65 78 61 6d 70 6c 65 73 0a 20 20 20 20 23 20 67  examples.    # g
04e0: 6c 6f 62 61 6c 20 74 73 63 74 72 0a 20 20 20 20  lobal tsctr.    
04f0: 23 20 70 75 74 73 20 22 64 6f 5f 65 78 65 63 73  # puts "do_execs
0500: 71 6c 5f 74 65 73 74 20 6a 73 6f 6e 31 30 32 2d  ql_test json102-
0510: 24 74 73 63 74 72 20 5c 31 37 33 22 0a 20 20 20  $tsctr \173".   
0520: 20 23 20 69 6e 63 72 20 74 73 63 74 72 20 31 30   # incr tsctr 10
0530: 0a 20 20 20 20 23 20 70 75 74 73 20 22 20 20 53  .    # puts "  S
0540: 45 4c 45 43 54 20 5b 73 74 72 69 6e 67 20 74 72  ELECT [string tr
0550: 69 6d 20 24 73 71 6c 5d 3b 22 0a 20 20 20 20 23  im $sql];".    #
0560: 20 73 65 74 20 78 20 5c 31 37 33 5b 73 74 72 69   set x \173[stri
0570: 6e 67 20 74 72 69 6d 20 24 72 65 73 20 27 5d 5c  ng trim $res ']\
0580: 31 37 35 0a 20 20 20 20 23 20 70 75 74 73 20 22  175.    # puts "
0590: 5c 31 37 35 20 5c 31 37 33 24 78 5c 31 37 35 22  \175 \173$x\175"
05a0: 0a 20 20 20 20 68 64 5f 70 75 74 73 20 22 3c 74  .    hd_puts "<t
05b0: 72 3e 3c 74 64 3e 5b 73 74 72 69 6e 67 20 74 72  r><td>[string tr
05c0: 69 6d 20 24 73 71 6c 5d 3c 2f 74 64 3e 5c 6e 22  im $sql]</td>\n"
05d0: 0a 20 20 20 20 68 64 5f 70 75 74 73 20 22 3c 74  .    hd_puts "<t
05e0: 64 20 77 69 64 74 68 3d 27 35 30 27 20 61 6c 69  d width='50' ali
05f0: 67 6e 3d 27 63 65 6e 74 65 72 27 3e 3c 62 3e 26  gn='center'><b>&
0600: 72 61 72 72 3b 3c 2f 62 3e 3c 2f 74 64 3e 5c 6e  rarr;</b></td>\n
0610: 22 0a 20 20 20 20 68 64 5f 70 75 74 73 20 22 3c  ".    hd_puts "<
0620: 74 64 3e 5b 73 74 72 69 6e 67 20 74 72 69 6d 20  td>[string trim 
0630: 24 72 65 73 5d 3c 2f 74 64 3e 3c 2f 74 72 3e 5c  $res]</td></tr>\
0640: 6e 22 0a 20 20 7d 0a 20 20 68 64 5f 70 75 74 73  n".  }.  hd_puts
0650: 20 22 3c 2f 74 61 62 6c 65 3e 3c 2f 62 6c 6f 63   "</table></bloc
0660: 6b 71 75 6f 74 65 3e 5c 6e 22 0a 7d 0a 0a 74 61  kquote>\n".}..ta
0670: 62 65 6e 74 72 79 20 7b 6a 73 6f 6e 28 6a 73 6f  bentry {json(jso
0680: 6e 29 7d 20 7b 0a 20 20 56 61 6c 69 64 61 74 65  n)} {.  Validate
0690: 20 61 6e 64 20 6d 69 6e 69 66 79 20 61 20 4a 53   and minify a JS
06a0: 4f 4e 20 73 74 72 69 6e 67 0a 7d 20 6a 6d 69 6e  ON string.} jmin
06b0: 69 0a 0a 74 61 62 65 6e 74 72 79 20 7b 6a 73 6f  i..tabentry {jso
06c0: 6e 5f 61 72 72 61 79 28 76 61 6c 75 65 31 2c 76  n_array(value1,v
06d0: 61 6c 75 65 32 2c 2e 2e 2e 29 7d 20 7b 0a 20 20  alue2,...)} {.  
06e0: 52 65 74 75 72 6e 20 61 20 4a 53 4f 4e 20 61 72  Return a JSON ar
06f0: 72 61 79 20 68 6f 6c 64 69 6e 67 20 74 68 65 20  ray holding the 
0700: 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e  function argumen
0710: 74 73 2e 0a 7d 20 6a 61 72 72 61 79 0a 0a 74 61  ts..} jarray..ta
0720: 62 65 6e 74 72 79 20 7b 6a 73 6f 6e 5f 61 72 72  bentry {json_arr
0730: 61 79 5f 6c 65 6e 67 74 68 28 6a 73 6f 6e 29 3c  ay_length(json)<
0740: 62 72 3e 6a 73 6f 6e 5f 61 72 72 61 79 5f 6c 65  br>json_array_le
0750: 6e 67 74 68 28 6a 73 6f 6e 2c 70 61 74 68 29 7d  ngth(json,path)}
0760: 20 7b 0a 20 20 52 65 74 75 72 6e 20 74 68 65 20   {.  Return the 
0770: 6e 75 6d 62 65 72 20 6f 66 20 65 6c 65 6d 65 6e  number of elemen
0780: 74 73 20 69 6e 20 74 68 65 20 4a 53 4f 4e 20 61  ts in the JSON a
0790: 72 72 61 79 20 69 64 65 6e 74 69 66 69 65 64 20  rray identified 
07a0: 62 79 0a 20 20 74 68 65 20 61 72 67 75 6d 65 6e  by.  the argumen
07b0: 74 73 2e 0a 7d 20 6a 61 72 72 61 79 6c 65 6e 0a  ts..} jarraylen.
07c0: 0a 74 61 62 65 6e 74 72 79 20 7b 6a 73 6f 6e 5f  .tabentry {json_
07d0: 65 78 74 72 61 63 74 28 6a 73 6f 6e 2c 70 61 74  extract(json,pat
07e0: 68 2c 2e 2e 2e 29 7d 20 7b 0a 20 20 45 78 74 72  h,...)} {.  Extr
07f0: 61 63 74 20 76 61 6c 75 65 73 20 6f 72 20 73 75  act values or su
0800: 62 63 6f 6d 70 6f 6e 65 6e 74 73 20 66 72 6f 6d  bcomponents from
0810: 20 61 20 4a 53 4f 4e 20 73 74 72 69 6e 67 2e 0a   a JSON string..
0820: 7d 20 6a 65 78 0a 0a 74 61 62 65 6e 74 72 79 20  } jex..tabentry 
0830: 7b 6a 73 6f 6e 5f 69 6e 73 65 72 74 28 6a 73 6f  {json_insert(jso
0840: 6e 2c 70 61 74 68 2c 76 61 6c 75 65 2c 2e 2e 2e  n,path,value,...
0850: 29 7d 20 7b 0a 20 20 49 6e 73 65 72 74 20 76 61  )} {.  Insert va
0860: 6c 75 65 73 20 69 6e 74 6f 20 61 20 4a 53 4f 4e  lues into a JSON
0870: 20 73 74 72 69 6e 67 20 77 69 74 68 6f 75 74 20   string without 
0880: 6f 76 65 72 77 72 69 74 69 6e 67 20 65 78 69 73  overwriting exis
0890: 74 69 6e 67 20 76 61 6c 75 65 73 2e 0a 7d 20 6a  ting values..} j
08a0: 69 6e 73 0a 0a 74 61 62 65 6e 74 72 79 20 7b 6a  ins..tabentry {j
08b0: 73 6f 6e 5f 6f 62 6a 65 63 74 28 6c 61 62 65 6c  son_object(label
08c0: 31 2c 76 61 6c 75 65 31 2c 2e 2e 2e 29 7d 20 7b  1,value1,...)} {
08d0: 0a 20 20 43 6f 6e 73 74 72 75 63 74 20 61 6e 64  .  Construct and
08e0: 20 72 65 74 75 72 6e 20 61 20 6e 65 77 20 4a 53   return a new JS
08f0: 4f 4e 20 6f 62 6a 65 63 74 20 62 61 73 65 64 20  ON object based 
0900: 6f 6e 20 74 68 65 20 61 72 67 75 6d 65 6e 74 73  on the arguments
0910: 2e 0a 7d 20 6a 6f 62 6a 0a 0a 74 61 62 65 6e 74  ..} jobj..tabent
0920: 72 79 20 7b 6a 73 6f 6e 5f 72 65 6d 6f 76 65 28  ry {json_remove(
0930: 6a 73 6f 6e 2c 70 61 74 68 2c 2e 2e 2e 29 7d 20  json,path,...)} 
0940: 7b 0a 20 20 52 65 6d 6f 76 65 20 74 68 65 20 73  {.  Remove the s
0950: 70 65 63 69 66 69 65 64 20 76 61 6c 75 65 73 20  pecified values 
0960: 66 72 6f 6d 20 61 20 4a 53 4f 4e 20 73 74 72 69  from a JSON stri
0970: 6e 67 2e 0a 7d 20 6a 72 6d 0a 0a 74 61 62 65 6e  ng..} jrm..taben
0980: 74 72 79 20 7b 6a 73 6f 6e 5f 72 65 70 6c 61 63  try {json_replac
0990: 65 28 6a 73 6f 6e 2c 70 61 74 68 2c 76 61 6c 75  e(json,path,valu
09a0: 65 2c 2e 2e 2e 29 7d 20 7b 0a 20 20 55 70 64 61  e,...)} {.  Upda
09b0: 74 65 20 65 78 69 73 74 69 6e 67 20 76 61 6c 75  te existing valu
09c0: 65 73 20 77 69 74 68 69 6e 20 61 20 4a 53 4f 4e  es within a JSON
09d0: 20 73 74 72 69 6e 67 2e 0a 7d 20 6a 72 65 70 6c   string..} jrepl
09e0: 0a 0a 74 61 62 65 6e 74 72 79 20 7b 6a 73 6f 6e  ..tabentry {json
09f0: 5f 73 65 74 28 6a 73 6f 6e 2c 70 61 74 68 2c 76  _set(json,path,v
0a00: 61 6c 75 65 2c 2e 2e 2e 29 7d 20 7b 0a 20 20 49  alue,...)} {.  I
0a10: 6e 73 65 72 74 20 6f 72 20 72 65 70 6c 61 63 65  nsert or replace
0a20: 20 76 61 6c 75 65 73 20 69 6e 20 61 20 4a 53 4f   values in a JSO
0a30: 4e 20 73 74 72 69 6e 67 2e 20 20 4f 76 65 72 77  N string.  Overw
0a40: 72 69 74 65 20 65 78 69 73 74 69 6e 67 20 65 6c  rite existing el
0a50: 65 6d 65 6e 74 73 0a 20 20 6f 72 20 63 72 65 61  ements.  or crea
0a60: 74 65 20 6e 65 77 20 65 6e 74 72 69 65 73 20 69  te new entries i
0a70: 6e 20 74 68 65 20 4a 53 4f 4e 20 73 74 72 69 6e  n the JSON strin
0a80: 67 20 66 6f 72 20 65 6c 65 6d 65 6e 74 73 20 74  g for elements t
0a90: 68 61 74 20 64 6f 20 6e 6f 74 20 0a 20 20 70 72  hat do not .  pr
0aa0: 65 76 69 6f 75 73 6c 79 20 65 78 69 73 74 2e 0a  eviously exist..
0ab0: 7d 20 6a 73 65 74 0a 0a 74 61 62 65 6e 74 72 79  } jset..tabentry
0ac0: 20 7b 6a 73 6f 6e 5f 74 79 70 65 28 6a 73 6f 6e   {json_type(json
0ad0: 29 3c 62 72 3e 6a 73 6f 6e 5f 74 79 70 65 28 6a  )<br>json_type(j
0ae0: 73 6f 6e 2c 70 61 74 68 29 7d 20 7b 0a 20 20 52  son,path)} {.  R
0af0: 65 74 75 72 6e 20 74 68 65 20 74 79 70 65 20 6f  eturn the type o
0b00: 66 20 61 20 4a 53 4f 4e 20 73 74 72 69 6e 67 20  f a JSON string 
0b10: 6f 72 20 73 75 62 63 6f 6d 70 6f 6e 65 6e 74 2e  or subcomponent.
0b20: 0a 7d 20 6a 74 79 70 65 0a 0a 74 61 62 65 6e 74  .} jtype..tabent
0b30: 72 79 20 7b 6a 73 6f 6e 5f 76 61 6c 69 64 28 6a  ry {json_valid(j
0b40: 73 6f 6e 29 7d 20 7b 0a 20 20 52 65 74 75 72 6e  son)} {.  Return
0b50: 20 74 72 75 65 20 28 31 29 20 69 66 20 74 68 65   true (1) if the
0b60: 20 69 6e 70 75 74 20 74 65 78 74 20 69 73 20 61   input text is a
0b70: 20 76 61 6c 69 64 20 4a 53 4f 4e 20 73 74 72 69   valid JSON stri
0b80: 6e 67 0a 7d 20 6a 76 61 6c 69 64 0a 3c 2f 74 63  ng.} jvalid.</tc
0b90: 6c 3e 0a 3c 2f 74 61 62 6c 65 3e 3c 2f 63 65 6e  l>.</table></cen
0ba0: 74 65 72 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  ter></blockquote
0bb0: 3e 0a 0a 3c 70 3e 54 68 65 72 65 20 61 72 65 20  >..<p>There are 
0bc0: 74 77 6f 20 61 67 67 72 65 67 61 74 65 20 53 51  two aggregate SQ
0bd0: 4c 20 66 75 6e 63 74 69 6f 6e 73 3a 0a 0a 3c 62  L functions:..<b
0be0: 6c 6f 63 6b 71 75 6f 74 65 3e 3c 63 65 6e 74 65  lockquote><cente
0bf0: 72 3e 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d  r><table border=
0c00: 30 20 63 65 6c 6c 70 61 64 64 69 6e 67 3d 35 3e  0 cellpadding=5>
0c10: 0a 3c 74 63 6c 3e 0a 74 61 62 65 6e 74 72 79 20  .<tcl>.tabentry 
0c20: 7b 6a 73 6f 6e 5f 67 72 6f 75 70 5f 61 72 72 61  {json_group_arra
0c30: 79 28 76 61 6c 75 65 29 7d 20 7b 0a 20 20 52 65  y(value)} {.  Re
0c40: 74 75 72 6e 20 61 20 4a 53 4f 4e 20 61 72 72 61  turn a JSON arra
0c50: 79 20 63 6f 6d 70 6f 73 65 64 20 6f 66 20 61 6c  y composed of al
0c60: 6c 20 3c 69 3e 76 61 6c 75 65 3c 2f 69 3e 20 65  l <i>value</i> e
0c70: 6c 65 6d 65 6e 74 73 20 0a 20 20 69 6e 20 74 68  lements .  in th
0c80: 65 20 61 67 67 72 65 67 61 74 69 6f 6e 2e 0a 7d  e aggregation..}
0c90: 20 6a 67 72 6f 75 70 61 72 72 61 79 0a 0a 74 61   jgrouparray..ta
0ca0: 62 65 6e 74 72 79 20 7b 6a 73 6f 6e 5f 67 72 6f  bentry {json_gro
0cb0: 75 70 5f 6f 62 6a 65 63 74 28 6e 61 6d 65 2c 76  up_object(name,v
0cc0: 61 6c 75 65 29 7d 20 7b 0a 20 20 52 65 74 75 72  alue)} {.  Retur
0cd0: 6e 20 61 20 4a 53 4f 4e 20 6f 62 6a 65 63 74 20  n a JSON object 
0ce0: 63 6f 6d 70 6f 73 65 64 20 6f 66 20 61 6c 6c 20  composed of all 
0cf0: 3c 69 3e 6e 61 6d 65 3c 2f 69 3e 20 61 6e 64 20  <i>name</i> and 
0d00: 3c 69 3e 76 61 6c 75 65 3c 2f 69 3e 20 70 61 69  <i>value</i> pai
0d10: 72 73 0a 20 20 69 6e 20 74 68 65 20 61 67 67 72  rs.  in the aggr
0d20: 65 67 61 74 69 6f 6e 2e 0a 7d 20 6a 67 72 6f 75  egation..} jgrou
0d30: 70 6f 62 6a 65 63 74 0a 3c 2f 74 63 6c 3e 0a 3c  pobject.</tcl>.<
0d40: 2f 74 61 62 6c 65 3e 3c 2f 63 65 6e 74 65 72 3e  /table></center>
0d50: 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 0a 3c  </blockquote>..<
0d60: 70 3e 54 68 65 20 5b 74 61 62 6c 65 2d 76 61 6c  p>The [table-val
0d70: 75 65 64 20 66 75 6e 63 74 69 6f 6e 73 5d 20 69  ued functions] i
0d80: 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79 20 74 68  mplemented by th
0d90: 69 73 20 72 6f 75 74 69 6e 65 20 61 72 65 3a 0a  is routine are:.
0da0: 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 63 65  .<blockquote><ce
0db0: 6e 74 65 72 3e 3c 74 61 62 6c 65 20 62 6f 72 64  nter><table bord
0dc0: 65 72 3d 30 20 63 65 6c 6c 70 61 64 64 69 6e 67  er=0 cellpadding
0dd0: 3d 35 3e 0a 3c 74 63 6c 3e 0a 74 61 62 65 6e 74  =5>.<tcl>.tabent
0de0: 72 79 20 7b 6a 73 6f 6e 5f 65 61 63 68 28 6a 73  ry {json_each(js
0df0: 6f 6e 29 3c 62 72 3e 6a 73 6f 6e 5f 65 61 63 68  on)<br>json_each
0e00: 28 6a 73 6f 6e 2c 70 61 74 68 29 7d 20 7b 0a 20  (json,path)} {. 
0e10: 20 52 65 74 75 72 6e 20 6f 6e 65 20 72 6f 77 20   Return one row 
0e20: 64 65 73 63 72 69 62 69 6e 67 20 65 61 63 68 20  describing each 
0e30: 65 6c 65 6d 65 6e 74 20 69 6e 20 61 6e 20 61 72  element in an ar
0e40: 72 61 79 20 6f 72 20 6f 62 6a 65 63 74 0a 20 20  ray or object.  
0e50: 61 74 20 74 68 65 20 74 6f 70 2d 6c 65 76 65 6c  at the top-level
0e60: 20 6f 72 20 61 74 20 22 70 61 74 68 22 20 77 69   or at "path" wi
0e70: 74 68 69 6e 20 74 68 65 20 69 6e 70 75 74 20 4a  thin the input J
0e80: 53 4f 4e 2e 0a 7d 20 6a 65 61 63 68 0a 0a 74 61  SON..} jeach..ta
0e90: 62 65 6e 74 72 79 20 7b 6a 73 6f 6e 5f 74 72 65  bentry {json_tre
0ea0: 65 28 6a 73 6f 6e 29 3c 62 72 3e 6a 73 6f 6e 5f  e(json)<br>json_
0eb0: 74 72 65 65 28 6a 73 6f 6e 2c 70 61 74 68 29 7d  tree(json,path)}
0ec0: 20 7b 0a 20 20 57 61 6c 6b 20 74 68 65 20 4a 53   {.  Walk the JS
0ed0: 4f 4e 20 72 65 63 75 72 73 69 76 65 6c 79 20 73  ON recursively s
0ee0: 74 61 72 74 69 6e 67 20 61 74 20 74 68 65 20 74  tarting at the t
0ef0: 6f 70 2d 6c 65 76 65 6c 20 6f 72 20 61 74 20 74  op-level or at t
0f00: 68 65 0a 20 20 73 70 65 63 69 66 69 65 64 20 22  he.  specified "
0f10: 70 61 74 68 22 20 61 6e 64 20 72 65 74 75 72 6e  path" and return
0f20: 20 6f 6e 65 20 72 6f 77 20 66 6f 72 20 65 61 63   one row for eac
0f30: 68 20 65 6c 65 6d 65 6e 74 2e 0a 7d 20 6a 74 72  h element..} jtr
0f40: 65 65 0a 3c 2f 74 63 6c 3e 0a 3c 2f 74 61 62 6c  ee.</tcl>.</tabl
0f50: 65 3e 3c 2f 63 65 6e 74 65 72 3e 3c 2f 62 6c 6f  e></center></blo
0f60: 63 6b 71 75 6f 74 65 3e 0a 0a 3c 74 63 6c 3e 68  ckquote>..<tcl>h
0f70: 64 5f 66 72 61 67 6d 65 6e 74 20 68 6f 77 74 6f  d_fragment howto
0f80: 63 6f 6d 70 69 6c 65 3c 2f 74 63 6c 3e 0a 3c 68  compile</tcl>.<h
0f90: 32 3e 31 2e 30 20 43 6f 6d 70 69 6c 69 6e 67 20  2>1.0 Compiling 
0fa0: 74 68 65 20 4a 53 4f 4e 31 20 45 78 74 65 6e 73  the JSON1 Extens
0fb0: 69 6f 6e 3c 2f 68 32 3e 0a 0a 3c 70 3e 0a 54 68  ion</h2>..<p>.Th
0fc0: 65 20 5b 6c 6f 61 64 61 62 6c 65 20 65 78 74 65  e [loadable exte
0fd0: 6e 73 69 6f 6e 73 5d 20 64 6f 63 75 6d 65 6e 74  nsions] document
0fe0: 61 74 69 6f 6e 20 63 6f 6e 74 61 69 6e 73 20 69  ation contains i
0ff0: 6e 73 74 72 75 63 74 69 6f 6e 73 20 6f 6e 20 0a  nstructions on .
1000: 68 6f 77 20 74 6f 20 5b 63 6f 6d 70 69 6c 65 20  how to [compile 
1010: 6c 6f 61 64 61 62 6c 65 20 65 78 74 65 6e 73 69  loadable extensi
1020: 6f 6e 73 5d 20 61 73 20 73 68 61 72 65 64 20 6c  ons] as shared l
1030: 69 62 72 61 72 69 65 73 2e 20 20 54 68 65 0a 74  ibraries.  The.t
1040: 65 63 68 6e 69 71 75 65 73 20 64 65 73 63 72 69  echniques descri
1050: 62 65 64 20 74 68 65 72 65 20 77 6f 72 6b 20 66  bed there work f
1060: 69 6e 65 20 66 6f 72 20 74 68 65 20 6a 73 6f 6e  ine for the json
1070: 31 20 6d 6f 64 75 6c 65 2e 0a 0a 3c 70 3e 0a 54  1 module...<p>.T
1080: 68 65 20 6a 73 6f 6e 31 20 73 6f 75 72 63 65 20  he json1 source 
1090: 63 6f 64 65 20 69 73 20 69 6e 63 6c 75 64 65 64  code is included
10a0: 20 77 69 74 68 20 74 68 65 20 53 51 4c 69 74 65   with the SQLite
10b0: 20 5b 61 6d 61 6c 67 61 6d 61 74 69 6f 6e 5d 2c   [amalgamation],
10c0: 20 74 68 6f 75 67 68 0a 69 74 20 69 73 20 74 75   though.it is tu
10d0: 72 6e 65 64 20 6f 66 66 20 62 79 20 64 65 66 61  rned off by defa
10e0: 75 6c 74 2e 20 20 41 64 64 20 74 68 65 20 5b 2d  ult.  Add the [-
10f0: 44 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4a  DSQLITE_ENABLE_J
1100: 53 4f 4e 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  SON1] compile-ti
1110: 6d 65 0a 6f 70 74 69 6f 6e 20 74 6f 20 65 6e 61  me.option to ena
1120: 62 6c 65 20 74 68 65 20 6a 73 6f 6e 31 20 65 78  ble the json1 ex
1130: 74 65 6e 73 69 6f 6e 20 74 68 61 74 20 69 73 20  tension that is 
1140: 62 75 69 6c 74 20 69 6e 74 6f 20 74 68 65 20 5b  built into the [
1150: 61 6d 61 6c 67 61 6d 61 74 69 6f 6e 5d 2e 0a 0a  amalgamation]...
1160: 3c 68 32 3e 32 2e 30 20 49 6e 74 65 72 66 61 63  <h2>2.0 Interfac
1170: 65 20 4f 76 65 72 76 69 65 77 3c 2f 68 32 3e 0a  e Overview</h2>.
1180: 0a 3c 70 3e 0a 54 68 65 20 6a 73 6f 6e 31 20 65  .<p>.The json1 e
1190: 78 74 65 6e 73 69 6f 6e 20 28 63 75 72 72 65 6e  xtension (curren
11a0: 74 6c 79 29 20 73 74 6f 72 65 73 20 4a 53 4f 4e  tly) stores JSON
11b0: 20 61 73 20 6f 72 64 69 6e 61 72 79 20 74 65 78   as ordinary tex
11c0: 74 2e 0a 0a 3c 70 3e 0a 42 61 63 6b 77 61 72 64  t...<p>.Backward
11d0: 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20  s compatibility 
11e0: 63 6f 6e 73 74 72 61 69 6e 74 73 20 6d 65 61 6e  constraints mean
11f0: 20 74 68 61 74 20 53 51 4c 69 74 65 20 69 73 20   that SQLite is 
1200: 6f 6e 6c 79 20 61 62 6c 65 20 74 6f 0a 73 74 6f  only able to.sto
1210: 72 65 20 76 61 6c 75 65 73 20 74 68 61 74 20 61  re values that a
1220: 72 65 20 4e 55 4c 4c 2c 20 69 6e 74 65 67 65 72  re NULL, integer
1230: 73 2c 20 66 6c 6f 61 74 69 6e 67 2d 70 6f 69 6e  s, floating-poin
1240: 74 20 6e 75 6d 62 65 72 73 2c 20 74 65 78 74 2c  t numbers, text,
1250: 0a 61 6e 64 20 42 4c 4f 42 73 2e 20 20 49 74 20  .and BLOBs.  It 
1260: 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20  is not possible 
1270: 74 6f 20 61 64 64 20 61 20 73 69 78 74 68 20 22  to add a sixth "
1280: 4a 53 4f 4e 22 20 74 79 70 65 2e 0a 0a 3c 70 3e  JSON" type...<p>
1290: 0a 54 68 65 20 6a 73 6f 6e 31 20 65 78 74 65 6e  .The json1 exten
12a0: 73 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 28 63  sion does not (c
12b0: 75 72 72 65 6e 74 6c 79 29 20 73 75 70 70 6f 72  urrently) suppor
12c0: 74 20 61 20 62 69 6e 61 72 79 20 65 6e 63 6f 64  t a binary encod
12d0: 69 6e 67 0a 6f 66 20 4a 53 4f 4e 2e 20 20 45 78  ing.of JSON.  Ex
12e0: 70 65 72 69 6d 65 6e 74 73 20 68 61 76 65 20 73  periments have s
12f0: 6f 20 66 61 72 20 62 65 65 6e 20 75 6e 61 62 6c  o far been unabl
1300: 65 20 74 6f 20 66 69 6e 64 20 61 20 62 69 6e 61  e to find a bina
1310: 72 79 20 65 6e 63 6f 64 69 6e 67 0a 74 68 61 74  ry encoding.that
1320: 20 69 73 20 73 69 67 6e 69 66 69 63 61 6e 74 6c   is significantl
1330: 79 20 73 6d 61 6c 6c 65 72 20 6f 72 20 66 61 73  y smaller or fas
1340: 74 65 72 20 74 68 61 6e 20 61 20 70 6c 61 69 6e  ter than a plain
1350: 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 2e 0a   text encoding..
1360: 28 54 68 65 20 70 72 65 73 65 6e 74 20 69 6d 70  (The present imp
1370: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 70 61 72 73  lementation pars
1380: 65 73 20 4a 53 4f 4e 20 74 65 78 74 20 61 74 20  es JSON text at 
1390: 6f 76 65 72 20 33 30 30 20 4d 42 2f 73 2e 29 0a  over 300 MB/s.).
13a0: 41 6c 6c 20 6a 73 6f 6e 31 20 66 75 6e 63 74 69  All json1 functi
13b0: 6f 6e 73 20 63 75 72 72 65 6e 74 6c 79 20 74 68  ons currently th
13c0: 72 6f 77 20 61 6e 20 65 72 72 6f 72 20 69 66 20  row an error if 
13d0: 61 6e 79 20 6f 66 20 74 68 65 69 72 0a 61 72 67  any of their.arg
13e0: 75 6d 65 6e 74 73 20 61 72 65 20 42 4c 4f 42 73  uments are BLOBs
13f0: 20 62 65 63 61 75 73 65 20 42 4c 4f 42 73 20 61   because BLOBs a
1400: 72 65 20 72 65 73 65 72 76 65 64 0a 66 6f 72 20  re reserved.for 
1410: 61 20 66 75 74 75 72 65 20 65 6e 68 61 6e 63 65  a future enhance
1420: 6d 65 6e 74 20 69 6e 20 77 68 69 63 68 20 42 4c  ment in which BL
1430: 4f 42 73 20 77 69 6c 6c 20 73 74 6f 72 65 20 74  OBs will store t
1440: 68 65 20 62 69 6e 61 72 79 20 65 6e 63 6f 64 69  he binary encodi
1450: 6e 67 0a 66 6f 72 20 4a 53 4f 4e 2e 0a 0a 3c 70  ng.for JSON...<p
1460: 3e 0a 54 68 65 20 22 31 22 20 61 74 20 74 68 65  >.The "1" at the
1470: 20 65 6e 64 20 6f 66 20 74 68 65 20 6e 61 6d 65   end of the name
1480: 20 66 6f 72 20 74 68 65 20 6a 73 6f 6e 31 20 65   for the json1 e
1490: 78 74 65 6e 73 69 6f 6e 20 69 73 20 64 65 6c 69  xtension is deli
14a0: 62 65 72 61 74 65 2e 0a 54 68 65 20 64 65 73 69  berate..The desi
14b0: 67 6e 65 72 73 20 61 6e 74 69 63 69 70 61 74 65  gners anticipate
14c0: 20 74 68 61 74 20 74 68 65 72 65 20 77 69 6c 6c   that there will
14d0: 20 62 65 20 66 75 74 75 72 65 20 69 6e 63 6f 6d   be future incom
14e0: 70 61 74 69 62 6c 65 20 4a 53 4f 4e 0a 65 78 74  patible JSON.ext
14f0: 65 6e 73 69 6f 6e 73 20 62 75 69 6c 64 69 6e 67  ensions building
1500: 20 75 70 6f 6e 20 74 68 65 20 6c 65 73 73 6f 6e   upon the lesson
1510: 73 20 6c 65 61 72 6e 65 64 20 66 72 6f 6d 20 6a  s learned from j
1520: 73 6f 6e 31 2e 0a 4f 6e 63 65 20 73 75 66 66 69  son1..Once suffi
1530: 63 69 65 6e 74 20 65 78 70 65 72 69 65 6e 63 65  cient experience
1540: 20 69 73 20 67 61 69 6e 65 64 2c 20 73 6f 6d 65   is gained, some
1550: 20 6b 69 6e 64 20 6f 66 0a 4a 53 4f 4e 20 65 78   kind of.JSON ex
1560: 74 65 6e 73 69 6f 6e 20 6d 69 67 68 74 20 62 65  tension might be
1570: 20 66 6f 6c 64 65 64 20 69 6e 74 6f 20 74 68 65   folded into the
1580: 20 53 51 4c 69 74 65 20 63 6f 72 65 2e 20 20 46   SQLite core.  F
1590: 6f 72 20 6e 6f 77 2c 0a 4a 53 4f 4e 20 73 75 70  or now,.JSON sup
15a0: 70 6f 72 74 20 72 65 6d 61 69 6e 73 20 61 6e 20  port remains an 
15b0: 65 78 74 65 6e 73 69 6f 6e 2e 0a 0a 3c 68 33 3e  extension...<h3>
15c0: 32 2e 31 20 4a 53 4f 4e 20 61 72 67 75 6d 65 6e  2.1 JSON argumen
15d0: 74 73 3c 2f 68 33 3e 0a 0a 3c 70 3e 0a 46 6f 72  ts</h3>..<p>.For
15e0: 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20   functions that 
15f0: 61 63 63 65 70 74 20 4a 53 4f 4e 20 61 73 20 74  accept JSON as t
1600: 68 65 69 72 20 66 69 72 73 74 20 61 72 67 75 6d  heir first argum
1610: 65 6e 74 2c 20 74 68 61 74 20 61 72 67 75 6d 65  ent, that argume
1620: 6e 74 0a 63 61 6e 20 62 65 20 61 20 4a 53 4f 4e  nt.can be a JSON
1630: 20 6f 62 6a 65 63 74 2c 20 61 72 72 61 79 2c 20   object, array, 
1640: 6e 75 6d 62 65 72 2c 20 73 74 72 69 6e 67 2c 20  number, string, 
1650: 6f 72 20 6e 75 6c 6c 2e 20 20 53 51 4c 69 74 65  or null.  SQLite
1660: 20 6e 75 6d 65 72 69 63 0a 76 61 6c 75 65 73 20   numeric.values 
1670: 61 6e 64 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20  and NULL values 
1680: 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 20  are interpreted 
1690: 61 73 20 4a 53 4f 4e 20 6e 75 6d 62 65 72 73 20  as JSON numbers 
16a0: 61 6e 64 20 6e 75 6c 6c 73 2c 20 72 65 73 70 65  and nulls, respe
16b0: 63 74 69 76 65 6c 79 2e 0a 53 51 4c 69 74 65 20  ctively..SQLite 
16c0: 74 65 78 74 20 76 61 6c 75 65 73 20 63 61 6e 20  text values can 
16d0: 62 65 20 75 6e 64 65 72 73 74 6f 6f 64 20 61 73  be understood as
16e0: 20 4a 53 4f 4e 20 6f 62 6a 65 63 74 73 2c 20 61   JSON objects, a
16f0: 72 72 61 79 73 2c 20 6f 72 20 73 74 72 69 6e 67  rrays, or string
1700: 73 2e 0a 49 66 20 61 6e 20 53 51 4c 69 74 65 20  s..If an SQLite 
1710: 74 65 78 74 20 76 61 6c 75 65 20 74 68 61 74 20  text value that 
1720: 69 73 20 6e 6f 74 20 61 20 77 65 6c 6c 2d 66 6f  is not a well-fo
1730: 72 6d 65 64 20 4a 53 4f 4e 20 6f 62 6a 65 63 74  rmed JSON object
1740: 2c 20 61 72 72 61 79 2c 20 6f 72 0a 73 74 72 69  , array, or.stri
1750: 6e 67 20 69 73 20 70 61 73 73 65 64 20 69 6e 74  ng is passed int
1760: 6f 20 6a 73 6f 6e 31 20 66 75 6e 63 74 69 6f 6e  o json1 function
1770: 2c 20 74 68 61 74 20 66 75 6e 63 74 69 6f 6e 20  , that function 
1780: 77 69 6c 6c 20 75 73 75 61 6c 6c 79 20 74 68 72  will usually thr
1790: 6f 77 0a 61 6e 20 65 72 72 6f 72 2e 20 20 28 41  ow.an error.  (A
17a0: 6e 20 65 78 63 65 70 74 69 6f 6e 20 69 73 20 74  n exception is t
17b0: 68 65 20 6a 73 6f 6e 5f 76 61 6c 69 64 28 58 29  he json_valid(X)
17c0: 20 0a 66 75 6e 63 74 69 6f 6e 20 77 68 69 63 68   .function which
17d0: 20 72 65 74 75 72 6e 73 20 31 20 69 66 20 58 20   returns 1 if X 
17e0: 69 73 20 77 65 6c 6c 2d 66 6f 72 6d 65 64 20 4a  is well-formed J
17f0: 53 4f 4e 20 61 6e 64 20 30 20 69 66 20 69 74 20  SON and 0 if it 
1800: 69 73 20 6e 6f 74 2e 29 0a 0a 3c 70 3e 0a 46 6f  is not.)..<p>.Fo
1810: 72 20 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f  r the purposes o
1820: 66 20 64 65 74 65 72 6d 69 6e 69 6e 67 20 76 61  f determining va
1830: 6c 69 64 69 74 79 2c 20 6c 65 61 64 69 6e 67 20  lidity, leading 
1840: 61 6e 64 20 74 72 61 69 6c 69 6e 67 20 77 68 69  and trailing whi
1850: 74 65 73 70 61 63 65 0a 6f 6e 20 4a 53 4f 4e 20  tespace.on JSON 
1860: 69 6e 70 75 74 73 20 69 73 20 69 67 6e 6f 72 65  inputs is ignore
1870: 64 2e 20 20 49 6e 74 65 72 69 6f 72 20 77 68 69  d.  Interior whi
1880: 74 65 73 70 61 63 65 20 69 73 20 61 6c 73 6f 20  tespace is also 
1890: 69 67 6e 6f 72 65 64 2c 20 69 6e 20 61 63 63 6f  ignored, in acco
18a0: 72 64 61 6e 63 65 0a 77 69 74 68 20 74 68 65 20  rdance.with the 
18b0: 4a 53 4f 4e 20 73 70 65 63 2e 20 20 54 68 65 73  JSON spec.  Thes
18c0: 65 20 72 6f 75 74 69 6e 65 73 20 61 63 63 65 70  e routines accep
18d0: 74 20 65 78 61 63 74 6c 79 20 74 68 65 20 0a 5b  t exactly the .[
18e0: 68 74 74 70 3a 2f 2f 77 77 77 2e 72 66 63 2d 65  http://www.rfc-e
18f0: 64 69 74 6f 72 2e 6f 72 67 2f 72 66 63 2f 72 66  ditor.org/rfc/rf
1900: 63 37 31 35 39 2e 74 78 74 20 7c 20 72 66 63 2d  c7159.txt | rfc-
1910: 37 31 35 39 20 4a 53 4f 4e 20 73 79 6e 74 61 78  7159 JSON syntax
1920: 5d 0a 26 6d 64 61 73 68 3b 20 6e 6f 20 6d 6f 72  ].&mdash; no mor
1930: 65 20 61 6e 64 20 6e 6f 20 6c 65 73 73 2e 0a 0a  e and no less...
1940: 3c 68 33 3e 32 2e 32 20 50 41 54 48 20 61 72 67  <h3>2.2 PATH arg
1950: 75 6d 65 6e 74 73 3c 2f 68 33 3e 0a 0a 3c 70 3e  uments</h3>..<p>
1960: 0a 46 6f 72 20 66 75 6e 63 74 69 6f 6e 73 20 74  .For functions t
1970: 68 61 74 20 61 63 63 65 70 74 20 50 41 54 48 20  hat accept PATH 
1980: 61 72 67 75 6d 65 6e 74 73 2c 20 74 68 61 74 20  arguments, that 
1990: 50 41 54 48 20 6d 75 73 74 20 62 65 20 77 65 6c  PATH must be wel
19a0: 6c 2d 66 6f 72 6d 65 64 20 6f 72 0a 65 6c 73 65  l-formed or.else
19b0: 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 77 69   the function wi
19c0: 6c 6c 20 74 68 72 6f 77 20 61 6e 20 65 72 72 6f  ll throw an erro
19d0: 72 2e 0a 41 20 77 65 6c 6c 2d 66 6f 72 6d 65 64  r..A well-formed
19e0: 20 50 41 54 48 20 69 73 20 61 20 74 65 78 74 20   PATH is a text 
19f0: 76 61 6c 75 65 20 74 68 61 74 20 62 65 67 69 6e  value that begin
1a00: 73 20 77 69 74 68 20 65 78 61 63 74 6c 79 20 6f  s with exactly o
1a10: 6e 65 0a 27 24 27 20 63 68 61 72 61 63 74 65 72  ne.'$' character
1a20: 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 7a 65 72   followed by zer
1a30: 6f 20 6f 72 20 6d 6f 72 65 20 69 6e 73 74 61 6e  o or more instan
1a40: 63 65 73 0a 6f 66 20 22 2e 3c 69 3e 6f 62 6a 65  ces.of ".<i>obje
1a50: 63 74 6c 61 62 65 6c 3c 2f 69 3e 22 20 6f 72 20  ctlabel</i>" or 
1a60: 22 26 23 39 31 3c 69 3e 61 72 72 61 79 69 6e 64  "&#91<i>arrayind
1a70: 65 78 3c 2f 69 3e 26 23 39 33 22 2e 0a 0a 3c 68  ex</i>&#93"...<h
1a80: 33 3e 32 2e 33 20 56 41 4c 55 45 20 61 72 67 75  3>2.3 VALUE argu
1a90: 6d 65 6e 74 73 3c 2f 68 33 3e 0a 0a 3c 70 3e 0a  ments</h3>..<p>.
1aa0: 46 6f 72 20 66 75 6e 63 74 69 6f 6e 73 20 74 68  For functions th
1ab0: 61 74 20 61 63 63 65 70 74 20 22 3c 69 3e 76 61  at accept "<i>va
1ac0: 6c 75 65 3c 2f 69 3e 22 20 61 72 67 75 6d 65 6e  lue</i>" argumen
1ad0: 74 73 20 28 61 6c 73 6f 20 73 68 6f 77 6e 20 61  ts (also shown a
1ae0: 73 0a 22 3c 69 3e 76 61 6c 75 65 31 3c 2f 69 3e  s."<i>value1</i>
1af0: 22 20 61 6e 64 20 22 3c 69 3e 76 61 6c 75 65 32  " and "<i>value2
1b00: 3c 2f 69 3e 22 29 2c 0a 74 68 6f 73 65 20 61 72  </i>"),.those ar
1b10: 67 75 6d 65 6e 74 73 20 69 73 20 75 73 75 61 6c  guments is usual
1b20: 6c 79 20 75 6e 64 65 72 73 74 6f 6f 64 0a 74 6f  ly understood.to
1b30: 20 62 65 20 61 20 6c 69 74 65 72 61 6c 20 73 74   be a literal st
1b40: 72 69 6e 67 73 20 74 68 61 74 20 61 72 65 20 71  rings that are q
1b50: 75 6f 74 65 64 20 61 6e 64 20 62 65 63 6f 6d 65  uoted and become
1b60: 73 20 4a 53 4f 4e 20 73 74 72 69 6e 67 20 76 61  s JSON string va
1b70: 6c 75 65 73 0a 69 6e 20 74 68 65 20 72 65 73 75  lues.in the resu
1b80: 6c 74 2e 20 20 45 76 65 6e 20 69 66 20 74 68 65  lt.  Even if the
1b90: 20 69 6e 70 75 74 20 3c 69 3e 76 61 6c 75 65 3c   input <i>value<
1ba0: 2f 69 3e 20 73 74 72 69 6e 67 73 20 6c 6f 6f 6b  /i> strings look
1bb0: 20 6c 69 6b 65 20 0a 77 65 6c 6c 2d 66 6f 72 6d   like .well-form
1bc0: 65 64 20 4a 53 4f 4e 2c 20 74 68 65 79 20 61 72  ed JSON, they ar
1bd0: 65 20 73 74 69 6c 6c 20 69 6e 74 65 72 70 72 65  e still interpre
1be0: 74 65 64 20 61 73 20 6c 69 74 65 72 61 6c 20 73  ted as literal s
1bf0: 74 72 69 6e 67 73 20 69 6e 20 74 68 65 0a 72 65  trings in the.re
1c00: 73 75 6c 74 2e 0a 0a 3c 70 3e 0a 48 6f 77 65 76  sult...<p>.Howev
1c10: 65 72 2c 20 69 66 20 61 20 3c 69 3e 76 61 6c 75  er, if a <i>valu
1c20: 65 3c 2f 69 3e 20 61 72 67 75 6d 65 6e 74 20 63  e</i> argument c
1c30: 6f 6d 65 20 64 69 72 65 63 74 6c 79 20 66 72 6f  ome directly fro
1c40: 6d 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20  m the result of 
1c50: 61 6e 6f 74 68 65 72 0a 6a 73 6f 6e 31 20 66 75  another.json1 fu
1c60: 6e 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65  nction, then the
1c70: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 75 6e 64   argument is und
1c80: 65 72 73 74 6f 6f 64 20 74 6f 20 62 65 20 61 63  erstood to be ac
1c90: 74 75 61 6c 20 4a 53 4f 4e 20 61 6e 64 0a 74 68  tual JSON and.th
1ca0: 65 20 63 6f 6d 70 6c 65 74 65 20 4a 53 4f 4e 20  e complete JSON 
1cb0: 69 73 20 69 6e 73 65 72 74 65 64 20 72 61 74 68  is inserted rath
1cc0: 65 72 20 74 68 61 6e 20 61 20 71 75 6f 74 65 64  er than a quoted
1cd0: 20 73 74 72 69 6e 67 2e 0a 0a 3c 70 3e 0a 46 6f   string...<p>.Fo
1ce0: 72 20 65 78 61 6d 70 6c 65 2c 20 69 6e 20 74 68  r example, in th
1cf0: 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 6c 6c  e following call
1d00: 20 74 6f 20 6a 73 6f 6e 5f 6f 62 6a 65 63 74 28   to json_object(
1d10: 29 2c 20 74 68 65 20 3c 69 3e 76 61 6c 75 65 3c  ), the <i>value<
1d20: 2f 69 3e 0a 61 72 67 75 6d 65 6e 74 20 6c 6f 6f  /i>.argument loo
1d30: 6b 73 20 6c 69 6b 65 20 61 20 77 65 6c 6c 2d 66  ks like a well-f
1d40: 6f 72 6d 65 64 20 4a 53 4f 4e 20 61 72 72 61 79  ormed JSON array
1d50: 2e 20 20 48 6f 77 65 76 65 72 2c 20 62 65 63 61  .  However, beca
1d60: 75 73 65 20 69 74 20 69 73 20 6a 75 73 74 0a 6f  use it is just.o
1d70: 72 64 69 6e 61 72 79 20 53 51 4c 20 74 65 78 74  rdinary SQL text
1d80: 2c 20 69 74 20 69 73 20 69 6e 74 65 72 70 72 65  , it is interpre
1d90: 74 65 64 20 61 73 20 61 20 6c 69 74 65 72 61 6c  ted as a literal
1da0: 20 73 74 72 69 6e 67 20 61 6e 64 20 61 64 64 65   string and adde
1db0: 64 20 74 6f 20 74 68 65 0a 72 65 73 75 6c 74 20  d to the.result 
1dc0: 61 73 20 61 20 71 75 6f 74 65 64 20 73 74 72 69  as a quoted stri
1dd0: 6e 67 3a 0a 0a 3c 74 63 6c 3e 0a 6a 65 78 61 6d  ng:..<tcl>.jexam
1de0: 70 6c 65 20 7b 6a 73 6f 6e 5f 6f 62 6a 65 63 74  ple {json_object
1df0: 28 27 65 78 27 2c 27 5b 35 32 2c 33 2e 31 34 31  ('ex','[52,3.141
1e00: 35 39 5d 27 29 7d 20 7b 27 7b 22 65 78 22 3a 22  59]')} {'{"ex":"
1e10: 5b 35 32 2c 33 2e 31 34 31 35 39 5d 22 7d 27 7d  [52,3.14159]"}'}
1e20: 0a 3c 2f 74 63 6c 3e 0a 0a 3c 70 3e 0a 42 75 74  .</tcl>..<p>.But
1e30: 20 69 66 20 74 68 65 20 3c 69 3e 76 61 6c 75 65   if the <i>value
1e40: 3c 2f 69 3e 20 61 72 67 75 6d 65 6e 74 20 69 6e  </i> argument in
1e50: 20 74 68 65 20 6f 75 74 65 72 20 6a 73 6f 6e 5f   the outer json_
1e60: 6f 62 6a 65 63 74 28 29 20 63 61 6c 6c 20 69 73  object() call is
1e70: 20 74 68 65 0a 72 65 73 75 6c 74 20 6f 66 20 61   the.result of a
1e80: 6e 6f 74 68 65 72 20 6a 73 6f 6e 31 20 66 75 6e  nother json1 fun
1e90: 63 74 69 6f 6e 20 6c 69 6b 65 20 5b 6a 73 6f 6e  ction like [json
1ea0: 28 29 5d 20 6f 72 20 5b 6a 73 6f 6e 5f 61 72 72  ()] or [json_arr
1eb0: 61 79 28 29 5d 2c 20 74 68 65 6e 0a 74 68 65 20  ay()], then.the 
1ec0: 76 61 6c 75 65 20 69 73 20 75 6e 64 65 72 73 74  value is underst
1ed0: 6f 6f 64 20 74 6f 20 62 65 20 61 63 74 75 61 6c  ood to be actual
1ee0: 20 4a 53 4f 4e 20 61 6e 64 20 69 73 20 69 6e 73   JSON and is ins
1ef0: 65 72 74 65 64 20 61 73 20 73 75 63 68 3a 0a 0a  erted as such:..
1f00: 3c 74 63 6c 3e 0a 6a 65 78 61 6d 70 6c 65 20 5c  <tcl>.jexample \
1f10: 0a 20 20 7b 6a 73 6f 6e 5f 6f 62 6a 65 63 74 28  .  {json_object(
1f20: 27 65 78 27 2c 6a 73 6f 6e 28 27 5b 35 32 2c 33  'ex',json('[52,3
1f30: 2e 31 34 31 35 39 5d 27 29 29 7d 20 7b 27 7b 22  .14159]'))} {'{"
1f40: 65 78 22 3a 5b 35 32 2c 33 2e 31 34 31 35 39 5d  ex":[52,3.14159]
1f50: 7d 27 7d 20 20 5c 0a 20 20 7b 6a 73 6f 6e 5f 6f  }'}  \.  {json_o
1f60: 62 6a 65 63 74 28 27 65 78 27 2c 6a 73 6f 6e 5f  bject('ex',json_
1f70: 61 72 72 61 79 28 35 32 2c 33 2e 31 34 31 35 39  array(52,3.14159
1f80: 29 29 7d 20 7b 27 7b 22 65 78 22 3a 5b 35 32 2c  ))} {'{"ex":[52,
1f90: 33 2e 31 34 31 35 39 5d 7d 27 7d 0a 3c 2f 74 63  3.14159]}'}.</tc
1fa0: 6c 3e 0a 0a 3c 70 3e 0a 54 6f 20 62 65 20 63 6c  l>..<p>.To be cl
1fb0: 65 61 72 3a 20 22 3c 69 3e 6a 73 6f 6e 3c 2f 69  ear: "<i>json</i
1fc0: 3e 22 20 61 72 67 75 6d 65 6e 74 73 20 61 72 65  >" arguments are
1fd0: 20 61 6c 77 61 79 73 20 69 6e 74 65 72 70 72 65   always interpre
1fe0: 74 65 64 20 61 73 20 4a 53 4f 4e 0a 72 65 67 61  ted as JSON.rega
1ff0: 72 64 6c 65 73 73 20 6f 66 20 77 68 65 72 65 20  rdless of where 
2000: 74 68 65 20 76 61 6c 75 65 20 66 6f 72 20 74 68  the value for th
2010: 61 74 20 61 72 67 75 6d 65 6e 74 20 63 6f 6d 65  at argument come
2020: 73 20 66 72 6f 6d 2e 20 20 42 75 74 0a 22 3c 69  s from.  But."<i
2030: 3e 76 61 6c 75 65 3c 2f 69 3e 22 20 61 72 67 75  >value</i>" argu
2040: 6d 65 6e 74 73 20 61 72 65 20 6f 6e 6c 79 20 69  ments are only i
2050: 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 4a 53  nterpreted as JS
2060: 4f 4e 20 69 66 20 74 68 6f 73 65 20 61 72 67 75  ON if those argu
2070: 6d 65 6e 74 73 0a 63 6f 6d 65 20 64 69 72 65 63  ments.come direc
2080: 74 6c 79 20 66 72 6f 6d 20 61 6e 6f 74 68 65 72  tly from another
2090: 20 6a 73 6f 6e 31 20 66 75 6e 63 74 69 6f 6e 2e   json1 function.
20a0: 0a 0a 3c 68 33 3e 32 2e 34 20 43 6f 6d 70 61 74  ..<h3>2.4 Compat
20b0: 69 62 69 6c 69 74 79 3c 2f 68 33 3e 0a 0a 3c 70  ibility</h3>..<p
20c0: 3e 0a 54 68 65 20 6a 73 6f 6e 31 20 65 78 74 65  >.The json1 exte
20d0: 6e 73 69 6f 6e 20 75 73 65 73 20 74 68 65 20 5b  nsion uses the [
20e0: 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 73 75  sqlite3_value_su
20f0: 62 74 79 70 65 28 29 5d 20 61 6e 64 0a 5b 73 71  btype()] and.[sq
2100: 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 73 75 62  lite3_result_sub
2110: 74 79 70 65 28 29 5d 20 69 6e 74 65 72 66 61 63  type()] interfac
2120: 65 73 20 74 68 61 74 20 77 65 72 65 20 69 6e 74  es that were int
2130: 72 6f 64 75 63 65 64 20 77 69 74 68 0a 53 51 4c  roduced with.SQL
2140: 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 39 2e  ite version 3.9.
2150: 30 2e 20 20 54 68 65 72 65 66 6f 72 65 20 74 68  0.  Therefore th
2160: 65 20 6a 73 6f 6e 31 20 65 78 74 65 6e 73 69 6f  e json1 extensio
2170: 6e 20 77 69 6c 6c 20 6e 6f 74 20 77 6f 72 6b 0a  n will not work.
2180: 69 6e 20 65 61 72 6c 69 65 72 20 76 65 72 73 69  in earlier versi
2190: 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 0a  ons of SQLite...
21a0: 3c 68 32 3e 33 2e 30 20 46 75 6e 63 74 69 6f 6e  <h2>3.0 Function
21b0: 20 44 65 74 61 69 6c 73 3c 2f 68 32 3e 0a 0a 3c   Details</h2>..<
21c0: 70 3e 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  p>The following 
21d0: 73 65 63 74 69 6f 6e 73 20 70 72 6f 76 69 64 65  sections provide
21e0: 20 61 64 64 69 74 69 6f 6e 61 6c 20 64 65 74 61   additional deta
21f0: 69 6c 20 6f 6e 20 74 68 65 20 6f 70 65 72 61 74  il on the operat
2200: 69 6f 6e 20 6f 66 0a 74 68 65 20 76 61 72 69 6f  ion of.the vario
2210: 75 73 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61  us functions tha
2220: 74 20 61 72 65 20 70 61 72 74 20 6f 66 20 74 68  t are part of th
2230: 65 20 6a 73 6f 6e 31 20 65 78 74 65 6e 73 69 6f  e json1 extensio
2240: 6e 2e 0a 0a 3c 74 63 6c 3e 68 64 5f 66 72 61 67  n...<tcl>hd_frag
2250: 6d 65 6e 74 20 6a 6d 69 6e 69 20 7b 6a 73 6f 6e  ment jmini {json
2260: 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 20 7b   SQL function} {
2270: 6a 73 6f 6e 7d 3c 2f 74 63 6c 3e 0a 3c 68 33 3e  json}</tcl>.<h3>
2280: 33 2e 31 20 54 68 65 20 6a 73 6f 6e 28 29 20 66  3.1 The json() f
2290: 75 6e 63 74 69 6f 6e 3c 2f 68 33 3e 0a 0a 3c 70  unction</h3>..<p
22a0: 3e 54 68 65 20 6a 73 6f 6e 28 58 29 20 66 75 6e  >The json(X) fun
22b0: 63 74 69 6f 6e 20 76 65 72 69 66 69 65 73 20 74  ction verifies t
22c0: 68 61 74 20 69 74 73 20 61 72 67 75 6d 65 6e 74  hat its argument
22d0: 20 58 20 69 73 20 61 20 76 61 6c 69 64 0a 4a 53   X is a valid.JS
22e0: 4f 4e 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65  ON string and re
22f0: 74 75 72 6e 73 20 61 20 6d 69 6e 69 66 69 65 64  turns a minified
2300: 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 61 74   version of that
2310: 20 4a 53 4f 4e 20 73 74 72 69 6e 67 0a 28 77 69   JSON string.(wi
2320: 74 68 20 61 6c 6c 20 75 6e 6e 65 63 65 73 73 61  th all unnecessa
2330: 72 79 20 77 68 69 74 65 73 70 61 63 65 20 72 65  ry whitespace re
2340: 6d 6f 76 65 64 29 2e 20 20 49 66 20 58 20 69 73  moved).  If X is
2350: 20 6e 6f 74 20 61 20 77 65 6c 6c 2d 66 6f 72 6d   not a well-form
2360: 65 64 0a 4a 53 4f 4e 20 73 74 72 69 6e 67 2c 20  ed.JSON string, 
2370: 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e  then this routin
2380: 65 20 74 68 72 6f 77 73 20 61 6e 20 65 72 72 6f  e throws an erro
2390: 72 2e 0a 0a 3c 70 3e 49 66 20 74 68 65 20 61 72  r...<p>If the ar
23a0: 67 75 6d 65 6e 74 20 58 20 74 6f 20 6a 73 6f 6e  gument X to json
23b0: 28 58 29 20 63 6f 6e 74 61 69 6e 73 20 4a 53 4f  (X) contains JSO
23c0: 4e 20 6f 62 6a 65 63 74 73 20 77 69 74 68 20 64  N objects with d
23d0: 75 70 6c 69 63 61 74 65 0a 6c 61 62 65 6c 73 2c  uplicate.labels,
23e0: 20 74 68 65 6e 20 69 74 20 69 73 20 75 6e 64 65   then it is unde
23f0: 66 69 6e 65 64 20 77 68 65 74 68 65 72 20 6f 72  fined whether or
2400: 20 6e 6f 74 20 74 68 65 20 64 75 70 6c 69 63 61   not the duplica
2410: 74 65 73 20 61 72 65 0a 70 72 65 73 65 72 76 65  tes are.preserve
2420: 64 2e 20 20 54 68 65 20 63 75 72 72 65 6e 74 20  d.  The current 
2430: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 70  implementation p
2440: 72 65 73 65 72 76 65 73 20 64 75 70 6c 69 63 61  reserves duplica
2450: 74 65 73 2e 0a 48 6f 77 65 76 65 72 2c 20 66 75  tes..However, fu
2460: 74 75 72 65 20 65 6e 68 61 6e 63 65 6d 65 6e 74  ture enhancement
2470: 73 0a 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e  s.to this routin
2480: 65 20 6d 61 79 20 63 68 6f 6f 73 65 20 74 6f 20  e may choose to 
2490: 73 69 6c 65 6e 74 6c 79 20 72 65 6d 6f 76 65 20  silently remove 
24a0: 64 75 70 6c 69 63 61 74 65 73 2e 0a 0a 3c 70 3e  duplicates...<p>
24b0: 0a 45 78 61 6d 70 6c 65 3a 0a 0a 3c 74 63 6c 3e  .Example:..<tcl>
24c0: 0a 6a 65 78 61 6d 70 6c 65 20 5c 0a 20 20 7b 6a  .jexample \.  {j
24d0: 73 6f 6e 28 27 20 7b 20 22 74 68 69 73 22 20 3a  son(' { "this" :
24e0: 20 22 69 73 22 2c 20 22 61 22 3a 20 5b 20 22 74   "is", "a": [ "t
24f0: 65 73 74 22 20 5d 20 7d 20 27 29 7d 20 5c 0a 20  est" ] } ')} \. 
2500: 20 20 20 20 20 7b 27 7b 22 74 68 69 73 22 3a 22       {'{"this":"
2510: 69 73 22 2c 22 61 22 3a 5b 22 74 65 73 74 22 5d  is","a":["test"]
2520: 7d 27 7d 0a 3c 2f 74 63 6c 3e 0a 0a 3c 74 63 6c  }'}.</tcl>..<tcl
2530: 3e 68 64 5f 66 72 61 67 6d 65 6e 74 20 6a 61 72  >hd_fragment jar
2540: 72 61 79 20 7b 6a 73 6f 6e 5f 61 72 72 61 79 20  ray {json_array 
2550: 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 20 7b 6a  SQL function} {j
2560: 73 6f 6e 5f 61 72 72 61 79 7d 3c 2f 74 63 6c 3e  son_array}</tcl>
2570: 0a 3c 68 33 3e 33 2e 32 20 54 68 65 20 6a 73 6f  .<h3>3.2 The jso
2580: 6e 5f 61 72 72 61 79 28 29 20 66 75 6e 63 74 69  n_array() functi
2590: 6f 6e 3c 2f 68 33 3e 0a 0a 3c 70 3e 54 68 65 20  on</h3>..<p>The 
25a0: 6a 73 6f 6e 5f 61 72 72 61 79 28 29 20 53 51 4c  json_array() SQL
25b0: 20 66 75 6e 63 74 69 6f 6e 20 61 63 63 65 70 74   function accept
25c0: 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 61  s zero or more a
25d0: 72 67 75 6d 65 6e 74 73 20 61 6e 64 0a 72 65 74  rguments and.ret
25e0: 75 72 6e 73 20 61 20 77 65 6c 6c 2d 66 6f 72 6d  urns a well-form
25f0: 65 64 20 4a 53 4f 4e 20 61 72 72 61 79 20 74 68  ed JSON array th
2600: 61 74 20 69 73 20 63 6f 6d 70 6f 73 65 64 20 66  at is composed f
2610: 72 6f 6d 20 74 68 6f 73 65 20 61 72 67 75 6d 65  rom those argume
2620: 6e 74 73 2e 0a 49 66 20 61 6e 79 20 61 72 67 75  nts..If any argu
2630: 6d 65 6e 74 20 74 6f 20 6a 73 6f 6e 5f 61 72 72  ment to json_arr
2640: 61 79 28 29 20 69 73 20 61 20 42 4c 4f 42 20 74  ay() is a BLOB t
2650: 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 69 73 20  hen an error is 
2660: 74 68 72 6f 77 6e 2e 0a 0a 3c 70 3e 41 6e 20 61  thrown...<p>An a
2670: 72 67 75 6d 65 6e 74 20 77 69 74 68 20 53 51 4c  rgument with SQL
2680: 20 74 79 70 65 20 54 45 58 54 20 69 74 20 69 73   type TEXT it is
2690: 20 6e 6f 72 6d 61 6c 6c 79 20 63 6f 6e 76 65 72   normally conver
26a0: 74 65 64 20 69 6e 74 6f 20 61 20 71 75 6f 74 65  ted into a quote
26b0: 64 20 0a 4a 53 4f 4e 20 73 74 72 69 6e 67 2e 20  d .JSON string. 
26c0: 20 48 6f 77 65 76 65 72 2c 20 69 66 20 74 68 65   However, if the
26d0: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
26e0: 20 6f 75 74 70 75 74 20 66 72 6f 6d 20 61 6e 6f   output from ano
26f0: 74 68 65 72 20 6a 73 6f 6e 31 0a 66 75 6e 63 74  ther json1.funct
2700: 69 6f 6e 2c 20 74 68 65 6e 20 69 74 20 69 73 20  ion, then it is 
2710: 73 74 6f 72 65 64 20 61 73 20 4a 53 4f 4e 2e 20  stored as JSON. 
2720: 20 54 68 69 73 20 61 6c 6c 6f 77 73 20 63 61 6c   This allows cal
2730: 6c 73 20 74 6f 20 6a 73 6f 6e 5f 61 72 72 61 79  ls to json_array
2740: 28 29 0a 61 6e 64 20 5b 6a 73 6f 6e 5f 6f 62 6a  ().and [json_obj
2750: 65 63 74 28 29 5d 20 74 6f 20 62 65 20 6e 65 73  ect()] to be nes
2760: 74 65 64 2e 20 20 54 68 65 20 5b 6a 73 6f 6e 28  ted.  The [json(
2770: 29 5d 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20  )] function can 
2780: 61 6c 73 6f 0a 62 65 20 75 73 65 64 20 74 6f 20  also.be used to 
2790: 66 6f 72 63 65 20 73 74 72 69 6e 67 73 20 74 6f  force strings to
27a0: 20 62 65 20 72 65 63 6f 67 6e 69 7a 65 64 20 61   be recognized a
27b0: 73 20 4a 53 4f 4e 2e 0a 0a 3c 70 3e 45 78 61 6d  s JSON...<p>Exam
27c0: 70 6c 65 73 3a 0a 0a 3c 74 63 6c 3e 0a 6a 65 78  ples:..<tcl>.jex
27d0: 61 6d 70 6c 65 20 5c 0a 20 20 7b 6a 73 6f 6e 5f  ample \.  {json_
27e0: 61 72 72 61 79 28 31 2c 32 2c 27 33 27 2c 34 29  array(1,2,'3',4)
27f0: 7d 20 7b 27 5b 31 2c 32 2c 22 33 22 2c 34 5d 27  } {'[1,2,"3",4]'
2800: 7d 20 5c 0a 20 20 7b 6a 73 6f 6e 5f 61 72 72 61  } \.  {json_arra
2810: 79 28 27 5b 31 2c 32 5d 27 29 7d 20 7b 27 5b 22  y('[1,2]')} {'["
2820: 5b 31 2c 32 5d 22 5d 27 7d 20 5c 0a 20 20 7b 6a  [1,2]"]'} \.  {j
2830: 73 6f 6e 5f 61 72 72 61 79 28 6a 73 6f 6e 5f 61  son_array(json_a
2840: 72 72 61 79 28 31 2c 32 29 29 7d 20 7b 27 5b 5b  rray(1,2))} {'[[
2850: 31 2c 32 5d 5d 27 7d 20 5c 0a 20 20 7b 6a 73 6f  1,2]]'} \.  {jso
2860: 6e 5f 61 72 72 61 79 28 31 2c 6e 75 6c 6c 2c 27  n_array(1,null,'
2870: 33 27 2c 27 5b 34 2c 35 5d 27 2c 27 7b 22 73 69  3','[4,5]','{"si
2880: 78 22 3a 37 2e 37 7d 27 29 7d 20 5c 0a 20 20 20  x":7.7}')} \.   
2890: 20 20 20 7b 27 5b 31 2c 6e 75 6c 6c 2c 22 33 22     {'[1,null,"3"
28a0: 2c 22 5b 34 2c 35 5d 22 2c 22 7b 5c 22 73 69 78  ,"[4,5]","{\"six
28b0: 5c 22 3a 37 2e 37 7d 22 5d 27 7d 20 5c 0a 20 20  \":7.7}"]'} \.  
28c0: 7b 6a 73 6f 6e 5f 61 72 72 61 79 28 31 2c 6e 75  {json_array(1,nu
28d0: 6c 6c 2c 27 33 27 2c 6a 73 6f 6e 28 27 5b 34 2c  ll,'3',json('[4,
28e0: 35 5d 27 29 2c 6a 73 6f 6e 28 27 7b 22 73 69 78  5]'),json('{"six
28f0: 22 3a 37 2e 37 7d 27 29 29 7d 20 5c 0a 20 20 20  ":7.7}'))} \.   
2900: 20 20 20 7b 27 5b 31 2c 6e 75 6c 6c 2c 22 33 22     {'[1,null,"3"
2910: 2c 5b 34 2c 35 5d 2c 7b 22 73 69 78 22 3a 37 2e  ,[4,5],{"six":7.
2920: 37 7d 5d 27 7d 0a 3c 2f 74 63 6c 3e 0a 0a 0a 3c  7}]'}.</tcl>...<
2930: 74 63 6c 3e 68 64 5f 66 72 61 67 6d 65 6e 74 20  tcl>hd_fragment 
2940: 6a 61 72 72 61 79 6c 65 6e 20 7b 6a 73 6f 6e 5f  jarraylen {json_
2950: 61 72 72 61 79 5f 6c 65 6e 67 74 68 20 53 51 4c  array_length SQL
2960: 20 66 75 6e 63 74 69 6f 6e 7d 20 5c 0a 20 20 20   function} \.   
2970: 20 20 20 20 20 20 7b 6a 73 6f 6e 5f 61 72 72 61        {json_arra
2980: 79 5f 6c 65 6e 67 74 68 7d 3c 2f 74 63 6c 3e 0a  y_length}</tcl>.
2990: 3c 68 33 3e 33 2e 33 20 54 68 65 20 6a 73 6f 6e  <h3>3.3 The json
29a0: 5f 61 72 72 61 79 5f 6c 65 6e 67 74 68 28 29 20  _array_length() 
29b0: 66 75 6e 63 74 69 6f 6e 3c 2f 68 33 3e 0a 0a 3c  function</h3>..<
29c0: 70 3e 54 68 65 20 6a 73 6f 6e 5f 61 72 72 61 79  p>The json_array
29d0: 5f 6c 65 6e 67 74 68 28 58 29 20 66 75 6e 63 74  _length(X) funct
29e0: 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  ion returns the 
29f0: 6e 75 6d 62 65 72 20 6f 66 20 65 6c 65 6d 65 6e  number of elemen
2a00: 74 73 0a 69 6e 20 74 68 65 20 4a 53 4f 4e 20 61  ts.in the JSON a
2a10: 72 72 61 79 20 58 2c 20 6f 72 20 30 20 69 66 20  rray X, or 0 if 
2a20: 58 20 69 73 20 73 6f 6d 65 20 6b 69 6e 64 20 6f  X is some kind o
2a30: 66 20 4a 53 4f 4e 20 76 61 6c 75 65 20 6f 74 68  f JSON value oth
2a40: 65 72 0a 74 68 61 6e 20 61 6e 20 61 72 72 61 79  er.than an array
2a50: 2e 20 20 54 68 65 20 6a 73 6f 6e 5f 61 72 72 61  .  The json_arra
2a60: 79 5f 6c 65 6e 67 74 68 28 58 2c 50 29 20 6c 6f  y_length(X,P) lo
2a70: 63 61 74 65 73 20 74 68 65 20 61 72 72 61 79 20  cates the array 
2a80: 61 74 20 70 61 74 68 20 50 0a 77 69 74 68 69 6e  at path P.within
2a90: 20 58 20 61 6e 64 20 72 65 74 75 72 6e 73 20 74   X and returns t
2aa0: 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 61  he length of tha
2ab0: 74 20 61 72 72 61 79 2c 20 6f 72 20 30 20 69 66  t array, or 0 if
2ac0: 20 70 61 74 68 20 50 20 6c 6f 63 61 74 65 73 0a   path P locates.
2ad0: 61 20 65 6c 65 6d 65 6e 74 20 6f 72 20 58 20 6f  a element or X o
2ae0: 74 68 65 72 20 74 68 61 6e 20 61 20 4a 53 4f 4e  ther than a JSON
2af0: 20 61 72 72 61 79 2c 20 61 6e 64 20 4e 55 4c 4c   array, and NULL
2b00: 20 69 66 20 70 61 74 68 20 50 20 64 6f 65 73 20   if path P does 
2b10: 6e 6f 74 0a 6c 6f 63 61 74 65 20 61 6e 79 20 65  not.locate any e
2b20: 6c 65 6d 65 6e 74 20 6f 66 20 58 2e 20 20 45 72  lement of X.  Er
2b30: 72 6f 72 73 20 61 72 65 20 74 68 72 6f 77 6e 20  rors are thrown 
2b40: 69 66 20 65 69 74 68 65 72 20 58 20 69 73 20 6e  if either X is n
2b50: 6f 74 20 0a 77 65 6c 6c 2d 66 6f 72 6d 65 64 20  ot .well-formed 
2b60: 4a 53 4f 4e 20 6f 72 20 69 66 20 50 20 69 73 20  JSON or if P is 
2b70: 6e 6f 74 20 61 20 77 65 6c 6c 2d 66 6f 72 6d 65  not a well-forme
2b80: 64 20 70 61 74 68 2e 0a 0a 3c 70 3e 45 78 61 6d  d path...<p>Exam
2b90: 70 6c 65 73 3a 0a 0a 3c 74 63 6c 3e 0a 6a 65 78  ples:..<tcl>.jex
2ba0: 61 6d 70 6c 65 20 5c 0a 20 20 7b 6a 73 6f 6e 5f  ample \.  {json_
2bb0: 61 72 72 61 79 5f 6c 65 6e 67 74 68 28 27 5b 31  array_length('[1
2bc0: 2c 32 2c 33 2c 34 5d 27 29 7d 20 7b 34 7d 20 5c  ,2,3,4]')} {4} \
2bd0: 0a 20 20 7b 6a 73 6f 6e 5f 61 72 72 61 79 5f 6c  .  {json_array_l
2be0: 65 6e 67 74 68 28 27 5b 31 2c 32 2c 33 2c 34 5d  ength('[1,2,3,4]
2bf0: 27 2c 20 27 24 27 29 7d 20 7b 34 7d 20 5c 0a 20  ', '$')} {4} \. 
2c00: 20 7b 6a 73 6f 6e 5f 61 72 72 61 79 5f 6c 65 6e   {json_array_len
2c10: 67 74 68 28 27 5b 31 2c 32 2c 33 2c 34 5d 27 2c  gth('[1,2,3,4]',
2c20: 20 27 24 5b 32 5d 27 29 7d 20 7b 30 7d 20 5c 0a   '$[2]')} {0} \.
2c30: 20 20 7b 6a 73 6f 6e 5f 61 72 72 61 79 5f 6c 65    {json_array_le
2c40: 6e 67 74 68 28 27 7b 22 6f 6e 65 22 3a 5b 31 2c  ngth('{"one":[1,
2c50: 32 2c 33 5d 7d 27 29 7d 20 7b 30 7d 20 5c 0a 20  2,3]}')} {0} \. 
2c60: 20 7b 6a 73 6f 6e 5f 61 72 72 61 79 5f 6c 65 6e   {json_array_len
2c70: 67 74 68 28 27 7b 22 6f 6e 65 22 3a 5b 31 2c 32  gth('{"one":[1,2
2c80: 2c 33 5d 7d 27 2c 20 27 24 2e 6f 6e 65 27 29 7d  ,3]}', '$.one')}
2c90: 20 7b 33 7d 20 5c 0a 20 20 7b 6a 73 6f 6e 5f 61   {3} \.  {json_a
2ca0: 72 72 61 79 5f 6c 65 6e 67 74 68 28 27 7b 22 6f  rray_length('{"o
2cb0: 6e 65 22 3a 5b 31 2c 32 2c 33 5d 7d 27 2c 20 27  ne":[1,2,3]}', '
2cc0: 24 2e 74 77 6f 27 29 7d 20 7b 4e 55 4c 4c 7d 0a  $.two')} {NULL}.
2cd0: 3c 2f 74 63 6c 3e 0a 0a 0a 3c 74 63 6c 3e 68 64  </tcl>...<tcl>hd
2ce0: 5f 66 72 61 67 6d 65 6e 74 20 6a 65 78 20 7b 6a  _fragment jex {j
2cf0: 73 6f 6e 5f 65 78 74 72 61 63 74 20 53 51 4c 20  son_extract SQL 
2d00: 66 75 6e 63 74 69 6f 6e 7d 20 7b 6a 73 6f 6e 5f  function} {json_
2d10: 65 78 74 72 61 63 74 7d 3c 2f 74 63 6c 3e 0a 3c  extract}</tcl>.<
2d20: 68 33 3e 33 2e 34 20 54 68 65 20 6a 73 6f 6e 5f  h3>3.4 The json_
2d30: 65 78 74 72 61 63 74 28 29 20 66 75 6e 63 74 69  extract() functi
2d40: 6f 6e 3c 2f 68 33 3e 0a 0a 3c 70 3e 54 68 65 20  on</h3>..<p>The 
2d50: 6a 73 6f 6e 5f 65 78 74 72 61 63 74 28 58 2c 50  json_extract(X,P
2d60: 31 2c 50 32 2c 2e 2e 2e 29 20 65 78 74 72 61 63  1,P2,...) extrac
2d70: 74 73 20 61 6e 64 20 72 65 74 75 72 6e 73 20 6f  ts and returns o
2d80: 6e 65 20 6f 72 20 6d 6f 72 65 20 0a 76 61 6c 75  ne or more .valu
2d90: 65 73 20 66 72 6f 6d 20 74 68 65 0a 77 65 6c 6c  es from the.well
2da0: 2d 66 6f 72 6d 65 64 20 4a 53 4f 4e 20 61 74 20  -formed JSON at 
2db0: 58 2e 20 20 49 66 20 6f 6e 6c 79 20 61 20 73 69  X.  If only a si
2dc0: 6e 67 6c 65 20 70 61 74 68 20 50 31 20 69 73 20  ngle path P1 is 
2dd0: 70 72 6f 76 69 64 65 64 2c 20 74 68 65 6e 20 74  provided, then t
2de0: 68 65 0a 53 51 4c 20 64 61 74 61 74 79 70 65 20  he.SQL datatype 
2df0: 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  of the result is
2e00: 20 4e 55 4c 4c 20 66 6f 72 20 61 20 4a 53 4f 4e   NULL for a JSON
2e10: 20 6e 75 6c 6c 2c 20 49 4e 54 45 47 45 52 20 6f   null, INTEGER o
2e20: 72 20 52 45 41 4c 0a 66 6f 72 20 61 20 4a 53 4f  r REAL.for a JSO
2e30: 4e 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 2c  N numeric value,
2e40: 20 61 6e 20 49 4e 54 45 47 45 52 20 7a 65 72 6f   an INTEGER zero
2e50: 20 66 6f 72 20 61 20 4a 53 4f 4e 20 66 61 6c 73   for a JSON fals
2e60: 65 20 76 61 6c 75 65 2c 0a 61 6e 20 49 4e 54 45  e value,.an INTE
2e70: 47 45 52 20 6f 6e 65 20 66 6f 72 20 61 20 4a 53  GER one for a JS
2e80: 4f 4e 20 74 72 75 65 20 76 61 6c 75 65 2c 20 74  ON true value, t
2e90: 68 65 20 64 65 71 75 6f 74 65 64 20 74 65 78 74  he dequoted text
2ea0: 20 66 6f 72 20 61 20 0a 4a 53 4f 4e 20 73 74 72   for a .JSON str
2eb0: 69 6e 67 20 76 61 6c 75 65 2c 20 61 6e 64 20 61  ing value, and a
2ec0: 20 74 65 78 74 20 72 65 70 72 65 73 65 6e 74 61   text representa
2ed0: 74 69 6f 6e 20 66 6f 72 20 4a 53 4f 4e 20 6f 62  tion for JSON ob
2ee0: 6a 65 63 74 20 61 6e 64 20 61 72 72 61 79 20 76  ject and array v
2ef0: 61 6c 75 65 73 2e 0a 49 66 20 74 68 65 72 65 20  alues..If there 
2f00: 61 72 65 20 6d 75 6c 74 69 70 6c 65 20 70 61 74  are multiple pat
2f10: 68 20 61 72 67 75 6d 65 6e 74 73 20 28 50 31 2c  h arguments (P1,
2f20: 20 50 32 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74   P2, and so fort
2f30: 68 29 20 74 68 65 6e 20 74 68 69 73 0a 72 6f 75  h) then this.rou
2f40: 74 69 6e 65 20 72 65 74 75 72 6e 73 20 53 51 4c  tine returns SQL
2f50: 69 74 65 20 74 65 78 74 20 77 68 69 63 68 20 69  ite text which i
2f60: 73 20 61 20 77 65 6c 6c 2d 66 6f 72 6d 65 64 20  s a well-formed 
2f70: 4a 53 4f 4e 20 61 72 72 61 79 20 68 6f 6c 64 69  JSON array holdi
2f80: 6e 67 0a 74 68 65 20 76 61 72 69 6f 75 73 20 76  ng.the various v
2f90: 61 6c 75 65 73 2e 0a 0a 3c 70 3e 45 78 61 6d 70  alues...<p>Examp
2fa0: 6c 65 73 3a 0a 0a 3c 74 63 6c 3e 0a 6a 65 78 61  les:..<tcl>.jexa
2fb0: 6d 70 6c 65 20 5c 0a 20 20 7b 6a 73 6f 6e 5f 65  mple \.  {json_e
2fc0: 78 74 72 61 63 74 28 27 7b 22 61 22 3a 32 2c 22  xtract('{"a":2,"
2fd0: 63 22 3a 5b 34 2c 35 2c 7b 22 66 22 3a 37 7d 5d  c":[4,5,{"f":7}]
2fe0: 7d 27 2c 20 27 24 27 29 7d 20 5c 0a 20 20 20 20  }', '$')} \.    
2ff0: 20 20 7b 27 7b 22 61 22 3a 32 2c 22 63 22 3a 5b    {'{"a":2,"c":[
3000: 34 2c 35 2c 7b 22 66 22 3a 37 7d 5d 7d 27 7d 20  4,5,{"f":7}]}'} 
3010: 5c 0a 20 20 7b 6a 73 6f 6e 5f 65 78 74 72 61 63  \.  {json_extrac
3020: 74 28 27 7b 22 61 22 3a 32 2c 22 63 22 3a 5b 34  t('{"a":2,"c":[4
3030: 2c 35 2c 7b 22 66 22 3a 37 7d 5d 7d 27 2c 20 27  ,5,{"f":7}]}', '
3040: 24 2e 63 27 29 7d 20 5c 0a 20 20 20 20 20 20 7b  $.c')} \.      {
3050: 27 5b 34 2c 35 2c 7b 22 66 22 3a 37 7d 5d 27 7d  '[4,5,{"f":7}]'}
3060: 20 5c 0a 20 20 7b 6a 73 6f 6e 5f 65 78 74 72 61   \.  {json_extra
3070: 63 74 28 27 7b 22 61 22 3a 32 2c 22 63 22 3a 5b  ct('{"a":2,"c":[
3080: 34 2c 35 2c 7b 22 66 22 3a 37 7d 5d 7d 27 2c 20  4,5,{"f":7}]}', 
3090: 27 24 2e 63 5b 32 5d 27 29 7d 20 5c 0a 20 20 20  '$.c[2]')} \.   
30a0: 20 20 20 7b 27 7b 22 66 22 3a 37 7d 27 7d 20 5c     {'{"f":7}'} \
30b0: 0a 20 20 7b 6a 73 6f 6e 5f 65 78 74 72 61 63 74  .  {json_extract
30c0: 28 27 7b 22 61 22 3a 32 2c 22 63 22 3a 5b 34 2c  ('{"a":2,"c":[4,
30d0: 35 2c 7b 22 66 22 3a 37 7d 5d 7d 27 2c 20 27 24  5,{"f":7}]}', '$
30e0: 2e 63 5b 32 5d 2e 66 27 29 7d 20 7b 37 7d 20 5c  .c[2].f')} {7} \
30f0: 0a 20 20 7b 6a 73 6f 6e 5f 65 78 74 72 61 63 74  .  {json_extract
3100: 28 27 7b 22 61 22 3a 32 2c 22 63 22 3a 5b 34 2c  ('{"a":2,"c":[4,
3110: 35 5d 2c 22 66 22 3a 37 7d 27 2c 27 24 2e 63 27  5],"f":7}','$.c'
3120: 2c 27 24 2e 61 27 29 7d 20 7b 27 5b 5b 34 2c 35  ,'$.a')} {'[[4,5
3130: 5d 2c 32 5d 27 7d 20 5c 0a 20 20 7b 6a 73 6f 6e  ],2]'} \.  {json
3140: 5f 65 78 74 72 61 63 74 28 27 7b 22 61 22 3a 32  _extract('{"a":2
3150: 2c 22 63 22 3a 5b 34 2c 35 2c 7b 22 66 22 3a 37  ,"c":[4,5,{"f":7
3160: 7d 5d 7d 27 2c 20 27 24 2e 78 27 29 7d 20 4e 55  }]}', '$.x')} NU
3170: 4c 4c 20 5c 0a 20 20 7b 6a 73 6f 6e 5f 65 78 74  LL \.  {json_ext
3180: 72 61 63 74 28 27 7b 22 61 22 3a 32 2c 22 63 22  ract('{"a":2,"c"
3190: 3a 5b 34 2c 35 2c 7b 22 66 22 3a 37 7d 5d 7d 27  :[4,5,{"f":7}]}'
31a0: 2c 20 27 24 2e 78 27 2c 20 27 24 2e 61 27 29 7d  , '$.x', '$.a')}
31b0: 20 7b 27 5b 6e 75 6c 6c 2c 32 5d 27 7d 0a 3c 2f   {'[null,2]'}.</
31c0: 74 63 6c 3e 20 20 0a 0a 3c 74 63 6c 3e 68 64 5f  tcl>  ..<tcl>hd_
31d0: 66 72 61 67 6d 65 6e 74 20 6a 69 6e 73 20 7b 6a  fragment jins {j
31e0: 73 6f 6e 5f 69 6e 73 65 72 74 20 53 51 4c 20 66  son_insert SQL f
31f0: 75 6e 63 74 69 6f 6e 7d 20 7b 6a 73 6f 6e 5f 69  unction} {json_i
3200: 6e 73 65 72 74 7d 3c 2f 74 63 6c 3e 0a 3c 74 63  nsert}</tcl>.<tc
3210: 6c 3e 68 64 5f 66 72 61 67 6d 65 6e 74 20 6a 72  l>hd_fragment jr
3220: 65 70 6c 20 7b 6a 73 6f 6e 5f 72 65 70 6c 61 63  epl {json_replac
3230: 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 20  e SQL function} 
3240: 7b 6a 73 6f 6e 5f 72 65 70 6c 61 63 65 7d 3c 2f  {json_replace}</
3250: 74 63 6c 3e 0a 3c 74 63 6c 3e 68 64 5f 66 72 61  tcl>.<tcl>hd_fra
3260: 67 6d 65 6e 74 20 6a 73 65 74 20 7b 6a 73 6f 6e  gment jset {json
3270: 5f 73 65 74 20 53 51 4c 20 66 75 6e 63 74 69 6f  _set SQL functio
3280: 6e 7d 20 7b 6a 73 6f 6e 5f 73 65 74 7d 3c 2f 74  n} {json_set}</t
3290: 63 6c 3e 0a 3c 68 33 3e 33 2e 35 20 54 68 65 20  cl>.<h3>3.5 The 
32a0: 6a 73 6f 6e 5f 69 6e 73 65 72 74 28 29 2c 20 6a  json_insert(), j
32b0: 73 6f 6e 5f 72 65 70 6c 61 63 65 2c 20 61 6e 64  son_replace, and
32c0: 20 6a 73 6f 6e 5f 73 65 74 28 29 20 66 75 6e 63   json_set() func
32d0: 74 69 6f 6e 73 3c 2f 68 33 3e 0a 0a 3c 70 3e 54  tions</h3>..<p>T
32e0: 68 65 20 6a 73 6f 6e 5f 69 6e 73 65 72 74 28 29  he json_insert()
32f0: 2c 20 6a 73 6f 6e 5f 72 65 70 6c 61 63 65 2c 20  , json_replace, 
3300: 61 6e 64 20 6a 73 6f 6e 5f 73 65 74 28 29 20 66  and json_set() f
3310: 75 6e 63 74 69 6f 6e 73 20 61 6c 6c 20 74 61 6b  unctions all tak
3320: 65 0a 61 20 73 69 6e 67 6c 65 20 4a 53 4f 4e 20  e.a single JSON 
3330: 76 61 6c 75 65 20 61 73 20 74 68 65 69 72 20 66  value as their f
3340: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 66 6f  irst argument fo
3350: 6c 6c 6f 77 65 64 20 62 79 20 7a 65 72 6f 20 6f  llowed by zero o
3360: 72 20 6d 6f 72 65 0a 70 61 69 72 73 20 6f 66 20  r more.pairs of 
3370: 70 61 74 68 20 61 6e 64 20 76 61 6c 75 65 20 61  path and value a
3380: 72 67 75 6d 65 6e 74 73 2c 20 61 6e 64 20 72 65  rguments, and re
3390: 74 75 72 6e 20 61 20 6e 65 77 20 4a 53 4f 4e 20  turn a new JSON 
33a0: 73 74 72 69 6e 67 20 66 6f 72 6d 65 64 0a 62 79  string formed.by
33b0: 20 75 70 64 61 74 69 6e 67 20 74 68 65 20 69 6e   updating the in
33c0: 70 75 74 20 4a 53 4f 4e 20 62 79 20 74 68 65 20  put JSON by the 
33d0: 70 61 74 68 2f 76 61 6c 75 65 20 70 61 69 72 73  path/value pairs
33e0: 2e 20 20 54 68 65 20 66 75 6e 63 74 69 6f 6e 73  .  The functions
33f0: 0a 64 69 66 66 65 72 20 6f 6e 6c 79 20 69 6e 20  .differ only in 
3400: 68 6f 77 20 74 68 65 79 20 64 65 61 6c 20 77 69  how they deal wi
3410: 74 68 20 63 72 65 61 74 69 6e 67 20 6e 65 77 20  th creating new 
3420: 76 61 6c 75 65 73 20 61 6e 64 20 6f 76 65 72 77  values and overw
3430: 72 69 74 69 6e 67 0a 70 72 65 65 78 69 73 74 69  riting.preexisti
3440: 6e 67 20 76 61 6c 75 65 73 2e 0a 0a 3c 63 65 6e  ng values...<cen
3450: 74 65 72 3e 0a 3c 74 61 62 6c 65 20 62 6f 72 64  ter>.<table bord
3460: 65 72 3d 31 20 63 65 6c 6c 70 61 64 64 69 6e 67  er=1 cellpadding
3470: 3d 33 3e 0a 3c 74 72 3e 0a 3c 74 68 3e 46 75 6e  =3>.<tr>.<th>Fun
3480: 63 74 69 6f 6e 3c 74 68 3e 4f 76 65 72 77 72 69  ction<th>Overwri
3490: 74 65 20 69 66 20 61 6c 72 65 61 64 79 20 65 78  te if already ex
34a0: 69 73 74 73 3f 3c 74 68 3e 43 72 65 61 74 65 20  ists?<th>Create 
34b0: 69 66 20 64 6f 65 73 20 6e 6f 74 20 65 78 69 73  if does not exis
34c0: 74 3f 0a 3c 74 72 3e 0a 3c 74 64 3e 6a 73 6f 6e  t?.<tr>.<td>json
34d0: 5f 69 6e 73 65 72 74 28 29 3c 74 64 20 61 6c 69  _insert()<td ali
34e0: 67 6e 3d 27 63 65 6e 74 65 72 27 3e 4e 6f 3c 74  gn='center'>No<t
34f0: 64 20 61 6c 69 67 6e 3d 27 63 65 6e 74 65 72 27  d align='center'
3500: 3e 59 65 73 0a 3c 74 72 3e 0a 3c 74 64 3e 6a 73  >Yes.<tr>.<td>js
3510: 6f 6e 5f 72 65 70 6c 61 63 65 28 29 3c 74 64 20  on_replace()<td 
3520: 61 6c 69 67 6e 3d 27 63 65 6e 74 65 72 27 3e 59  align='center'>Y
3530: 65 73 3c 74 64 20 61 6c 69 67 6e 3d 27 63 65 6e  es<td align='cen
3540: 74 65 72 27 3e 4e 6f 0a 3c 74 72 3e 0a 3c 74 64  ter'>No.<tr>.<td
3550: 3e 6a 73 6f 6e 5f 73 65 74 28 29 3c 74 64 20 61  >json_set()<td a
3560: 6c 69 67 6e 3d 27 63 65 6e 74 65 72 27 3e 59 65  lign='center'>Ye
3570: 73 3c 74 64 20 61 6c 69 67 6e 3d 27 63 65 6e 74  s<td align='cent
3580: 65 72 27 3e 59 65 73 0a 3c 2f 74 61 62 6c 65 3e  er'>Yes.</table>
3590: 3c 2f 63 65 6e 74 65 72 3e 0a 0a 3c 70 3e 54 68  </center>..<p>Th
35a0: 65 20 6a 73 6f 6e 5f 69 6e 73 65 72 74 28 29 2c  e json_insert(),
35b0: 20 6a 73 6f 6e 5f 72 65 70 6c 61 63 65 28 29 2c   json_replace(),
35c0: 20 61 6e 64 20 6a 73 6f 6e 5f 73 65 74 28 29 20   and json_set() 
35d0: 66 75 6e 63 74 69 6f 6e 73 20 61 6c 77 61 79 73  functions always
35e0: 0a 74 61 6b 65 20 61 6e 20 6f 64 64 20 6e 75 6d  .take an odd num
35f0: 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73  ber of arguments
3600: 2e 20 20 54 68 65 20 66 69 72 73 74 20 61 72 67  .  The first arg
3610: 75 6d 65 6e 74 20 69 73 20 61 6c 77 61 79 73 20  ument is always 
3620: 74 68 65 20 6f 72 69 67 69 6e 61 6c 0a 4a 53 4f  the original.JSO
3630: 4e 20 74 6f 20 62 65 20 65 64 69 74 65 64 2e 20  N to be edited. 
3640: 20 53 75 62 73 65 71 75 65 6e 74 20 61 72 67 75   Subsequent argu
3650: 6d 65 6e 74 73 20 6f 63 63 75 72 20 69 6e 20 70  ments occur in p
3660: 61 69 72 73 20 77 69 74 68 20 74 68 65 20 66 69  airs with the fi
3670: 72 73 74 0a 65 6c 65 6d 65 6e 74 20 6f 66 20 65  rst.element of e
3680: 61 63 68 20 70 61 69 72 20 62 65 69 6e 67 20 61  ach pair being a
3690: 20 70 61 74 68 20 61 6e 64 20 74 68 65 20 73 65   path and the se
36a0: 63 6f 6e 64 20 65 6c 65 6d 65 6e 74 20 62 65 69  cond element bei
36b0: 6e 67 20 74 68 65 20 76 61 6c 75 65 0a 74 6f 20  ng the value.to 
36c0: 69 6e 73 65 72 74 20 6f 72 20 72 65 70 6c 61 63  insert or replac
36d0: 65 20 6f 72 20 73 65 74 20 6f 6e 20 74 68 61 74  e or set on that
36e0: 20 70 61 74 68 2e 0a 0a 3c 70 3e 45 64 69 74 73   path...<p>Edits
36f0: 20 6f 63 63 75 72 73 20 73 65 71 75 65 6e 74 69   occurs sequenti
3700: 61 6c 6c 79 20 66 72 6f 6d 20 6c 65 66 74 20 74  ally from left t
3710: 6f 20 72 69 67 68 74 2e 20 20 43 68 61 6e 67 65  o right.  Change
3720: 73 20 63 61 75 73 65 64 20 62 79 0a 70 72 69 6f  s caused by.prio
3730: 72 20 65 64 69 74 73 20 63 61 6e 20 61 66 66 65  r edits can affe
3740: 63 74 20 74 68 65 20 70 61 74 68 20 73 65 61 72  ct the path sear
3750: 63 68 20 66 6f 72 20 73 75 62 73 65 71 75 65 6e  ch for subsequen
3760: 74 20 65 64 69 74 73 2e 0a 0a 3c 70 3e 49 66 20  t edits...<p>If 
3770: 74 68 65 20 76 61 6c 75 65 20 6f 66 20 61 20 70  the value of a p
3780: 61 74 68 2f 76 61 6c 75 65 20 70 61 69 72 20 69  ath/value pair i
3790: 73 20 61 6e 20 53 51 4c 69 74 65 20 54 45 58 54  s an SQLite TEXT
37a0: 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 69 74 0a   value, then it.
37b0: 69 73 20 6e 6f 72 6d 61 6c 6c 79 20 69 6e 73 65  is normally inse
37c0: 72 74 65 64 20 61 73 20 61 20 71 75 6f 74 65 64  rted as a quoted
37d0: 20 4a 53 4f 4e 20 73 74 72 69 6e 67 2c 20 65 76   JSON string, ev
37e0: 65 6e 20 69 66 20 74 68 65 20 73 74 72 69 6e 67  en if the string
37f0: 20 6c 6f 6f 6b 73 0a 6c 69 6b 65 20 76 61 6c 69   looks.like vali
3800: 64 20 4a 53 4f 4e 2e 20 20 48 6f 77 65 76 65 72  d JSON.  However
3810: 2c 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 69  , if the value i
3820: 73 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20  s the result of 
3830: 61 6e 6f 74 68 65 72 0a 6a 73 6f 6e 31 20 66 75  another.json1 fu
3840: 6e 63 74 69 6f 6e 20 28 73 75 63 68 20 61 73 20  nction (such as 
3850: 5b 6a 73 6f 6e 28 29 5d 20 6f 72 20 5b 6a 73 6f  [json()] or [jso
3860: 6e 5f 61 72 72 61 79 28 29 5d 20 6f 72 20 5b 6a  n_array()] or [j
3870: 73 6f 6e 5f 6f 62 6a 65 63 74 28 29 5d 29 0a 74  son_object()]).t
3880: 68 65 6e 20 69 74 20 69 73 20 69 6e 74 65 72 70  hen it is interp
3890: 72 65 74 65 64 20 61 73 20 4a 53 4f 4e 20 61 6e  reted as JSON an
38a0: 64 20 69 73 20 69 6e 73 65 72 74 65 64 20 61 73  d is inserted as
38b0: 20 4a 53 4f 4e 20 72 65 74 61 69 6e 69 6e 67 20   JSON retaining 
38c0: 61 6c 6c 0a 6f 66 20 69 74 73 20 73 75 62 73 74  all.of its subst
38d0: 72 75 63 74 75 72 65 2e 0a 0a 3c 70 3e 54 68 65  ructure...<p>The
38e0: 73 65 20 72 6f 75 74 69 6e 65 73 20 74 68 72 6f  se routines thro
38f0: 77 20 61 6e 20 65 72 72 6f 72 20 69 66 20 74 68  w an error if th
3900: 65 20 66 69 72 73 74 20 4a 53 4f 4e 20 61 72 67  e first JSON arg
3910: 75 6d 65 6e 74 20 69 73 20 6e 6f 74 0a 77 65 6c  ument is not.wel
3920: 6c 2d 66 6f 72 6d 65 64 20 6f 72 20 69 66 20 61  l-formed or if a
3930: 6e 79 20 50 41 54 48 20 61 72 67 75 6d 65 6e 74  ny PATH argument
3940: 20 69 73 20 6e 6f 74 20 77 65 6c 6c 2d 66 6f 72   is not well-for
3950: 6d 65 64 20 6f 72 20 69 66 20 61 6e 79 0a 61 72  med or if any.ar
3960: 67 75 6d 65 6e 74 20 69 73 20 61 20 42 4c 4f 42  gument is a BLOB
3970: 2e 0a 0a 3c 70 3e 45 78 61 6d 70 6c 65 73 3a 0a  ...<p>Examples:.
3980: 0a 3c 74 63 6c 3e 0a 6a 65 78 61 6d 70 6c 65 20  .<tcl>.jexample 
3990: 5c 0a 20 20 7b 6a 73 6f 6e 5f 69 6e 73 65 72 74  \.  {json_insert
39a0: 28 27 7b 22 61 22 3a 32 2c 22 63 22 3a 34 7d 27  ('{"a":2,"c":4}'
39b0: 2c 20 27 24 2e 61 27 2c 20 39 39 29 7d 20 7b 27  , '$.a', 99)} {'
39c0: 7b 22 61 22 3a 32 2c 22 63 22 3a 34 7d 27 7d 20  {"a":2,"c":4}'} 
39d0: 5c 0a 20 20 7b 6a 73 6f 6e 5f 69 6e 73 65 72 74  \.  {json_insert
39e0: 28 27 7b 22 61 22 3a 32 2c 22 63 22 3a 34 7d 27  ('{"a":2,"c":4}'
39f0: 2c 20 27 24 2e 65 27 2c 20 39 39 29 7d 20 7b 27  , '$.e', 99)} {'
3a00: 7b 22 61 22 3a 32 2c 22 63 22 3a 34 2c 22 65 22  {"a":2,"c":4,"e"
3a10: 3a 39 39 7d 27 7d 20 5c 0a 20 20 7b 6a 73 6f 6e  :99}'} \.  {json
3a20: 5f 72 65 70 6c 61 63 65 28 27 7b 22 61 22 3a 32  _replace('{"a":2
3a30: 2c 22 63 22 3a 34 7d 27 2c 20 27 24 2e 61 27 2c  ,"c":4}', '$.a',
3a40: 20 39 39 29 7d 20 7b 27 7b 22 61 22 3a 39 39 2c   99)} {'{"a":99,
3a50: 22 63 22 3a 34 7d 27 7d 20 5c 0a 20 20 7b 6a 73  "c":4}'} \.  {js
3a60: 6f 6e 5f 72 65 70 6c 61 63 65 28 27 7b 22 61 22  on_replace('{"a"
3a70: 3a 32 2c 22 63 22 3a 34 7d 27 2c 20 27 24 2e 65  :2,"c":4}', '$.e
3a80: 27 2c 20 39 39 29 7d 20 7b 27 7b 22 61 22 3a 32  ', 99)} {'{"a":2
3a90: 2c 22 63 22 3a 34 7d 27 7d 20 5c 0a 20 20 7b 6a  ,"c":4}'} \.  {j
3aa0: 73 6f 6e 5f 73 65 74 28 27 7b 22 61 22 3a 32 2c  son_set('{"a":2,
3ab0: 22 63 22 3a 34 7d 27 2c 20 27 24 2e 61 27 2c 20  "c":4}', '$.a', 
3ac0: 39 39 29 7d 20 7b 27 7b 22 61 22 3a 39 39 2c 22  99)} {'{"a":99,"
3ad0: 63 22 3a 34 7d 27 7d 20 5c 0a 20 20 7b 6a 73 6f  c":4}'} \.  {jso
3ae0: 6e 5f 73 65 74 28 27 7b 22 61 22 3a 32 2c 22 63  n_set('{"a":2,"c
3af0: 22 3a 34 7d 27 2c 20 27 24 2e 65 27 2c 20 39 39  ":4}', '$.e', 99
3b00: 29 7d 20 7b 27 7b 22 61 22 3a 32 2c 22 63 22 3a  )} {'{"a":2,"c":
3b10: 34 2c 22 65 22 3a 39 39 7d 27 7d 20 5c 0a 20 20  4,"e":99}'} \.  
3b20: 7b 6a 73 6f 6e 5f 73 65 74 28 27 7b 22 61 22 3a  {json_set('{"a":
3b30: 32 2c 22 63 22 3a 34 7d 27 2c 20 27 24 2e 63 27  2,"c":4}', '$.c'
3b40: 2c 20 27 5b 39 37 2c 39 36 5d 27 29 7d 20 5c 0a  , '[97,96]')} \.
3b50: 20 20 20 20 20 20 20 20 20 20 20 20 7b 27 7b 22              {'{"
3b60: 61 22 3a 32 2c 22 63 22 3a 22 5b 39 37 2c 39 36  a":2,"c":"[97,96
3b70: 5d 22 7d 27 7d 20 5c 0a 20 20 7b 6a 73 6f 6e 5f  ]"}'} \.  {json_
3b80: 73 65 74 28 27 7b 22 61 22 3a 32 2c 22 63 22 3a  set('{"a":2,"c":
3b90: 34 7d 27 2c 20 27 24 2e 63 27 2c 20 6a 73 6f 6e  4}', '$.c', json
3ba0: 28 27 5b 39 37 2c 39 36 5d 27 29 29 7d 20 5c 0a  ('[97,96]'))} \.
3bb0: 20 20 20 20 20 20 20 20 20 20 20 20 7b 27 7b 22              {'{"
3bc0: 61 22 3a 32 2c 22 63 22 3a 5b 39 37 2c 39 36 5d  a":2,"c":[97,96]
3bd0: 7d 27 7d 20 5c 0a 20 20 7b 6a 73 6f 6e 5f 73 65  }'} \.  {json_se
3be0: 74 28 27 7b 22 61 22 3a 32 2c 22 63 22 3a 34 7d  t('{"a":2,"c":4}
3bf0: 27 2c 20 27 24 2e 63 27 2c 20 6a 73 6f 6e 5f 61  ', '$.c', json_a
3c00: 72 72 61 79 28 39 37 2c 39 36 29 29 7d 20 5c 0a  rray(97,96))} \.
3c10: 20 20 20 20 20 20 20 20 20 20 20 20 7b 27 7b 22              {'{"
3c20: 61 22 3a 32 2c 22 63 22 3a 5b 39 37 2c 39 36 5d  a":2,"c":[97,96]
3c30: 7d 27 7d 0a 3c 2f 74 63 6c 3e 0a 0a 3c 74 63 6c  }'}.</tcl>..<tcl
3c40: 3e 68 64 5f 66 72 61 67 6d 65 6e 74 20 6a 6f 62  >hd_fragment job
3c50: 6a 20 7b 6a 73 6f 6e 5f 6f 62 6a 65 63 74 20 53  j {json_object S
3c60: 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 20 7b 6a 73  QL function} {js
3c70: 6f 6e 5f 6f 62 6a 65 63 74 7d 3c 2f 74 63 6c 3e  on_object}</tcl>
3c80: 0a 3c 68 33 3e 33 2e 36 20 54 68 65 20 6a 73 6f  .<h3>3.6 The jso
3c90: 6e 5f 6f 62 6a 65 63 74 28 29 20 66 75 6e 63 74  n_object() funct
3ca0: 69 6f 6e 3c 2f 68 33 3e 0a 0a 3c 70 3e 54 68 65  ion</h3>..<p>The
3cb0: 20 6a 73 6f 6e 5f 6f 62 6a 65 63 74 28 29 20 53   json_object() S
3cc0: 51 4c 20 66 75 6e 63 74 69 6f 6e 20 61 63 63 65  QL function acce
3cd0: 70 74 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65  pts zero or more
3ce0: 20 70 61 69 72 73 20 6f 66 20 61 72 67 75 6d 65   pairs of argume
3cf0: 6e 74 73 0a 61 6e 64 20 72 65 74 75 72 6e 73 20  nts.and returns 
3d00: 61 20 77 65 6c 6c 2d 66 6f 72 6d 65 64 20 4a 53  a well-formed JS
3d10: 4f 4e 20 6f 62 6a 65 63 74 20 74 68 61 74 20 69  ON object that i
3d20: 73 20 63 6f 6d 70 6f 73 65 64 20 66 72 6f 6d 20  s composed from 
3d30: 74 68 6f 73 65 20 61 72 67 75 6d 65 6e 74 73 2e  those arguments.
3d40: 0a 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d  .The first argum
3d50: 65 6e 74 20 6f 66 20 65 61 63 68 20 70 61 69 72  ent of each pair
3d60: 20 69 73 20 74 68 65 20 6c 61 62 65 6c 20 61 6e   is the label an
3d70: 64 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  d the second arg
3d80: 75 6d 65 6e 74 20 6f 66 0a 65 61 63 68 20 70 61  ument of.each pa
3d90: 69 72 20 69 73 20 74 68 65 20 76 61 6c 75 65 2e  ir is the value.
3da0: 0a 49 66 20 61 6e 79 20 61 72 67 75 6d 65 6e 74  .If any argument
3db0: 20 74 6f 20 6a 73 6f 6e 5f 6f 62 6a 65 63 74 28   to json_object(
3dc0: 29 20 69 73 20 61 20 42 4c 4f 42 20 74 68 65 6e  ) is a BLOB then
3dd0: 20 61 6e 20 65 72 72 6f 72 20 69 73 20 74 68 72   an error is thr
3de0: 6f 77 6e 2e 0a 0a 3c 70 3e 54 68 65 20 6a 73 6f  own...<p>The jso
3df0: 6e 5f 6f 62 6a 65 63 74 28 29 20 66 75 6e 63 74  n_object() funct
3e00: 69 6f 6e 20 63 75 72 72 65 6e 74 6c 79 20 61 6c  ion currently al
3e10: 6c 6f 77 73 20 64 75 70 6c 69 63 61 74 65 20 6c  lows duplicate l
3e20: 61 62 65 6c 73 20 77 69 74 68 6f 75 74 0a 63 6f  abels without.co
3e30: 6d 70 6c 61 69 6e 74 2c 20 74 68 6f 75 67 68 20  mplaint, though 
3e40: 74 68 69 73 20 6d 69 67 68 74 20 63 68 61 6e 67  this might chang
3e50: 65 20 69 6e 20 61 20 66 75 74 75 72 65 20 65 6e  e in a future en
3e60: 68 61 6e 63 65 6d 65 6e 74 2e 0a 0a 3c 70 3e 41  hancement...<p>A
3e70: 6e 20 61 72 67 75 6d 65 6e 74 20 77 69 74 68 20  n argument with 
3e80: 53 51 4c 20 74 79 70 65 20 54 45 58 54 20 69 74  SQL type TEXT it
3e90: 20 69 73 20 6e 6f 72 6d 61 6c 6c 79 20 63 6f 6e   is normally con
3ea0: 76 65 72 74 65 64 20 69 6e 74 6f 20 61 20 71 75  verted into a qu
3eb0: 6f 74 65 64 20 0a 4a 53 4f 4e 20 73 74 72 69 6e  oted .JSON strin
3ec0: 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 69 6e  g even if the in
3ed0: 70 75 74 20 74 65 78 74 20 69 73 20 77 65 6c 6c  put text is well
3ee0: 2d 66 6f 72 6d 65 64 20 4a 53 4f 4e 2e 20 20 0a  -formed JSON.  .
3ef0: 48 6f 77 65 76 65 72 2c 20 69 66 20 74 68 65 20  However, if the 
3f00: 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
3f10: 64 69 72 65 63 74 20 72 65 73 75 6c 74 20 66 72  direct result fr
3f20: 6f 6d 20 61 6e 6f 74 68 65 72 20 6a 73 6f 6e 31  om another json1
3f30: 0a 66 75 6e 63 74 69 6f 6e 2c 20 74 68 65 6e 20  .function, then 
3f40: 69 74 20 69 73 20 74 72 65 61 74 65 64 20 61 73  it is treated as
3f50: 20 4a 53 4f 4e 20 61 6e 64 20 61 6c 6c 20 6f 66   JSON and all of
3f60: 20 69 74 73 20 4a 53 4f 4e 20 74 79 70 65 20 69   its JSON type i
3f70: 6e 66 6f 72 6d 61 74 69 6f 6e 0a 61 6e 64 20 73  nformation.and s
3f80: 75 62 73 74 72 75 63 74 75 72 65 20 69 73 20 70  ubstructure is p
3f90: 72 65 73 65 72 76 65 64 2e 20 20 54 68 69 73 20  reserved.  This 
3fa0: 61 6c 6c 6f 77 73 20 63 61 6c 6c 73 20 74 6f 20  allows calls to 
3fb0: 6a 73 6f 6e 5f 6f 62 6a 65 63 74 28 29 0a 61 6e  json_object().an
3fc0: 64 20 5b 6a 73 6f 6e 5f 61 72 72 61 79 28 29 5d  d [json_array()]
3fd0: 20 74 6f 20 62 65 20 6e 65 73 74 65 64 2e 20 20   to be nested.  
3fe0: 54 68 65 20 5b 6a 73 6f 6e 28 29 5d 20 66 75 6e  The [json()] fun
3ff0: 63 74 69 6f 6e 20 63 61 6e 20 61 6c 73 6f 0a 62  ction can also.b
4000: 65 20 75 73 65 64 20 74 6f 20 66 6f 72 63 65 20  e used to force 
4010: 73 74 72 69 6e 67 73 20 74 6f 20 62 65 20 72 65  strings to be re
4020: 63 6f 67 6e 69 7a 65 64 20 61 73 20 4a 53 4f 4e  cognized as JSON
4030: 2e 0a 0a 3c 70 3e 45 78 61 6d 70 6c 65 73 3a 0a  ...<p>Examples:.
4040: 0a 3c 74 63 6c 3e 0a 6a 65 78 61 6d 70 6c 65 20  .<tcl>.jexample 
4050: 5c 0a 20 20 7b 6a 73 6f 6e 5f 6f 62 6a 65 63 74  \.  {json_object
4060: 28 27 61 27 2c 32 2c 27 63 27 2c 34 29 7d 20 7b  ('a',2,'c',4)} {
4070: 27 7b 22 61 22 3a 32 2c 22 63 22 3a 34 7d 27 7d  '{"a":2,"c":4}'}
4080: 20 5c 0a 20 20 7b 6a 73 6f 6e 5f 6f 62 6a 65 63   \.  {json_objec
4090: 74 28 27 61 27 2c 32 2c 27 63 27 2c 27 7b 65 3a  t('a',2,'c','{e:
40a0: 35 7d 27 29 7d 20 7b 27 7b 22 61 22 3a 32 2c 22  5}')} {'{"a":2,"
40b0: 63 22 3a 22 7b 65 3a 35 7d 22 7d 27 7d 20 5c 0a  c":"{e:5}"}'} \.
40c0: 20 20 7b 6a 73 6f 6e 5f 6f 62 6a 65 63 74 28 27    {json_object('
40d0: 61 27 2c 32 2c 27 63 27 2c 6a 73 6f 6e 5f 6f 62  a',2,'c',json_ob
40e0: 6a 65 63 74 28 27 65 27 2c 35 29 29 7d 20 7b 27  ject('e',5))} {'
40f0: 7b 22 61 22 3a 32 2c 22 63 22 3a 7b 22 65 22 3a  {"a":2,"c":{"e":
4100: 35 7d 7d 27 7d 0a 3c 2f 74 63 6c 3e 0a 0a 0a 3c  5}}'}.</tcl>...<
4110: 74 63 6c 3e 68 64 5f 66 72 61 67 6d 65 6e 74 20  tcl>hd_fragment 
4120: 6a 72 6d 20 7b 6a 73 6f 6e 5f 72 65 6d 6f 76 65  jrm {json_remove
4130: 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 20 7b   SQL function} {
4140: 6a 73 6f 6e 5f 72 65 6d 6f 76 65 7d 3c 2f 74 63  json_remove}</tc
4150: 6c 3e 0a 3c 68 33 3e 33 2e 37 20 54 68 65 20 6a  l>.<h3>3.7 The j
4160: 73 6f 6e 5f 72 65 6d 6f 76 65 28 29 20 66 75 6e  son_remove() fun
4170: 63 74 69 6f 6e 3c 2f 68 33 3e 0a 0a 3c 70 3e 54  ction</h3>..<p>T
4180: 68 65 20 6a 73 6f 6e 5f 72 65 6d 6f 76 65 28 58  he json_remove(X
4190: 2c 50 2c 2e 2e 2e 29 20 66 75 6e 63 74 69 6f 6e  ,P,...) function
41a0: 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
41b0: 4a 53 4f 4e 20 76 61 6c 75 65 20 61 73 20 69 74  JSON value as it
41c0: 73 0a 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  s.first argument
41d0: 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 7a 65 72   followed by zer
41e0: 6f 20 6f 72 20 6d 6f 72 65 20 70 61 74 68 20 61  o or more path a
41f0: 72 67 75 6d 65 6e 74 73 2e 0a 54 68 65 20 6a 73  rguments..The js
4200: 6f 6e 5f 72 65 6d 6f 76 65 28 58 2c 50 2c 2e 2e  on_remove(X,P,..
4210: 2e 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  .) function retu
4220: 72 6e 73 0a 61 20 6e 65 77 20 4a 53 4f 4e 20 76  rns.a new JSON v
4230: 61 6c 75 65 20 74 68 61 74 20 69 73 20 74 68 65  alue that is the
4240: 20 58 20 77 69 74 68 20 61 6c 6c 20 74 68 65 20   X with all the 
4250: 65 6c 65 6d 65 6e 74 73 20 0a 69 64 65 6e 74 69  elements .identi
4260: 66 69 65 64 20 62 79 20 70 61 74 68 20 61 72 67  fied by path arg
4270: 75 6d 65 6e 74 73 20 72 65 6d 6f 76 65 64 2e 20  uments removed. 
4280: 20 50 61 74 68 73 20 74 68 61 74 20 73 65 6c 65   Paths that sele
4290: 63 74 20 65 6c 65 6d 65 6e 74 73 0a 6e 6f 74 20  ct elements.not 
42a0: 66 6f 75 6e 64 20 69 6e 20 58 20 61 72 65 20 73  found in X are s
42b0: 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65 64 2e  ilently ignored.
42c0: 0a 0a 3c 70 3e 52 65 6d 6f 76 61 6c 73 20 6f 63  ..<p>Removals oc
42d0: 63 75 72 73 20 73 65 71 75 65 6e 74 69 61 6c 6c  curs sequentiall
42e0: 79 20 66 72 6f 6d 20 6c 65 66 74 20 74 6f 20 72  y from left to r
42f0: 69 67 68 74 2e 20 20 43 68 61 6e 67 65 73 20 63  ight.  Changes c
4300: 61 75 73 65 64 20 62 79 0a 70 72 69 6f 72 20 72  aused by.prior r
4310: 65 6d 6f 76 61 6c 73 20 63 61 6e 20 61 66 66 65  emovals can affe
4320: 63 74 20 74 68 65 20 70 61 74 68 20 73 65 61 72  ct the path sear
4330: 63 68 20 66 6f 72 20 73 75 62 73 65 71 75 65 6e  ch for subsequen
4340: 74 20 61 72 67 75 6d 65 6e 74 73 2e 0a 0a 3c 70  t arguments...<p
4350: 3e 49 66 20 74 68 65 20 6a 73 6f 6e 5f 72 65 6d  >If the json_rem
4360: 6f 76 65 28 58 29 20 66 75 6e 63 74 69 6f 6e 20  ove(X) function 
4370: 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 6e  is called with n
4380: 6f 20 70 61 74 68 20 61 72 67 75 6d 65 6e 74 73  o path arguments
4390: 2c 0a 74 68 65 6e 20 69 74 20 72 65 74 75 72 6e  ,.then it return
43a0: 73 20 74 68 65 20 69 6e 70 75 74 20 58 20 72 65  s the input X re
43b0: 66 6f 72 6d 61 74 74 65 64 2c 20 77 69 74 68 20  formatted, with 
43c0: 65 78 63 65 73 73 20 77 68 69 74 65 73 70 61 63  excess whitespac
43d0: 65 0a 72 65 6d 6f 76 65 64 2e 0a 0a 3c 70 3e 54  e.removed...<p>T
43e0: 68 65 20 6a 73 6f 6e 5f 72 65 6d 6f 76 65 28 29  he json_remove()
43f0: 20 66 75 6e 63 74 69 6f 6e 20 74 68 72 6f 77 73   function throws
4400: 20 61 6e 20 65 72 72 6f 72 20 69 66 20 74 68 65   an error if the
4410: 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 0a   first argument.
4420: 69 73 20 6e 6f 74 20 77 65 6c 6c 2d 66 6f 72 6d  is not well-form
4430: 65 64 20 4a 53 4f 4e 20 6f 72 20 69 66 20 61 6e  ed JSON or if an
4440: 79 20 6c 61 74 65 72 20 61 72 67 75 6d 65 6e 74  y later argument
4450: 20 69 73 20 6e 6f 74 20 61 20 77 65 6c 6c 2d 66   is not a well-f
4460: 6f 72 6d 65 64 0a 70 61 74 68 2c 20 6f 72 20 69  ormed.path, or i
4470: 66 20 61 6e 79 20 61 72 67 75 6d 65 6e 74 20 69  f any argument i
4480: 73 20 61 20 42 4c 4f 42 2e 0a 0a 3c 70 3e 45 78  s a BLOB...<p>Ex
4490: 61 6d 70 6c 65 73 3a 0a 0a 3c 74 63 6c 3e 0a 6a  amples:..<tcl>.j
44a0: 65 78 61 6d 70 6c 65 20 5c 0a 20 20 7b 6a 73 6f  example \.  {jso
44b0: 6e 5f 72 65 6d 6f 76 65 28 27 5b 30 2c 31 2c 32  n_remove('[0,1,2
44c0: 2c 33 2c 34 5d 27 2c 27 24 5b 32 5d 27 29 7d 20  ,3,4]','$[2]')} 
44d0: 7b 27 5b 30 2c 31 2c 33 2c 34 5d 27 7d 20 5c 0a  {'[0,1,3,4]'} \.
44e0: 20 20 7b 6a 73 6f 6e 5f 72 65 6d 6f 76 65 28 27    {json_remove('
44f0: 5b 30 2c 31 2c 32 2c 33 2c 34 5d 27 2c 27 24 5b  [0,1,2,3,4]','$[
4500: 32 5d 27 2c 27 24 5b 30 5d 27 29 7d 20 7b 27 5b  2]','$[0]')} {'[
4510: 31 2c 33 2c 34 5d 27 7d 20 5c 0a 20 20 7b 6a 73  1,3,4]'} \.  {js
4520: 6f 6e 5f 72 65 6d 6f 76 65 28 27 5b 30 2c 31 2c  on_remove('[0,1,
4530: 32 2c 33 2c 34 5d 27 2c 27 24 5b 30 5d 27 2c 27  2,3,4]','$[0]','
4540: 24 5b 32 5d 27 29 7d 20 7b 27 5b 31 2c 32 2c 34  $[2]')} {'[1,2,4
4550: 5d 27 7d 20 5c 0a 20 20 7b 6a 73 6f 6e 5f 72 65  ]'} \.  {json_re
4560: 6d 6f 76 65 28 27 7b 22 78 22 3a 32 35 2c 22 79  move('{"x":25,"y
4570: 22 3a 34 32 7d 27 29 7d 20 7b 27 7b 22 78 22 3a  ":42}')} {'{"x":
4580: 32 35 2c 22 79 22 3a 34 32 7d 27 7d 20 5c 0a 20  25,"y":42}'} \. 
4590: 20 7b 6a 73 6f 6e 5f 72 65 6d 6f 76 65 28 27 7b   {json_remove('{
45a0: 22 78 22 3a 32 35 2c 22 79 22 3a 34 32 7d 27 2c  "x":25,"y":42}',
45b0: 27 24 2e 7a 27 29 7d 20 7b 27 7b 22 78 22 3a 32  '$.z')} {'{"x":2
45c0: 35 2c 22 79 22 3a 34 32 7d 27 7d 20 5c 0a 20 20  5,"y":42}'} \.  
45d0: 7b 6a 73 6f 6e 5f 72 65 6d 6f 76 65 28 27 7b 22  {json_remove('{"
45e0: 78 22 3a 32 35 2c 22 79 22 3a 34 32 7d 27 2c 27  x":25,"y":42}','
45f0: 24 2e 79 27 29 7d 20 7b 27 7b 22 78 22 3a 32 35  $.y')} {'{"x":25
4600: 7d 27 7d 20 5c 0a 20 20 7b 6a 73 6f 6e 5f 72 65  }'} \.  {json_re
4610: 6d 6f 76 65 28 27 7b 22 78 22 3a 32 35 2c 22 79  move('{"x":25,"y
4620: 22 3a 34 32 7d 27 2c 27 24 27 29 7d 20 4e 55 4c  ":42}','$')} NUL
4630: 4c 0a 3c 2f 74 63 6c 3e 0a 0a 3c 74 63 6c 3e 68  L.</tcl>..<tcl>h
4640: 64 5f 66 72 61 67 6d 65 6e 74 20 6a 74 79 70 65  d_fragment jtype
4650: 20 7b 6a 73 6f 6e 5f 74 79 70 65 20 53 51 4c 20   {json_type SQL 
4660: 66 75 6e 63 74 69 6f 6e 7d 20 7b 6a 73 6f 6e 5f  function} {json_
4670: 74 79 70 65 7d 3c 2f 74 63 6c 3e 0a 3c 68 33 3e  type}</tcl>.<h3>
4680: 33 2e 37 20 54 68 65 20 6a 73 6f 6e 5f 74 79 70  3.7 The json_typ
4690: 65 28 29 20 66 75 6e 63 74 69 6f 6e 3c 2f 68 33  e() function</h3
46a0: 3e 0a 0a 3c 70 3e 54 68 65 20 6a 73 6f 6e 5f 74  >..<p>The json_t
46b0: 79 70 65 28 58 29 20 66 75 6e 63 74 69 6f 6e 20  ype(X) function 
46c0: 72 65 74 75 72 6e 73 20 74 68 65 20 22 74 79 70  returns the "typ
46d0: 65 22 20 6f 66 20 74 68 65 20 6f 75 74 65 72 6d  e" of the outerm
46e0: 6f 73 74 20 65 6c 65 6d 65 6e 74 0a 6f 66 20 58  ost element.of X
46f0: 2e 20 20 54 68 65 20 6a 73 6f 6e 5f 74 79 70 65  .  The json_type
4700: 28 58 2c 50 29 20 66 75 6e 63 74 69 6f 6e 20 72  (X,P) function r
4710: 65 74 75 72 6e 73 20 74 68 65 20 22 74 79 70 65  eturns the "type
4720: 22 20 6f 66 20 74 68 65 20 65 6c 65 6d 65 6e 74  " of the element
4730: 0a 69 6e 20 58 20 74 68 61 74 20 69 73 20 73 65  .in X that is se
4740: 6c 65 63 74 65 64 20 62 79 20 70 61 74 68 20 50  lected by path P
4750: 2e 20 20 54 68 65 20 22 74 79 70 65 22 20 72 65  .  The "type" re
4760: 74 75 72 6e 65 64 20 62 79 20 6a 73 6f 6e 5f 74  turned by json_t
4770: 79 70 65 28 29 20 69 73 0a 6f 6e 20 6f 66 20 74  ype() is.on of t
4780: 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 20  he following an 
4790: 53 51 4c 20 74 65 78 74 20 76 61 6c 75 65 73 3a  SQL text values:
47a0: 0a 27 6e 75 6c 6c 27 2c 20 27 74 72 75 65 27 2c  .'null', 'true',
47b0: 20 27 66 61 6c 73 65 27 2c 20 27 69 6e 74 65 67   'false', 'integ
47c0: 65 72 27 2c 20 27 72 65 61 6c 27 2c 20 27 74 65  er', 'real', 'te
47d0: 78 74 27 2c 20 27 61 72 72 61 79 27 2c 20 6f 72  xt', 'array', or
47e0: 20 27 6f 62 6a 65 63 74 27 2e 0a 49 66 20 74 68   'object'..If th
47f0: 65 20 70 61 74 68 20 50 20 69 6e 20 6a 73 6f 6e  e path P in json
4800: 5f 74 79 70 65 28 58 2c 50 29 20 73 65 6c 65 63  _type(X,P) selec
4810: 74 73 20 61 20 65 6c 65 6d 65 6e 74 20 74 68 61  ts a element tha
4820: 74 20 64 6f 65 73 20 6e 6f 74 20 65 78 69 73 74  t does not exist
4830: 0a 69 6e 20 58 2c 20 74 68 65 6e 20 74 68 69 73  .in X, then this
4840: 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
4850: 73 20 4e 55 4c 4c 2e 0a 0a 3c 70 3e 54 68 65 20  s NULL...<p>The 
4860: 6a 73 6f 6e 5f 74 79 70 65 28 29 20 66 75 6e 63  json_type() func
4870: 74 69 6f 6e 20 74 68 72 6f 77 73 20 61 6e 20 65  tion throws an e
4880: 72 72 6f 72 20 69 66 20 61 6e 79 20 6f 66 20 69  rror if any of i
4890: 74 73 20 61 72 67 75 6d 65 6e 74 73 20 61 72 65  ts arguments are
48a0: 0a 6e 6f 74 20 77 65 6c 6c 2d 66 6f 72 6d 65 64  .not well-formed
48b0: 20 6f 72 20 69 73 20 61 20 42 4c 4f 42 2e 0a 0a   or is a BLOB...
48c0: 3c 70 3e 45 78 61 6d 70 6c 65 73 3a 0a 0a 3c 74  <p>Examples:..<t
48d0: 63 6c 3e 0a 6a 65 78 61 6d 70 6c 65 20 5c 0a 20  cl>.jexample \. 
48e0: 20 7b 6a 73 6f 6e 5f 74 79 70 65 28 27 7b 22 61   {json_type('{"a
48f0: 22 3a 5b 32 2c 33 2e 35 2c 74 72 75 65 2c 66 61  ":[2,3.5,true,fa
4900: 6c 73 65 2c 6e 75 6c 6c 2c 22 78 22 5d 7d 27 29  lse,null,"x"]}')
4910: 7d 20 27 6f 62 6a 65 63 74 27 20 5c 0a 20 20 7b  } 'object' \.  {
4920: 6a 73 6f 6e 5f 74 79 70 65 28 27 7b 22 61 22 3a  json_type('{"a":
4930: 5b 32 2c 33 2e 35 2c 74 72 75 65 2c 66 61 6c 73  [2,3.5,true,fals
4940: 65 2c 6e 75 6c 6c 2c 22 78 22 5d 7d 27 2c 27 24  e,null,"x"]}','$
4950: 27 29 7d 20 27 6f 62 6a 65 63 74 27 20 5c 0a 20  ')} 'object' \. 
4960: 20 7b 6a 73 6f 6e 5f 74 79 70 65 28 27 7b 22 61   {json_type('{"a
4970: 22 3a 5b 32 2c 33 2e 35 2c 74 72 75 65 2c 66 61  ":[2,3.5,true,fa
4980: 6c 73 65 2c 6e 75 6c 6c 2c 22 78 22 5d 7d 27 2c  lse,null,"x"]}',
4990: 27 24 2e 61 27 29 7d 20 27 61 72 72 61 79 27 20  '$.a')} 'array' 
49a0: 5c 0a 20 20 7b 6a 73 6f 6e 5f 74 79 70 65 28 27  \.  {json_type('
49b0: 7b 22 61 22 3a 5b 32 2c 33 2e 35 2c 74 72 75 65  {"a":[2,3.5,true
49c0: 2c 66 61 6c 73 65 2c 6e 75 6c 6c 2c 22 78 22 5d  ,false,null,"x"]
49d0: 7d 27 2c 27 24 2e 61 5b 30 5d 27 29 7d 20 27 69  }','$.a[0]')} 'i
49e0: 6e 74 65 67 65 72 27 20 5c 0a 20 20 7b 6a 73 6f  nteger' \.  {jso
49f0: 6e 5f 74 79 70 65 28 27 7b 22 61 22 3a 5b 32 2c  n_type('{"a":[2,
4a00: 33 2e 35 2c 74 72 75 65 2c 66 61 6c 73 65 2c 6e  3.5,true,false,n
4a10: 75 6c 6c 2c 22 78 22 5d 7d 27 2c 27 24 2e 61 5b  ull,"x"]}','$.a[
4a20: 31 5d 27 29 7d 20 27 72 65 61 6c 27 20 5c 0a 20  1]')} 'real' \. 
4a30: 20 7b 6a 73 6f 6e 5f 74 79 70 65 28 27 7b 22 61   {json_type('{"a
4a40: 22 3a 5b 32 2c 33 2e 35 2c 74 72 75 65 2c 66 61  ":[2,3.5,true,fa
4a50: 6c 73 65 2c 6e 75 6c 6c 2c 22 78 22 5d 7d 27 2c  lse,null,"x"]}',
4a60: 27 24 2e 61 5b 32 5d 27 29 7d 20 27 74 72 75 65  '$.a[2]')} 'true
4a70: 27 20 5c 0a 20 20 7b 6a 73 6f 6e 5f 74 79 70 65  ' \.  {json_type
4a80: 28 27 7b 22 61 22 3a 5b 32 2c 33 2e 35 2c 74 72  ('{"a":[2,3.5,tr
4a90: 75 65 2c 66 61 6c 73 65 2c 6e 75 6c 6c 2c 22 78  ue,false,null,"x
4aa0: 22 5d 7d 27 2c 27 24 2e 61 5b 33 5d 27 29 7d 20  "]}','$.a[3]')} 
4ab0: 27 66 61 6c 73 65 27 20 5c 0a 20 20 7b 6a 73 6f  'false' \.  {jso
4ac0: 6e 5f 74 79 70 65 28 27 7b 22 61 22 3a 5b 32 2c  n_type('{"a":[2,
4ad0: 33 2e 35 2c 74 72 75 65 2c 66 61 6c 73 65 2c 6e  3.5,true,false,n
4ae0: 75 6c 6c 2c 22 78 22 5d 7d 27 2c 27 24 2e 61 5b  ull,"x"]}','$.a[
4af0: 34 5d 27 29 7d 20 27 6e 75 6c 6c 27 20 5c 0a 20  4]')} 'null' \. 
4b00: 20 7b 6a 73 6f 6e 5f 74 79 70 65 28 27 7b 22 61   {json_type('{"a
4b10: 22 3a 5b 32 2c 33 2e 35 2c 74 72 75 65 2c 66 61  ":[2,3.5,true,fa
4b20: 6c 73 65 2c 6e 75 6c 6c 2c 22 78 22 5d 7d 27 2c  lse,null,"x"]}',
4b30: 27 24 2e 61 5b 35 5d 27 29 7d 20 27 74 65 78 74  '$.a[5]')} 'text
4b40: 27 20 5c 0a 20 20 7b 6a 73 6f 6e 5f 74 79 70 65  ' \.  {json_type
4b50: 28 27 7b 22 61 22 3a 5b 32 2c 33 2e 35 2c 74 72  ('{"a":[2,3.5,tr
4b60: 75 65 2c 66 61 6c 73 65 2c 6e 75 6c 6c 2c 22 78  ue,false,null,"x
4b70: 22 5d 7d 27 2c 27 24 2e 61 5b 36 5d 27 29 7d 20  "]}','$.a[6]')} 
4b80: 4e 55 4c 4c 0a 3c 2f 74 63 6c 3e 0a 0a 3c 74 63  NULL.</tcl>..<tc
4b90: 6c 3e 68 64 5f 66 72 61 67 6d 65 6e 74 20 6a 76  l>hd_fragment jv
4ba0: 61 6c 69 64 20 7b 6a 73 6f 6e 5f 76 61 6c 69 64  alid {json_valid
4bb0: 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 20 7b   SQL function} {
4bc0: 6a 73 6f 6e 5f 76 61 6c 69 64 7d 3c 2f 74 63 6c  json_valid}</tcl
4bd0: 3e 0a 3c 68 33 3e 33 2e 39 20 54 68 65 20 6a 73  >.<h3>3.9 The js
4be0: 6f 6e 5f 76 61 6c 69 64 28 29 20 66 75 6e 63 74  on_valid() funct
4bf0: 69 6f 6e 3c 2f 68 33 3e 0a 0a 3c 70 3e 54 68 65  ion</h3>..<p>The
4c00: 20 6a 73 6f 6e 5f 76 61 6c 69 64 28 58 29 20 66   json_valid(X) f
4c10: 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 20 31  unction return 1
4c20: 20 69 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74   if the argument
4c30: 20 58 20 69 73 20 77 65 6c 6c 2d 66 6f 72 6d 65   X is well-forme
4c40: 64 0a 4a 53 4f 4e 20 61 6e 64 20 72 65 74 75 72  d.JSON and retur
4c50: 6e 20 30 20 69 66 20 74 68 65 20 61 72 67 75 6d  n 0 if the argum
4c60: 65 6e 74 20 58 20 69 73 20 6e 6f 74 20 77 65 6c  ent X is not wel
4c70: 6c 2d 66 6f 72 6d 65 64 20 4a 53 4f 4e 2e 0a 0a  l-formed JSON...
4c80: 3c 70 3e 45 78 61 6d 70 6c 65 73 3a 0a 0a 3c 74  <p>Examples:..<t
4c90: 63 6c 3e 0a 6a 65 78 61 6d 70 6c 65 20 5c 0a 20  cl>.jexample \. 
4ca0: 20 7b 6a 73 6f 6e 5f 76 61 6c 69 64 28 27 7b 22   {json_valid('{"
4cb0: 78 22 3a 33 35 7d 27 29 7d 20 31 20 5c 0a 20 20  x":35}')} 1 \.  
4cc0: 22 6a 73 6f 6e 5f 76 61 6c 69 64 28 27 5c 31 37  "json_valid('\17
4cd0: 33 5c 22 78 5c 22 3a 33 35 27 29 22 20 30 0a 3c  3\"x\":35')" 0.<
4ce0: 2f 74 63 6c 3e 0a 0a 3c 74 63 6c 3e 0a 68 64 5f  /tcl>..<tcl>.hd_
4cf0: 66 72 61 67 6d 65 6e 74 20 6a 67 72 6f 75 70 61  fragment jgroupa
4d00: 72 72 61 79 20 7b 6a 73 6f 6e 5f 67 72 6f 75 70  rray {json_group
4d10: 5f 61 72 72 61 79 20 53 51 4c 20 66 75 6e 63 74  _array SQL funct
4d20: 69 6f 6e 7d 20 5c 0a 20 20 20 7b 6a 73 6f 6e 5f  ion} \.   {json_
4d30: 67 72 6f 75 70 5f 61 72 72 61 79 7d 0a 68 64 5f  group_array}.hd_
4d40: 66 72 61 67 6d 65 6e 74 20 6a 67 72 6f 75 70 6f  fragment jgroupo
4d50: 62 6a 65 63 74 20 7b 6a 73 6f 6e 5f 67 72 6f 75  bject {json_grou
4d60: 70 5f 6f 62 6a 65 63 74 20 53 51 4c 20 66 75 6e  p_object SQL fun
4d70: 63 74 69 6f 6e 7d 20 5c 0a 20 20 20 7b 6a 73 6f  ction} \.   {jso
4d80: 6e 5f 67 72 6f 75 70 5f 6f 62 6a 65 63 74 7d 0a  n_group_object}.
4d90: 3c 2f 74 63 6c 3e 0a 3c 68 33 3e 33 2e 31 30 20  </tcl>.<h3>3.10 
4da0: 54 68 65 20 6a 73 6f 6e 5f 67 72 6f 75 70 5f 61  The json_group_a
4db0: 72 72 61 79 28 29 20 61 6e 64 20 6a 73 6f 6e 5f  rray() and json_
4dc0: 67 72 6f 75 70 5f 6f 62 6a 65 63 74 28 29 0a 61  group_object().a
4dd0: 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e  ggregate SQL fun
4de0: 63 74 69 6f 6e 73 3c 2f 68 33 3e 0a 0a 3c 70 3e  ctions</h3>..<p>
4df0: 54 68 65 20 6a 73 6f 6e 5f 67 72 6f 75 70 5f 61  The json_group_a
4e00: 72 72 61 79 28 58 29 20 66 75 6e 63 74 69 6f 6e  rray(X) function
4e10: 20 69 73 20 61 6e 20 0a 5b 41 67 67 72 65 67 61   is an .[Aggrega
4e20: 74 65 20 46 75 6e 63 74 69 6f 6e 73 7c 61 67 67  te Functions|agg
4e30: 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74  regate SQL funct
4e40: 69 6f 6e 5d 20 74 68 61 74 20 72 65 74 75 72 6e  ion] that return
4e50: 73 20 61 20 4a 53 4f 4e 20 61 72 72 61 79 0a 63  s a JSON array.c
4e60: 6f 6d 70 72 69 73 65 64 20 6f 66 20 61 6c 6c 20  omprised of all 
4e70: 58 20 76 61 6c 75 65 73 20 69 6e 20 74 68 65 20  X values in the 
4e80: 61 67 67 72 65 67 61 74 69 6f 6e 2e 0a 53 69 6d  aggregation..Sim
4e90: 69 6c 61 72 6c 79 2c 20 74 68 65 20 6a 73 6f 6e  ilarly, the json
4ea0: 5f 67 72 6f 75 70 5f 6f 62 6a 65 63 74 28 4e 41  _group_object(NA
4eb0: 4d 45 2c 56 41 4c 55 45 29 20 66 75 6e 63 74 69  ME,VALUE) functi
4ec0: 6f 6e 20 72 65 74 75 72 6e 73 20 61 20 4a 53 4f  on returns a JSO
4ed0: 4e 20 6f 62 6a 65 63 74 0a 63 6f 6d 70 72 69 73  N object.compris
4ee0: 65 64 20 6f 66 20 61 6c 6c 20 4e 41 4d 45 2f 56  ed of all NAME/V
4ef0: 41 4c 55 45 20 70 61 69 72 73 20 69 6e 20 74 68  ALUE pairs in th
4f00: 65 20 61 67 67 72 65 67 61 74 69 6f 6e 2e 0a 0a  e aggregation...
4f10: 0a 3c 74 63 6c 3e 68 64 5f 66 72 61 67 6d 65 6e  .<tcl>hd_fragmen
4f20: 74 20 6a 65 61 63 68 20 7b 6a 73 6f 6e 5f 65 61  t jeach {json_ea
4f30: 63 68 20 74 61 62 6c 65 2d 76 61 6c 75 65 64 20  ch table-valued 
4f40: 66 75 6e 63 74 69 6f 6e 7d 20 7b 6a 73 6f 6e 5f  function} {json_
4f50: 65 61 63 68 7d 3c 2f 74 63 6c 3e 0a 3c 74 63 6c  each}</tcl>.<tcl
4f60: 3e 68 64 5f 66 72 61 67 6d 65 6e 74 20 6a 74 72  >hd_fragment jtr
4f70: 65 65 20 7b 6a 73 6f 6e 5f 74 72 65 65 20 74 61  ee {json_tree ta
4f80: 62 6c 65 2d 76 61 6c 75 65 64 20 66 75 6e 63 74  ble-valued funct
4f90: 69 6f 6e 7d 20 7b 6a 73 6f 6e 5f 74 72 65 65 7d  ion} {json_tree}
4fa0: 3c 2f 74 63 6c 3e 0a 3c 68 33 3e 33 2e 31 31 20  </tcl>.<h3>3.11 
4fb0: 54 68 65 20 6a 73 6f 6e 5f 65 61 63 68 28 29 20  The json_each() 
4fc0: 61 6e 64 20 6a 73 6f 6e 5f 74 72 65 65 28 29 20  and json_tree() 
4fd0: 74 61 62 6c 65 2d 76 61 6c 75 65 64 20 66 75 6e  table-valued fun
4fe0: 63 74 69 6f 6e 73 3c 2f 68 33 3e 0a 0a 3c 70 3e  ctions</h3>..<p>
4ff0: 54 68 65 20 6a 73 6f 6e 5f 65 61 63 68 28 58 29  The json_each(X)
5000: 20 61 6e 64 20 6a 73 6f 6e 5f 74 72 65 65 28 58   and json_tree(X
5010: 29 20 5b 74 61 62 6c 65 2d 76 61 6c 75 65 64 20  ) [table-valued 
5020: 66 75 6e 63 74 69 6f 6e 73 5d 20 77 61 6c 6b 20  functions] walk 
5030: 74 68 65 0a 4a 53 4f 4e 20 76 61 6c 75 65 20 70  the.JSON value p
5040: 72 6f 76 69 64 65 64 20 61 73 20 74 68 65 69 72  rovided as their
5050: 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
5060: 61 6e 64 20 72 65 74 75 72 6e 20 6f 6e 65 20 72  and return one r
5070: 6f 77 20 66 6f 72 20 65 61 63 68 0a 65 6c 65 6d  ow for each.elem
5080: 65 6e 74 2e 20 20 54 68 65 20 6a 73 6f 6e 5f 65  ent.  The json_e
5090: 61 63 68 28 58 29 20 66 75 6e 63 74 69 6f 6e 20  ach(X) function 
50a0: 6f 6e 6c 79 20 77 61 6c 6b 73 20 74 68 65 20 69  only walks the i
50b0: 6d 6d 65 64 69 61 74 65 20 63 68 69 6c 64 72 65  mmediate childre
50c0: 6e 0a 6f 66 20 74 68 65 20 74 6f 70 2d 6c 65 76  n.of the top-lev
50d0: 65 6c 20 61 72 72 61 79 20 6f 72 20 6f 62 6a 65  el array or obje
50e0: 63 74 20 6f 72 20 0a 6f 72 20 6a 75 73 74 20 74  ct or .or just t
50f0: 68 65 20 74 6f 70 2d 6c 65 76 65 6c 20 65 6c 65  he top-level ele
5100: 6d 65 6e 74 20 69 74 73 65 6c 66 20 69 66 20 74  ment itself if t
5110: 68 65 20 74 6f 70 2d 6c 65 76 65 6c 0a 65 6c 65  he top-level.ele
5120: 6d 65 6e 74 20 69 73 20 61 20 70 72 69 6d 69 74  ment is a primit
5130: 69 76 65 20 76 61 6c 75 65 2e 0a 54 68 65 20 6a  ive value..The j
5140: 73 6f 6e 5f 74 72 65 65 28 58 29 20 66 75 6e 63  son_tree(X) func
5150: 74 69 6f 6e 20 72 65 63 75 72 73 69 76 65 6c 79  tion recursively
5160: 20 77 61 6c 6b 73 20 74 68 72 6f 75 67 68 20 74   walks through t
5170: 68 65 0a 4a 53 4f 4e 20 73 75 62 73 74 72 75 63  he.JSON substruc
5180: 74 75 72 65 20 73 74 61 72 74 69 6e 67 20 77 69  ture starting wi
5190: 74 68 20 74 68 65 20 74 6f 70 2d 6c 65 76 65 6c  th the top-level
51a0: 20 65 6c 65 6d 65 6e 74 2e 20 20 0a 0a 3c 70 3e   element.  ..<p>
51b0: 54 68 65 20 6a 73 6f 6e 5f 65 61 63 68 28 58 2c  The json_each(X,
51c0: 50 29 20 61 6e 64 20 6a 73 6f 6e 5f 74 72 65 65  P) and json_tree
51d0: 28 58 2c 50 29 20 66 75 6e 63 74 69 6f 6e 73 20  (X,P) functions 
51e0: 77 6f 72 6b 20 6a 75 73 74 20 6c 69 6b 65 0a 74  work just like.t
51f0: 68 65 69 72 20 6f 6e 65 2d 61 72 67 75 6d 65 6e  heir one-argumen
5200: 74 20 63 6f 75 6e 74 65 72 70 61 72 74 73 20 65  t counterparts e
5210: 78 63 65 70 74 20 74 68 61 74 20 74 68 65 79 20  xcept that they 
5220: 74 72 65 61 74 20 74 68 65 20 65 6c 65 6d 65 6e  treat the elemen
5230: 74 0a 69 64 65 6e 74 69 66 69 65 64 20 62 79 20  t.identified by 
5240: 70 61 74 68 20 50 20 61 73 20 74 68 65 20 74 6f  path P as the to
5250: 70 2d 6c 65 76 65 6c 20 65 6c 65 6d 65 6e 74 2e  p-level element.
5260: 0a 0a 3c 70 3e 54 68 65 20 73 63 68 65 6d 61 20  ..<p>The schema 
5270: 66 6f 72 20 74 68 65 20 74 61 62 6c 65 20 72 65  for the table re
5280: 74 75 72 6e 65 64 20 62 79 20 6a 73 6f 6e 5f 65  turned by json_e
5290: 61 63 68 28 29 20 61 6e 64 20 6a 73 6f 6e 5f 74  ach() and json_t
52a0: 72 65 65 28 29 20 69 73 0a 61 73 20 66 6f 6c 6c  ree() is.as foll
52b0: 6f 77 73 3a 0a 0a 3c 62 6c 6f 63 6b 71 75 6f 74  ows:..<blockquot
52c0: 65 3e 3c 70 72 65 3e 0a 43 52 45 41 54 45 20 54  e><pre>.CREATE T
52d0: 41 42 4c 45 20 6a 73 6f 6e 5f 74 72 65 65 28 0a  ABLE json_tree(.
52e0: 20 20 20 20 6b 65 79 20 41 4e 59 2c 20 20 20 20      key ANY,    
52f0: 20 20 20 20 20 20 20 20 20 2d 2d 20 6b 65 79 20           -- key 
5300: 66 6f 72 20 63 75 72 72 65 6e 74 20 65 6c 65 6d  for current elem
5310: 65 6e 74 20 72 65 6c 61 74 69 76 65 20 74 6f 20  ent relative to 
5320: 69 74 73 20 70 61 72 65 6e 74 0a 20 20 20 20 76  its parent.    v
5330: 61 6c 75 65 20 41 4e 59 2c 20 20 20 20 20 20 20  alue ANY,       
5340: 20 20 20 20 2d 2d 20 76 61 6c 75 65 20 66 6f 72      -- value for
5350: 20 74 68 65 20 63 75 72 72 65 6e 74 20 65 6c 65   the current ele
5360: 6d 65 6e 74 0a 20 20 20 20 74 79 70 65 20 54 45  ment.    type TE
5370: 58 54 2c 20 20 20 20 20 20 20 20 20 20 20 2d 2d  XT,           --
5380: 20 27 6f 62 6a 65 63 74 27 2c 27 61 72 72 61 79   'object','array
5390: 27 2c 27 73 74 72 69 6e 67 27 2c 27 69 6e 74 65  ','string','inte
53a0: 67 65 72 27 2c 20 65 74 63 2e 0a 20 20 20 20 61  ger', etc..    a
53b0: 74 6f 6d 20 41 4e 59 2c 20 20 20 20 20 20 20 20  tom ANY,        
53c0: 20 20 20 20 2d 2d 20 76 61 6c 75 65 20 66 6f 72      -- value for
53d0: 20 70 72 69 6d 69 74 69 76 65 20 74 79 70 65 73   primitive types
53e0: 2c 20 6e 75 6c 6c 20 66 6f 72 20 61 72 72 61 79  , null for array
53f0: 20 26 20 6f 62 6a 65 63 74 0a 20 20 20 20 69 64   & object.    id
5400: 20 49 4e 54 45 47 45 52 20 20 20 20 20 20 20 20   INTEGER        
5410: 20 20 20 2d 2d 20 69 6e 74 65 67 65 72 20 49 44     -- integer ID
5420: 20 66 6f 72 20 74 68 69 73 20 65 6c 65 6d 65 6e   for this elemen
5430: 74 0a 20 20 20 20 70 61 72 65 6e 74 20 49 4e 54  t.    parent INT
5440: 45 47 45 52 2c 20 20 20 20 20 20 2d 2d 20 69 6e  EGER,      -- in
5450: 74 65 67 65 72 20 49 44 20 66 6f 72 20 74 68 65  teger ID for the
5460: 20 70 61 72 65 6e 74 20 6f 66 20 74 68 69 73 20   parent of this 
5470: 65 6c 65 6d 65 6e 74 0a 20 20 20 20 66 75 6c 6c  element.    full
5480: 6b 65 79 20 54 45 58 54 2c 20 20 20 20 20 20 20  key TEXT,       
5490: 20 2d 2d 20 66 75 6c 6c 20 70 61 74 68 20 64 65   -- full path de
54a0: 73 63 72 69 62 69 6e 67 20 74 68 65 20 63 75 72  scribing the cur
54b0: 72 65 6e 74 20 65 6c 65 6d 65 6e 74 0a 20 20 20  rent element.   
54c0: 20 70 61 74 68 20 54 45 58 54 2c 20 20 20 20 20   path TEXT,     
54d0: 20 20 20 20 20 20 2d 2d 20 70 61 74 68 20 74 6f        -- path to
54e0: 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72 20 6f   the container o
54f0: 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f  f the current ro
5500: 77 0a 20 20 20 20 6a 73 6f 6e 20 4a 53 4f 4e 20  w.    json JSON 
5510: 48 49 44 44 45 4e 2c 20 20 20 20 2d 2d 20 31 73  HIDDEN,    -- 1s
5520: 74 20 69 6e 70 75 74 20 70 61 72 61 6d 65 74 65  t input paramete
5530: 72 3a 20 74 68 65 20 72 61 77 20 4a 53 4f 4e 0a  r: the raw JSON.
5540: 20 20 20 20 72 6f 6f 74 20 54 45 58 54 20 48 49      root TEXT HI
5550: 44 44 45 4e 20 20 20 20 20 2d 2d 20 32 6e 64 20  DDEN     -- 2nd 
5560: 69 6e 70 75 74 20 70 61 72 61 6d 65 74 65 72 3a  input parameter:
5570: 20 74 68 65 20 50 41 54 48 20 61 74 20 77 68 69   the PATH at whi
5580: 63 68 20 74 6f 20 73 74 61 72 74 0a 29 3b 0a 3c  ch to start.);.<
5590: 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
55a0: 65 3e 0a 0a 3c 70 3e 0a 54 68 65 20 22 6b 65 79  e>..<p>.The "key
55b0: 22 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20  " column is the 
55c0: 69 6e 74 65 67 65 72 20 61 72 72 61 79 20 69 6e  integer array in
55d0: 64 65 78 20 66 6f 72 20 65 6c 65 6d 65 6e 74 73  dex for elements
55e0: 20 6f 66 20 61 20 4a 53 4f 4e 20 61 72 72 61 79   of a JSON array
55f0: 20 0a 61 6e 64 20 74 68 65 20 74 65 78 74 20 6c   .and the text l
5600: 61 62 65 6c 20 66 6f 72 20 65 6c 65 6d 65 6e 74  abel for element
5610: 73 20 6f 66 20 61 20 4a 53 4f 4e 20 6f 62 6a 65  s of a JSON obje
5620: 63 74 2e 20 20 54 68 65 20 6b 65 79 20 63 6f 6c  ct.  The key col
5630: 75 6d 6e 20 69 73 0a 4e 55 4c 4c 20 69 6e 20 61  umn is.NULL in a
5640: 6c 6c 20 6f 74 68 65 72 20 63 61 73 65 73 2e 0a  ll other cases..
5650: 0a 3c 70 3e 0a 54 68 65 20 22 61 74 6f 6d 22 20  .<p>.The "atom" 
5660: 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20 53 51  column is the SQ
5670: 4c 20 76 61 6c 75 65 20 63 6f 72 72 65 73 70 6f  L value correspo
5680: 6e 64 69 6e 67 20 74 6f 20 70 72 69 6d 69 74 69  nding to primiti
5690: 76 65 20 65 6c 65 6d 65 6e 74 73 20 2d 20 0a 65  ve elements - .e
56a0: 6c 65 6d 65 6e 74 73 20 6f 74 68 65 72 20 74 68  lements other th
56b0: 61 6e 20 4a 53 4f 4e 20 61 72 72 61 79 73 20 61  an JSON arrays a
56c0: 6e 64 20 6f 62 6a 65 63 74 73 2e 20 20 54 68 65  nd objects.  The
56d0: 20 22 61 74 6f 6d 22 20 63 6f 6c 75 6d 6e 20 69   "atom" column i
56e0: 73 20 4e 55 4c 4c 0a 66 6f 72 20 61 20 4a 53 4f  s NULL.for a JSO
56f0: 4e 20 61 72 72 61 79 20 6f 72 20 6f 62 6a 65 63  N array or objec
5700: 74 2e 20 20 54 68 65 20 22 76 61 6c 75 65 22 20  t.  The "value" 
5710: 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20 73 61  column is the sa
5720: 6d 65 20 61 73 20 74 68 65 0a 22 61 74 6f 6d 22  me as the."atom"
5730: 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 70 72 69 6d   column for prim
5740: 69 74 69 76 65 20 4a 53 4f 4e 20 65 6c 65 6d 65  itive JSON eleme
5750: 6e 74 73 20 62 75 74 20 74 61 6b 65 73 20 6f 6e  nts but takes on
5760: 20 74 68 65 20 74 65 78 74 20 4a 53 4f 4e 20 76   the text JSON v
5770: 61 6c 75 65 0a 66 6f 72 20 61 72 72 61 79 73 20  alue.for arrays 
5780: 61 6e 64 20 6f 62 6a 65 63 74 73 2e 0a 0a 3c 70  and objects...<p
5790: 3e 0a 54 68 65 20 22 74 79 70 65 22 20 63 6f 6c  >.The "type" col
57a0: 75 6d 6e 20 69 73 20 61 6e 20 53 51 4c 20 74 65  umn is an SQL te
57b0: 78 74 20 76 61 6c 75 65 20 74 61 6b 65 6e 20 66  xt value taken f
57c0: 72 6f 6d 20 28 27 6e 75 6c 6c 27 2c 20 27 74 72  rom ('null', 'tr
57d0: 75 65 27 2c 20 27 66 61 6c 73 65 27 2c 0a 27 69  ue', 'false',.'i
57e0: 6e 74 65 67 65 72 27 2c 20 27 72 65 61 6c 27 2c  nteger', 'real',
57f0: 20 27 74 65 78 74 27 2c 20 27 61 72 72 61 79 27   'text', 'array'
5800: 2c 20 27 6f 62 6a 65 63 74 27 29 20 61 63 63 6f  , 'object') acco
5810: 72 64 69 6e 67 20 74 6f 20 74 68 65 20 74 79 70  rding to the typ
5820: 65 20 6f 66 0a 74 68 65 20 63 75 72 72 65 6e 74  e of.the current
5830: 20 4a 53 4f 4e 20 65 6c 65 6d 65 6e 74 2e 0a 0a   JSON element...
5840: 3c 70 3e 0a 54 68 65 20 22 69 64 22 20 63 6f 6c  <p>.The "id" col
5850: 75 6d 6e 20 69 73 20 61 6e 20 69 6e 74 65 67 65  umn is an intege
5860: 72 20 74 68 61 74 20 69 64 65 6e 74 69 66 69 65  r that identifie
5870: 73 20 61 20 73 70 65 63 69 66 69 63 20 4a 53 4f  s a specific JSO
5880: 4e 20 65 6c 65 6d 65 6e 74 0a 77 69 74 68 69 6e  N element.within
5890: 20 74 68 65 20 63 6f 6d 70 6c 65 74 65 20 4a 53   the complete JS
58a0: 4f 4e 20 73 74 72 69 6e 67 2e 20 20 54 68 65 20  ON string.  The 
58b0: 22 69 64 22 20 69 6e 74 65 67 65 72 20 69 73 20  "id" integer is 
58c0: 61 6e 20 69 6e 74 65 72 6e 61 6c 20 68 6f 75 73  an internal hous
58d0: 65 6b 65 65 70 69 6e 67 0a 6e 75 6d 62 65 72 2c  ekeeping.number,
58e0: 20 74 68 65 20 63 6f 6d 70 75 74 61 74 69 6f 6e   the computation
58f0: 20 6f 66 20 77 68 69 63 68 20 6d 69 67 68 74 20   of which might 
5900: 63 68 61 6e 67 65 20 69 6e 20 66 75 74 75 72 65  change in future
5910: 20 72 65 6c 65 61 73 65 73 2e 20 20 54 68 65 0a   releases.  The.
5920: 6f 6e 6c 79 20 67 75 61 72 61 6e 74 65 65 20 69  only guarantee i
5930: 73 20 74 68 61 74 20 74 68 65 20 22 69 64 22 20  s that the "id" 
5940: 63 6f 6c 75 6d 6e 20 77 69 6c 6c 20 62 65 20 64  column will be d
5950: 69 66 66 65 72 65 6e 74 20 66 6f 72 20 65 76 65  ifferent for eve
5960: 72 79 20 72 6f 77 2e 0a 0a 3c 70 3e 0a 54 68 65  ry row...<p>.The
5970: 20 22 70 61 72 65 6e 74 22 20 63 6f 6c 75 6d 6e   "parent" column
5980: 20 69 73 20 61 6c 77 61 79 73 20 4e 55 4c 4c 20   is always NULL 
5990: 66 6f 72 20 6a 73 6f 6e 5f 65 61 63 68 28 29 2e  for json_each().
59a0: 0a 46 6f 72 20 6a 73 6f 6e 5f 74 72 65 65 28 29  .For json_tree()
59b0: 2c 0a 74 68 65 20 22 70 61 72 65 6e 74 22 20 63  ,.the "parent" c
59c0: 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20 22 69 64  olumn is the "id
59d0: 22 20 69 6e 74 65 67 65 72 20 66 6f 72 20 74 68  " integer for th
59e0: 65 20 70 61 72 65 6e 74 20 6f 66 20 74 68 65 20  e parent of the 
59f0: 63 75 72 72 65 6e 74 0a 65 6c 65 6d 65 6e 74 2c  current.element,
5a00: 20 6f 72 20 4e 55 4c 4c 20 66 6f 72 20 74 68 65   or NULL for the
5a10: 20 74 6f 70 2d 6c 65 76 65 6c 20 4a 53 4f 4e 20   top-level JSON 
5a20: 65 6c 65 6d 65 6e 74 20 6f 72 20 74 68 65 20 65  element or the e
5a30: 6c 65 6d 65 6e 74 20 69 64 65 6e 74 69 66 69 65  lement identifie
5a40: 64 0a 62 79 20 74 68 65 20 72 6f 6f 74 20 70 61  d.by the root pa
5a50: 74 68 20 69 6e 20 74 68 65 20 73 65 63 6f 6e 64  th in the second
5a60: 20 61 72 67 75 6d 65 6e 74 2e 0a 0a 3c 70 3e 0a   argument...<p>.
5a70: 54 68 65 20 22 66 75 6c 6c 6b 65 79 22 20 63 6f  The "fullkey" co
5a80: 6c 75 6d 6e 20 69 73 20 61 20 74 65 78 74 20 70  lumn is a text p
5a90: 61 74 68 20 74 68 61 74 20 75 6e 69 71 75 65 6c  ath that uniquel
5aa0: 79 20 69 64 65 6e 74 69 66 69 65 73 20 74 68 65  y identifies the
5ab0: 20 63 75 72 72 65 6e 74 0a 72 6f 77 20 65 6c 65   current.row ele
5ac0: 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20  ment within the 
5ad0: 6f 72 69 67 69 6e 61 6c 20 4a 53 4f 4e 20 73 74  original JSON st
5ae0: 72 69 6e 67 2e 20 20 54 68 65 20 63 6f 6d 70 6c  ring.  The compl
5af0: 65 74 65 20 6b 65 79 20 74 6f 20 74 68 65 0a 74  ete key to the.t
5b00: 72 75 65 20 74 6f 70 2d 6c 65 76 65 6c 20 65 6c  rue top-level el
5b10: 65 6d 65 6e 74 20 69 73 20 72 65 74 75 72 6e 65  ement is returne
5b20: 64 20 65 76 65 6e 20 69 66 20 61 6e 20 61 6c 74  d even if an alt
5b30: 65 72 6e 61 74 69 76 65 20 73 74 61 72 74 69 6e  ernative startin
5b40: 67 20 70 6f 69 6e 74 0a 69 73 20 70 72 6f 76 69  g point.is provi
5b50: 64 65 64 20 62 79 20 74 68 65 20 22 72 6f 6f 74  ded by the "root
5b60: 22 20 61 72 67 75 6d 65 6e 74 2e 0a 0a 3c 70 3e  " argument...<p>
5b70: 0a 54 68 65 20 22 70 61 74 68 22 20 63 6f 6c 75  .The "path" colu
5b80: 6d 6e 20 69 73 20 74 68 65 20 70 61 74 68 20 74  mn is the path t
5b90: 6f 20 74 68 65 20 61 72 72 61 79 20 6f 72 20 6f  o the array or o
5ba0: 62 6a 65 63 74 20 63 6f 6e 74 61 69 6e 65 72 20  bject container 
5bb0: 74 68 65 20 68 6f 6c 64 73 20 0a 74 68 65 20 63  the holds .the c
5bc0: 75 72 72 65 6e 74 20 72 6f 77 2c 20 6f 72 20 74  urrent row, or t
5bd0: 68 65 20 70 61 74 68 20 74 6f 20 74 68 65 20 63  he path to the c
5be0: 75 72 72 65 6e 74 20 72 6f 77 20 69 6e 20 74 68  urrent row in th
5bf0: 65 20 63 61 73 65 20 77 68 65 72 65 20 74 68 65  e case where the
5c00: 20 0a 69 74 65 72 61 74 69 6f 6e 20 73 74 61 72   .iteration star
5c10: 74 73 20 6f 6e 20 61 20 70 72 69 6d 69 74 69 76  ts on a primitiv
5c20: 65 20 74 79 70 65 20 61 6e 64 20 74 68 75 73 20  e type and thus 
5c30: 6f 6e 6c 79 20 70 72 6f 76 69 64 65 73 20 61 20  only provides a 
5c40: 73 69 6e 67 6c 65 0a 72 6f 77 20 6f 66 20 6f 75  single.row of ou
5c50: 74 70 75 74 2e 0a 0a 3c 68 34 3e 33 2e 31 31 2e  tput...<h4>3.11.
5c60: 31 20 45 78 61 6d 70 6c 65 73 20 75 73 69 6e 67  1 Examples using
5c70: 20 6a 73 6f 6e 5f 65 61 63 68 28 29 20 61 6e 64   json_each() and
5c80: 20 6a 73 6f 6e 5f 74 72 65 65 28 29 3c 2f 68 34   json_tree()</h4
5c90: 3e 0a 0a 3c 70 3e 53 75 70 70 6f 73 65 20 74 68  >..<p>Suppose th
5ca0: 65 20 74 61 62 6c 65 20 22 43 52 45 41 54 45 20  e table "CREATE 
5cb0: 54 41 42 4c 45 20 75 73 65 72 28 6e 61 6d 65 2c  TABLE user(name,
5cc0: 70 68 6f 6e 65 29 22 20 73 74 6f 72 65 73 20 7a  phone)" stores z
5cd0: 65 72 6f 20 6f 72 0a 6d 6f 72 65 20 70 68 6f 6e  ero or.more phon
5ce0: 65 20 6e 75 6d 62 65 72 73 20 61 73 20 61 20 4a  e numbers as a J
5cf0: 53 4f 4e 20 61 72 72 61 79 20 6f 62 6a 65 63 74  SON array object
5d00: 20 69 6e 20 74 68 65 20 75 73 65 72 2e 70 68 6f   in the user.pho
5d10: 6e 65 20 66 69 65 6c 64 2e 0a 54 6f 20 66 69 6e  ne field..To fin
5d20: 64 20 61 6c 6c 20 75 73 65 72 73 20 77 68 6f 20  d all users who 
5d30: 68 61 76 65 20 61 6e 79 20 70 68 6f 6e 65 20 6e  have any phone n
5d40: 75 6d 62 65 72 20 77 69 74 68 20 61 20 37 30 34  umber with a 704
5d50: 20 61 72 65 61 20 63 6f 64 65 3a 0a 0a 3c 62 6c   area code:..<bl
5d60: 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 53  ockquote><pre>.S
5d70: 45 4c 45 43 54 20 44 49 53 54 49 4e 43 54 20 75  ELECT DISTINCT u
5d80: 73 65 72 2e 6e 61 6d 65 0a 20 20 46 52 4f 4d 20  ser.name.  FROM 
5d90: 75 73 65 72 2c 20 6a 73 6f 6e 5f 65 61 63 68 28  user, json_each(
5da0: 75 73 65 72 2e 70 68 6f 6e 65 29 0a 20 57 48 45  user.phone). WHE
5db0: 52 45 20 6a 73 6f 6e 5f 65 61 63 68 2e 76 61 6c  RE json_each.val
5dc0: 75 65 20 4c 49 4b 45 20 27 37 30 34 2d 25 27 3b  ue LIKE '704-%';
5dd0: 0a 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75  .</pre></blockqu
5de0: 6f 74 65 3e 0a 0a 3c 70 3e 4e 6f 77 20 73 75 70  ote>..<p>Now sup
5df0: 70 6f 73 65 20 74 68 65 20 75 73 65 72 2e 70 68  pose the user.ph
5e00: 6f 6e 65 20 66 69 65 6c 64 20 63 6f 6e 74 61 69  one field contai
5e10: 6e 73 20 70 6c 61 69 6e 20 74 65 78 74 20 69 66  ns plain text if
5e20: 20 74 68 65 20 75 73 65 72 0a 68 61 73 20 6f 6e   the user.has on
5e30: 6c 79 20 61 20 73 69 6e 67 6c 65 20 70 68 6f 6e  ly a single phon
5e40: 65 20 6e 75 6d 62 65 72 20 61 6e 64 20 61 20 4a  e number and a J
5e50: 53 4f 4e 20 61 72 72 61 79 20 69 66 20 74 68 65  SON array if the
5e60: 20 75 73 65 72 20 68 61 73 20 6d 75 6c 74 69 70   user has multip
5e70: 6c 65 0a 70 68 6f 6e 65 20 6e 75 6d 62 65 72 73  le.phone numbers
5e80: 2e 20 20 54 68 65 20 73 61 6d 65 20 71 75 65 73  .  The same ques
5e90: 74 69 6f 6e 20 69 73 20 70 6f 73 65 64 3a 20 22  tion is posed: "
5ea0: 57 68 69 63 68 20 75 73 65 72 73 20 68 61 76 65  Which users have
5eb0: 20 61 20 70 68 6f 6e 65 20 6e 75 6d 62 65 72 0a   a phone number.
5ec0: 69 6e 20 74 68 65 20 37 30 34 20 61 72 65 61 20  in the 704 area 
5ed0: 63 6f 64 65 3f 22 20 20 42 75 74 20 6e 6f 77 20  code?"  But now 
5ee0: 74 68 65 20 6a 73 6f 6e 5f 65 61 63 68 28 29 20  the json_each() 
5ef0: 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c  function can onl
5f00: 79 20 62 65 20 63 61 6c 6c 65 64 0a 66 6f 72 20  y be called.for 
5f10: 74 68 6f 73 65 20 75 73 65 72 73 20 74 68 61 74  those users that
5f20: 20 68 61 76 65 20 74 77 6f 20 6f 72 20 6d 6f 72   have two or mor
5f30: 65 20 70 68 6f 6e 65 20 6e 75 6d 62 65 72 73 20  e phone numbers 
5f40: 73 69 6e 63 65 20 6a 73 6f 6e 5f 65 61 63 68 28  since json_each(
5f50: 29 0a 72 65 71 75 69 72 65 73 20 77 65 6c 6c 2d  ).requires well-
5f60: 66 6f 72 6d 65 64 20 4a 53 4f 4e 20 61 73 20 69  formed JSON as i
5f70: 74 73 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  ts first argumen
5f80: 74 3a 0a 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  t:..<blockquote>
5f90: 3c 70 72 65 3e 0a 53 45 4c 45 43 54 20 6e 61 6d  <pre>.SELECT nam
5fa0: 65 20 46 52 4f 4d 20 75 73 65 72 20 57 48 45 52  e FROM user WHER
5fb0: 45 20 70 68 6f 6e 65 20 4c 49 4b 45 20 27 37 30  E phone LIKE '70
5fc0: 34 2d 25 27 0a 55 4e 49 4f 4e 0a 53 45 4c 45 43  4-%'.UNION.SELEC
5fd0: 54 20 75 73 65 72 2e 6e 61 6d 65 0a 20 20 46 52  T user.name.  FR
5fe0: 4f 4d 20 75 73 65 72 2c 20 6a 73 6f 6e 5f 65 61  OM user, json_ea
5ff0: 63 68 28 75 73 65 72 2e 70 68 6f 6e 65 29 0a 20  ch(user.phone). 
6000: 57 48 45 52 45 20 6a 73 6f 6e 5f 76 61 6c 69 64  WHERE json_valid
6010: 28 75 73 65 72 2e 70 68 6f 6e 65 29 0a 20 20 20  (user.phone).   
6020: 41 4e 44 20 6a 73 6f 6e 5f 65 61 63 68 2e 76 61  AND json_each.va
6030: 6c 75 65 20 4c 49 4b 45 20 27 37 30 34 2d 25 27  lue LIKE '704-%'
6040: 3b 0a 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  ;.</pre></blockq
6050: 75 6f 74 65 3e 0a 0a 3c 70 3e 43 6f 6e 73 69 64  uote>..<p>Consid
6060: 65 72 20 61 20 64 69 66 66 65 72 65 6e 74 20 64  er a different d
6070: 61 74 61 62 61 73 65 20 77 69 74 68 20 22 43 52  atabase with "CR
6080: 45 41 54 45 20 54 41 42 4c 45 20 62 69 67 28 6a  EATE TABLE big(j
6090: 73 6f 6e 20 4a 53 4f 4e 29 22 2e 0a 54 6f 20 73  son JSON)"..To s
60a0: 65 65 20 61 20 63 6f 6d 70 6c 65 74 65 20 6c 69  ee a complete li
60b0: 6e 65 2d 62 79 2d 6c 69 6e 65 20 64 65 63 6f 6d  ne-by-line decom
60c0: 70 6f 73 69 74 69 6f 6e 20 6f 66 20 74 68 65 20  position of the 
60d0: 64 61 74 61 3a 0a 0a 3c 62 6c 6f 63 6b 71 75 6f  data:..<blockquo
60e0: 74 65 3e 3c 70 72 65 3e 0a 53 45 4c 45 43 54 20  te><pre>.SELECT 
60f0: 62 69 67 2e 72 6f 77 69 64 2c 20 66 75 6c 6c 6b  big.rowid, fullk
6100: 65 79 2c 20 76 61 6c 75 65 0a 20 20 46 52 4f 4d  ey, value.  FROM
6110: 20 62 69 67 2c 20 6a 73 6f 6e 5f 74 72 65 65 28   big, json_tree(
6120: 62 69 67 2e 6a 73 6f 6e 29 0a 20 57 48 45 52 45  big.json). WHERE
6130: 20 6a 73 6f 6e 5f 74 72 65 65 2e 74 79 70 65 20   json_tree.type 
6140: 4e 4f 54 20 49 4e 20 28 27 6f 62 6a 65 63 74 27  NOT IN ('object'
6150: 2c 27 61 72 72 61 79 27 29 3b 0a 3c 2f 70 72 65  ,'array');.</pre
6160: 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 0a  ></blockquote>..
6170: 3c 70 3e 49 6e 20 74 68 65 20 70 72 65 76 69 6f  <p>In the previo
6180: 75 73 2c 20 74 68 65 20 22 74 79 70 65 20 4e 4f  us, the "type NO
6190: 54 20 49 4e 20 28 27 6f 62 6a 65 63 74 27 2c 27  T IN ('object','
61a0: 61 72 72 61 79 27 29 22 20 74 65 72 6d 20 6f 66  array')" term of
61b0: 20 74 68 65 0a 57 48 45 52 45 20 63 6c 61 75 73   the.WHERE claus
61c0: 65 20 73 75 70 70 72 65 73 73 65 73 20 63 6f 6e  e suppresses con
61d0: 74 61 69 6e 65 72 73 20 61 6e 64 20 6f 6e 6c 79  tainers and only
61e0: 20 6c 65 74 73 20 74 68 72 6f 75 67 68 20 6c 65   lets through le
61f0: 61 66 20 65 6c 65 6d 65 6e 74 73 2e 0a 54 68 65  af elements..The
6200: 20 73 61 6d 65 20 65 66 66 65 63 74 20 63 6f 75   same effect cou
6210: 6c 64 20 62 65 20 61 63 68 69 65 76 65 64 20 74  ld be achieved t
6220: 68 69 73 20 77 61 79 3a 0a 0a 3c 62 6c 6f 63 6b  his way:..<block
6230: 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 53 45 4c 45  quote><pre>.SELE
6240: 43 54 20 62 69 67 2e 72 6f 77 69 64 2c 20 66 75  CT big.rowid, fu
6250: 6c 6c 6b 65 79 2c 20 61 74 6f 6d 0a 20 20 46 52  llkey, atom.  FR
6260: 4f 4d 20 62 69 67 2c 20 6a 73 6f 6e 5f 74 72 65  OM big, json_tre
6270: 65 28 62 69 67 2e 6a 73 6f 6e 29 0a 20 57 48 45  e(big.json). WHE
6280: 52 45 20 61 74 6f 6d 20 49 53 20 4e 4f 54 20 4e  RE atom IS NOT N
6290: 55 4c 4c 3b 0a 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ULL;.</pre></blo
62a0: 63 6b 71 75 6f 74 65 3e 0a 0a 3c 70 3e 53 75 70  ckquote>..<p>Sup
62b0: 70 6f 73 65 20 65 61 63 68 20 65 6e 74 72 79 20  pose each entry 
62c0: 69 6e 20 74 68 65 20 42 49 47 20 74 61 62 6c 65  in the BIG table
62d0: 20 69 73 20 61 20 4a 53 4f 4e 20 6f 62 6a 65 63   is a JSON objec
62e0: 74 20 0a 77 69 74 68 20 61 20 27 24 2e 69 64 27  t .with a '$.id'
62f0: 20 66 69 65 6c 64 20 74 68 61 74 20 69 73 20 61   field that is a
6300: 20 75 6e 69 71 75 65 20 69 64 65 6e 74 69 66 69   unique identifi
6310: 65 72 0a 61 6e 64 20 61 20 27 24 2e 70 61 72 74  er.and a '$.part
6320: 6c 69 73 74 27 20 66 69 65 6c 64 20 74 68 61 74  list' field that
6330: 20 63 61 6e 20 62 65 20 61 20 64 65 65 70 6c 79   can be a deeply
6340: 20 6e 65 73 74 65 64 20 6f 62 6a 65 63 74 2e 0a   nested object..
6350: 59 6f 75 20 77 61 6e 74 20 74 6f 20 66 69 6e 64  You want to find
6360: 20 74 68 65 20 69 64 20 6f 66 20 65 76 65 72 79   the id of every
6370: 20 65 6e 74 72 79 20 74 68 61 74 20 63 6f 6e 74   entry that cont
6380: 61 69 6e 73 20 6f 6e 65 0a 6f 72 20 6d 6f 72 65  ains one.or more
6390: 20 72 65 66 65 72 65 6e 63 65 73 20 74 6f 20 75   references to u
63a0: 75 69 64 20 27 36 66 61 35 31 38 31 65 2d 35 37  uid '6fa5181e-57
63b0: 32 31 2d 31 31 65 35 2d 61 30 34 65 2d 35 37 66  21-11e5-a04e-57f
63c0: 33 64 37 62 33 32 38 30 38 27 20 61 6e 79 77 68  3d7b32808' anywh
63d0: 65 72 65 0a 69 6e 20 69 74 73 20 27 24 2e 70 61  ere.in its '$.pa
63e0: 72 74 6c 69 73 74 27 2e 0a 0a 3c 62 6c 6f 63 6b  rtlist'...<block
63f0: 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 53 45 4c 45  quote><pre>.SELE
6400: 43 54 20 44 49 53 54 49 4e 43 54 20 6a 73 6f 6e  CT DISTINCT json
6410: 5f 65 78 74 72 61 63 74 28 62 69 67 2e 6a 73 6f  _extract(big.jso
6420: 6e 2c 27 24 2e 69 64 27 29 0a 20 20 46 52 4f 4d  n,'$.id').  FROM
6430: 20 62 69 67 2c 20 6a 73 6f 6e 5f 74 72 65 65 28   big, json_tree(
6440: 62 69 67 2e 6a 73 6f 6e 2c 20 27 24 2e 70 61 72  big.json, '$.par
6450: 74 6c 69 73 74 27 29 0a 20 57 48 45 52 45 20 6a  tlist'). WHERE j
6460: 73 6f 6e 5f 74 72 65 65 2e 6b 65 79 3d 27 75 75  son_tree.key='uu
6470: 69 64 27 0a 20 20 20 41 4e 44 20 6a 73 6f 6e 5f  id'.   AND json_
6480: 74 72 65 65 2e 76 61 6c 75 65 3d 27 36 66 61 35  tree.value='6fa5
6490: 31 38 31 65 2d 35 37 32 31 2d 31 31 65 35 2d 61  181e-5721-11e5-a
64a0: 30 34 65 2d 35 37 66 33 64 37 62 33 32 38 30 38  04e-57f3d7b32808
64b0: 27 3b 0a 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ';.</pre></block
64c0: 71 75 6f 74 65 3e 0a                             quote>.