Permalink
Browse files

Some docs what this is all about and how to use it

  • Loading branch information...
1 parent 9cf1391 commit dd8443ef2479385f0f0f635b36a53244632fc742 @claesjac committed Sep 5, 2011
Showing with 65 additions and 0 deletions.
  1. +65 −0 README
View
65 README
@@ -0,0 +1,65 @@
+pg-json - JSON support for PostgreSQL
+-------------------------------------
+
+This is a postgres extension which provides a JSON type and rudimentary opertators
+and functions on them. It uses the Jansson JSON library (http://www.digip.org/jansson/)
+which you need installed and findable by your linker.
+
+INSTALL
+--------------
+$ make
+$ make install
+$ psql -f <path to pg-json.sql> <your database>
+
+USAGE
+-------------
+This module provides a 'json' datatype. It's more or less just a bytea which assumes that
+the data is UTF-8 encoded. When created it validates that it's parseable as JSON.
+
+Functions
+---------
+
+* json_get_value(data json, path text) : text
+
+ In the json value "data" returns the element for a given "path". The "path" is a combination of keys (separated by .) and array indices (specified in []). For example in the structure '{"foo": {"bar": "quax"}}' the path to the value "quax" would be "foo.bar".
+
+ More examples
+
+ 'foo[3][2]' from '{"foo":[1,2,3, [3,4,5]]}' returns '5'
+ 'foo.bar[2].orz' from '{"foo": {"bar": [{}, {}, {"orz", "herp"}]}}' returns 'herp'
+
+* json_equals(this json, that json) : boolean
+
+ Checks if the value "this" is equal to "that". This definition of equality (stolen from Jansson documentation) sums it up
+
+ "
+ Two JSON values can be equal not only if they are exactly the same value, but also if they have equal “contents”:
+
+ - Two integer or real values are equal if their contained numeric values are equal. An integer value is never equal to a real value, though.
+ - Two strings are equal if their contained UTF-8 strings are equal, byte by byte. Unicode comparison algorithms are not implemented.
+ - Two arrays are equal if they have the same number of elements and each element in the first array is equal to the corresponding element in the second array.
+ - Two objects are equal if they have exactly the same keys and the value for each key in the first object is equal to the value of the corresponding key in the second object.
+ - Two true, false or null values have no “contents”, so they are equal if their types are equal.
+ "
+
+* json_not_equals(this json, that json) : boolean
+
+ The inverse of json_equals().
+
+Operators
+---------
+
+* json ~ text
+
+ This is the operator version of json_get_value
+
+* json = json
+
+ This is the operator version of json_equals
+
+* json != json
+
+ This is the operator version of json_not_equals
+
+
+

0 comments on commit dd8443e

Please sign in to comment.