Module: Collection

Factory function that creates a DevAPI Collection instance. This instance is used to create and/or execute various CRUD-like statements.
Mixes In:
See:

Methods


add(documentsOrJSON)

Creates a statement that adds one or more documents to the collection. This method does not cause the statement to be executed.
Parameters:
Name Type Argument Description
documentsOrJSON DocumentsOrJSON <repeatable>
One or more plain JavaScript objects, JSON strings or X DevAPI expressions that represent document definitions provided as an array or as multiple arguments.
See:
Returns:
A new instance of a statement containing the documents which will be added to the collection.
Type
module:CollectionAdd
Example
// arguments as single documents
collection.add({ foo: 'baz' }, { bar: 'qux' })

// array of documents
collection.add([{ foo: 'baz' }, { bar: 'qux' }])

addOrReplaceOne(id, data)

Creates a document with a given id and set of fields and values or replace one if it already exists. This method executes a statement in the database.
Parameters:
Name Type Description
id string The id of the document.
data Object An Object containing the document fields and corresponding values.
See:
Throws:
Object contains an _id field whose value is different then the given document id from the first argument.
Returns:
A Promise that resolves to an object containing the details reported by the server.
Type
Promise.<module:Result>
Example
collection.addOrReplaceOne('foo', { prop1: 'bar', prop2: 'baz' })

count()

Retrieves the total number of documents in the collection. This method executes a statement in the database.
Returns:
A Promise that resolves to the number of documents in the collection.
Type
Promise.<number>

createIndex(name, constraint)

Creates an index with the given name and properties in the collection. This method executes a statement in the database.
Parameters:
Name Type Description
name string The name of the index.
constraint IndexDefinition An object containing the index definition.
See:
Throws:
  • Index name is not a valid string.
  • Index definition does not include a valid field list.
  • Index definition includes an empty field list.
  • Index definition includes an invalid field.
  • Index definition is a missing field.
  • Index definition includes a field without a datatype.
  • Index with the given name already exists.
  • Index is supposed to ensure uniqueness.
Returns:
A Promise that always resolves to true.
Type
Promise.<boolean>

dropIndex(name)

Removes an index with the given name that has been previously created in the collection. This method executes a statement in the database and does not fail if the index does not exist.
Parameters:
Name Type Description
name string The name of the index.
See:
Throws:
Index name is not a valid string.
Returns:
A Promise that resolves to a boolean value which indicates whether the index was removed or not (i.e. it did not exist).
Type
Promise.<boolean>

existsInDatabase()

Checks if this collection exists in the database. This method executes a statement in the database.
Returns:
A Promise that resolves to a boolean value which indicates whether the collection exists or not.
Type
Promise.<boolean>

find( [searchConditionStr])

Creates a statement that looks for one or more documents in the collection which match an optional filtering criteria. All documents will be part of an eventual result set if no filtering criteria is provided.
Parameters:
Name Type Argument Description
searchConditionStr SearchConditionStr <optional>
An optional filtering criteria specified as a string or an X DevAPI expression.
See:
Returns:
A new instance of a statement containing the filtering criteria which will be used to perform the lookup.
Type
module:CollectionFind

getName()

Retrieves the collection name. This method works with the local collection instance and does not execute any statement in the database.
Returns:
The name of the collection.
Type
string

getOne(id)

Retrieves a single document with the given id. This method executes a statement in the database.
Parameters:
Name Type Description
id string The id of the document.
See:
Returns:
An object representing a local instance of the document in the database. If the document does not exist in the database, the object will be null.
Type
Object
Example
collection.getOne('1')

getSchema()

Retrieves the instance of the schema where the collection lives under. This method works with the local collection instance and does not execute any statement in the database.
Returns:
The instance of the schema where statements will be executed.
Type
module:Schema

inspect()

Retrieve the collection metadata. This method works with the local collection instance and does not execute any statement in the database.
Returns:
An object containing metadata about the collection.
Type
Object

modify(searchConditionStr)

Creates a statement to modify one or more documents in the collection that match a given filtering criteria. The filtering criteria is required, and needs to match a truthy value (e.g. '1', 'true') to modify all documents in the collection. This method does not cause the statement to be executed.
Parameters:
Name Type Description
searchConditionStr SearchConditionStr The required filtering criteria specified as a string or as an X DevAPI expression.
See:
Returns:
A new instance of a statement containing the filtering criteria which will be used for determining which documents will be modified.
Type
module:CollectionModify
Example
// update all documents in a collection
collection.modify('true').set('name', 'bar')

// update documents that match a given condition
collection.modify('name = "foo"').set('name', 'bar')

remove(searchConditionStr)

Creates a statement to remove one or more documents from the collection that match a given filtering criteria. The filtering criteria is required, and needs to match a truthy value (e.g. '1', 'true') when the goal is to remove all documents from the collection. This method does not cause the statement to be executed.
Parameters:
Name Type Description
searchConditionStr SearchConditionStr The required filtering criteria specified as a string or as an X DevAPI expression.
See:
Returns:
A new instance of a statement containing the filtering criteria which will be used for determining which documents will be removed.
Type
module:CollectionRemove
Example
// remove all documents from a collection
collection.remove('true')

// remove documents that match a given condition
collection.remove('name = "foobar"')

removeOne(id)

Removes a single document with the given id. This method executes a statement in the database.
Parameters:
Name Type Description
id string The id of the dcoument.
See:
Returns:
A Promise that resolves to an object containing the details reported by the server.
Type
Promise.<module:Result>
Example
collection.removeOne('1')

replaceOne(id, data)

Replaces a document that matches a given id with the set of field names and values defined by a given object. This method executes a statement in the database.
Parameters:
Name Type Description
id string The id of the document.
data Object An object containing the document fields and corresponding values.
See:
Throws:
Object contains an _id field whose value is different then the given document id from the first argument.
Returns:
A Promise that resolves to an object containing the details reported by the server.
Type
Promise.<module:Result>
Example
collection.replaceOne('foo', { prop1: 'bar', prop2: 'baz' })

Type Definitions


FieldDefinition

A field is identified by a given document path, has a given datatype, is or is not required and can include geo-related options.
Type:
  • Object
Properties:
Name Type Argument Default Description
field string The full document path of the field.
type string The index datatype (see example).
required boolean <optional>
false Allow NULL column values.
options number <optional>
Describes how to handle GeoJSON documents that contain geometries with coordinate dimensions higher than 2.
srid number <optional>
Unique value used to unambiguously identify projected, unprojected, and local spatial coordinate system definitions.
Example
INT [UNSIGNED]
TINYINT [UNSIGNED]
SMALLINT [UNSIGNED]
MEDIUMINT [UNSIGNED]
INTEGER [UNSIGNED]
BIGINT [UNSIGNED]
REAL [UNSIGNED]
FLOAT [UNSIGNED]
DOUBLE [UNSIGNED]
DECIMAL [UNSIGNED]
NUMERIC [UNSIGNED]
DATE
TIME
TIMESTAMP
DATETIME
TEXT[(length)]
GEOJSON (extra options: options, srid)

IndexDefinition

A collection index has a given type and a specific set of properties for each document field that is covered by the index.
Type:
  • Object
Properties:
Name Type Argument Default Description
type string <optional>
INDEX The index type (INDEX or SPATIAL).
fields Array.<FieldDefinition> The list of definitions for each of the index fields.