MySQL Shell API 8.0.29
Unified development interface for MySQL Products
Methods | List of all members
CollectionAdd Class Reference

Handler for document addition on a Collection. More...

Methods

CollectionAdd add (DocDefinition document[, DocDefinition document,...])
 Stores documents to be added into a collection. More...
 
Result execute ()
 Executes the add operation, the documents are added to the target collection. More...
 

Detailed Description

Handler for document addition on a Collection.

This object provides the necessary functions to allow adding documents into a collection.

This object should only be created by calling any of the add functions on the collection object where the documents will be added.

See also
Collection

Member Function Documentation

◆ add()

CollectionAdd add ( DocDefinition  document[, DocDefinition document,...])

Stores documents to be added into a collection.

Returns
This CollectionAdd object.

This function receives one or more document definitions to be added into a collection. The documents are cached in an internal list and are added to the collection when the execute() method is called.

A document definition may be provided in two ways:

  • Using a dictionary containing the document fields.
  • Using A JSON string as a document expression.

There are three ways to add multiple documents:

  • Passing several parameters to the function, each parameter should be a document definition.
  • Passing a list of document definitions.
  • Calling this function several times before calling execute().

To be added, every document must have a string property named '_id' ideally with a universal unique identifier (UUID) as value. If the '_id' property is missing, it is automatically set with an internally generated UUID.

Method Chaining

This method can be called many times, every time it is called the received document(s) will be cached into an internal list. The actual addition into the collection will occur only when the execute() method is called.

See also
Usage examples at execute().

◆ execute()

Result execute ( )

Executes the add operation, the documents are added to the target collection.

Returns
A Result object.

Method Chaining

This function can be invoked once after:

Examples

Using a Document List

Adding document using an existing document list

result = collection.add([{ "name": 'my sexth', "passed": 'again', "count": 5 }, mysqlx.expr('{"name": "my senevth", "passed": "yep again", "count": 5}')]).execute()
print("Affected Rows Mixed List:", result.affected_items_count, "\n")

Multiple Parameters

Adding document using a separate parameter for each document on a single call to add(...)

result = collection.add({ "name": 'my eigth', "passed": 'yep', "count": 6 }, mysqlx.expr('{"name": "my nineth", "passed": "yep again", "count": 6}')).execute()
print("Affected Rows Multiple Params:", result.affected_items_count, "\n")

Chaining Addition

Adding documents using chained calls to add(...)

result = collection.add({ "name": 'my fourth', "passed": 'again', "count": 4 }).add({ "name": 'my fifth', "passed": 'once again', "count": 5 }).execute()
print("Affected Rows Chained:", result.affected_items_count, "\n")

JSON as Document Expressions

A document can be represented as a JSON expression as follows:

result = collection.add(mysqlx.expr('{"name": "my fifth", "passed": "document", "count": 1}')).execute()
print("Affected Rows Single Expression:", result.affected_items_count, "\n")