This page was generated
June  25,  2015
8:15  AM
XQuery & XSLT Built-In & Modules Function Reference

Built-In: Extension - JSON Functions

The JSON built-in functions serialize XQuery items to JSON and read a JSON string and create XQuery items from it. JSON (JavaScript Object Notation) is a data-interchange format popular mechanism for passing data from JavaScript to other programming environments.

Function Summary
json:array Creates a (JSON) array, which is like a sequence of values, but allows for nesting.
json:array-pop Pop a value from the end of the array.
json:array-push Push a value to the end of the array, increasing the size of the array by one.
json:array-resize Resize the array to the new size.
json:array-size Returns the size of the array.
json:array-values Returns the array values as an XQuery sequence.
json:object Creates a JSON object, which is a kind of map with a fixed and ordered set of keys.
json:object-define Creates a JSON object.
json:set-item-at Sets a value in an array at a specified position.
json:subarray Extract a subarray from an array, producing a new array.
json:to-array Constructs an array from a sequence of items.
xdmp:from-json Parses a string as JSON, returning an item sequence.
xdmp:to-json Returns a string representing a JSON serialization of a given item sequence.
Function Detail
json:array(
[$array as element(json:array)]
)  as   json:array
Summary:

Creates a (JSON) array, which is like a sequence of values, but allows for nesting.

Parameters:
$array (optional): A serialized array element.

Example:
xquery version "1.0-ml";

json:array(
  <json:array xmlns:json="http://marklogic.com/xdmp/json"
              xmlns:xs="http://www.w3.org/2001/XMLSchema"
              xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <json:value xsi:type="xs:string">hello</json:value>
   <json:value xsi:type="xs:string">world</json:value>
   <json:array>
     <json:value xsi:type="xs:string">one</json:value>
     <json:value xsi:type="xs:string">two</json:value>
   </json:array>
  </json:array>
)
=> ["hello", "world", ["one", "two"]]

json:array-pop(
$array as json:array
)  as   item()*
Summary:

Pop a value from the end of the array.

Parameters:
$array : An array.

Example:
  let $a := json:to-array((1, 2, 3))
  let $v := json:array-pop($a)
  return (xdmp:to-json($a), $v)
  => [1, 2] 3

json:array-push(
$array as json:array,
$item as item()*
)  as   empty-sequence()
Summary:

Push a value to the end of the array, increasing the size of the array by one.

Parameters:
$array : An array.
$item : New entries.

Example:
  let $a := json:to-array(1 to 3)
  let $_ := json:array-push($a, 4)
  return xdmp:to-json($a)
  => [1,2,3,4]

json:array-resize(
$array as json:array,
$newSize as xs:unsignedLong,
[$zero as item()?]
)  as   empty-sequence()
Summary:

Resize the array to the new size. If the new size is greater than the old size, the new entries will be null. If the new size if smaller than the old size, the extra entries will be removed.

Parameters:
$array : An array.
$newSize : New size.
$zero (optional): The value to use to pad out the array, if necessary. By default the empty sequence is used.

Example:
  let $a := json:to-array(1 to 3)
  let $_ := json:array-resize($a, 4)
  return xdmp:to-json($a)
  => [1, 2, 3, null]

json:array-size(
$array as json:array?
)  as   xs:unsignedLong?
Summary:

Returns the size of the array.

Parameters:
$array : An array.

Example:
  json:array-size(json:to-array(("a","b")))
  => 2

json:array-values(
$array as json:array,
[$flatten as xs:boolean?]
)  as   item()*
Summary:

Returns the array values as an XQuery sequence.

Parameters:
$array : An array.
$flatten (optional): Include values from subarrays in the sequence. The default is false, meaning that subarrays are returned as array values.

Example:
xquery version "1.0-ml";

let $array := 
  json:array(
    <json:array xmlns:json="http://marklogic.com/xdmp/json"
                xmlns:xs="http://www.w3.org/2001/XMLSchema"
                xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
     <json:value xsi:type="xs:string">hello</json:value>
     <json:value xsi:type="xs:string">world</json:value>
     <json:array>
       <json:value xsi:type="xs:string">one</json:value>
       <json:value xsi:type="xs:string">two</json:value>
     </json:array>
    </json:array>
  )
return json:array-values($array)
=> ("hello", "world", ["one", "two"])
Example:
xquery version "1.0-ml";

let $array := 
  json:array(
    <json:array xmlns:json="http://marklogic.com/xdmp/json"
                xmlns:xs="http://www.w3.org/2001/XMLSchema"
                xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
     <json:value xsi:type="xs:string">hello</json:value>
     <json:value xsi:type="xs:string">world</json:value>
     <json:array>
       <json:value xsi:type="xs:string">one</json:value>
       <json:value xsi:type="xs:string">two</json:value>
     </json:array>
    </json:array>
  )
return json:array-values($array, fn:true())
=> ("hello", "world", "one", "two")

json:object(
[$map as element(json:object)]
)  as   map:map
Summary:

Creates a JSON object, which is a kind of map with a fixed and ordered set of keys.

Parameters:
$map (optional): A serialized JSON object.

Example:
  json:object()
  => json:object(<json xmlns="http://marklogic.com/xdmp/json"/>)
Example:
xquery version "1.0-ml";

let $obj := 
<json:object xmlns:json="http://marklogic.com/xdmp/json">
 <json:entry>
   <json:key>2</json:key>
   <json:value xsi:type="xs:string"
      xmlns:xs="http://www.w3.org/2001/XMLSchema"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    world</json:value>
 </json:entry>
 <json:entry>
   <json:key>1</json:key>
   <json:value xsi:type="xs:string"
      xmlns:xs="http://www.w3.org/2001/XMLSchema"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    hello</json:value>
 </json:entry>
</json:object>
return
map:keys(json:object($obj))
=> 
2 1

json:object-define(
[$keys as xs:string*]
)  as   json:object
Summary:

Creates a JSON object.

Parameters:
$keys (optional): The sequence of keys in this object.

Example:
  let $obj := json:object-define(("a","b","c"))
  return map:keys($obj)
  => "a","b","c"

json:set-item-at(
$array as json:array,
$pos as xs:double,
$value as item()*
)  as   empty-sequence()
Summary:

Sets a value in an array at a specified position.

Parameters:
$array : An array.
$pos : The position to update. Invalid positions throw XDMP-ARRAYINDEXOUTOFBOUNDS
$value : A value. Empty sequences are allowed.

Example:
let $array := json:to-array( ("a","b","c"), 5 )
let $put := json:set-item-at($array, 5 , <info>45683</info>)
return
<result>{$array}</result>

=>
<result>
  <json:array xmlns:json="http://marklogic.com/xdmp/json">
    <json:value xsi:type="xs:string">a</json:value>
    <json:value xsi:type="xs:string">b</json:value>
    <json:value xsi:type="xs:string">c</json:value>
    <json:value xsi:nil="true"/>
    <json:value><info>45683</info></json:value>
  </json:array>
</result>
Example:
xquery version "1.0-ml";

let $array := json:to-array(("a", "z", "c")) 
return (
    $array[2],
    json:set-item-at($array, 2, "b"),
    $array[2]
    )
=>
z
b


json:subarray(
$array as json:array,
$startingLoc as xs:double,
[$length as xs:double]
)  as   json:array
Summary:

Extract a subarray from an array, producing a new array. The second and third arguments to this function operate similarly to those of fn:subsequence for XQuery sequences.

Parameters:
$array : An array.
$startingLoc : The starting position of the start of the subarray.
$length (optional): The length of the subarray.

Example:
  xdmp:to-json(json:subarray(json:to-array(1 to 6), 2, 4))
  => [2,3,4,5]

json:to-array(
[$items as item()*],
[$limit as xs:double?],
[$zero as item()?]
)  as   json:array
Summary:

Constructs an array from a sequence of items.

Parameters:
$items (optional): A sequence of items.
$limit (optional): The size of the array to construct. If the size is less than the length of the item sequence, only as "limit" items are put into the array. If the size is more than the length of the sequence, the array is filled with null values up to the limit.
$zero (optional): The value to use to pad out the array, if necessary. By default the empty sequence is used.

Example:
xquery version "1.0-ml";

json:to-array(1 to 2)
=>
  json:array(
    <json:array xmlns:json="http://marklogic.com/xdmp/json"
                xmlns:xs="http://www.w3.org/2001/XMLSchema"
                xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
     <json:value xsi:type="xs:integer">1</json:value>
     <json:value xsi:type="xs:integer">2</json:value>
    </json:array>
  )

xdmp:from-json(
$arg as xs:string
)  as   item()*
Summary:

Parses a string as JSON, returning an item sequence.

Parameters:
$arg : JSON input to be parsed.

Usage Notes:

A JSON object or string is parsed as a json:object.

The JSON null value is represented as the empty sequence, and serializes in a way that indicates it is a null value. Therefore, when the null value is returned to JSON via xdmp:to-json, the null value is preserved.

Nested arrays in JSON are turned into nested sets of json:arrays.

Any codepoints in the JSON string that aren't allowed in XML are rejected and an error is thrown.


Example:
xdmp:from-json('["a", null, false]')
=>
json:array(
<json:array xmlns:xs="http://www.w3.org/2001/XMLSchema"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns:json="http://marklogic.com/xdmp/json">
   <json:value xsi:type="xs:string">a</json:value>
   <json:value xsi:nil="true"/>
   <json:value xsi:type="xs:boolean">false</json:value>
</json:array>) 
  
Example:
xquery version "1.0-ml";

let $json :=
  '[{"some-key":45683}, "this is a string", 123]'
return
xdmp:from-json($json)

=>

json:array(
<json:array xmlns:xs="http://www.w3.org/2001/XMLSchema"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:json="http://marklogic.com/xdmp/json">
  <json:value>
    <json:object>
      <json:entry key="some-key">
        <json:value xsi:type="xs:integer">45683</json:value>
      </json:entry>
    </json:object>
  </json:value>
  <json:value xsi:type="xs:string">this is a string</json:value>
  <json:value xsi:type="xs:integer">123</json:value></json:array>)

Note that what is shown above is the serialization of the XQuery items to
a json:array.  You can also use some or all of the items in the XQuery data
model.  For example, consider the following, which adds to the map based on the
other values:

xquery version "1.0-ml";
let $json :=
  '[{"some-key":45683}, "this is a string", 123]'
let $items := xdmp:from-json($json)
let $put := map:put($items[1], xs:string($items[3]), $items[2])
return
($items[1], xdmp:to-json($items[1]))

(: returns the following json:array and JSON string:
json:object(
<json:object xmlns:xs="http://www.w3.org/2001/XMLSchema"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:json="http://marklogic.com/xdmp/json">
  <entry key="some-key">
    <json:value xsi:type="xs:integer">45683</json:value>
  </entry>
  <entry key="123">
    <json:value xsi:type="xs:string">this is a string</json:value>
  </entry>
</json:object>)
{"some-key":45683, "123":"this is a string"}

This query uses the map functions to modify the first json:object
in the json:array.
:)

xdmp:to-json(
$item as item()*
)  as   xs:string
Summary:

Returns a string representing a JSON serialization of a given item sequence.

Parameters:
$item : The item sequence whose JSON serialization is returned.

Usage Notes:

XML nodes are serialized to JSON strings.

JSON has no serialization for infinity, not a number, and negative 0, therefore if you try and serialize INF, -INF, NaN, or -0 as JSON, an exception is thrown. If you want to represent these values in some way in your serialized JSON, then you can catch the exception (with a try/catch, for example) and provide your own value for it.

XQuery maps (map:map types) serialize to JSON name-value pairs.


Example:
  xdmp:to-json(("a",fn:false()))
   => ["a", false]
Example:
xquery version "1.0-ml";

xdmp:to-json(
    xdmp:from-json('
        { "a":111 }
     ')
)

=>

{"a":111}