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;

// params array value types and slot assignments

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

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

	Btree1Bits = 20,	// Btree1 page size in bits	(int)
	Btree1Xtra,			// leaf page extra bits	(int)

	Btree2Bits = 23,	// Btree2 page size in bits	(int)
	Btree2Xtra,			// leaf page extra bits	(int)

	CursorDeDup = 25,	// de-duplicate cursor results	(bool)

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

typedef union {
	uint64_t intVal;
	uint32_t offset;
	double dblVal;
	char charVal;
	bool boolVal;
	DbAddr addr;
	void *obj;
} Params;

// types of handles/arenas

typedef enum {
	Hndl_newarena = 0,
	Hndl_catalog,
	Hndl_database,
	Hndl_docStore,
	Hndl_artIndex,
	Hndl_btree1Index,
	Hndl_btree2Index,
	Hndl_colIndex,
	Hndl_iterator,
	Hndl_cursor,
	Hndl_txns
} HandleType;