|
MySQL Shell API 8.0.40
Unified development interface for MySQL Products
|
Operation to update documents on a Collection. More...
Methods | |
| CollectionModify | modify (str searchCondition) |
| Sets the search condition to identify the Documents to be updated on the owner Collection. More... | |
| CollectionModify | set (str attribute, Value value) |
| Sets or updates attributes on documents in a collection. More... | |
| CollectionModify | unset (str attribute[, str 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 | array_append (str docPath, Value value) |
| Appends a value into an array attribute in documents of a collection. More... | |
| CollectionModify | array_insert (str docPath, Value value) |
| Inserts a value into a specific position in an array attribute in documents of a collection. More... | |
| CollectionModify | array_delete (str 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 (int numberOfRows) |
| Sets a limit for the documents to be updated by the operations added to the handler. More... | |
| CollectionModify | bind (str 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... | |
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.
| CollectionModify modify | ( | str | searchCondition | ) |
Sets the search condition to identify the Documents to be updated on the owner Collection.
| searchCondition | An expression to identify the documents to be updated. |
Creates a handler to update documents in the collection.
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'.
This function is called automatically when Collection.modify(searchCondition) is called.
After this function invocation, the following functions can be invoked:
| CollectionModify set | ( | str | attribute, |
| Value | value | ||
| ) |
Sets or updates attributes on documents in a collection.
| attribute | A string with the document path of the item to be set. |
| value | The value to be set on the specified attribute. |
Adds an operation into the modify handler to set an attribute on the documents that were included on the selection filter and limit.
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:
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.
This function can be invoked multiple times after:
| CollectionModify unset | ( | str | attribute[, str attribute,...] | ) |
Removes attributes from documents in a collection.
| attribute | A string with the document path of the attribute to be removed. |
The attribute removal will be done on the collection's documents once the execute() method is called.
This function can be invoked multiple times after:
| CollectionModify unset | ( | list | attributes | ) |
Removes attributes from documents in a collection.
| attributes | A list with the document paths of the attributes to be removed. |
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.
This function can be invoked multiple times after:
| CollectionModify merge | ( | Document | document | ) |
Adds attributes taken from a document into the documents in a collection.
| document | The document from which the attributes will be merged. |
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.
This function can be invoked multiple times after:
| CollectionModify patch | ( | Document | document | ) |
Performs modifications on a document based on a patch JSON object.
| document | The JSON object to be used on the patch process. |
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:
Special considerations:
The patch operations will be done on the collection's documents once the execute() method is called.
This function can be invoked multiple times after:
| CollectionModify array_append | ( | str | docPath, |
| Value | value | ||
| ) |
Appends a value into an array attribute in documents of a collection.
| docPath | A document path that identifies the array attribute where the value will be appended. |
| value | The value to be appended. |
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.
This function can be invoked multiple times after:
| CollectionModify array_insert | ( | str | docPath, |
| Value | value | ||
| ) |
Inserts a value into a specific position in an array attribute in documents of a collection.
| docPath | A document path that identifies the array attribute and position where the value will be inserted. |
| value | The value to be inserted. |
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.
This function can be invoked multiple times after:
| CollectionModify array_delete | ( | str | docPath | ) |
Deletes the value at a specific position in an array attribute in documents of a collection.
| docPath | A document path that identifies the array attribute and position of the value to be deleted. |
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.
This function can be invoked multiple times after:
| CollectionModify sort | ( | list | sortCriteria | ) |
Sets the document order in which the update operations added to the handler should be done.
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.
This function can be invoked only once after:
| CollectionModify limit | ( | int | numberOfDocs | ) |
Sets a limit for the documents to be updated by the operations added to the handler.
| numberOfDocs | the number of documents to affect on the update operations. |
This method is usually used in combination with sort to fix the amount of documents to be updated.
This function can be invoked only once after:
After this function invocation, the following functions can be invoked:
| CollectionModify bind | ( | str | name, |
| Value | value | ||
| ) |
Binds a value to a specific placeholder used on this CollectionModify object.
| name | The name of the placeholder to which the value will be bound. |
| value | The value to be bound on the placeholder. |
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.
This function can be invoked multiple times right before calling execute().
After this function invocation, the following functions can be invoked:
| Result execute | ( | ) |
Executes the update operations added to the handler with the configured filter and limit.
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.
1.9.2