MySQL Connector/Node.js X DevAPI Reference 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:

DatabaseObject

See:

Collection CRUD Functions

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:

CollectionAddFunction

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:

Single Document Operations

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:

Creating an Index

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:

Creating an Index

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:

CollectionFindFunction

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:

Single Document Operations

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:

CollectionModifyFunction

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:

CollectionRemoveFunction

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:

Single Document Operations

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:

Single Document Operations

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.