Skip to content

Commit 48d3918

Browse files
rakhi-prathaprakhi-prathap
authored
[DOC-2427] Update JSON Functions - 7.6 (#601)
1 parent 765e19e commit 48d3918

1 file changed

Lines changed: 211 additions & 20 deletions

File tree

‎modules/n1ql/pages/n1ql-language-reference/jsonfun.adoc‎

Lines changed: 211 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -1,32 +1,223 @@
11
= JSON Functions
2-
:description: DECODE_JSON(expression)
2+
:description: Functions for encoding, decoding, and evaluating JSON values.
33
:page-topic-type: reference
44

5+
[abstract]
56
{description}
67

7-
Unmarshals the JSON-encoded string into a {sqlpp} value.
8-
The empty string is MISSING.
8+
== DECODE_JSON(`expression`)
99

10-
ENCODE_JSON(expression)
10+
Converts a JSON-encoded string into a {sqlpp} value.
1111

12-
Marshals the {sqlpp} value into a JSON-encoded string.
13-
MISSING becomes the empty string.
12+
=== Arguments
1413

15-
ENCODED_SIZE(expression)
14+
expression:: [Required] An expression that represents a JSON-encoded string.
1615

17-
Number of bytes in an uncompressed JSON encoding of the value.
18-
The exact size is implementation-dependent.
19-
Always returns an integer, and never MISSING or NULL.
20-
Returns 0 for MISSING.
16+
=== Return Value
2117

22-
POLY_LENGTH(expression)
18+
The function returns 1 of the following:
2319

24-
Returns length of the value after evaluating the expression.
25-
The exact meaning of length depends on the type of the value:
20+
* A {sqlpp} value.
21+
* `NULL` if the input is NULL or not a valid JSON value.
22+
* `MISSING` if the input is empty.
2623

27-
* MISSING: MISSING
28-
* NULL: NULL
29-
* String: The length of the string.
30-
* Array: The number of elements in the array.
31-
* Object: The number of name/value pairs in the object
32-
* Any other value: NULL
24+
=== Example
25+
26+
.Decode a JSON string into a {sqlpp} value
27+
====
28+
29+
.Query
30+
[source,sqlpp]
31+
----
32+
SELECT DECODE_JSON(
33+
"{\"airline\":
34+
{ \"callsign\": \"Mile-Air\",
35+
\"country\": \"United States\",
36+
\"iata\": \"Q5\",
37+
\"id\": 10,
38+
\"name\": \"40-mile Air\",
39+
\"type\": \"airline\"
40+
}
41+
}"
42+
) as decoded_value;
43+
----
44+
45+
.Result
46+
[source,json]
47+
----
48+
[
49+
{
50+
"decoded_value": {
51+
"airline": {
52+
"callsign": "Mile-Air",
53+
"country": "United States",
54+
"iata": "Q5",
55+
"id": 10,
56+
"name": "40-mile Air",
57+
"type": "airline"
58+
}
59+
}
60+
}
61+
]
62+
----
63+
====
64+
65+
== ENCODE_JSON(`expression`)
66+
67+
Converts a {sqlpp} value into a JSON-encoded string.
68+
69+
=== Arguments
70+
71+
expression:: [Required] A {sqlpp} expression to be encoded.
72+
73+
=== Return Value
74+
75+
The function returns 1 of the following:
76+
77+
* A JSON encoded string.
78+
* `NULL` if the input is `NULL`.
79+
* `MISSING` if the input is `MISSING`.
80+
81+
=== Example
82+
83+
.Encode a {sqlpp} value into a JSON string
84+
====
85+
86+
.Query
87+
[source,sqlpp]
88+
----
89+
SELECT ENCODE_JSON(
90+
{
91+
"airline": {
92+
"callsign": "Mile-Air",
93+
"country": "United States",
94+
"iata": "Q5",
95+
"id": 10,
96+
"name": "40-mile Air",
97+
"type": "airline"
98+
}
99+
}
100+
) as encoded_value;
101+
----
102+
103+
.Result
104+
[source,json]
105+
----
106+
[
107+
{
108+
"encoded_value":
109+
"{ \"airline\":
110+
{ \"callsign\":\"Mile-Air\",
111+
\"country\":\"United States\",
112+
\"iata\":\"Q5\",
113+
\"id\":10,
114+
\"name\":\"40-mile Air\",
115+
\"type\":\"airline\"
116+
}
117+
}"
118+
}
119+
]
120+
----
121+
====
122+
123+
== ENCODED_SIZE(`expression`)
124+
125+
Returns the number of bytes in an uncompressed JSON encoding of a value.
126+
The exact size depends on the implementation and may vary.
127+
128+
=== Arguments
129+
130+
expression:: [Required] An expression to evaluate.
131+
132+
=== Return Value
133+
134+
An integer representing the size in bytes.
135+
136+
The function never returns `NULL` or `MISSING`.
137+
If the input value is `MISSING`, the function returns `0`.
138+
139+
=== Example
140+
141+
.Calculate the size of a JSON-encoded value
142+
====
143+
144+
.Query
145+
[source,sqlpp]
146+
----
147+
SELECT ENCODED_SIZE(
148+
{
149+
"airline": {
150+
"callsign": "Mile-Air",
151+
"country": "United States",
152+
"iata": "Q5",
153+
"id": 10,
154+
"name": "40-mile Air",
155+
"type": "airline"
156+
}
157+
}
158+
) as encoded_size;
159+
----
160+
161+
.Result
162+
[source,json]
163+
----
164+
[
165+
{
166+
"encoded_size": 119
167+
}
168+
]
169+
----
170+
====
171+
172+
== POLY_LENGTH(`expression`)
173+
174+
Evaluates an expression and returns the length of the resulting value.
175+
The definition of length depends on the type of the evaluated value.
176+
For more information, see the <<poly-length-return-value>> section.
177+
178+
=== Arguments
179+
180+
expression:: [Required] An expression to evaluate.
181+
182+
[[poly-length-return-value]]
183+
=== Return Value
184+
185+
The function returns a value based on the data type of the result:
186+
187+
* String: Returns the number of characters in the string.
188+
* Array: Returns the number of elements in the array.
189+
* Object: Returns the number of name/value pairs in the object.
190+
* MISSING: Returns `MISSING`.
191+
* NULL: Returns `NULL`.
192+
* Any other value: Returns `NULL`.
193+
194+
=== Example
195+
196+
.Find the length of a string, array, and object
197+
====
198+
199+
.Query
200+
[source,sqlpp]
201+
----
202+
SELECT
203+
POLY_LENGTH("Flight 101") as string_length,
204+
POLY_LENGTH(["Flight 101", "Flight 202", "Flight 303"]) as array_length,
205+
POLY_LENGTH({
206+
"flight": 101,
207+
"airline": "Mile-Air",
208+
"destination": "United States"
209+
}) as object_length;
210+
----
211+
212+
.Result
213+
[source,json]
214+
----
215+
[
216+
{
217+
"string_length": 10,
218+
"array_length": 3,
219+
"object_length": 3
220+
}
221+
]
222+
----
223+
====

0 commit comments

Comments
 (0)