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

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

Methods

CollectionRemove remove (str searchCondition)
 Sets the search condition to filter the documents to be deleted from the owner Collection. More...
 
CollectionRemove sort (list sortCriteria)
 Sets the order in which the deletion should be done. More...
 
CollectionRemove limit (int numberOfRows)
 Sets a limit for the documents to be deleted. More...
 
CollectionRemove bind (str name, Value value)
 Binds a value to a specific placeholder used on this CollectionRemove object. More...
 
Result execute ()
 Executes the document deletion with the configured filter and limit. More...
 

Detailed Description

Operation to delete documents on a Collection.

A CollectionRemove object represents an operation to remove documents on a Collection, it is created through the remove function on the Collection class.

See also
Collection

Member Function Documentation

◆ remove()

CollectionRemove remove ( str  searchCondition)

Sets the search condition to filter the documents to be deleted from the owner Collection.

Parameters
searchConditionAn expression to filter the documents to be deleted.
Returns
This CollectionRemove object.

Creates a handler for the deletion of documents on the collection.

A condition must be provided to this function, all the documents matching the condition will be removed from the collection.

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

The searchCondition supports parameter binding.

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

The actual deletion of the documents will occur only when the execute() method is called.

Method Chaining

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

See also
Usage examples at execute().

◆ sort()

CollectionRemove sort ( list  sortCriteria)

Sets the order in which the deletion should be done.

Returns
This CollectionRemove 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 deleted.

Method Chaining

This function can be invoked only once after:

See also
Usage examples at execute().

◆ limit()

CollectionRemove limit ( int  numberOfDocs)

Sets a limit for the documents to be deleted.

Parameters
numberOfDocsthe number of documents to affect in the remove execution.
Returns
This CollectionRemove object.

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

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()

CollectionRemove bind ( str  name,
Value  value 
)

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

Parameters
nameThe name of the placeholder to which the value will be bound.
valueThe value to be bound on the placeholder.
Returns
This CollectionRemove 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 document deletion with the configured filter and limit.

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

Method Chaining

This function can be invoked after any other function on this class.

Examples

Remove under condition

result = collection.remove('age = 15').execute()
print('Affected Rows:', result.affected_items_count, '\n')
docs = collection.find().execute().fetch_all()
print('Records Left:', len(docs), '\n')

Remove with binding

result = collection.remove('gender = :heorshe').limit(2).bind('heorshe', 'male').execute()
print('Affected Rows:', result.affected_items_count, '\n')

Full remove

result = collection.remove('1').execute()
print('Affected Rows:', result.affected_items_count, '\n')
docs = collection.find().execute().fetch_all()
print('Records Left:', len(docs), '\n')