Class: DocumentStoreTransaction

Represents a document store transaction. The transaction object shares all methods from the DocumentStore except for the transactional methods. You can not create a nested transaction!

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.
: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.
: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 DocumentStoreTransaction: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 DocumentStoreTransaction: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 DocumentStoreTransaction: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: remove

function DocumentStoreTransaction: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 DocumentStoreTransaction: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 DocumentStoreTransaction: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 DocumentStoreTransaction: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: 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 DocumentStoreTransaction: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 DocumentStoreTransaction: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