1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
|
<sect1 id="json">
<title>json</title>
<indexterm zone="json">
<primary>json</primary>
</indexterm>
<para>
This module implements the <type>json</> data type for storing <ulink url="http://www.json.org/">JSON</ulink> content in <productname>PostgreSQL</>. The advantage of using the <type>json</> type over storing JSON content in a <type>text</> field is that it makes sure input values are valid JSON, and there are several type-safe functions for manipulating JSON content.
</para>
<para>
The <type>json</> type stores valid JSON <quote>values</quote> as defined by <ulink url="http://json.org/">json.org</ulink>. That is, a <type>json</> field can hold a string, number, object, array, 'true', 'false', or 'null'.
</para>
<para>
The <type>json</> datatype should be thought of as a specialization of <type>text</type> rather than a wrapper around <type>text</>, <type>int</>, <type>float</>, etc. For instance, <literal>' "string" '::json::text</literal> will simply yield <literal>' "string" '</literal>. Also, bear in mind that JSON null (<literal>'null'::json</literal>) and SQL NULL (<literal>NULL::json</literal>) are two different things.
</para>
<para>
The json module is currently under development.
</para>
<sect2>
<title><type>json</> Functions</title>
<table id="json-func-table">
<title><type>json</type> Functions</title>
<tgroup cols="5">
<thead>
<row>
<entry>Function</entry>
<entry>Return Type</entry>
<entry>Description</entry>
<entry>Example</entry>
<entry>Result</entry>
</row>
</thead>
<tbody>
<row>
<entry morerows="1"><function>to_json(anyelement)</function></entry>
<entry morerows="1"><type>json</type></entry>
<entry morerows="1">Encode a value as JSON.</entry>
<entry><literal>to_json('string'::TEXT)</literal></entry>
<entry><literal>'"string"'</literal></entry>
</row>
<row>
<entry><literal>to_json(array['one','two','three',null]::text[])</literal></entry>
<entry><literal>'["one","two","three",null]'</literal></entry>
</row>
<row>
<entry><function>from_json(json)</function></entry>
<entry><type>text</type></entry>
<entry>Decode a JSON-encoded value.</entry>
<entry><literal>from_json('"string"')</literal></entry>
<entry><literal>'string'</literal></entry>
</row>
<row>
<entry morerows="1"><function>json_validate(text)</function></entry>
<entry morerows="1"><type>boolean</type></entry>
<entry morerows="1">Determine if text is valid JSON.</entry>
<entry><literal>json_validate('{key: "value"}')</literal></entry>
<entry><literal>false</literal></entry>
</row>
<row>
<entry><literal>json_validate('{"key": "value"}')</literal></entry>
<entry><literal>true</literal></entry>
</row>
<row>
<entry morerows="2"><function>json_get(json, jsonpath text)</function></entry>
<entry morerows="2"><type>json</type></entry>
<entry morerows="2">Select a single value from a JSON tree using a JSONPath expression.</entry>
<entry><literal>json_get('[0,1,2]', '$[1]')</literal></entry>
<entry><literal>'1'</literal></entry>
</row>
<row>
<entry><literal>json_get('[0,1,2]', '$[100]')</literal></entry>
<entry><literal>NULL</literal></entry>
</row>
<row>
<entry><literal>json_get('[0,1,2]', '$[*]')</literal></entry>
<entry><literal>Error</literal></entry>
</row>
<row>
<entry morerows="2"><function>json_set(json, jsonpath text, json)</function></entry>
<entry morerows="2"><type>json</type></entry>
<entry morerows="2">Set items in a JSON tree that match a JSONPath expression.</entry>
<entry><literal>json_set('[0,1,2]', '$[1]', '"x"')</literal></entry>
<entry><literal>'[0,"x",2]'</literal></entry>
</row>
<row>
<entry><literal>json_set('[0,1,2]', '$[100]', '"x"')</literal></entry>
<entry><literal>'[0,1,2]'</literal></entry>
</row>
<row>
<entry><literal>json_set('[0,1,2]', '$[*]', '"x"')</literal></entry>
<entry><literal>'["x","x","x"]'</literal></entry>
</row>
<row>
<entry morerows="2"><function>json_path(json, jsonpath text)</function></entry>
<entry morerows="2"><type>setof json</type></entry>
<entry morerows="2">Select multiple values from a JSON tree using a JSONPath expression.</entry>
<entry><literal>json_path('[0,1,2]', '$[1]')</literal></entry>
<entry>
<programlisting>
1
(1 row)
</programlisting>
</entry>
</row>
<row>
<entry><literal>json_path('[0,1,2]', '$[100]')</literal></entry>
<entry>
<programlisting>
(0 rows)
</programlisting>
</entry>
</row>
<row>
<entry><literal>json_path('[0,1,2]', '$[*]')</literal></entry>
<entry>
<programlisting>
0
1
2
(3 rows)
</programlisting>
</entry>
</row>
<row>
<entry morerows="1"><function>json_condense(json)</function></entry>
<entry morerows="1"><type>json</type></entry>
<entry morerows="1">Re-encodes JSON to form a string with minimal length (mainly removes whitespace).</entry>
<entry><literal>json_condense(' { "key" : "value"} ')</literal></entry>
<entry><literal>'{"key":"value"}'</literal></entry>
</row>
<row>
<entry><literal>json_condense($$ "\u266B" $$)</literal></entry>
<entry><literal>'"♫"' -- if encoding supports Unicode</literal></entry>
</row>
<row>
<entry><function>json_get_type(json)</function></entry>
<entry><type>json_type</type> - one of:
<programlisting>
'null'
'string'
'number'
'bool'
'object'
'array'
</programlisting>
</entry>
<entry>Get the type of a <type>json</type> value.</entry>
<entry><literal>json_get_type('{"pi": "3.14159", "e": "2.71828"}')</literal></entry>
<entry><literal>'object'</literal></entry>
</row>
</tbody>
</tgroup>
</table>
</sect2>
<sect2>
<title>Author</title>
<para>
Joey Adams <email>[email protected]</email>
</para>
<para>
Development of this module was sponsored by Google through its Google Summer of Code program (<ulink url="http://code.google.com/soc">code.google.com/soc</ulink>).
</para>
</sect2>
</sect1>
|
