Collections

You will need a collection object for these methods. See Database.

Methods:

• insert
• update
• update_all
• find_one
• query
• delete
• count
• drop
• find
• getmore
• kill_cursors
• aggregate

Add

:insert

Add a new document or documents.

Parameters

Name	Description	Default	Required
documents	A table array of documents (tables)	none	Yes
continue_on_error	Processing ignores any doc insertion errors	false	No
safe	Issue a cmd getlasterror to server to query the result	false	No

Returns

On success returns 0, or nil and error message.

OR

If safe is set to true then success is -1 or getlasterror result.

local n, err = collection:insert( documents, continue_on_error, safe )

Update

:update

Update a record or records.

Parameters

Name	Description	Default	Required
selector	A document query (table)	none	Yes
update	Document to update with (table)	none	Yes
upsert	Insert if no record found to update	false	No
multiupdate	Update all matching documents	false	No
safe	Issue a cmd getlasterror to server to query the result	false	No

Returns

On success returns rows updated, or nil and error message.

Returns

local rows, err = collection:update( selector, update, upsert, multiupdate, safe )

Batches

:update_all

Batch document update.

Parameters

Name	Description	Default	Required
queries	A table array of queries (see below)	none	Yes
ordered	Execute the operations in the order they are given	?	No
writeConcern	a write concern document {w=, j=, etc}	none	No

Queries

For batch queries include the following table structure for each entry:

{ q=<Table>, u=<Table>, upsert=<Boolean>, multi=<Boolean> }

--== q=query | u=update
local batch = 
{
  { q={name="Chris"}, u={name="Jim"}, upsert=[Boolean], multi=[Boolean] },
  { q={ age={["$gt"] = 30} }, u={selected=true}, upsert=[Boolean], multi=[Boolean] }
}

See Also: Update

Returns

Update result document as described in Mongo docs, or nil and error message.

local res, err = collection:update_all( queries, ordered, writeConcern )

Get

:find_one

Find a single document.

Parameters

Name	Description	Default	Required
query	The document query (table)	none	Yes
returnfields	The fields to filter (table)	none	No

Return Fields

Limit or show fields by providing a table file flags:

Flag	Action
<field>=0	Hide field
<field>=1	Show field

-- The following filter will only show the username and country fields.
{ username=1, country=1 }
-- The following filter will show all fields except age.
{ age = 0 }

Returns

A single element array, or nil.

local res = collection:find_one( query, returnfields )
local record = res[1]

:query

Performs a document search query. This method does not return a Cursor.

Parameters

Name	Description	Default	Required
query	A document query (table)	none	Yes
returnfields	A table with field flags (see below)	false	No
startIndex	The starting index for the query	0	No
resultCount	Maximum amount of documents to return	100	No

Returns

A binaryId (usage unknown), table array of documents, and query info. Or nil and error message.

The info table:

Namespace	Type
info.startingFrom	Number
info.numberReturned	Number
info.QueryFailure	Boolean
info.CursorNotFound	Boolean
info.AwaitCapable	Boolean

local id, result, info = collection:query( query, returnfields, startIndex, resultCount )
for _, doc in ipairs( docs ) do
  print( doc._id )
end

Remove

:delete

Remove a document or documents.

Parameters

Name	Description	Default	Required
selector	A document query (table)	none	Yes
singleRemove	Only remove the first occurrence	false	No
safe	Issue a cmd getlasterror to server to query the result	false	No

Returns

On success returns rows deleted, or nil and error message.

OR

If safe is set to true then success is -1 or getlasterror result.

local rows, err = collection:delete( selector, singleRemove, safe )

Maintenance

:count

Get a collection count based on a query.

Parameters

Name	Description	Default	Required
query	A table query	none	Yes

Returns

Number

local count = collection:count( query )

:drop

Removes collection and all related documents.

Parameters

None

Returns

On success 1, or nil and error message

local ok, err = collection:drop()

Cursor

:find

Returns a collection cursor object.

Parameters

Name	Description	Default	Required
query	A document query (table)	none	Yes
returnfields	A table with field flags (see below)	none	No
num_each_query	Amount of records per cursor advance	100	No

Returns

A document query cursor.

local cursor = collection:find( query, returnfields, num_each_query )

See Also: Cursor Objects.

:getmore

Get more records from an existing cursor.

Parameters

Name	Description	Default	Required
cursorID	8 byte string representing the cursor	none	Yes
numberToReturn	Number of results to return	-1	No
offset_i	Start table numbering from offset	1	No

Returns

More records.

local res = collection:getmore( cursorID, numberToReturn, offset_i )

:kill_cursors

Clear and release cursor(s).

Parameters

Name	Description	Default	Required
cursor_ids	8 byte string representing the cursor(s) (table)	none	Yes

Returns

Nothing

collection:kill_cursors( cursor_ids )

Aggregation

:aggregate

See mongo aggregation db command docs for more info.

Parameters

Name	Description	Default	Required
pipeline	Ordered list of aggregation pipeline functions	none	Yes

Returns

A result document, or nil and error message.

local n, err = collection:aggregate( pipeline )