From 5f5035c25938daed666bd4cc1d01c7a94ce24403 Mon Sep 17 00:00:00 2001 From: Adamansky Anton Date: Thu, 18 Jul 2013 07:52:05 -0700 Subject: [PATCH] Update README --- tcejdb/README | 281 +--------------------------------------------------------- 1 file changed, 1 insertion(+), 280 deletions(-) diff --git a/tcejdb/README b/tcejdb/README index a588221..21bf2c7 100644 --- a/tcejdb/README +++ b/tcejdb/README @@ -1,280 +1 @@ -[![EJDB](https://raw.github.com/Softmotions/ejdb/master/misc/ejdblogo3.png)](http://ejdb.org) - - -Embedded JSON Database engine -==================================== - -It aims to be a fast [MongoDB](http://mongodb.org)-like library **which can be embedded into C/C++/NodeJS/Python/Lua/Java applications under terms of LGPL license.** - -EJDB is the C library based on modified version of [Tokyo Cabinet](http://fallabs.com/tokyocabinet/). - -JSON representation of queries and data implemented with API based on [C BSON](https://github.com/mongodb/mongo-c-driver/tree/master/src/) - -News -=============================== -* `2013-04-03` **[Java API binding available](https://github.com/Softmotions/ejdb/blob/master/jejdb/)** -* `2013-03-20` **[Lua binding available](https://github.com/Softmotions/ejdb/blob/master/luaejdb/)** -* `2013-02-15` **[EJDB Python3 binding available](https://github.com/Softmotions/ejdb/blob/master/pyejdb/)** -* `2013-02-07` **[Debian packages provided](https://github.com/Softmotions/ejdb/wiki/Debian-Ubuntu-installation)** -* `2013-01-22` **[Collection joins now supported](https://github.com/Softmotions/ejdb/wiki/Collection-joins)** - -Features -================================ -* LGPL license allows you to embed this library into proprietary software. -* MongoDB-like queries and overall philosophy. -* Collection level write locking. -* Collection level transactions. -* String token matching queries: ```$stror``` ```$strand``` -* [Node.js](http://nodejs.org) binding -* [Collection joins](https://github.com/Softmotions/ejdb/wiki/Collection-joins) -* Python binding -* Lua binding -* Java binding - -EJDB C Library -================================== - -One snippet intro ------------------------------------ - -~~~~~~ -#include - -static EJDB *jb; - -int main() { - jb = ejdbnew(); - if (!ejdbopen(jb, "addressbook", JBOWRITER | JBOCREAT | JBOTRUNC)) { - return 1; - } - //Get or create collection 'contacts' - EJCOLL *coll = ejdbcreatecoll(jb, "contacts", NULL); - - bson bsrec; - bson_oid_t oid; - - //Insert one record: - //JSON: {'name' : 'Bruce', 'phone' : '333-222-333', 'age' : 58} - bson_init(&bsrec); - bson_append_string(&bsrec, "name", "Bruce"); - bson_append_string(&bsrec, "phone", "333-222-333"); - bson_append_int(&bsrec, "age", 58); - bson_finish(&bsrec); - //Save BSON - ejdbsavebson(coll, &bsrec, &oid); - fprintf(stderr, "\nSaved Bruce"); - bson_destroy(&bsrec); - - //Now execute query - //QUERY: {'name' : {'$begin' : 'Bru'}} //Name starts with 'Bru' string - bson bq1; - bson_init_as_query(&bq1); - bson_append_start_object(&bq1, "name"); - bson_append_string(&bq1, "$begin", "Bru"); - bson_append_finish_object(&bq1); - bson_finish(&bq1); - - EJQ *q1 = ejdbcreatequery(jb, &bq1, NULL, 0, NULL); - - uint32_t count; - TCLIST *res = ejdbqryexecute(coll, q1, &count, 0, NULL); - fprintf(stderr, "\n\nRecords found: %d\n", count); - - //Now print the result set records - for (int i = 0; i < TCLISTNUM(res); ++i) { - void *bsdata = TCLISTVALPTR(res, i); - bson_print_raw(bsdata, 0); - } - fprintf(stderr, "\n"); - - //Dispose result set - tclistdel(res); - - //Dispose query - ejdbquerydel(q1); - bson_destroy(&bq1); - - //Close database - ejdbclose(jb); - ejdbdel(jb); - return 0; -} -~~~~~~ - -You can save this code in `csnippet.c` And build: - - -```sh -gcc -std=c99 -Wall -pedantic -c -o csnippet.o csnippet.c -gcc -o csnippet csnippet.o -ltcejdb -``` - -Building & Installation --------------------------------- - -[Installing on Debian/Ubuntu](https://github.com/Softmotions/ejdb/wiki/Debian-Ubuntu-installation) - -Manual installation -------------------------------- - -### Prerequisites -**System libraries:** - -* gcc -* zlib-dev - -### Build and install - -~~~~~~ - cd ./tcejdb - ./configure --prefix= && make && make check - make install -~~~~~~ -* library name: **tcejdb** (with pkgconfig) -* main include header: `````` - -C API ---------------------------------- -EJDB API presented in **[ejdb.h](https://github.com/Softmotions/ejdb/blob/master/tcejdb/ejdb.h)** C header file. - -JSON processing API: **[bson.h](https://github.com/Softmotions/ejdb/blob/master/tcejdb/bson.h)** - -Queries ---------------------------------- - -~~~~~~ -/** - * Create query object. - * Sucessfully created queries must be destroyed with ejdbquerydel(). - * - * EJDB queries inspired by MongoDB (mongodb.org) and follows same philosophy. - * - * - Supported queries: - * - Simple matching of String OR Number OR Array value: - * - {'fpath' : 'val', ...} - * - $not Negate operation. - * - {'fpath' : {'$not' : val}} //Field not equal to val - * - {'fpath' : {'$not' : {'$begin' : prefix}}} //Field not begins with val - * - $begin String starts with prefix - * - {'fpath' : {'$begin' : prefix}} - * - $gt, $gte (>, >=) and $lt, $lte for number types: - * - {'fpath' : {'$gt' : number}, ...} - * - $bt Between for number types: - * - {'fpath' : {'$bt' : [num1, num2]}} - * - $in String OR Number OR Array val matches to value in specified array: - * - {'fpath' : {'$in' : [val1, val2, val3]}} - * - $nin - Not IN - * - $strand String tokens OR String array val matches all tokens in specified array: - * - {'fpath' : {'$strand' : [val1, val2, val3]}} - * - $stror String tokens OR String array val matches any token in specified array: - * - {'fpath' : {'$stror' : [val1, val2, val3]}} - * - $exists Field existence matching: - * - {'fpath' : {'$exists' : true|false}} - * - $icase Case insensitive string matching: - * - {'fpath' : {'$icase' : 'val1'}} //icase matching - * Ignore case matching with '$in' operation: - * - {'name' : {'$icase' : {'$in' : ['tHéâtre - театр', 'heLLo WorlD']}}} - * For case insensitive matching you can create special index of type: `JBIDXISTR` - * - $elemMatch The $elemMatch operator matches more than one component within an array element. - * - { array: { $elemMatch: { value1 : 1, value2 : { $gt: 1 } } } } - * Restriction: only one $elemMatch allowed in context of one array field. - * - * - Queries can be used to update records: - * $set Field set operation. - * - {.., '$set' : {'field1' : val1, 'fieldN' : valN}} - * $upsert Atomic upsert. If matching records are found it will be '$set' operation, - * otherwise new record will be inserted with fields specified by argment object. - * - {.., '$upsert' : {'field1' : val1, 'fieldN' : valN}} - * $inc Increment operation. Only number types are supported. - * - {.., '$inc' : {'field1' : number, ..., 'field1' : number} - * $dropall In-place record removal operation. - * - {.., '$dropall' : true} - * $addToSet Atomically adds value to the array only if its not in the array already. - * If containing array is missing it will be created. - * - {.., '$addToSet' : {'fpath' : val1, 'fpathN' : valN, ...}} - * $addToSetAll Batch version if $addToSet - * - {.., '$addToSetAll' : {'fpath' : [array of values to add], ...}} - * $pull Atomically removes all occurrences of value from field, if field is an array. - * - {.., '$pull' : {'fpath' : val1, 'fpathN' : valN, ...}} - * $pullAll Batch version of $pull - * - {.., '$pullAll' : {'fpath' : [array of values to remove], ...}} - * - * NOTE: Negate operations: $not and $nin not using indexes - * so they can be slow in comparison to other matching operations. - * - * NOTE: Only one index can be used in search query operation. - * - * QUERY HINTS (specified by `hints` argument): - * - $max Maximum number in the result set - * - $skip Number of skipped results in the result set - * - $orderby Sorting order of query fields. - * - $fields Set subset of fetched fields - If a field presented in $orderby clause it will be forced to include in resulting records. - * Example: - * hints: { - * "$orderby" : { //ORDER BY field1 ASC, field2 DESC - * "field1" : 1, - * "field2" : -1 - * }, - * "$fields" : { //SELECT ONLY {_id, field1, field2} - * "field1" : 1, - * "field2" : 1 - * } - * } - * - * Many query examples can be found in `testejdb/t2.c` test case. - * - * @param EJDB database handle. - * @param qobj Main BSON query object. - * @param orqobjs Array of additional OR query objects (joined with OR predicate). - * @param orqobjsnum Number of OR query objects. - * @param hints BSON object with query hints. - * @return On success return query handle. On error returns NULL. - */ -EJDB_EXPORT EJQ* ejdbcreatequery(EJDB *jb, bson *qobj, bson *orqobjs, int orqobjsnum, bson *hints); -~~~~~~ - -EJDB C Samples ------------------------------------- -You can find some code samples in: - -* [tcejdb/samples](https://github.com/Softmotions/ejdb/tree/master/tcejdb/samples) -* [tcejdb/testejdb](https://github.com/Softmotions/ejdb/tree/master/tcejdb/testejdb) - -Basic EJDB architecture ------------------------------------- -**EJDB database files structure** - -~~~~~~ -. -├── -├── _ -├── ... -├── _ -└── __. -~~~~~~ - -Where - -* `````` - name of database. It is metadata DB. -* `````` - name of collection. Collection database. -* `````` - JSON field path used in index -* `````` - Collection index extension: - * ```.lex``` String index - * ```.dec``` Number index - * ```.tok``` Array index - -Limitations ------------------------------------- -* One ejdb database can handle up to 1024 collections. -* Indexes for objects in nested arrays currently not supported (#37) - -TODO ------------------------------------- -* Collect collection index statistic - -Related software ------------------------------------- -[Connect session store backed by EJDB database](https://github.com/Softmotions/connect-session-ejdb) - - +http://ejdb.org -- 2.7.4