Permalink
Browse files

Adjusted doc, fixed one edge case

  • Loading branch information...
theirix committed Oct 2, 2012
1 parent 7eeec14 commit b3e5e5e7d6979c17889545758c89bf81433b0a9d
Showing with 26 additions and 80 deletions.
  1. +3 −51 README.md
  2. +8 −17 doc/json_accessors.md
  3. +1 −1 sql/json_accessors.sql
  4. +3 −11 src/json_accessors.c
  5. +6 −0 test/expected/regress.out
  6. +5 −0 test/sql/regress.sql
View
@@ -1,69 +1,21 @@
JSON accessor functions for PostgreSQL
======================================
-[PostgreSQL](http://www.postgresql.org/) stored functions for accessing [JSON](http://www.json.org/) fields.
+[PostgreSQL](http://www.postgresql.org/) extension with stored functions for accessing [JSON](http://www.json.org/) fields.
This project contains PostgreSQL [extension](http://www.postgresql.org/docs/9.1/static/extend-extensions.html) `json_accessors` with stored functions. Extension is native and writen in C on top of [cJSON](http://sourceforge.net/projects/cjson/) library.
-If you have text (varchar) columns with data like this:
-
- {"create_date":"2009-12-01 01:23:45","tags":["foo","bar","baz"]}
-
-These functions can be used for:
-
- - creating queries to JSON object fields
- - creating B-tree (default) indexes on JSON object fields (`create_date` field)
- - creating [GIN](http://www.postgresql.org/docs/9.1/static/gin.html) indexes on JSON arrays (`tags` field)
-
PostgreSQL have had no JSON support until version 9.2, which [introduced some support](http://www.postgresql.org/docs/9.2/static/functions-json.html).
These 9.2 functions won't help with indexing JSON data.
JSON parsing functions may be written using [PL/V8](http://code.google.com/p/plv8js/wiki/PLV8) module,
[this article](http://people.planetpostgresql.org/andrew/index.php?/archives/249-Using-PLV8-to-index-JSON.html) has an example of PL/V8 usage.
This project provides accessor functions for JSON without using PL/V8.
-Functions
+Usage
---------
-__Function for accessing JSON object fields:__
-
- function json_get_text(text, text) returns text
-
-Usage example, returns `qq`:
-
- select json_get_text('{"foo":"qq", "bar": true}', 'foo')
-
-There are also similar functions returning `boolean`, `int`, `bigint`, `numeric` and `timestamp without timezone`.
-Timestamp format `yyyy-MM-dd HH:mm:ss` is fixed.
-
-To access complex JSON object fields you can use:
-
- function json_get_object(text, text) returns text
-
-It extractc child JSON object and returns it as text.
-Usage example, returns `{"boo":42}`:
-
- select json_get_object('{"foo":{"boo":42}, "bar": true}', 'foo')
-
-To access JSON object fields, that contain arrays, there are functions for different array types
-(including arrays of objects and multidimensional arrays), this example returns `array[42,43]`:
-
- json_get_int_array('{"boo": [42, 43]}', 'boo')
-
-Arrays with different element types are not supported
-
-__Function for converting JSON arrays into PostgreSQL arrays:__
-
- function json_array_to_text_array(text) returns text[]
-
-Usage example, returns `array['foo', 'bar']`:
-
- select json_array_to_text_array('["foo", "bar"]')
-
-There are also similar functions returning `boolean[]`, `int[]`, `bigint[]`, `numeric[]` and `timestamp without timezone[]`.
-All primitive arrays returns from Java functions in boxed form (`Boolean[]` etc.) to allow returning `NULL` elements.
-Having nulls in such arrays is not a good idea, but "Cannot assign null to int" errors in stored functions are worse.
-Functions for arrays of objects and multidimensional arrays return `text[]`.
+Please consult with [doc/json_accessors.md](doc/json_accessors.md) for a function reference.
Installing extension
View
@@ -11,16 +11,7 @@ Extension is compatible witgh PostgreSQL 9.1 and 9.2.
Description
-----------
-[PostgreSQL](http://www.postgresql.org/) stored functions for accessing [JSON](http://www.json.org/) fields.
-
-This project contains PostgreSQL [extension](http://www.postgresql.org/docs/9.1/static/extend-extensions.html) `json_accessors` with stored functions. Extension is native and writen in C on top of [cJSON](http://sourceforge.net/projects/cjson/) library.
-
-PostgreSQL have had no JSON support until version 9.2, which [introduced some support](http://www.postgresql.org/docs/9.2/static/functions-json.html).
-These 9.2 functions won't help with indexing JSON data.
-
-JSON parsing functions may be written using [PL/V8](http://code.google.com/p/plv8js/wiki/PLV8) module,
-[this article](http://people.planetpostgresql.org/andrew/index.php?/archives/249-Using-PLV8-to-index-JSON.html) has an example of PL/V8 usage.
-Project provides accessor functions for JSON without using PL/V8.
+[PostgreSQL](http://www.postgresql.org/) native extension with stored functions for accessing [JSON](http://www.json.org/) fields.
Usage
-----
@@ -117,21 +108,21 @@ Functions convert JSON arrays to PostgreSQL arrays.
#### json_array_to_object_array(text) -> text[]
-Converts a JSON array of JSON objects to PG array `text[]`.
+Converts a JSON array of any JSON objects to PG array `text[]`. Each object is represented as a string.
Example:
- TODO
select json_array_to_object_array('[{"foo":42}, {"bar":[]}]') = array['{"foo":42}','{"bar":[]}']
#### json_array_to_multi_array(text) -> text[]
-Cnverts a JSON array of JSON arrays to PG array of text arrays `text[]`.
+_Experimental_
+
+Converts a JSON array of any depth (single or multidimensional) to a PG multidimensional array. Original JSON must contains only arrays, objects are not allowed.
Example:
- TODO fix a primer
select json_array_to_multi_array('[["foo", "bar"], []]') = array[['foo','bar'], []];
#### json_array_to_text_array(text) -> text[]
@@ -172,20 +163,20 @@ Array is referenced in a JSON expression by a key.
#### json_get_object_array(text, text) -> text[]
-Extract and converts a JSON array of JSON objects to PG array `text[]`.
+Extract and converts a JSON array of any JSON objects to PG array `text[]`. JSON objects are represented as a text.
Example:
- TODO
select json_get_object_array('{"key" : [{"foo":42}, {"bar":[]}]}', 'key') = array['{"foo":42}','{"bar":[]}'];
#### json_get_multi_array(text, text) -> text[]
+_Experimental_
+
Extract and converts a JSON array of JSON arrays to PG array of text arrays `text[]`.
Example:
- TODO
select json_get_multi_array('{"key" : [["foo", "bar"], []] }', 'key') = array[['foo','bar'], []];
#### json_get_text_array(text, text) -> text[]
View
@@ -26,7 +26,7 @@ create or replace function json_get_bigint(text, text) returns bigint
create or replace function json_get_numeric(text, text) returns numeric
as 'MODULE_PATHNAME' language C immutable strict;
-create or replace function json_get_timestamp(text, text) returns timestamp without timezone
+create or replace function json_get_timestamp(text, text) returns timestamp without time zone
as 'MODULE_PATHNAME' language C immutable strict;
-- Array functions
View
@@ -471,7 +471,7 @@ bool extract_json_to_string(cJSON *elem, DatumPtr result)
bool extract_object_array(cJSON *elem, DatumPtr result)
{
- *result = json_array_to_array_generic_impl(elem, cJSON_String, TEXTOID, extract_json_to_string);
+ *result = json_array_to_array_generic_impl(elem, CJSON_TYPE_ANY, TEXTOID, extract_json_to_string);
return true;
}
@@ -538,13 +538,9 @@ Datum json_array_to_object_array(PG_FUNCTION_ARGS)
return json_array_to_array_generic_args(fcinfo, CJSON_TYPE_ANY, TEXTOID, extract_json_to_string);
}
-/**
- *
- * Added to mirror java function, but this one doesn't check element types before converting them to string
- *
- */
Datum json_array_to_multi_array(PG_FUNCTION_ARGS)
{
+ // TODO convert to multidim
return json_array_to_array_generic_args(fcinfo, CJSON_TYPE_ANY, TEXTOID, extract_json_to_string);
}
@@ -593,13 +589,9 @@ Datum json_get_object_array(PG_FUNCTION_ARGS)
return json_object_get_generic_args(fcinfo, cJSON_Array, extract_object_array);
}
-/**
- *
- * Added to mirror java function, but this one doesn't check element types before converting them to string
- *
- */
Datum json_get_multi_array(PG_FUNCTION_ARGS)
{
+ // TODO convert to multidim
return json_object_get_generic_args(fcinfo, cJSON_Array, extract_object_array);
}
@@ -75,6 +75,9 @@ select json_get_object('{"foo":"qq", "bar": ["baz1", "baz2", "baz3"]}', 'foo');
-- ["baz1","baz2","baz3"]
select json_get_object('{"foo":"qq", "bar": ["baz1", "baz2", "baz3"]}', 'bar');
["baz1","baz2","baz3"]
+-- {"baz1":"baz2"}
+select json_get_object('{"foo":"qq", "bar": {"baz1": "baz2"}}', 'bar');
+{"baz1":"baz2"}
-- {baz1,baz2,baz3}
select json_array_to_text_array(json_get_object('{"foo":"qq", "bar": ["baz1", "baz2", "baz3"]}', 'bar'));
{baz1,baz2,baz3}
@@ -87,5 +90,8 @@ select json_array_to_object_array('[{"foo":42}, {"bar":[]}]');
-- {"[\"foo\",\"bar\"]",[]}
select json_array_to_multi_array('[["foo", "bar"], []]');
{"[\"foo\",\"bar\"]",[]}
+-- {"{\"foo\":42}","{\"bar\":[]}"}
+select json_get_object_array('{"key" : [{"foo":42}, {"bar":[]}]}', 'key');
+{"{\"foo\":42}","{\"bar\":[]}"}
\t off
\pset format aligned
View
@@ -58,6 +58,8 @@ select json_get_timestamp_array('{"foo":"qq", "bar": ["2009-12-01 01:23:45", "20
select json_get_object('{"foo":"qq", "bar": ["baz1", "baz2", "baz3"]}', 'foo');
-- ["baz1","baz2","baz3"]
select json_get_object('{"foo":"qq", "bar": ["baz1", "baz2", "baz3"]}', 'bar');
+-- {"baz1":"baz2"}
+select json_get_object('{"foo":"qq", "bar": {"baz1": "baz2"}}', 'bar');
-- {baz1,baz2,baz3}
select json_array_to_text_array(json_get_object('{"foo":"qq", "bar": ["baz1", "baz2", "baz3"]}', 'bar'));
-- baz2
@@ -68,5 +70,8 @@ select json_array_to_object_array('[{"foo":42}, {"bar":[]}]');
-- {"[\"foo\",\"bar\"]",[]}
select json_array_to_multi_array('[["foo", "bar"], []]');
+-- {"{\"foo\":42}","{\"bar\":[]}"}
+select json_get_object_array('{"key" : [{"foo":42}, {"bar":[]}]}', 'key');
+
\t off
\pset format aligned

0 comments on commit b3e5e5e

Please sign in to comment.