goejdb

package module
v0.0.0-...-4004152 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 21, 2015 License: LGPL-2.1 Imports: 6 Imported by: 1

README

EJDB Go binding Build Status

One snippet intro

package ejdbtutorial

import (
    "fmt"
    "github.com/mkilling/goejdb"
    "labix.org/v2/mgo/bson"
    "os"
)

func main() {
    // Create a new database file and open it
    jb, err := goejdb.Open("addressbook", JBOWRITER | JBOCREAT | JBOTRUNC)
    if err != nil {
        os.Exit(1)
    }
    // Get or create collection 'contacts'
    coll, _ := jb.CreateColl("contacts", nil)

    // Insert one record:
    // JSON: {'name' : 'Bruce', 'phone' : '333-222-333', 'age' : 58}
    rec := map[string]interface{} {"name" : "Bruce", "phone" : "333-222-333", "age" : 58}
    bsrec, _ := bson.Marshal(rec)
    coll.SaveBson(bsrec)
    fmt.Printf("\nSaved Bruce")

    // Now execute query
    res, _ := coll.Find(`{"name" : {"$begin" : "Bru"}}`) // Name starts with 'Bru' string
    fmt.Printf("\n\nRecords found: %d\n", len(res))

    // Now print the result set records
    for _, bs := range res {
        var m map[string]interface{}
        bson.Unmarshal(bs, &m)
        fmt.Println(m)
    }

    // Close database
    jb.Close()
}

You can save this code in ejdbtutorial.go and build:

go build ejdbtutorial.go
./ejdbtutorial

Installation

Prerequisites

System libraries:

Install
go get github.com/mkilling/goejdb

Queries

// Create query object.
// Sucessfully created queries must be destroyed with Query.Del().
//
// 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], ...}}
//
// - Collection joins supported in the following form:
//
//      {..., $do : {fpath : {$join : 'collectionname'}} }
//      Where 'fpath' value points to object's OIDs from 'collectionname'. Its value
//      can be OID, string representation of OID or array of this pointers.
//
//  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.
func (ejdb *Ejdb) CreateQuery(query string, queries ...string) (*EjQuery, *EjdbError)

Documentation

Index

Constants

View Source 
const (
	// Drop index.
	JBIDXDROP = C.JBIDXDROP
	// Drop index for all types.
	JBIDXDROPALL = C.JBIDXDROPALL
	// Optimize indexes.
	JBIDXOP = C.JBIDXOP
	// Rebuild index.
	JBIDXREBLD = C.JBIDXREBLD
	// Number index.
	JBIDXNUM = C.JBIDXNUM
	// String index.*/
	JBIDXSTR = C.JBIDXSTR
	// Array token index.
	JBIDXARR = C.JBIDXARR
	// Case insensitive string index
	JBIDXISTR = C.JBIDXISTR
)

Index modes, index types.

View Source 
const (
	// Open as a reader.
	JBOREADER = C.JBOREADER
	// Open as a writer.
	JBOWRITER = C.JBOWRITER
	// Create if db file not exists.
	JBOCREAT = C.JBOCREAT
	// Truncate db on open.
	JBOTRUNC = C.JBOTRUNC
	// Open without locking.
	JBONOLCK = C.JBONOLCK
	// Lock without blocking.
	JBOLCKNB = C.JBOLCKNB
	// Synchronize every transaction.
	JBOTSYNC = C.JBOTSYNC
)

Database open modes

View Source 
const (
	// Invalid collection name.
	JBEINVALIDCOLNAME = C.JBEINVALIDCOLNAME
	// Invalid bson object.
	JBEINVALIDBSON = C.JBEINVALIDBSON
	// Invalid bson object id.
	JBEINVALIDBSONPK = C.JBEINVALIDBSONPK
	// Invalid query control field starting with '$'.
	JBEQINVALIDQCONTROL = C.JBEQINVALIDQCONTROL
	// $strand, $stror, $in, $nin, $bt keys requires not empty array value.
	JBEQINOPNOTARRAY = C.JBEQINOPNOTARRAY
	// Inconsistent database metadata.
	JBEMETANVALID = C.JBEMETANVALID
	// Invalid field path value.
	JBEFPATHINVALID = C.JBEFPATHINVALID
	// Invalid query regexp value.
	JBEQINVALIDQRX = C.JBEQINVALIDQRX
	// Result set sorting error.
	JBEQRSSORTING = C.JBEQRSSORTING
	// Query generic error.
	JBEQERROR = C.JBEQERROR
	// Updating failed.
	JBEQUPDFAILED = C.JBEQUPDFAILED
	// Only one $elemMatch allowed in the fieldpath.
	JBEQONEEMATCH = C.JBEQONEEMATCH
	// $fields hint cannot mix include and exclude fields
	JBEQINCEXCL = C.JBEQINCEXCL
	// action key in $do block can only be one of: $join
	JBEQACTKEY = C.JBEQACTKEY
	// Exceeded the maximum number of collections per database
	JBEMAXNUMCOLS = C.JBEMAXNUMCOLS
)

Error codes

Variables

This section is empty.

Functions

func IsValidOidStr 

func IsValidOidStr(oid string) bool

Return true if passed `oid` string cat be converted to valid 12 bit BSON object identifier (OID).

func Open 

func Open(path string, options int) (*Ejdb, *EjdbError)

Returns a new open EJDB database. path is the path to the database file. options specify the open mode bitmask flags.

func Version 

func Version() string

Returns EJDB library version string. Eg: "1.1.13"

Types

type EjColl 

type EjColl struct {
	// contains filtered or unexported fields
}

An EJDB collection

func (*EjColl) AbortTransaction 

func (coll *EjColl) AbortTransaction() *EjdbError

Abort transaction for EJDB collection.

func (*EjColl) BeginTransaction 

func (coll *EjColl) BeginTransaction() *EjdbError

Begin transaction for EJDB collection.

func (*EjColl) CommitTransaction 

func (coll *EjColl) CommitTransaction() *EjdbError

Commit transaction for EJDB collection.

func (*EjColl) Count 

func (coll *EjColl) Count(query string, queries ...string) (int, *EjdbError)

Execute a query specified by JSON strings query, queries and return the number of results, not the results themselves. See the documentation of EjQuery for a description of the query format.

func (*EjColl) Find 

func (coll *EjColl) Find(query string, queries ...string) ([][]byte, *EjdbError)

Execute a query specified by JSON strings query, queries and return the results as a slice of BSON objects See the documentation of EjQuery for a description of the query format.

func (*EjColl) FindOne 

func (coll *EjColl) FindOne(query string, queries ...string) (*[]byte, *EjdbError)

Execute a query specified by JSON strings query, queries and return only the first result as a BSON object See the documentation of EjQuery for a description of the query format.

func (*EjColl) IsTransactionActive 

func (coll *EjColl) IsTransactionActive() bool

Get current transaction status. Return true if a transaction is active, false otherwise.

func (*EjColl) LoadBson 

func (coll *EjColl) LoadBson(oid string) []byte

EJDB_EXPORT bson* ejdbloadbson(EJCOLL *coll, const bson_oid_t *oid);

func (*EjColl) RmBson 

func (coll *EjColl) RmBson(oid string) bool

EJDB_EXPORT bool ejdbrmbson(EJCOLL *coll, bson_oid_t *oid);

func (*EjColl) SaveBson 

func (coll *EjColl) SaveBson(bsdata []byte) (string, *EjdbError)

Persist BSON object in the collection. If saved bson does't have _id primary key then `oid` will be set to generated bson _id, otherwise `oid` will be set to the current bson's _id field.

NOTE: Field names of passed `bs` object may not contain `$` and `.` characters, 

error condition will be fired in this case.

BSON object must be a byte slice, for instance one created by the "labix.org/v2/mgo/bson" library

func (*EjColl) SaveJson 

func (coll *EjColl) SaveJson(j string) (string, *EjdbError)

Persist JSON string in the collection. If saved json does't have _id primary key then `oid` will be set to generated bson _id, otherwise `oid` will be set to the current json's _id field.

NOTE: Integer literals in the JSON string will be converted to float64

func (*EjColl) SetIndex 

func (coll *EjColl) SetIndex(ipath string, flags int) *EjdbError

Set index for JSON field in EJDB collection.

  • Available index types:

  • `JBIDXSTR` String index for JSON string values.

  • `JBIDXISTR` Case insensitive string index for JSON string values.

  • `JBIDXNUM` Index for JSON number values.

  • `JBIDXARR` Token index for JSON arrays and string values.

  • One JSON field can have several indexes for different types.

  • Available index operations:

  • `JBIDXDROP` Drop index of specified type.

  • Eg: flag = JBIDXDROP | JBIDXNUM (Drop number index)

  • `JBIDXDROPALL` Drop index for all types.

  • `JBIDXREBLD` Rebuild index of specified type.

  • `JBIDXOP` Optimize index of specified type. (Optimize the B+ tree index file)

    Examples:

  • Set index for JSON path `addressbook.number` for strings and numbers: `ccoll.SetIndex("album.number", JBIDXSTR | JBIDXNUM)`

  • Set index for array: `ccoll.SetIndex("album.tags", JBIDXARR)`

  • Rebuild previous index: `ccoll.SetIndex("album.tags", JBIDXARR | JBIDXREBLD)`

func (*EjColl) Sync 

func (coll *EjColl) Sync() (bool, *EjdbError)

Synchronize content of a EJDB collection database with the file on device. On success return true.

func (*EjColl) Update 

func (coll *EjColl) Update(query string, queries ...string) (int, *EjdbError)

EJDB_EXPORT uint32_t ejdbupdate(EJCOLL *jcoll, bson *qobj, bson *orqobjs, int orqobjsnum, bson *hints, TCXSTR *log);

type EjCollOpts 

type EjCollOpts struct {
	// Large collection. It can be larger than 2GB. Default false
	Large bool
	// Collection records will be compressed with DEFLATE compression. Default: false
	Compressed bool
	// Expected records number in the collection. Default: 128K
	Records int
	// Maximum number of cached records. Default: 0
	CachedRecords int
}

EJDB collection tuning options

type EjQuery 

type EjQuery struct {
	// contains filtered or unexported fields
}

An EJDB query

func (*EjQuery) AddOr 

func (q *EjQuery) AddOr(orquery string) *EjdbError

Add OR restriction to query object. Expects orquery to be a JSON string.

func (*EjQuery) Count 

func (q *EjQuery) Count(coll *EjColl) (int, *EjdbError)

Execute the query and only return the number of results it returned, not the results themselves

func (*EjQuery) Del 

func (q *EjQuery) Del()

Delete the query. This must be called in order to not leak memory.

func (*EjQuery) Execute 

func (q *EjQuery) Execute(coll *EjColl) ([][]byte, *EjdbError)

Execute the query and return all results as a slice of BSON objects

func (*EjQuery) ExecuteOne 

func (q *EjQuery) ExecuteOne(coll *EjColl) (*[]byte, *EjdbError)

Execute the query and return only the first result as a BSON object

func (*EjQuery) SetHints 

func (q *EjQuery) SetHints(hints string) *EjdbError

Set query hints. `hints` is a JSON string

  • $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 } }

type Ejdb 

type Ejdb struct {
	// contains filtered or unexported fields
}

An EJDB database

func (*Ejdb) Close 

func (ejdb *Ejdb) Close() *EjdbError

Close a table database object. If a writer opens a database but does not close it appropriately, the database will be broken. If successful return true, otherwise return false.

func (*Ejdb) Command 

func (ejdb *Ejdb) Command(bson []byte) (*[]byte, *EjdbError)

Execute ejdb database command.

Supported commands:

  1. Exports database collections data. See ejdbexport() method.

    "export" : { "path" : string, //Exports database collections data "cnames" : [string array]|null, //List of collection names to export "mode" : int|null //Values: null|`JBJSONEXPORT` See ejdbexport() method }

    Command response: { "log" : string, //Diagnostic log about executing this command "error" : string|null, //ejdb error message "errorCode" : int|0, //ejdb error code }

  2. Imports previously exported collections data into ejdb.

    "import" : { "path" : string //The directory path in which data resides "cnames" : [string array]|null, //List of collection names to import "mode" : int|null //Values: null|`JBIMPORTUPDATE`|`JBIMPORTREPLACE` See ejdbimport() method }

    Command response: { "log" : string, //Diagnostic log about executing this command "error" : string|null, //ejdb error message "errorCode" : int|0, //ejdb error code }

func (*Ejdb) CreateColl 

func (ejdb *Ejdb) CreateColl(colname string, opts *EjCollOpts) (*EjColl, *EjdbError)

Same as GetColl() but automatically creates new collection if it doesn't exists.

func (*Ejdb) CreateQuery 

func (ejdb *Ejdb) CreateQuery(query string, queries ...string) (*EjQuery, *EjdbError)

Create query object. Sucessfully created queries must be destroyed with Query.Del().

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], ...}}

- Collection joins supported in the following form: 

    {..., $do : {fpath : {$join : 'collectionname'}} }
    Where 'fpath' value points to object's OIDs from 'collectionname'. Its value
    can be OID, string representation of OID or array of this pointers.

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.

func (*Ejdb) Del 

func (ejdb *Ejdb) Del()

Delete database object. If the database is not closed, it is closed implicitly. Note that the deleted object and its derivatives can not be used anymore

func (*Ejdb) Export 

func (ejdb *Ejdb) Export(path string, cnames *[]string, flags int) (log string, err *EjdbError)

Exports database collections data to the specified directory. Database read lock will be taken on each collection.

NOTE: Only data exported as BSONs can be imported with `Ejdb.Import()`

`path` is the directory path in which data will be exported. `cnames` is a list of collection names to export. `nil` implies that all existing collections will be exported. `flags` can be set to `JBJSONEXPORT` in order to export data as JSON files instead exporting into BSONs. Export() returns the log for the operation as a string

func (*Ejdb) GetColl 

func (ejdb *Ejdb) GetColl(colname string) (*EjColl, *EjdbError)

Retrieve collection handle for collection specified `collname`. If collection with specified name does't exists it will return nil.

func (*Ejdb) GetColls 

func (ejdb *Ejdb) GetColls() ([]*EjColl, *EjdbError)

Return a slice containing shallow copies of all collection handles (EjColl) currently open.

func (*Ejdb) Import 

func (ejdb *Ejdb) Import(path string, cnames *[]string, flags int) (log string, err *EjdbError)

Imports previously exported collections data into ejdb. Global database write lock will be applied during import operation.

NOTE: Only data exported as BSONs can be imported with `Ejdb.Import()`

`path` is the directory path in which data resides. `cnames` is a list of collection names to import. `nil` implies that all collections found in `path` will be imported. `flags` can be one of: 

`JBIMPORTUPDATE`  Update existing collection entries with imported ones.
                  Existing collections will not be recreated.
                  For existing collections options will not be imported.

`JBIMPORTREPLACE` Recreate existing collections and replace
                  all their data with imported entries.
                  Collections options will be imported.

`0`              Implies `JBIMPORTUPDATE`

Import() returns the log for the operation as a string

func (*Ejdb) IsOpen 

func (ejdb *Ejdb) IsOpen() bool

Return true if database is in open state, false otherwise

func (*Ejdb) JsonCommand 

func (ejdb *Ejdb) JsonCommand(json string) (*[]byte, *EjdbError)

func (*Ejdb) Meta 

func (ejdb *Ejdb) Meta() ([]byte, *EjdbError)

Gets description of EJDB database and its collections as a BSON object.

func (*Ejdb) RmColl 

func (ejdb *Ejdb) RmColl(colname string, unlinkfile bool) (bool, *EjdbError)

Removes collections specified by `colname`. If `unlinkfile` is true the collection db file and all of its index files will be removed. If removal was successful return true, otherwise return false.

func (*Ejdb) Sync 

func (ejdb *Ejdb) Sync() (bool, *EjdbError)

Synchronize entire EJDB database and all of its collections with storage.

type EjdbError 

type EjdbError struct {
	// Error code returned by EJDB
	ErrorCode int
	// contains filtered or unexported fields
}

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.