QueryRequest

class borneo.QueryRequest

Bases: borneo.operations.Request

A request that represents a query. A query may be specified as either a textual SQL statement (a String) or a prepared query (an instance of PreparedStatement), which may include bind variables.

For performance reasons prepared queries are preferred for queries that may be reused. This is because prepared queries bypass query compilation. They also allow for parameterized queries using bind variables.

To compute and retrieve the full result set of a query, the same QueryRequest instance will, in general, have to be executed multiple times (via NoSQLHandle.query()). Each execution returns a QueryResult, which contains a subset of the result set. The following code snippet illustrates a typical query execution:

handle = ...
request = QueryRequest().set_statement('SELECT * FROM foo')
while True:
    result = handle.query(request)
    results = result.get_results()
    # do something with the results
    if request.is_done():
        break

Notice that a batch of results returned by a QueryRequest execution may be empty. This is because during each execution the query is allowed to read or write a maximum number of bytes. If this maximum is reached, execution stops. This can happen before any result was generated (for example, if none of the rows read satisfied the query conditions).

If an application wishes to terminate query execution before retrieving all of the query results, it should call close() in order to release any local resources held by the query. This also allows the application to reuse the QueryRequest instance to run the same query from the beginning or a different query.

QueryRequest instances are not thread-safe. That is, if two or more application threads need to run the same query concurrently, they must create and use their own QueryRequest instances.

The statement or prepared_statement is required parameter.

Methods Summary

close()	Terminates the query execution and releases any memory consumed by the query at the driver.
get_compartment()	Cloud service only.
get_consistency()	Returns the consistency set for this request, or None if not set.
get_limit()	Returns the limit on number of items returned by the operation.
get_math_context()	Returns the Context used for Decimal operations.
get_max_memory_consumption()	Returns the maximum number of memory bytes that may be consumed by the statement at the driver for operations such as duplicate elimination (which may be required due to the use of an index on a list or map) and sorting (sorting by distance when a query contains a geo_near() function).
get_max_read_kb()	Returns the limit on the total data read during this operation, in KB.
get_max_write_kb()	Returns the limit on the total data written during this operation, in KB.
get_prepared_statement()	Returns the prepared query statement.
get_statement()	Returns the query statement.
get_timeout()	Returns the timeout to use for the operation, in milliseconds.
is_done()	Returns True if the query execution is finished, i.e., there are no more query results to be generated.
set_compartment(compartment)	Cloud service only.
set_consistency(consistency)	Sets the consistency to use for the operation.
set_limit(limit)	Sets the limit on number of items returned by the operation.
set_math_context(math_context)	Sets the Context used for Decimal operations.
set_max_memory_consumption(memory_consumption)	Sets the maximum number of memory bytes that may be consumed by the statement at the driver for operations such as duplicate elimination (which may be required due to the use of an index on a list or map) and sorting.
set_max_read_kb(max_read_kb)	Sets the limit on the total data read during this operation, in KB.
set_max_write_kb(max_write_kb)	Sets the limit on the total data written during this operation, in KB.
set_prepared_statement(value)	Sets the prepared query statement.
set_statement(statement)	Sets the query statement.
set_timeout(timeout_ms)	Sets the request timeout value, in milliseconds.

Methods Documentation

close()

Terminates the query execution and releases any memory consumed by the query at the driver. An application should use this method if it wishes to terminate query execution before retrieving all of the query results.

get_compartment()

Cloud service only.

Get the compartment id or name if set for the request.

Returns:compartment id or name if set for the request, otherwise None if not set. Return type:str

get_consistency()

Returns the consistency set for this request, or None if not set.

Returns:the consistency Return type:Consistency

get_limit()

Returns the limit on number of items returned by the operation. If not set by the application this value will be 0 which means no limit.

Returns:the limit, or 0 if not set. Return type:int

get_math_context()

Returns the Context used for Decimal operations.

Returns:the Context used for Decimal operations. Return type:Context

get_max_memory_consumption()

Returns the maximum number of memory bytes that may be consumed by the statement at the driver for operations such as duplicate elimination (which may be required due to the use of an index on a list or map) and sorting (sorting by distance when a query contains a geo_near() function). Such operations may consume a lot of memory as they need to cache the full result set at the client memory. The default value is 100MB.

Returns:the maximum number of memory bytes. Return type:long

get_max_read_kb()

Returns the limit on the total data read during this operation, in KB. If not set by the application this value will be 0 which means no application-defined limit.

Returns:the limit, or 0 if not set. Return type:int

get_max_write_kb()

Returns the limit on the total data written during this operation, in KB. If not set by the application this value will be 0 which means no application-defined limit.

Returns:the limit, or 0 if not set. Return type:int

get_prepared_statement()

Returns the prepared query statement.

Returns:the statement, or None if it has not been set. Return type:PreparedStatement

get_statement()

Returns the query statement.

Returns:the statement, or None if it has not been set. Return type:str

get_timeout()

Returns the timeout to use for the operation, in milliseconds. A value of 0 indicates that the timeout has not been set.

Returns:the timeout value. Return type:int

is_done()

Returns True if the query execution is finished, i.e., there are no more query results to be generated. Otherwise False.

Returns:Whether the query execution is finished or not. Return type:bool

set_compartment(compartment)

Cloud service only.

Sets the name or id of a compartment to be used for this operation.

The compartment may be specified as either a name (or path for nested compartments) or as an id (OCID). A name (vs id) can only be used when authenticated using a specific user identity. It is not available if authenticated as an Instance Principal which can be done when calling the service from a compute instance in the Oracle Cloud Infrastructure. See borneo.iam.SignatureProvider.create_with_instance_principal().

Parameters:compartment (str) – the compartment name or id. If using a nested compartment, specify the full compartment path compartmentA.compartmentB, but exclude the name of the root compartment (tenant). Returns:self. Raises:IllegalArgumentException – raises the exception if compartment is not a str.

set_consistency(consistency)

Sets the consistency to use for the operation.

Parameters:consistency (Consistency) – the consistency. Returns:self. Raises:IllegalArgumentException – raises the exception if consistency is not Consistency.ABSOLUTE or Consistency.EVENTUAL.

set_limit(limit)

Sets the limit on number of items returned by the operation. This allows an operation to return less than the default amount of data.

Parameters:limit (int) – the limit in terms of number of items returned. Returns:self. Raises:IllegalArgumentException – raises the exception if the limit is a negative number.

set_math_context(math_context)

Sets the Context used for Decimal operations.

Parameters:math_context (Context) – the Context used for Decimal operations. Returns:self. Raises:IllegalArgumentException – raises the exception if math_context is not an instance of Context.

set_max_memory_consumption(memory_consumption)

Sets the maximum number of memory bytes that may be consumed by the statement at the driver for operations such as duplicate elimination (which may be required due to the use of an index on a list or map) and sorting. Such operations may consume a lot of memory as they need to cache the full result set or a large subset of it at the client memory. The default value is 1GB.

Parameters:memory_consumption (long) – the maximum number of memory bytes that may be consumed by the statement at the driver for blocking operations. Returns:self. Raises:IllegalArgumentException – raises the exception if memory_consumption is a negative number or 0.

set_max_read_kb(max_read_kb)

Sets the limit on the total data read during this operation, in KB. This value can only reduce the system defined limit. This limit is independent of read units consumed by the operation.

It is recommended that for tables with relatively low provisioned read throughput that this limit be reduced to less than or equal to one half of the provisioned throughput in order to avoid or reduce throttling exceptions.

Parameters:max_read_kb (int) – the limit in terms of number of KB read during this operation. Returns:self. Raises:IllegalArgumentException – raises the exception if the max_read_kb value is less than 0.

set_max_write_kb(max_write_kb)

Sets the limit on the total data written during this operation, in KB. This limit is independent of write units consumed by the operation.

Parameters:max_write_kb (int) – the limit in terms of number of KB written during this operation. Returns:self. Raises:IllegalArgumentException – raises the exception if the max_write_kb value is less than 0.

set_prepared_statement(value)

Sets the prepared query statement.

Parameters:value (PreparedStatement) – the prepared query statement or the result of a prepare request. Returns:self. Raises:IllegalArgumentException – raises the exception if value is not an instance of PrepareResult or PreparedStatement.

set_statement(statement)

Sets the query statement.

Parameters:statement (str) – the query statement. Returns:self. Raises:IllegalArgumentException – raises the exception if statement is not a string.

set_timeout(timeout_ms)

Sets the request timeout value, in milliseconds. This overrides any default value set in NoSQLHandleConfig. The value must be positive.

Parameters:timeout_ms (int) – the timeout value, in milliseconds. Returns:self. Raises:IllegalArgumentException – raises the exception if the timeout value is less than or equal to 0.