mysqlx.FindStatement¶

class mysqlx.FindStatement(collection: DatabaseObject, condition: str | None = None)¶

Bases: ReadStatement

A statement document selection on a Collection.

Parameters:

collection (mysqlx.Collection) – The Collection object.
condition (Optional[str]) – An optional expression to identify the documents to be retrieved. If not specified all the documents will be included on the result unless a limit is set.

bind(*args: Any) → FilterableStatement¶

Binds value(s) to a specific placeholder(s).

Parameters:: *args – The name of the placeholder and the value to bind. A mysqlx.DbDoc object or a JSON string representation can be used.
Returns:: FilterableStatement object.
Return type:: mysqlx.FilterableStatement
Raises:: ProgrammingError – If the number of arguments is invalid.

property changed: bool¶

True if this statement has changes.

Type:: bool

property deallocate_prepare_execute: bool¶

True to deallocate + prepare + execute statement.

Type:: bool

property exec_counter: int¶

The number of times this statement was executed.

Type:: int

execute() → DocResult | RowResult¶

Execute the statement.

Returns:: Result object.
Return type:: mysqlx.Result

fields(*fields: str) → FindStatement¶

Sets a document field filter.

Parameters:: *fields – The string expressions identifying the fields to be extracted.
Returns:: FindStatement object.
Return type:: mysqlx.FindStatement

get_binding_map() → Dict[str, Any]¶

Returns the binding map dictionary.

Returns:: The binding map dictionary.
Return type:: dict

get_bindings() → Dict[str, Any] | List¶

Returns the bindings list.

Returns:: The bindings list.
Return type:: list

get_grouping() → List[ProtoMessage | Dict[str, Any]]¶

Returns the grouping expression list.

Returns:: The grouping expression list.
Return type:: list

get_having() → XdevMessage¶

Returns the having expression.

Returns:: The having expression.
Return type:: object

get_limit_offset() → int¶

Returns the limit offset.

Returns:: The limit offset.
Return type:: int

get_limit_row_count() → int¶

Returns the limit row count.

Returns:: The limit row count.
Return type:: int

get_projection_expr() → List[ProtoMessage | Dict[str, Any]]¶

Returns the projection expression.

Returns:: The projection expression.
Return type:: object

get_sort_expr() → List[ProtoMessage | Dict[str, Any]]¶

Returns the sort expression.

Returns:: The sort expression.
Return type:: object

get_where_expr() → XdevMessage¶

Returns the where expression.

Returns:: The where expression.
Return type:: object

group_by(*fields: str) → ReadStatement¶

Sets a grouping criteria for the resultset.

Parameters:: *fields – The string expressions identifying the grouping criteria.
Returns:: ReadStatement object.
Return type:: mysqlx.ReadStatement

having(condition: str) → ReadStatement¶

Sets a condition for records to be considered in agregate function operations.

Parameters:: condition (string) – A condition on the agregate functions used on the grouping criteria.
Returns:: ReadStatement object.
Return type:: mysqlx.ReadStatement

increment_exec_counter() → None¶: Increments the number of times this statement has been executed.

is_doc_based() → bool¶

Check if it is document based.

Returns:: True if it is document based.
Return type:: bool

is_lock_exclusive() → bool¶

Returns True if is EXCLUSIVE LOCK.

Returns:: True if is EXCLUSIVE LOCK.
Return type:: bool

is_lock_shared() → bool¶

Returns True if is SHARED LOCK.

Returns:: True if is SHARED LOCK.
Return type:: bool

limit(row_count: int, offset: int | None = None) → FilterableStatement¶

Sets the maximum number of items to be returned.

Parameters:: row_count (int) – The maximum number of items.
Returns:: FilterableStatement object.
Return type:: mysqlx.FilterableStatement
Raises:: ValueError – If row_count is not a positive integer.

Changed in version 8.0.12: The usage of offset was deprecated.

property lock_contention: LockContention¶

The lock contention value.

Type:: mysqlx.LockContention

lock_exclusive(lock_contention: LockContention = LockContention.DEFAULT) → ReadStatement¶

Execute a read operation with EXCLUSIVE LOCK. Only one lock can be: active at a time.

Parameters:: lock_contention (mysqlx.LockContention) – Lock contention.

lock_shared(lock_contention: LockContention = LockContention.DEFAULT) → ReadStatement¶

Execute a read operation with SHARED LOCK. Only one lock can be: active at a time.

Parameters:: lock_contention (mysqlx.LockContention) – Lock contention.

offset(offset: int) → FilterableStatement¶

Sets the number of items to skip.

Parameters:: offset (int) – The number of items to skip.
Returns:: FilterableStatement object.
Return type:: mysqlx.FilterableStatement
Raises:: ValueError – If offset is not a positive integer.

New in version 8.0.12.

property prepared: bool¶

True if this statement has been prepared.

Type:: bool

property repeated: bool¶

True if this statement was executed more than once.

Type:: bool

reset_exec_counter() → None¶: Resets the number of times this statement has been executed.

property schema: Schema¶

The Schema object.

Type:: mysqlx.Schema

sort(*clauses: str) → FindStatement¶

Sets the sorting criteria.

Parameters:: *clauses – The expression strings defining the sort criteria.
Returns:: FindStatement object.
Return type:: mysqlx.FindStatement

property stmt_id: int¶

Returns this statement ID.

Returns:: The statement ID.
Return type:: int

property target: DatabaseObject¶

The database object target.

Type:: object

where(condition: str) → FilterableStatement¶

Sets the search condition to filter.

Parameters:: condition (str) – Sets the search condition to filter documents or records.
Returns:: FilterableStatement object.
Return type:: mysqlx.FilterableStatement

Deprecated since version 8.0.12.