EJDB2 platforms matrix

Native language bindings

Unofficial EJDB2 language bindings

Status

Used by

macOS

brew install ejdb

Building from sources

git clone --recurse-submodules git@github.com:Softmotions/ejdb.gitmkdir build && cd buildcmake .. -DCMAKE_BUILD_TYPE=Releasemake install

Linux

Building debian packages

mkdir build&&cd buildcmake .. -DCMAKE_BUILD_TYPE=Release -DPACKAGE_DEB=ONmake package

RPM based Linux distributions

mkdir build&&cd buildcmake .. -DCMAKE_BUILD_TYPE=Release -DPACKAGE_RPM=ONmake package

Windows

IWSTART

WARNING: Unsupported now. Maintainer needed.

Android

Sample Android application

JQL

JQL grammar

Non formal JQL grammar adapted for brief overview

QUERY = FILTERS [ '|' APPLY ] [ '|' PROJECTIONS ] [ '|' OPTS ];STR = { quoted_string | unquoted_string };JSONVAL = json_value;PLACEHOLDER = { ':'placeholder_name | '?' }FILTERS = FILTER [{ and | or } [ not ] FILTER];  FILTER = [@collection_name]/NODE[/NODE]...;  NODE = { '*' | '**' | NODE_EXPRESSION | STR };  NODE_EXPRESSION = '[' NODE_EXPR_LEFT OP NODE_EXPR_RIGHT ']'                        [{ and | or } [ not ] NODE_EXPRESSION]...;  OP =   [ '!' ] { '=' | '>=' | '<=' | '>' | '<' | ~ }      | [ '!' ] { 'eq' | 'gte' | 'lte' | 'gt' | 'lt' }      | [ not ] { 'in' | 'ni' | 're' };  NODE_EXPR_LEFT = { '*' | '**' | STR | NODE_KEY_EXPR };  NODE_KEY_EXPR = '[' '*' OP NODE_EXPR_RIGHT ']'  NODE_EXPR_RIGHT =  JSONVAL | STR | PLACEHOLDERAPPLY = { 'apply' | 'upsert' } { PLACEHOLDER | json_object | json_array  } | 'del'OPTS = { 'skip' n | 'limit' n | 'count' | 'noidx' | 'inverse' | ORDERBY }...  ORDERBY = { 'asc' | 'desc' } PLACEHOLDER | json_pathPROJECTIONS = PROJECTION [ {'+' | '-'} PROJECTION ]  PROJECTION = 'all' | json_path

JQL quick introduction

{"firstName":"John","lastName":"Doe","age":28,"pets": [    {"name":"Rexy rex","kind":"dog","likes": ["bones","jumping","toys"]},    {"name":"Grenny","kind":"parrot","likes": ["green color","night","toys"]}  ]}

# Start HTTP/WS server protected by some access token./jbs -a'myaccess01'8 Mar 16:15:58.601 INFO: HTTP/WS endpoint at localhost:9191

curl -d'@sample.json' -H'X-Access-Token:myaccess01' -X POST http://localhost:9191/family

wscat  -H'X-Access-Token:myaccess01' -c http://localhost:9191connected (press CTRL+C to quit)> k info< k     {"version":"2.0.0","file":"db.jb","size": 8192,"collections": [  {"name":"family","dbid": 3,"rnum": 1,"indexes": []  } ]}> k get family 1< k     1       {"firstName":"John","lastName":"Doe","age": 28,"pets": [  {"name":"Rexy rex","kind":"dog","likes": ["bones","jumping","toys"   ]  },  {"name":"Grenny","kind":"parrot","likes": ["green color","night","toys"   ]  } ]}

<key> query <collection> <query>

Get all elements in collection

k query family /*

k query family /**

k @family/*

curl --data-raw '@family/[firstName = John]' -H'X-Access-Token:myaccess01' -X POST http://localhost:91911{"firstName":"John","lastName":"Doe","age":28,"pets":[{"name":"Rexy rex","kind":"dog","likes":["bones","jumping","toys"]},{"name":"Grenny","kind":"parrot","likes":["green color","night","toys"]}]}

Set the maximum number of elements in result set

k @family/* | limit 10

Get documents where specified json path exists

> k query family /pets/*/likes/1< k     1       {"firstName":"John"...

> k query family /**/likes/1< k     1       {"firstName":"John"...

Get documents by primary key

> k @users/=112

awaitdb.createQuery('@jobs/ = :? | apply :? | count').setNumber(0,id).setJSON(1,{ tags}).completionPromise();

awaitdb.createQuery('@jobs/ = :?| apply :? | count').setJSON(0,[23,1,2]).setJSON(1,{ tags}).completionPromise();

Matching JSON entry values

/pets/*/[name = "Rexy rex"]/pets/*/[name eq "Rexy rex"]/pets/*/[name = "Rexy rex" or name = Grenny]

/[age > 20] and /pets/*/likes/[** in ["bones", "toys"]]

/pets/*/[likes ni "bones"]

( /[age <= 20] or /[lastName re "Do.*"] )  and /pets/*/likes/[** in ["bones", "toys"]]

/[lastName ~ Do]

Arrays and maps can be matched as is

/**/[likes = ["bones","jumping","toys"]]

Conditions on key names

/[* = "firstName"]

/[[* = "firstName"] = John]

/[[* in ["firstName", "lastName"]] = John]

/[[* = :keyName] = :keyValue]

JQL data modification

APPLY = ({'apply' | `upsert`} { PLACEHOLDER | json_object | json_array  }) | 'del'

/[firstName = John] | apply {"address":{"city":"New York", "street":""}}

/* | apply :?

/[firstName = John] | apply [{"op":"replace", "path":"/address/street", "value":"Fifth Avenue"}]

/[firstName = John]| apply [{"op":"add", "path":"/pets/-", "value": {"name":"Neo", "kind":"fish"}}]

/[firstName = John] | upsert {"firstName": "John", "address":{"city":"New York"}}

Non standard JSON patch extensions

increment

 Document:  {"foo": 1} Patch:     [{"op": "increment", "path": "/foo", "value": 2}] Result:    {"foo": 3}

add_create

Document: {"foo": {"bar": 1}}Patch:    [{"op": "add_create", "path": "/foo/zaz/gaz", "value": 22}]Result:   {"foo":{"bar":1,"zaz":{"gaz":22}}}

Document: {"foo": {"bar": 1}}Patch:    [{"op": "add_create", "path": "/foo/bar/gaz", "value": 22}]Result:   Error since element pointed by /foo/bar is not an object

swap

Document: {"foo": ["bar"], "baz": {"gaz": 11}}Patch:    [{"op": "swap", "from": "/foo/0", "path": "/baz/gaz"}]Result:   {"foo": [11], "baz": {"gaz": "bar"}}

Document: {"foo": ["bar"], "baz": {"gaz": 11}}Patch:    [{"op": "swap", "from": "/foo/0", "path": "/baz/zaz"}]Result:   {"foo":[],"baz":{"gaz":11,"zaz":"bar"}}

Removing documents

/FILTERS | del

> k add family {"firstName":"Jack"}< k     2> k query family /[firstName re "Ja.*"]< k     2       {"firstName":"Jack"}# Remove selected elements from collection> k query family /[firstName=Jack] | del< k     2       {"firstName":"Jack"}

JQL projections

PROJECTIONS = PROJECTION [ {'+' | '-'} PROJECTION ]  PROJECTION = 'all' | json_path | join_clause

$ cat<<EOF | curl -d @- -H'X-Access-Token:myaccess01' -X POST http://localhost:9191/family{"firstName":"Jack","lastName":"Parker","age":35,"pets":[{"name":"Sonic", "kind":"mouse", "likes":[]}]}EOF

> k query family /* | /{firstName,lastName}< k     3       {"firstName":"Jack","lastName":"Parker"}< k     1       {"firstName":"John","lastName":"Doe"}< k

> k query family /* | /{firstName,lastName} + /pets< k     3       {"firstName":"Jack","lastName":"Parker","pets":[...< k     1       {"firstName":"John","lastName":"Doe","pets":[...

> k query family /* | all - /pets< k     3       {"firstName":"Jack","lastName":"Parker","age":35}< k     1       {"firstName":"John","lastName":"Doe","age":28,"address":{"city":"New York","street":"Fifth Avenue"}}< k

> k query family /[age > 20] | /age + /pets/0< k     3       {"age":35,"pets":[{"name":"Sonic","kind":"mouse","likes":[]}]}< k     1       {"age":28,"pets":[{"name":"Rexy rex","kind":"dog","likes":["bones","jumping","toys"]}]}< k

JQL collection joins

/.../field<collection

> k add artists {"name":"Leonardo Da Vinci", "years":[1452,1519]}< k     1> k add paintings {"name":"Mona Lisa", "year":1490, "origin":"Italy", "artist": 1}< k     1> k add paintings {"name":"Madonna Litta - Madonna And The Child", "year":1490, "origin":"Italy", "artist": 1}< k     2# Lists paintings documents> k @paintings/*< k     2       {"name":"Madonna Litta - Madonna And The Child","year":1490,"origin":"Italy","artist":1}< k     1       {"name":"Mona Lisa","year":1490,"origin":"Italy","artist":1}< k># Do simple join with artists collection> k @paintings/* | /artist<artists< k     2       {"name":"Madonna Litta - Madonna And The Child","year":1490,"origin":"Italy",                  "artist":{"name":"Leonardo Da Vinci","years":[1452,1519]}}< k     1       {"name":"Mona Lisa","year":1490,"origin":"Italy",                  "artist":{"name":"Leonardo Da Vinci","years":[1452,1519]}}< k# Strip all document fields except `name` and `artist` join> k @paintings/* | /artist<artists + /name + /artist/*< k     2       {"name":"Madonna Litta - Madonna And The Child","artist":{"name":"Leonardo Da Vinci","years":[1452,1519]}}< k     1       {"name":"Mona Lisa","artist":{"name":"Leonardo Da Vinci","years":[1452,1519]}}< k># Same results as above:> k @paintings/* | /{name, artist<artists} + /artist/*< k     2       {"name":"Madonna Litta - Madonna And The Child","artist":{"name":"Leonardo Da Vinci","years":[1452,1519]}}< k     1       {"name":"Mona Lisa","artist":{"name":"Leonardo Da Vinci","years":[1452,1519]}}< k

>  k add paintings {"name":"Mona Lisa2", "year":1490, "origin":"Italy", "artist": 9999}< k     3> k @paintings/* |  /artist<artists< k     3       {"name":"Mona Lisa2","year":1490,"origin":"Italy","artist":9999}< k     2       {"name":"Madonna Litta - Madonna And The Child","year":1490,"origin":"Italy","artist":{"name":"Leonardo Da Vinci","years":[1452,1519]}}< k     1       {"name":"Mona Lisa","year":1490,"origin":"Italy","artist":{"name":"Leonardo Da Vinci","years":[1452,1519]}}

JQL results ordering

  ORDERBY = ({ 'asc' | 'desc' } PLACEHOLDER | json_path)...

> k add family {"firstName":"John", "lastName":"Ryan", "age":39}< k     4

> k query family /* | /{firstName,lastName,age} | asc /firstName desc /age< k     3       {"firstName":"Jack","lastName":"Parker","age":35}< k     4       {"firstName":"John","lastName":"Ryan","age":39}< k     1       {"firstName":"John","lastName":"Doe","age":28}< k

JQL Options

OPTS = { 'skip' n | 'limit' n | 'count' | 'noidx' | 'inverse' | ORDERBY }...

JQL Indexes and performance tips

> k idx family 4 /lastName< k

> k explain family /[lastName=Doe] and /[age!=27]< k     explain [INDEX] MATCHED  STR|3 /lastName EXPR1: 'lastName = Doe' INIT: IWKV_CURSOR_EQ[INDEX] SELECTED STR|3 /lastName EXPR1: 'lastName = Doe' INIT: IWKV_CURSOR_EQ [COLLECTOR] PLAIN

Performance tip: Physical ordering of documents

Performance tip: Brute force scan vs indexed access

Performance tip: Get rid of unnecessary document data

HTTP REST/Websocket API endpoint

jbs server

Usage: ./jbs [options]-v, --versionPrint program version.-f, --file=<>Database file path. Default: ejdb2.db-p, --port=NUMHTTP server port numer. Default: 9191-l, --listen=<>Network address server will listen. Default: localhost-k, --key=<>PEM private key file for TLS 1.2 HTTP server.-c, --certs=<>PEM certificates file for TLS 1.2 HTTP server.-a, --access=TOKEN|@FILEAccess token to match 'X-Access-Token' HTTP header value.-r, --access-readAllows unrestricted read-only data access.-C, --corsEnable COSR response headers for HTTP server-t, --truncCleanup/reset database file on open.-w, --waluse the write ahead log (WAL). Used to provide data durability.Advanced options:-S, --sbz=NUMMax sorting buffer size. If exceeded, an overflow temp file for data will be created.                  Default: 16777216, min: 1048576-D, --dsz=NUMInitial size of buffer to process/store document on queries. Preferable average size of document.                   Default: 65536, min: 16384-T, --trylock Exit with error if database is locked by another process.                 If not set, current process will wait for lock release.

HTTP API

REST API

POST /{collection}

PUT /{collection}/{id}

DELETE /{collection}/{id}

PATCH /{collection}/{id}

GET | HEAD /{collections}/{id}

POST /

curl -v --data-raw '@family/[age > 18]' -H 'X-Access-Token:myaccess01' http://localhost:9191* Rebuilt URL to: http://localhost:9191/*   Trying 127.0.0.1...* TCP_NODELAY set* Connected to localhost (127.0.0.1) port 9191 (#0)> POST / HTTP/1.1> Host: localhost:9191> User-Agent: curl/7.58.0> Accept: */*> X-Access-Token:myaccess01> Content-Length: 18> Content-Type: application/x-www-form-urlencoded>* upload completely sent off: 18 out of 18 bytes< HTTP/1.1 200 OK< connection:keep-alive< content-type:application/json< transfer-encoding:chunked<4{"firstName":"John","lastName":"Ryan","age":39}3{"firstName":"Jack","lastName":"Parker","age":35,"pets":[{"name":"Sonic","kind":"mouse","likes":[]}]}1{"firstName":"John","lastName":"Doe","age":28,"pets":[{"name":"Rexy rex","kind":"dog","likes":["bones","jumping","toys"]},{"name":"Grenny","kind":"parrot","likes":["green color","night","toys"]}],"address":{"city":"New York","street":"Fifth Avenue"}}* Connection #0 to host localhost left intact

curl --data-raw '@family/[lastName = "Ryan"]' -H 'X-Access-Token:myaccess01' -H 'X-Hints:explain' http://localhost:9191[INDEX] MATCHED  STR|3 /lastName EXPR1: 'lastName = "Ryan"' INIT: IWKV_CURSOR_EQ[INDEX] SELECTED STR|3 /lastName EXPR1: 'lastName = "Ryan"' INIT: IWKV_CURSOR_EQ [COLLECTOR] PLAIN--------------------4{"firstName":"John","lastName":"Ryan","age":39}

OPTIONS /

curl -X OPTIONS -H 'X-Access-Token:myaccess01'  http://localhost:9191/{ "version": "2.0.0", "file": "db.jb", "size": 16384, "collections": [  {   "name": "family",   "dbid": 3,   "rnum": 3,   "indexes": [    {     "ptr": "/lastName",     "mode": 4,     "idbf": 64,     "dbid": 4,     "rnum": 3    }   ]  } ]}

Websocket API

Commands

?

wscat  -H 'X-Access-Token:myaccess01' -c http://localhost:9191> ?<<key> info<key> get     <collection> <id><key> set     <collection> <id> <document json><key> add     <collection> <document json><key> del     <collection> <id><key> patch   <collection> <id> <patch json><key> idx     <collection> <mode> <path><key> rmi     <collection> <mode> <path><key> rmc     <collection><key> query   <collection> <query><key> explain <collection> <query><key> <query>>

<key> ERROR: <error description>

<key> info

<key> get <collection> <id>

> k get family 3< k     3       { "firstName": "Jack", "lastName": "Parker", "age": 35, "pets": [  {   "name": "Sonic",   "kind": "mouse",   "likes": []  } ]}

> k get family 55< k ERROR: Key not found. (IWKV_ERROR_NOTFOUND)>

<key> set <collection> <id> <document json>

<key> add <collection> <document json>

> k add mycollection {"foo":"bar"}< k     1> k add mycollection {"foo":"bar"}< k     2>

<key> del <collection> <id>

<key> patch <collection> <id> <patch json>

<key> query <collection> <query>

> k query family /* | /firstName< k     4       {"firstName":"John"}< k     3       {"firstName":"Jack"}< k     1       {"firstName":"John"}< k

<key> explain <collection> <query>

> k explain family /* | /firstName< k     explain [INDEX] NO [COLLECTOR] PLAIN< k     4       {"firstName":"John"}< k     3       {"firstName":"Jack"}< k     1       {"firstName":"John"}< k

<key> idx <collection> <mode> <path>

Example

k idx mycollection 5 /name

<key> rmi <collection> <mode> <path>

<key> rmc <collection>

Docker support

cd dockerdocker build -t ejdb2 .docker run -d -p 9191:9191 --name myEJDB ejdb2 --access myAccessKey

docker run -d -p 9191:9191 --name myEJDB softmotions/ejdb2 --access myAccessKey

C API

#include<ejdb2/ejdb2.h>#defineCHECK(rc_)          \  if (rc_) {                 \    iwlog_ecode_error3(rc_); \    return 1;                \  }staticiwrcdocuments_visitor(EJDB_EXEC*ctx,constEJDB_DOCdoc,int64_t*step) {// Print document to stderrreturnjbl_as_json(doc->raw,jbl_fstream_json_printer,stderr,JBL_PRINT_PRETTY);}intmain() {EJDB_OPTSopts= {    .kv= {      .path="example.db",      .oflags=IWKV_TRUNC    }  };EJDBdb;// EJDB2 storage handleint64_tid;// Document id placeholderJQLq=0;// Query instanceJBLjbl=0;// Json documentiwrcrc=ejdb_init();CHECK(rc);rc=ejdb_open(&opts,&db);CHECK(rc);// First recordrc=jbl_from_json(&jbl,"{\"name\":\"Bianca\", \"age\":4}");RCGO(rc,finish);rc=ejdb_put_new(db,"parrots",jbl,&id);RCGO(rc,finish);jbl_destroy(&jbl);// Second recordrc=jbl_from_json(&jbl,"{\"name\":\"Darko\", \"age\":8}");RCGO(rc,finish);rc=ejdb_put_new(db,"parrots",jbl,&id);RCGO(rc,finish);jbl_destroy(&jbl);// Now execute a queryrc=jql_create(&q,"parrots","/[age > :age]");RCGO(rc,finish);EJDB_EXECux= {    .db=db,    .q=q,    .visitor=documents_visitor  };// Set query placeholder value.// Actual query will be /[age > 3]rc=jql_set_i64(q,"age",0,3);RCGO(rc,finish);// Now execute the queryrc=ejdb_exec(&ux);finish:jql_destroy(&q);jbl_destroy(&jbl);ejdb_close(&db);CHECK(rc);return0;}

gcc -std=gnu11 -Wall -pedantic -c -o example1.o example1.cgcc -o example1 example1.o -lejdb2./example1{ "name": "Darko", "age": 8}{ "name": "Bianca", "age": 4}

License

MIT LicenseCopyright (c) 2012-2024 Softmotions Ltd <info@softmotions.com>Permission is hereby granted, free of charge, to any person obtaining a copyof this software and associated documentation files (the "Software"), to dealin the Software without restriction, including without limitation the rightsto use, copy, modify, merge, publish, distribute, sublicense, and/or sellcopies of the Software, and to permit persons to whom the Software isfurnished to do so, subject to the following conditions:The above copyright notice and this permission notice shall be included in allcopies or substantial portions of the Software.THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS ORIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THEAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHERLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THESOFTWARE.