Home

Database API

Create/Open a database file using the array of options. Fills-in hndl with the database handle. If the database doesn't exist, it will be created from the filePath specified. The database file will contain the names, specifications, and options for all collection and index files that make up the database. This allows deployment of a single file to instantiate an initial copy of the database in a new location.

DbStatus openDatabase(DbHandle hndl[1], char *filePath, uint32_t pathLen, Params *params);

Create/Open a document store within the database dbHndl using the params array of options. Fills-in hndl with the document collection file handle. The docStore name and creation options are added or updated in the database. The docStore file name is constructed by concatenating a dot and the docStore name onto the database filePath.

DbStatus openDocStore(DbHandle hndl[1], DbHandle dbHndl[1], char *name, uint32_t nameLen, Params *params);

Create/Open an index file under a docStore using the params array of options. The index file name is constructed by concatenating a dot and the index name onto the docStore file path.

DbStatus createIndex(DbHandle hndl[1], DbHandle docHndl[1], char *name, uint32_t nameLen, void *keySpec, uint16_t specSize, Params *params);

Create new cursor for the given index.

DbStatus createCursor(DbHandle hndl[1], DbHandle idxHndl[1], Params *params);

Release one of the returned handles and render it invalid.

DbStatus closeHandle(DbHandle hndl[1]);

Reposition the cursor according to the given operation op, and the key and keyLen.

DbStatus positionCursor(DbHandle hndl[1], CursorOp op, uint8_t *key, uint32_t keyLen);

OpFind:  position the cursor on the first key greater than or equal to the given key.
OpOne:   position the cursor as in OpFind, but limit OpNext and OpPrev operations to the single key found.
OpBefore: position the cursor immediately before the given key.
OpAfter:  position the cursor immediately after the given key.

Move the cursor according to the given operation.

DbStatus moveCursor(DbHandle hndl[1], CursorOp op);

OpLeft:  position the cursor before the first key in the associated index.
OpRight: position the cursor after the last key.
OpNext:  position the cursor on the next key.  The optional key sets a maximum key value.
OpPrev:  position the cursor on the previous key.  The optional key sets a minimum key value.

Return the cursor key pointer and length. Return a pointer to the cursor's key and its length.

DbStatus keyAtCursor(DbHandle hndl[1], uint8_t **key, uint32_t *keyLen);

Fetch a document from a docStore by docId. Return a pointer to it in doc.

DbStatus fetchDoc(DbHandle hndl[1], Doc **doc, ObjId docId);

Store a new document in a docStore. Return the newly created docId for the document

DbStatus storeDoc(DbHandle hndl[1], void *obj, uint32_t objSize, ObjId *docId);

Delete a key from an index

DbStatus deleteKey(DbHandle hndl[1], void *key, uint32_t len);

Insert a key into an index

DbStatus insertKey(DbHandle hndl[1], void *key, uint32_t len);

Create a document iterator. Return a handle for the iterator in hndl.

DbStatus createIterator(DbHandle hndl[1], DbHandle docHndl[1], Params *params);

Advance iterator forward and return a pointer to the next docid slot or NULL.

void *iteratorNext(DbHandle hndl[1]);

Advance iterator backward and return a pointer to the previous docId slot or NULL.

void *iteratorPrev(DbHandle hndl[1]);

Move iterator to a specific document ID, fill-in docId, and return a pointer to the document.

DbStatus moveIterator (DbHandle hndl[1], IteratorOp op, void **doc, ObjId *docId);

//	Iterator operations

typedef enum {
	IterNext  = 'n',
	IterPrev  = 'p',
	IterBegin = 'b',
	IterEnd   = 'e',
	IterSeek  = 's',
} IteratorOp;

// param slots

typedef enum {
	Size = 0,		// total Params structure size
	OnDisk,			// Arena resides on disk
	InitSize,		// initial arena size
	HndlXtra,		// extra bytes in handle struct
	ObjIdSize,		// size of arena ObjId array element
	MapXtra,		// local process extra map storage
	ArenaXtra,		// extra bytes in arena
	ResetVersion,	// reset arena version

	IdxKeyUnique = 10,
	IdxKeyDeferred,		// uniqueness constraints deferred to commit
	IdxKeyAddr,			// index key definition address
	IdxKeySparse,
	IdxKeyPartial,		// offset of partial document
	IdxKeyFlds,			// store field lengths in keys
	IdxType,			// 0 for artree, 1 & 2 for btree
	IdxNoDocs,			// stand-alone index file

	Btree1Bits = 20,	// Btree1 set
	Btree1Xtra,

	Btree2Bits = 23,	// Btree2 set
	Btree2Xtra,

	CursorDeDup = 25,	// de-duplicate cursor results

	UserParams = 30,
	MaxParam = 64		// count of param slots defined
} ParamSlot;