Collection Class Reference

Represents a collection of documents in a schema. More...

Public Member Functions
uint64_t	count ()
	Get the number of documents in the collection.
CollectionFind	find ()
	Return an operation which fetches all documents from the collection. More...
CollectionFind	find (const string &cond)
	Return an operation which finds documents that satisfy given criteria. More...
template<typename... Types>
CollectionAdd	add (Types... args)
	Return an operation which adds documents to the collection. More...
CollectionRemove	remove (const string &cond)
	Return an operation which removes documents satisfying given criteria. More...
CollectionModify	modify (const string &expr)
	Return an operation which modifies documents that satisfy given criteria. More...
DbDoc	getOne (const string &id)
	Return the document with the given id. More...
Result	removeOne (const string &id)
	Remove the document with the given id. More...
Result	replaceOne (const string &id, Value &&document)
	Replace the document with the given id by a new one. More...
Result	addOrReplaceOne (const string &id, Value &&document)
	Add a new document or replace an existing document with the given id. More...
void	createIndex (const string &name, const string &idx_spec)
	Create index on the collection. More...
void	dropIndex (const string &name)
	Drop index on the collection. More...

Protected Member Functions
const string &	getName () const
	Get database object name.
Session &	getSession ()
	Get Session object.
const Schema &	getSchema () const
	Get schema object.

Detailed Description

Represents a collection of documents in a schema.

A collection object can be obtained from Schema::getCollection() method:

Schema db;
Collection myColl;
 
myColl= db.getCollection("My Collection");

or directly constructed as follows:

Schema db;
Collection myColl(db, "My Collection");

When creating a Collection object, by default no checks are made that it actually exists in the database. An operation that is executed on the server and involves such a non-existent collection throws an error. Call existsInDatabase() to check the existence of the collection.

Note

A Collection object should be used by at most one thread at a time. It is not safe to call its methods by several threads simultaneously. It is responsibility of the user to ensure this using a synchronization mechanism such as mutexes.

Member Function Documentation

find() [1/2]

CollectionFind find ( )

inline

Return an operation which fetches all documents from the collection.

Call execute() on the returned operation object to execute it and get a DocResult object that gives access to the documents. Specify additional query parameters, such as ordering of the documents, using chained methods of CollectionFind class before making the final call to execute().

Note

Any errors related to the operation are reported when the operation is executed, not when it is created.

See also

CollectionFind

find() [2/2]

CollectionFind find ( const string &  cond )

inline

Return an operation which finds documents that satisfy given criteria.

The criteria are specified as a Boolean expression string. Call execute() on the returned operation object to execute it and get a DocResult object that gives access to the documents. Specify additional query parameters, such as ordering of the documents, using chained methods of CollectionFind class before making the final call to execute().

Note

Any errors related to the operation are reported when the operation is executed, not when it is created.

See also

CollectionFind

add()

CollectionAdd add ( Types...  args )

inline

Return an operation which adds documents to the collection.

Specify documents to be added in the same way as when calling CollectionAdd::add() method. Make additional calls to add() method on the returned operation object to add more documents. Call execute() to execute the operation and add all specified documents to the collection.

Note

Any errors related to the operation are reported when the operation is executed, not when it is created.

See also

CollectionAdd

remove()

CollectionRemove remove ( const string &  cond )

inline

Return an operation which removes documents satisfying given criteria.

The criteria are specified as a Boolean expression string. Call execute() on the returned operation object to execute it and remove the matching documents. Use chained methods of CollectionRemove class before the final call to execute() to further limit the set of documents that are removed.

Note

To remove all documents in the collection, pass "true" as selection criteria.

Any errors related to the operation are reported when the operation is executed, not when it is created.

See also

CollectionRemove

modify()

CollectionModify modify ( const string &  expr )

inline

Return an operation which modifies documents that satisfy given criteria.

The criteria are specified as a Boolean expression string. Specify modifications to be applied to each document using chained methods of CollectionModify class on the returned operation object. Call execute() to execute the operation and modify matching documents as specified.

Note

To modify all documents in the collection, pass "true" as selection criteria.

Any errors related to the operation are reported when the operation is executed, not when it is created.

See also

CollectionModify

getOne()

DbDoc getOne ( const string &  id )

inline

Return the document with the given id.

Returns null document if a document with the given id does not exist in the collection.

removeOne()

Result removeOne ( const string &  id )

inline

Remove the document with the given id.

Does nothing if a document with the given id does not exist in the collection.

replaceOne()

Result replaceOne ( const string &  id, Value &&  document  )

inline

Replace the document with the given id by a new one.

Specify the new document as either a DbDoc object, a JSON string or an expr(docexpr) argument, where docexpr is like a JSON string but field values are given by expressions to be evaluated on the server.

If a document with the given id does not exist in the collection, nothing is done and the returned Result object indicates that no documents were modified.

Note

If expressions are used, they can not use named parameters because it is not possible to bind values prior to execution of replaceOne() operation.

addOrReplaceOne()

Result addOrReplaceOne ( const string &  id, Value &&  document  )

inline

Add a new document or replace an existing document with the given id.

Specify the new document as either a DbDoc object, a JSON string or an expr(docexpr) argument, where docexpr is like a JSON string but field values are given by expressions to be evaluated on the server.

If a document with the given id does not exist, the new document is added to the collection.

Note

If expressions are used, they can not use named parameters because it is not possible to bind values prior to execution of addOrReplaceOne() operation.

createIndex()

void createIndex ( const string &  name, const string &  idx_spec  )

inline

Create index on the collection.

This function creates a named index in the collection using a JSON index specification.

Parameters

name	name for an index to be created
idx_spec	index specification as a JSON string

See also

Indexing Document Collections for information on how to define document collection indexes.

dropIndex()

void dropIndex ( const string &  name )

inline

Drop index on the collection.

Parameters

name	name for an index to be dropped

---

The documentation for this class was generated from the following file:

• include/mysqlx/xdevapi.h