MySQL Shell API 8.0.40
Unified development interface for MySQL Products
Methods | List of all members
CollectionModify Class Reference
X DevAPI

Operation to update documents on a Collection. More...

Methods

CollectionModify modify (String searchCondition)
 Sets the search condition to identify the Documents to be updated on the owner Collection. More...
 
CollectionModify set (String attribute, Value value)
 Sets or updates attributes on documents in a collection. More...
 
CollectionModify unset (String attribute[, String attribute,...])
 Removes attributes from documents in a collection. More...
 
CollectionModify unset (List attributes)
 Removes attributes from documents in a collection. More...
 
CollectionModify merge (Document document)
 Adds attributes taken from a document into the documents in a collection. More...
 
CollectionModify patch (Document document)
 Performs modifications on a document based on a patch JSON object. More...
 
CollectionModify arrayAppend (String docPath, Value value)
 Appends a value into an array attribute in documents of a collection. More...
 
CollectionModify arrayInsert (String docPath, Value value)
 Inserts a value into a specific position in an array attribute in documents of a collection. More...
 
CollectionModify arrayDelete (String docPath)
 Deletes the value at a specific position in an array attribute in documents of a collection. More...
 
CollectionModify sort (List sortCriteria)
 Sets the document order in which the update operations added to the handler should be done. More...
 
CollectionModify limit (Integer numberOfRows)
 Sets a limit for the documents to be updated by the operations added to the handler. More...
 
CollectionModify bind (String name, Value value)
 Binds a value to a specific placeholder used on this CollectionModify object. More...
 
Result execute ()
 Executes the update operations added to the handler with the configured filter and limit. More...
 

Detailed Description

Operation to update documents on a Collection.

A CollectionModify object represents an operation to update documents on a Collection, it is created through the modify function on the Collection class.

See also
Collection

Member Function Documentation

◆ modify()

CollectionModify modify ( String  searchCondition)

Sets the search condition to identify the Documents to be updated on the owner Collection.

Parameters
searchConditionAn expression to identify the documents to be updated.

Creates a handler to update documents in the collection.

Returns
This CollectionModify object.

A condition must be provided to this function, all the documents matching the condition will be updated.

To update all the documents, set a condition that always evaluates to true, for example '1'.

Method Chaining

This function is called automatically when Collection.modify(searchCondition) is called.

After this function invocation, the following functions can be invoked:

◆ set()

CollectionModify set ( String  attribute,
Value  value 
)

Sets or updates attributes on documents in a collection.

Parameters
attributeA string with the document path of the item to be set.
valueThe value to be set on the specified attribute.
Returns
This CollectionModify object.

Adds an operation into the modify handler to set an attribute on the documents that were included on the selection filter and limit.

  • If the attribute is not present on the document, it will be added with the given value.
  • If the attribute already exists on the document, it will be updated with the given value.

Using Expressions for Values

The received values are set into the document in a literal way unless an expression is used.

When an expression is used, it is evaluated on the server and the resulting value is set into the document.

To define an expression use:

mysqlx.expr(expression)

The expression also can be used for Parameter Binding.

The attribute addition will be done on the collection's documents once the execute() method is called.

Method Chaining

This function can be invoked multiple times after:

See also
Usage examples at execute().

◆ unset() [1/2]

CollectionModify unset ( String  attribute[, String attribute,...])

Removes attributes from documents in a collection.

Parameters
attributeA string with the document path of the attribute to be removed.
Returns
This CollectionModify object.

The attribute removal will be done on the collection's documents once the execute() method is called.

Method Chaining

This function can be invoked multiple times after:

See also
Usage examples at execute().

◆ unset() [2/2]

CollectionModify unset ( List  attributes)

Removes attributes from documents in a collection.

Parameters
attributesA list with the document paths of the attributes to be removed.
Returns
This CollectionModify object.

For each attribute on the attributes list, adds an operation into the modify handler to remove the attribute on the documents that were included on the selection filter and limit.

The attribute removal will be done on the collection's documents once the execute() method is called.

Method Chaining

This function can be invoked multiple times after:

See also
Usage examples at execute().

◆ merge()

CollectionModify merge ( Document  document)

Adds attributes taken from a document into the documents in a collection.

Parameters
documentThe document from which the attributes will be merged.
Returns
This CollectionModify object.

This function adds an operation to add into the documents of a collection, all the attributes defined in document that do not exist on the collection's documents.

The attribute addition will be done on the collection's documents once the execute() method is called.

Attention
This function will be removed in a future release, use the patch() function instead.

Method Chaining

This function can be invoked multiple times after:

See also
Usage examples at execute().

◆ patch()

CollectionModify patch ( Document  document)

Performs modifications on a document based on a patch JSON object.

Parameters
documentThe JSON object to be used on the patch process.
Returns
This CollectionModify object.

This function adds an operation to update the documents of a collection, the patch operation follows the algorithm described on the JSON Merge Patch RFC7386.

The patch JSON object will be used to either add, update or remove fields from documents in the collection that match the filter specified on the call to the modify() function.

The operation to be performed depends on the attributes defined at the patch JSON object:

  • Any attribute with value equal to null will be removed if exists.
  • Any attribute with value different than null will be updated if exists.
  • Any attribute with value different than null will be added if does not exists.

Special considerations:

  • The _id of the documents is immutable, so it will not be affected by the patch operation even if it is included on the patch JSON object.
  • The patch JSON object accepts expression objects as values. If used they will be evaluated at the server side.

The patch operations will be done on the collection's documents once the execute() method is called.

Method Chaining

This function can be invoked multiple times after:

See also
Usage examples at execute().

◆ arrayAppend()

CollectionModify arrayAppend ( String  docPath,
Value  value 
)

Appends a value into an array attribute in documents of a collection.

Parameters
docPathA document path that identifies the array attribute where the value will be appended.
valueThe value to be appended.
Returns
This CollectionModify object.

Adds an operation into the modify handler to append a value into an array attribute on the documents that were included on the selection filter and limit.

Method Chaining

This function can be invoked multiple times after:

See also
Usage examples at execute().

◆ arrayInsert()

CollectionModify arrayInsert ( String  docPath,
Value  value 
)

Inserts a value into a specific position in an array attribute in documents of a collection.

Parameters
docPathA document path that identifies the array attribute and position where the value will be inserted.
valueThe value to be inserted.
Returns
This CollectionModify object.

Adds an operation into the modify handler to insert a value into an array attribute on the documents that were included on the selection filter and limit.

The insertion of the value will be done on the collection's documents once the execute() method is called.

Method Chaining

This function can be invoked multiple times after:

See also
Usage examples at execute().

◆ arrayDelete()

CollectionModify arrayDelete ( String  docPath)

Deletes the value at a specific position in an array attribute in documents of a collection.

Parameters
docPathA document path that identifies the array attribute and position of the value to be deleted.
Returns
This CollectionModify object.

Adds an operation into the modify handler to delete a value from an array attribute on the documents that were included on the selection filter and limit.

The attribute deletion will be done on the collection's documents once the execute() method is called.

Attention
This function will be removed in a future release, use the unset() function instead.

Method Chaining

This function can be invoked multiple times after:

See also
Usage examples at execute().

◆ sort()

CollectionModify sort ( List  sortCriteria)

Sets the document order in which the update operations added to the handler should be done.

Returns
This CollectionModify object.

Every defined sort criterion follows the format:

name [ ASC | DESC ]

ASC is used by default if the sort order is not specified.

This method is usually used in combination with limit to fix the amount of documents to be updated.

Method Chaining

This function can be invoked only once after:

See also
Usage examples at execute().

◆ limit()

CollectionModify limit ( Integer  numberOfDocs)

Sets a limit for the documents to be updated by the operations added to the handler.

Parameters
numberOfDocsthe number of documents to affect on the update operations.
Returns
This CollectionModify object.

This method is usually used in combination with sort to fix the amount of documents to be updated.

Method Chaining

This function can be invoked only once after:

After this function invocation, the following functions can be invoked:

See also
Usage examples at execute().

◆ bind()

CollectionModify bind ( String  name,
Value  value 
)

Binds a value to a specific placeholder used on this CollectionModify object.

Parameters
nameThe name of the placeholder to which the value will be bound.
valueThe value to be bound on the placeholder.
Returns
This CollectionModify object.

Binds the given value to the placeholder with the specified name.

An error will be raised if the placeholder indicated by name does not exist.

This function must be called once for each used placeholder or an error will be raised when the execute() method is called.

Method Chaining

This function can be invoked multiple times right before calling execute().

After this function invocation, the following functions can be invoked:

See also
Usage examples at execute().

◆ execute()

Result execute ( )

Executes the update operations added to the handler with the configured filter and limit.

Returns
CollectionResultset A Result object that can be used to retrieve the results of the update operation.

Method Chaining

This function can be invoked after any other function on this class except modify().

The update operation will be executed in the order they were added.

Examples

Modify multiple attributes

var result = collection.modify('name = "brian"').set('alias', 'bri').set('last_name', 'black').set('age', mysqlx.expr('13+1')).execute();
print('Set Affected Rows:', result.affectedItemsCount, '\n');

Modify an attribute with an array value

var result = collection.modify('name = "brian"').set('hobbies', mysqlx.expr(':list')).bind('list', ['soccer', 'dance', 'read']).execute();
print('Set Affected Rows:', result.affectedItemsCount, '\n');

Unset an attribute

var result = collection.modify('name = "brian"').unset('last_name').execute();
print('Unset Affected Rows:', result.affectedItemsCount, '\n');

Unset multiple attributes using an array

var result = collection.modify('name = "brian"').unset(['alias', 'age']).execute();
print('Unset Affected Rows:', result.affectedItemsCount, '\n');

Patch multiple attributes

var result = collection.modify('name = "brian"').patch({'last_name': 'white', 'age': 14, 'alias': 'bw', 'girlfriends': ['lois', 'jane'] }).execute();
print('Patch Affected Rows:', result.affectedItemsCount, '\n');

Append to an array attribute

var result = collection.modify('name = "brian"').arrayAppend('girlfriends', 'cloe').execute();
print('Array Append Affected Rows:', result.affectedItemsCount, '\n');

Insert into an array attribute

var result = collection.modify('name = "brian"').arrayInsert('girlfriends[1]', 'samantha').execute();
print('Array Insert Affected Rows:', result.affectedItemsCount, '\n');

Sorting and setting a limit

var result = collection.modify('age = 15').set('sample', 'in_limit').sort(['name']).limit(2).execute();
print('Affected Rows:', result.affectedItemsCount, '\n');
© Copyright 2014, 2024, Oracle and/or its affiliates. All rights reserved. Generated on Sep 19, 2024 by   doxygen 1.9.2