MySQL Shell API 8.4.1
Unified development interface for MySQL Products
|
Handler for document selection on a Collection. More...
Methods | |
CollectionFind | find (String searchCondition) |
Sets the search condition to identify the Documents to be retrieved from the owner Collection. More... | |
CollectionFind | fields (String fieldDefinition[, String fieldDefinition,...]) |
Sets the fields to be retrieved from each document matching the criteria on this find operation. More... | |
CollectionFind | groupBy (List fields) |
Sets a grouping criteria for the resultset. More... | |
CollectionFind | having (String condition) |
Sets a condition for records to be considered in aggregate function operations. More... | |
CollectionFind | sort (List sortCriteria) |
Sets the sorting criteria to be used on the DocResult. More... | |
CollectionFind | limit (Integer numberOfDocs) |
Sets the maximum number of documents to be returned by the operation. More... | |
CollectionFind | offset (Integer numberOfDocs) |
Sets number of documents to skip on the resultset when a limit has been defined. More... | |
CollectionFind | lockShared (String lockContention) |
Instructs the server to acquire shared row locks in documents matched by this find operation. More... | |
CollectionFind | lockExclusive (String lockContention) |
Instructs the server to acquire an exclusive lock on documents matched by this find operation. More... | |
CollectionFind | bind (String name, Value value) |
Binds a value to a specific placeholder used on this CollectionFind object. More... | |
DocResult | execute () |
Executes the find operation with all the configured options. More... | |
Handler for document selection on a Collection.
This object provides the necessary functions to allow selecting document data from a collection.
This object should only be created by calling the find function on the collection object from which the documents will be retrieved.
CollectionFind find | ( | String | searchCondition | ) |
Sets the search condition to identify the Documents to be retrieved from the owner Collection.
searchCondition | Optional String expression defining the condition to be used on the selection. |
Sets the search condition to identify the Documents to be retrieved from the owner Collection. If the search condition is not specified the find operation will be executed over all the documents in the collection.
The search condition supports parameter binding.
After this function invocation, the following functions can be invoked:
CollectionFind fields | ( | String | fieldDefinition[, String fieldDefinition,...] | ) |
Sets the fields to be retrieved from each document matching the criteria on this find operation.
fieldDefinition | Definition of the fields to be retrieved. |
This function sets the fields to be retrieved from each document matching the criteria on this find operation.
A field is defined as a string value containing an expression defining the field to be retrieved.
The fields to be retrieved can be set using any of the next methods:
This function can be invoked only once after:
CollectionFind groupBy | ( | List | fields | ) |
Sets a grouping criteria for the resultset.
Sets a grouping criteria for the resultset.
This function can be invoked only once after:
CollectionFind having | ( | String | condition | ) |
Sets a condition for records to be considered in aggregate function operations.
condition | A condition on the aggregate functions used on the grouping criteria. |
Sets a condition for records to be considered in aggregate function operations.
This function can be invoked only once after:
CollectionFind sort | ( | List | sortCriteria | ) |
Sets the sorting criteria to be used on the DocResult.
If used, the CollectionFind operation will return the records sorted with the defined criteria.
Every defined sort criterion follows the format:
name [ ASC | DESC ]
ASC is used by default if the sort order is not specified.
This function can be invoked only once after:
CollectionFind limit | ( | Integer | numberOfDocs | ) |
Sets the maximum number of documents to be returned by the operation.
numberOfDocs | The maximum number of documents to be retrieved. |
If used, the operation will return at most numberOfDocs documents.
This function can be invoked only once after:
After this function invocation, the following functions can be invoked:
CollectionFind offset | ( | Integer | quantity | ) |
Sets number of documents to skip on the resultset when a limit has been defined.
quantity | The number of documents to skip before start including them on the DocResult. |
If used, the first quantity records will not be included on the result.
This function can be invoked only once after:
CollectionFind lockShared | ( | String | lockContention | ) |
Instructs the server to acquire shared row locks in documents matched by this find operation.
lockContention | optional parameter to indicate how to handle documents that are already locked. |
When this function is called, the selected documents will be locked for write operations, they may be retrieved on a different session, but no updates will be allowed.
The acquired locks will be released when the current transaction is committed or rolled back.
The lockContention parameter defines the behavior of the operation if another session contains an exclusive lock to matching documents.
The lockContention can be specified using the following constants:
The lockContention can also be specified using the following string literals (no case sensitive):
If no lockContention or the default is specified, the operation will block if another session already holds an exclusive lock on matching documents until the lock is released.
If lockContention is set to NOWAIT and another session already holds an exclusive lock on matching documents, the operation will not block and an error will be generated.
If lockContention is set to SKIP_LOCKED and another session already holds an exclusive lock on matching documents, the operation will not block and will return only those documents not having an exclusive lock.
This operation only makes sense within a transaction.
This function can be invoked at any time before bind() or execute() are called.
After this function invocation, the following functions can be invoked:
If lockExclusive() is called, it will override the lock type to be used on the selected documents.
CollectionFind lockExclusive | ( | String | lockContention | ) |
Instructs the server to acquire an exclusive lock on documents matched by this find operation.
lockContention | optional parameter to indicate how to handle documents that are already locked. |
When this function is called, the selected documents will be locked for read operations, they will not be retrievable by other session.
The acquired locks will be released when the current transaction is committed or rolled back.
The lockContention parameter defines the behavior of the operation if another session contains a lock to matching documents.
The lockContention can be specified using the following constants:
The lockContention can also be specified using the following string literals (no case sensitive):
If no lockContention or the default is specified, the operation will block if another session already holds a lock on matching documents.
If lockContention is set to NOWAIT and another session already holds a lock on matching documents, the operation will not block and an error will be generated.
If lockContention is set to SKIP_LOCKED and another session already holds a lock on matching documents, the operation will not block and will return only those documents not having a lock.
This operation only makes sense within a transaction.
This function can be invoked at any time before bind() or execute() are called.
After this function invocation, the following functions can be invoked:
If lockShared() is called, it will override the lock type to be used on the selected documents.
CollectionFind bind | ( | String | name, |
Value | value | ||
) |
Binds a value to a specific placeholder used on this CollectionFind 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:
DocResult execute | ( | ) |
Executes the find operation with all the configured options.
This function can be invoked after any other function on this class.
Using a field selection list
Using separate field selection parameters
Using a projection expression