Class: DocumentStore

Document store provides a document-like access to the database. You can use it to acess any persistent data within the game.

Methods

Name	Description
:get(doc,id)	Returns a document specified by a primary key, or nil if not found.
:getByIndex(doc,index,key)	Returns a document integer ID and the document based on document's index name
:insert(doc,value)	Inserts a new document and returns its new ID as an integer.
:newTransaction()	Creates a new transaction object
:remove(doc,id)
:seek(doc,start)	Creates a new DocumentStoreDocumentCursor that can go through all documents.
:seekIndex(doc,name,key)	Creates a new DocumentStoreIndexCursor that can go through all documents specified by an index name.
:seekRange(doc,start,end)	Creates a new DocumentStoreDocumentCursor that can go through all documents in a range.
:transaction(fn)	Creates a new transaction and runs it inside a callback function.
:update(doc,id,value_or_func)	Updates the document given its integer ID with a specific value or a callback function.
:upsert(doc,value)	Inserts a new document or updates an existing one. The document schema must define

Method declarations

Method: get

Returns a document specified by a primary key, or nil if not found.

function DocumentStore:get(
    doc,
    id
) end

Parameters:

• doc (string) - The document name
• id (integer) - The document ID to get

Returns:

• boolean|string|number|table|nil - The value of the document or nil if not found

Method: getByIndex

Returns a document integer ID and the document based on document's index name and index key value. Returns two values (a tuple). First one is the document id and second one is the document itself.

function DocumentStore:getByIndex(
    doc,
    index,
    key
) end

Parameters:

• doc (string) - The document name
• index (string) - The name of the document index (schema defined!)
• key (boolean|string|number) - The value of the index key

Returns:

• number - The document ID or 0 if not found

• any - The document value or nil if not found

Method: insert

Inserts a new document and returns its new ID as an integer. The document ID is always non-zero.

function DocumentStore:insert(
    doc,
    value
) end

Parameters:

• doc (string) - The document name
• value (boolean|string|number|table) - The value to insert

Returns:

• integer - The new document ID that was inserted

Method: newTransaction

Creates a new transaction object

function DocumentStore:newTransaction() end

Returns:

• DocumentStoreTransaction - A new transaction object

Method: remove

function DocumentStore:remove(
    doc,
    id
) end

Parameters:

• doc (string) - The document name
• id (integer) - The document ID to delete

Method: seek

Creates a new DocumentStoreDocumentCursor that can go through all documents. The starting document ID is used as the beginning where the cursor will start from.

function DocumentStore:seek(
    doc,
    start
) end

Parameters:

• doc (string) - The document name
• start (integer) - The document ID where to start the seek from (inclusive)

Returns:

• DocumentStoreDocumentCursor - A new cursor object

Method: seekIndex

Creates a new DocumentStoreIndexCursor that can go through all documents specified by an index name. This can be used in situations where you want to find all documents which have a specific index value.

function DocumentStore:seekIndex(
    doc,
    name,
    key
) end

Parameters:

• doc (string) - The document name
• name (string) - The name of the document index (from schema!)
• key (boolean|string|number) - The value of the index key

Returns:

• DocumentStoreIndexCursor - A new cursor object

Method: seekRange

Creates a new DocumentStoreDocumentCursor that can go through all documents in a range. The starting document ID is used as the beginning where the cursor will start from. The end document ID is used as the end of iteration.

function DocumentStore:seekRange(
    doc,
    start,
    end
) end

Parameters:

• doc (string) - The document name
• start (integer) - The document ID where to start the seek from (inclusive)
• end (integer) - The document ID where to stop the seek at (inclusive)

Returns:

• DocumentStoreDocumentCursor - A new cursor object

Method: transaction

Creates a new transaction and runs it inside a callback function.

The callback function must accept a single argument of DocumentStoreTransaction! Also, the callback function must return boolean true or false depending whether to complete or abort (rollback) the transaction.

Any error raised inside the callback will abort the transaction and the error is re-thrown.

function DocumentStore:transaction(
    fn
) end

Parameters:

• fn (function) - A callback function where the transaction will run

Returns:

• boolean - True if the transaction has completed or false otherwise

Method: update

Updates the document given its integer ID with a specific value or a callback function. If a callback function is used, then the function must accept a single argument which is the value that is found, and must return an updated value that should be saved. Raises an error if the document by such ID does not exist.

If you need to update by an index, use a transaction istead!

function DocumentStore:update(
    doc,
    id,
    value_or_func
) end

Parameters:

• doc (string) - The document name
• id (integer) - The document ID to update
• value_or_func (boolean|string|number|function|table) - The value to update, or a callback function

Method: upsert

Inserts a new document or updates an existing one. The document schema must define a unique field which will be hashed and used as a unique constraint. If the document with such unique field already exists, it will be updated. If the document with such unique field does not exist, it will be created. Raises an error if the document schema does not define a unique field.

function DocumentStore:upsert(
    doc,
    value
) end

Parameters:

• doc (string) - The document name
• value (any) - The document value to insert

Returns:

• integer - new or existing integer ID of the inserted or updated document