Content-Length: 15580 | pFad | http://github.com/postgrespro/jsquery/pull/5.patch

thub.com From 1f710fb2f1e45ac32962f1c35a7b9b5b7f66f056 Mon Sep 17 00:00:00 2001 From: niquola Date: Mon, 17 Nov 2014 22:24:10 +0300 Subject: [PATCH 1/3] Start documentation & travis ci --- .gitignore | 1 + .travis.yml | 8 ++++ .travis/install | 47 ++++++++++++++++++++++ .travis/test | 17 ++++++++ Dockerfile | 56 ++++++++++++++++++++++++++ README.md | 102 +++++++++++++++++++++++++++++++++++++++++++++++ doc/indexes.md | 0 doc/intro.md | 39 ++++++++++++++++++ doc/jsquery.ebnf | 75 ++++++++++++++++++++++++++++++++++ doc/operators.md | 0 doc/optimizer.md | 0 doc/syntax.md | 74 ++++++++++++++++++++++++++++++++++ 12 files changed, 419 insertions(+) create mode 100644 .travis.yml create mode 100755 .travis/install create mode 100755 .travis/test create mode 100644 Dockerfile create mode 100644 README.md create mode 100644 doc/indexes.md create mode 100644 doc/intro.md create mode 100644 doc/jsquery.ebnf create mode 100644 doc/operators.md create mode 100644 doc/optimizer.md create mode 100644 doc/syntax.md diff --git a/.gitignore b/.gitignore index b32b222..c4700b5 100644 --- a/.gitignore +++ b/.gitignore @@ -6,3 +6,4 @@ jsquery_gram.h regression.diffs regression.out results +*sw? diff --git a/.travis.yml b/.travis.yml new file mode 100644 index 0000000..2d16d6a --- /dev/null +++ b/.travis.yml @@ -0,0 +1,8 @@ +before_script: + - sudo su $USER -c ".travis/install" + +script: sudo su $USER -c ".travis/test" + +addons: + postgresql: "9.3" + diff --git a/.travis/install b/.travis/install new file mode 100755 index 0000000..ebc252f --- /dev/null +++ b/.travis/install @@ -0,0 +1,47 @@ +#!/bin/bash + +export ROOT=`pwd` +export BUILD_DIR=/home/travis/build/pg +export SOURCE_DIR=$BUILD_DIR/src + +export PGDATA=$BUILD_DIR/data +export PGPORT=5777 +export PGHOST=localhost + +export PG_BIN=$BUILD_DIR/bin +export PG_CONFIG=$BUILD_DIR + +export PATH=$PATH:$PG_BIN + +sudo apt-get -y -qq --purge remove postgresql libpq-dev libpq5 postgresql-client-common postgresql-common +sudo apt-get -qq update +sudo apt-get -qqy install \ + git \ + build-essential \ + gettext \ + libreadline6 \ + libreadline6-dev \ + zlib1g-dev \ + flex \ + bison \ + libxml2-dev \ + libxslt-dev + +git clone -b REL9_4_STABLE --depth=1 git://git.postgresql.org/git/postgresql.git $SOURCE_DIR + +# XML2_CONFIG=`which xml2-config` cd $SOURCE_DIR ./configure --prefix=$BUILD_DIR --with-libxml &&\ + +cd $SOURCE_DIR && ./configure --prefix=$BUILD_DIR && make && make install + + +cd $ROOT && make USE_PGXS=1 && make install USE_PGXS=1 + +mkdir -p $PGDATA + +$PG_BIN/initdb -D $PGDATA -E utf8 + +# echo "host all all 0.0.0.0/0 md5" >> $PGDATA/pg_hba.conf +# echo "listen_addresses='*'" >> $PGDATA/postgresql.conf +# echo "port=$PGPORT" >> $PGDATA/postgresql.conf + +$PG_BIN/pg_ctl -D $PGDATA start diff --git a/.travis/test b/.travis/test new file mode 100755 index 0000000..0dd1289 --- /dev/null +++ b/.travis/test @@ -0,0 +1,17 @@ +#!/bin/bash + +export BUILD_DIR=/home/travis/build/pg +export SOURCE_DIR=$BUILD_DIR/src + +export PGDATA=$BUILD_DIR/data +export PGPORT=5777 +export PGHOST=localhost + +export PG_BIN=$BUILD_DIR/bin +export PG_CONFIG=$BUILD_DIR + +export PATH=$PATH:$PG_BIN + +export ROOT=`pwd` + +make installcheck USE_PGXS=1 diff --git a/Dockerfile b/Dockerfile new file mode 100644 index 0000000..4c90d3b --- /dev/null +++ b/Dockerfile @@ -0,0 +1,56 @@ +FROM ubuntu:14.04 +MAINTAINER Nikolay Ryzhikov + +RUN apt-get -qq update +RUN apt-get -qqy install git \ + build-essential \ + gettext \ + libreadline6 \ + libreadline6-dev \ + zlib1g-dev \ + flex \ + bison \ + libxml2-dev \ + libxslt-dev + +RUN echo "en_US.UTF-8 UTF-8" > /etc/locale.gen && locale-gen + +RUN useradd -m -s /bin/bash db && echo "db:db"|chpasswd && adduser db sudo +RUN echo 'db ALL=(ALL) NOPASSWD: ALL' >> /etc/sudoers + +USER db +ENV HOME /home/db +ENV PG_BRANCH REL9_4_STABLE +ENV PG_REPO git://git.postgresql.org/git/postgresql.git + +RUN git clone -b $PG_BRANCH --depth=1 $PG_REPO $HOME/src +RUN cd $HOME/src && ./configure --prefix=$HOME/bin && make && make install + +ENV SOURCE_DIR $HOME/src + +ENV PATH $HOME/bin/bin:$PATH +ENV PGDATA $HOME/data +ENV PGPORT 5432 +ENV PGHOST localhost +RUN mkdir -p $PGDATA +RUN initdb -D $PGDATA -E utf8 + +RUN echo "host all all 0.0.0.0/0 md5" >> $PGDATA/pg_hba.conf +RUN echo "listen_addresses='*'" >> $PGDATA/postgresql.conf +RUN echo "port=$PGPORT" >> $PGDATA/postgresql.conf + +RUN pg_ctl -D $HOME/data -w start && psql postgres -c "alter user db with password 'db';" + +RUN pg_ctl -D $HOME/data -w start && \ + cd $SOURCE_DIR/contrib/pgcrypto && \ + make && make install && make installcheck && \ + pg_ctl -w stop + +RUN pg_ctl -D $HOME/data -w start && \ + cd $SOURCE_DIR/contrib && \ + git clone https://github.com/akorotkov/jsquery.git && \ + cd jsquery && make && make install && make installcheck && \ + pg_ctl -w stop + +EXPOSE 5432 +CMD pg_ctl -D $HOME/data -w start && psql postgres diff --git a/README.md b/README.md new file mode 100644 index 0000000..cbf9938 --- /dev/null +++ b/README.md @@ -0,0 +1,102 @@ +# jsquery + +[![Build Status](https://travis-ci.org/niquola/jsquery.svg)](https://travis-ci.org/niquola/jsquery) + +`Jsquery` is PostgreSQL extension, +which provides advanced query language for jsonb documents. + +Features: + +* recursive structure of query +* search in array +* rich set of comparison operators +* types support +* schema support (constraints on keys, values) +* indexes support +* hinting support + +Jsquery implemented as datatype `jsquery` and operator `@@`. + +Examples: + +`#` - any element array + +```SQL +SELECT '{"a": {"b": [1,2,3]}}'::jsonb @@ 'a.b.# = 2'; +``` + +`%` - any key + +```SQL +SELECT '{"a": {"b": [1,2,3]}}'::jsonb @@ '%.b.# = 2'; +``` + +`*` - anything + +```SQL +SELECT '{"a": {"b": [1,2,3]}}'::jsonb @@ '*.# = 2'; +``` + +`$` - current element + +```SQL +select '{"a": {"b": [1,2,3]}}'::jsonb @@ 'a.b.# ($ = 2 OR $ < 3)'; +``` + +Use "double quotes" for key ! + +```SQL +select 'a1."12222" < 111'::jsquery; +``` + +## Documentation + +* [Getting Started](doc/intro.md) +* [Syntax](doc/syntax.md) +* [Operators](doc/operators.md) +* [Indexes](doc/indexes.md) +* [Optimizer](doc/optimiser.md) + +## Installation + +Requirements: + +* PostgreSQL >= 9.4 + +### Using pgxn.org ? + +http://pgxn.org/ + +### Build from sources + +```sh +git clone https://github.com/akorotkov/jsquery.git $SOURCE_DIR/contrib +cd $SOURCE_DIR/contrib/jsquery && make && make install && make installcheck + +``` + +### Using docker + +``` +docker run --name=myjsquery -p 5432:5555 -i -t jsquery/jsquery + +psql -p 5555 +``` + +## Roadmap + +* TODO1 +* TODO2 + +## Contribution + +You can contribute by: + +* stars +* [issues](https://github.com/akorotkov/jsquery/issues) +* documentation +* pull requests + +## License + +MIT? diff --git a/doc/indexes.md b/doc/indexes.md new file mode 100644 index 0000000..e69de29 diff --git a/doc/intro.md b/doc/intro.md new file mode 100644 index 0000000..6f35f98 --- /dev/null +++ b/doc/intro.md @@ -0,0 +1,39 @@ +# Jsquery intro + +```jsquery``` implemented as datatype and `@@` operator. + +Search query has a form: + +```SQL +SELECT * FROM mytable + WHERE jsonb_column @@ 'jsquery_expression'; +``` + + +```jsquery_expression``` usually consists +of *path* and *value_expression*. + +For example if we are looking for: + +```json +{ + "user": { + "name": "Diego" + }, + "site": { + "url": "diego.com" + } +} +``` + +the expresion is: + +``` +user.name = 'diego' +``` + +Sevral expressions could be connected using `AND` & `OR` operators: + +``` +user.name = 'diego' AND site.url = 'diego.com' +``` diff --git a/doc/jsquery.ebnf b/doc/jsquery.ebnf new file mode 100644 index 0000000..5424995 --- /dev/null +++ b/doc/jsquery.ebnf @@ -0,0 +1,75 @@ +result ::= ( expr | null) + +array ::= '[' value_list ']' + +scalar_value ::= ( + STRING_P + | IN_P + | IS_P + | OR_P + | AND_P + | NOT_P + | NULL_P + | TRUE_P + | ARRAY_T + | FALSE_P + | NUMERIC_T + | OBJECT_T + | STRING_T + | BOOLEAN_T + | NUMERIC_P ) + +value_list ::= (scalar_value | value_list ',' scalar_value) + +right_expr ::= ( + '='right_exprscalar_value + | IN_P '(' value_list ')' + | '=' array + | '=' '*' + | '<' NUMERIC_P + | '>' NUMERIC_P + | '<' '=' NUMERIC_P + | '>' '=' NUMERIC_P + | '@' '>' array + | '<' '@' array + | '&' '&' array + | IS_P ARRAY_T + | IS_P NUMERIC_T + | IS_P OBJECT_T + | IS_P STRING_T + | IS_P BOOLEAN_T ) + +expr ::= ( + path right_expr + | path HINT_P right_expr + | NOT_P expr + | NOT_P HINT_P right_expr + | NOT_P right_expr + | path '(' expr ')' + | '(' expr ')' + | expr AND_P expr + | expr OR_P expr) + +key ::= ( + '*' + | '#' + | '%' + | '$' + | STRING_P + | IN_P + | IS_P + | OR_P + | AND_P + | NULL_P + | TRUE_P + | ARRAY_T + | FALSE_P + | NUMERIC_T + | OBJECT_T + | STRING_T + | BOOLEAN_T + | NUMERIC_P ) + +key_any ::= ( key | NOT_P) + +path ::= ( key | path '.' key_any | NOT_P '.' key_any ) diff --git a/doc/operators.md b/doc/operators.md new file mode 100644 index 0000000..e69de29 diff --git a/doc/optimizer.md b/doc/optimizer.md new file mode 100644 index 0000000..e69de29 diff --git a/doc/syntax.md b/doc/syntax.md new file mode 100644 index 0000000..1b39533 --- /dev/null +++ b/doc/syntax.md @@ -0,0 +1,74 @@ +## Syntax + +```jsquery``` expresion usually consists of *path* and *value_expression*: + +```json +{ + "user": { + "name": "Diego" + }, + "site": { + "url": "diego.com" + } +} +``` + +``` +user.name = 'diego' +``` + + +```ebnf + expr ::= path value_expr + | path HINT value_expr + | NOT expr + | NOT HINT value_expr + | NOT value_expr + | path '(' expr ')' + | '(' expr ')' + | expr AND expr + | expr OR expr + + value_expr ::= '=' scalar_value + | IN '(' value_list ')' + | '=' array + | '=' '*' + | '<' NUMERIC + | '<' '=' NUMERIC + | '>' NUMERIC + | '>' '=' NUMERIC + | '@' '>' array + | '<' '@' array + | '&' '&' array + | IS ARRAY + | IS NUMERIC + | IS OBJECT + | IS STRING + | IS BOOLEAN + + path ::= key + | path '.' key_any + | NOT '.' key_any + + key ::= '*' + | '#' + | '%' + | '$' + | STRING + + key_any ::= key + | NOT + + value_list ::= scalar_value + | value_list ',' scalar_value + + array ::= '[' value_list ']' + + scalar_value ::= null + | STRING + | true + | false + | NUMERIC + | OBJECT +``` + From a0126023de3ca2bda14bb206cd898c2a828b58c9 Mon Sep 17 00:00:00 2001 From: niquola Date: Wed, 10 Dec 2014 13:47:54 +0300 Subject: [PATCH 2/3] readme --- README.md | 30 ++++++++++++++++++------------ 1 file changed, 18 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index cbf9938..299fe82 100644 --- a/README.md +++ b/README.md @@ -63,30 +63,26 @@ Requirements: * PostgreSQL >= 9.4 -### Using pgxn.org ? - -http://pgxn.org/ - ### Build from sources ```sh git clone https://github.com/akorotkov/jsquery.git $SOURCE_DIR/contrib cd $SOURCE_DIR/contrib/jsquery && make && make install && make installcheck -``` +# or not from pg sources -### Using docker +git clone https://github.com/akorotkov/jsquery.git +cd jsquery && make USE_PGXS=1 && make install USE_PGXS=1 ``` -docker run --name=myjsquery -p 5432:5555 -i -t jsquery/jsquery -psql -p 5555 -``` +### Using docker + +TODO ## Roadmap -* TODO1 -* TODO2 +* Implement jsquery as extension of SQL syntax ## Contribution @@ -97,6 +93,16 @@ You can contribute by: * documentation * pull requests +## Authors + +* Oleg Bartunov +* Teodor Sigaev +* Alexand Korotkov + +## Regards + +Development is sponsored by [Wargaming.net] + ## License -MIT? +GPL From e5766ce226ff482bfe4b3a72699e7d33bef50ccf Mon Sep 17 00:00:00 2001 From: niquola Date: Fri, 26 Dec 2014 00:57:20 +0300 Subject: [PATCH 3/3] update readme --- README.md | 6 ++-- doc/intro.md | 89 ++++++++++++++++++++++++++++++++++++++++++++++++++-- 2 files changed, 90 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 299fe82..f7bac6a 100644 --- a/README.md +++ b/README.md @@ -2,6 +2,7 @@ [![Build Status](https://travis-ci.org/niquola/jsquery.svg)](https://travis-ci.org/niquola/jsquery) + `Jsquery` is PostgreSQL extension, which provides advanced query language for jsonb documents. @@ -15,6 +16,7 @@ Features: * indexes support * hinting support + Jsquery implemented as datatype `jsquery` and operator `@@`. Examples: @@ -51,9 +53,7 @@ select 'a1."12222" < 111'::jsquery; ## Documentation -* [Getting Started](doc/intro.md) -* [Syntax](doc/syntax.md) -* [Operators](doc/operators.md) +* [Syntax](doc/intro.md) * [Indexes](doc/indexes.md) * [Optimizer](doc/optimiser.md) diff --git a/doc/intro.md b/doc/intro.md index 6f35f98..3d6343e 100644 --- a/doc/intro.md +++ b/doc/intro.md @@ -26,14 +26,99 @@ For example if we are looking for: } ``` -the expresion is: +the expression is: ``` user.name = 'diego' ``` -Sevral expressions could be connected using `AND` & `OR` operators: +Sevral expressions could be connected using boolean `AND` & `OR` operators: ``` user.name = 'diego' AND site.url = 'diego.com' ``` + +Expression could be negated with `NOT` operator: + +``` +NOT user.name = 'diego' +``` + +JSON value could be one following types: + +* array +* numeric +* object +* string +* boolean + +You can check type using `is` operator: + +``` +user.name is array +user.name is numeric +user.name is object +user.name is string +user.name is boolean +``` + +For all types you `=` (equality) operator is defined: + +``` +user.roles = ["admin","root"] +user.age = 3 +user.active = true +user.address = {city: "SPb"} +user.name = "diego" +``` + +For numerics there are expected comparison operators: + +``` +x > 1 AND x < 10 +x >= 1 AND x <= 10 +``` + +To check that scalar value belongs to some list: + +```sql +select '{a: 2}'::jsonb @@ 'a IN (1,2,5)'; +``` + +For arrays there are convenient operators: + +```sql +-- overlap +select '{"a": {"b": [1,2,3]}}'::jsonb @@ 'a.b && [1,2,5]'; + +-- contains +select '{"a": {"b": [1,2,3]}}'::jsonb @@ 'a.b @> [1,2]'; + +-- contained +select '{"a": {"b": [1,2,3]}}'::jsonb @@ 'a.b <@ [1,2,3,4,5]' +``` + +If you just want to check that some path exists in json document use `=*`: + +select '{"a": {"b": [1,2,3]}}'::jsonb @@ 'a.b = *' + + +Path expression supports wild cards: + +`#` - any alement of array +`%` - any key in object +`*` - any path + +```sql +select '{a: {b: {c: 1}}}'::jsonb @@ '*.c = 1' +select '{a: {b: {c: 1}}}'::jsonb @@ 'a.%.c = 1' +select '{a: {b: [1,2]}}'::jsonb @@ 'a.b.# = 1' +``` + +jsquery expression could be expressed recursively using `()`: + +``` +address(city = "SPB" AND street = "Nevskiy") +``` + +This means eval `city = "SPB" AND street = "Nevskiy"` expression in context of `address` attribute.

pFad - (p)hone/(F)rame/(a)nonymizer/(d)eclutterfier! Saves Data!