All,
Here's a draft cleanup on the JSON section of the Datatype docs. Since
there's been a bunch of incremental patches on this, I just did a diff
against HEAD.
I looked over json-functions a bit, but am not clear on what needs to
change there; the docs are pretty similar to other sections of
Functions, and if they're complex it's because of the sheer number of
JSON-related functions.
Anyway, this version of datatypes introduces a comparison table, which I
think should make things a bit clearer for users.
--
Josh Berkus
PostgreSQL Experts Inc.
http://pgexperts.com
diff --git a/doc/src/sgml/datatype.sgml b/doc/src/sgml/datatype.sgml
index 00ccbe1..4baefb6 100644
--- a/doc/src/sgml/datatype.sgml
+++ b/doc/src/sgml/datatype.sgml
@@ -13,7 +13,7 @@
</indexterm>
<para>
- <productname>PostgreSQL</productname> has a rich set of native data
+ <productname>PostgreSQL</productname> has a rich set of native data<
types available to users. Users can add new types to
<productname>PostgreSQL</productname> using the <xref
linkend="sql-createtype"> command.
@@ -139,7 +139,13 @@
<row>
<entry><type>json</type></entry>
<entry></entry>
- <entry>JSON data</entry>
+ <entry>JSON data, varlena format</entry>
+ </row>
+
+ <row>
+ <entry><type>jsonb</type></entry>
+ <entry></entry>
+ <entry>JSON data, binary structured format</entry>
</row>
<row>
@@ -3156,7 +3162,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays
coordinates, as floating-point numbers.
</para>
- <para>
+ <para>f
Points are output using the first syntax.
</para>
</sect2>
@@ -4233,27 +4239,101 @@ SET xmloption TO { DOCUMENT | CONTENT };
</sect1>
<sect1 id="datatype-json">
- <title><acronym>JSON</> Type</title>
+ <title><acronym>JSON</> Types</title>
<indexterm zone="datatype-json">
<primary>JSON</primary>
</indexterm>
+ <indexterm zone="datatype-json">
+ <primary>JSONB</primary>
+ </indexterm>
+
<para>
- The <type>json</type> data type can be used to store JSON (JavaScript
- Object Notation) data, as specified in <ulink
- url="http://www.ietf.org/rfc/rfc4627.txt";>RFC 4627</ulink>. Such
- data can also be stored as <type>text</type>, but the
- <type>json</type> data type has the advantage of checking that each
- stored value is a valid JSON value. There are also related support
+ JSON data types are for storing JSON (JavaScript Object Notation)
+ data, as specified in <ulink url="http://www.ietf.org/rfc/rfc4627.txt";
+ >RFC 4627</ulink>. Such data can also be stored as <type>text</type>,
+ but the JSON data types have the advantage of checking that each
+ stored value is a valid JSON value. There are also related support
functions available; see <xref linkend="functions-json">.
</para>
<para>
+ There are two JSON data types: <type>json</type> and <type>jsonb</type>.
+ Both accept identical sets of values as input. The difference is primarily
+ a matter of storage. The <type>json</type> data type stores an exact
+ copy of the input text, while the <type>jsonb</type> is stored in a decomposed
+ binary format which limits reparsing and supports future index and operator features.
+ </para>
+
+ <table id="datatype-json-table">
+ <title>JSON and JSONB Comparison</title>
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry>Feature</entry>
+ <entry>JSON</entry>
+ <entry>JSONB</entry>
+ </row>
+ </thead>
+
+ <tbody>
+
+ <row>
+ <entry>Storage Format</entry>
+ <entry>Varlena (text)</entry>
+ <entry>Binary structured, decomposed</entry>
+ </row>
+
+ <row>
+ <entry>Parsed On</entry>
+ <entry>Every use</entry>
+ <entry>Input only</entry>
+ </row>
+
+ <row>
+ <entry>Whitespace</entry>
+ <entry>Preserved</entry>
+ <entry>Normalized</entry>
+ </row>
+
+ <row>
+ <entry>Duplicate keys</entry>
+ <entry>Preserved</entry>
+ <entry>Removed (keeps last key)</entry>
+ </row>
+
+ <row>
+ <entry>Key ordering</entry>
+ <entry>Preserved</entry>
+ <entry>Normalized</entry>
+ </row>
+
+ <row>
+ <entry>Indexing</entry>
+ <entry>Function indexes only</entry>
+ <entry>Function and GIN indexes (with Hstore2 Extension)</entry>
+ </row>
+
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para>
+ In general, most applications will find it advantageous to store JSON data
+ as <type>jsonb</type>, as jsonb is more efficient for most purposes and will
+ support future advanced json index, operator and search features. The
+ <type>json</type> will primarily be useful for applications which need to
+ preserve exact formatting of the input JSON, or users with existing
+ <type>json</type> columns which they do not want to convert to
+ <type>jsonb</type>.
+ </para>
+
+ <para>
<productname>PostgreSQL</productname> allows only one server encoding
- per database. It is therefore not possible for JSON to conform rigidly
- to the specification unless the server encoding is UTF-8. Attempts to
- directly include characters which cannot be represented in the server
+ per database. It is therefore not possible for the JSON types to conform
+ rigidly to the specification unless the server encoding is UTF-8. Attempts
+ to directly include characters which cannot be represented in the server
encoding will fail; conversely, characters which can be represented in
the server encoding but not in UTF-8 will be allowed.
<literal>\uXXXX</literal> escapes are allowed regardless of the server
--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers
