pyreindexer 0.5.120002

A connector that allows to interact with Reindexer. Reindexer static library or reindexer-dev package must be installed

The PyReindexer module provides a connector and its auxiliary tools for interaction with Reindexer. Reindexer static library or reindexer-dev package must be installed

• The PyReindexer module provides a connector and its auxiliary tools for interaction with Reindexer. Reindexer static library or reindexer-dev package must be installed
• pyreindexer.rx_connector
  • RxConnector Objects
    • Arguments
    • Attributes
    • RxConnector.close
      • Raises
    • RxConnector.namespace_open
      • Arguments
      • Raises
    • RxConnector.namespace_close
      • Arguments
      • Raises
    • RxConnector.namespace_drop
      • Arguments
      • Raises
    • RxConnector.namespaces_enum
      • Arguments
      • Returns
      • Raises
    • RxConnector.index_add
      • Arguments
      • Raises
    • RxConnector.index_update
      • Arguments
      • Raises
    • RxConnector.index_drop
      • Arguments
      • Raises
    • RxConnector.item_insert
      • Arguments
      • Raises
    • RxConnector.item_update
      • Arguments
      • Raises
    • RxConnector.item_upsert
      • Arguments
      • Raises
    • RxConnector.item_delete
      • Arguments
      • Raises
    • RxConnector.meta_put
      • Arguments
      • Raises
    • RxConnector.meta_get
      • Arguments
      • Returns
      • Raises
    • RxConnector.meta_delete
      • Arguments
      • Raises
    • RxConnector.meta_enum
      • Arguments
      • Returns
      • Raises
    • RxConnector.exec_sql
      • Arguments
      • Returns
      • Raises
    • RxConnector.new_transaction
      • Arguments
      • Returns
      • Raises
    • RxConnector.new_query
      • Arguments
      • Returns
      • Raises
• pyreindexer.query_results
  • QueryResults Objects
    • Attributes
    • QueryResults.status
      • Raises
    • QueryResults.count
      • Returns
    • QueryResults.total_count
      • Returns
    • QueryResults.get_agg_results
      • Returns
      • Raises
    • QueryResults.get_explain_results
      • Returns
      • Raises
• pyreindexer.transaction
  • Transaction Objects
    • Attributes
    • Transaction.insert
      • Arguments
      • Raises
    • Transaction.update
      • Arguments
      • Raises
    • Transaction.update_query
      • Arguments
      • Raises
    • Transaction.upsert
      • Arguments
      • Raises
    • Transaction.delete
      • Arguments
      • Raises
    • Transaction.delete_query
      • Arguments
      • Raises
    • Transaction.commit
      • Arguments
      • Raises
    • Transaction.commit_with_count
      • Arguments
      • Raises
    • Transaction.rollback
      • Arguments
      • Raises
• pyreindexer.point
  • Point Objects
    • Attributes
• pyreindexer.query
  • Query Objects
    • Attributes
    • Query.where
      • Arguments
      • Returns
      • Raises
    • Query.where_query
      • Arguments
      • Returns
      • Raises
    • Query.where_subquery
      • Arguments
      • Returns
    • Query.where_composite
      • Arguments
      • Returns
      • Raises
    • Query.where_uuid
      • Arguments
      • Returns
      • Raises
    • Query.where_between_fields
      • Arguments
      • Returns
    • Query.where_knn
      • Arguments
      • Returns
      • Raises
    • Query.where_knn_string
      • Arguments
      • Returns
      • Raises
    • Query.open_bracket
      • Returns
      • Raises
    • Query.close_bracket
      • Returns
      • Raises
    • Query.match
      • Arguments
      • Returns
      • Raises
    • Query.dwithin
      • Arguments
      • Returns
    • Query.distinct
      • Arguments
      • Returns
    • Query.aggregate_sum
      • Arguments
      • Returns
    • Query.aggregate_avg
      • Arguments
      • Returns
    • Query.aggregate_min
      • Arguments
      • Returns
    • Query.aggregate_max
      • Arguments
      • Returns
    • Query.aggregate_facet
      • Arguments
      • Returns
    • Query.sort
      • Arguments
      • Returns
      • Raises
    • Query.sort_stpoint_distance
      • Arguments
      • Returns
    • Query.sort_stfield_distance
      • Arguments
      • Returns
      • Raises
    • Query.op_and
      • Returns
    • Query.op_or
      • Returns
    • Query.op_not
      • Returns
    • Query.request_total
      • Arguments
      • Returns
    • Query.cached_total
      • Arguments
      • Returns
    • Query.limit
      • Arguments
      • Returns
    • Query.offset
      • Arguments
      • Returns
    • Query.debug
      • Arguments
      • Returns
    • Query.strict
      • Arguments
      • Returns
    • Query.explain
      • Returns
    • Query.with_rank
      • Returns
    • Query.execute
      • Arguments
      • Returns
      • Raises
    • Query.delete
      • Arguments
      • Returns
      • Raises
    • Query.set_object
      • Arguments
      • Returns
      • Raises
    • Query.set
      • Arguments
      • Returns
      • Raises
    • Query.drop
      • Arguments
      • Returns
    • Query.expression
      • Arguments
      • Returns
    • Query.update
      • Arguments
      • Returns
      • Raises
    • Query.must_execute
      • Arguments
      • Returns
      • Raises
    • Query.get
      • Arguments
      • Returns
      • Raises
    • Query.inner_join
      • Arguments
      • Returns
    • Query.join
      • Arguments
      • Returns
    • Query.left_join
      • Arguments
      • Returns
    • Query.merge
      • Arguments
      • Returns
    • Query.on
      • Arguments
      • Returns
      • Raises
    • Query.select_fields
      • Arguments
      • Returns
      • Raises
    • Query.functions
      • Arguments
      • Returns
      • Raises
    • Query.equal_position
      • Arguments
      • Returns
      • Raises
• pyreindexer.index_search_params
  • IndexSearchParamBruteForce Objects
    • Attributes
  • IndexSearchParamHnsw Objects
    • Attributes
  • IndexSearchParamIvf Objects
    • Attributes
• pyreindexer.index_definition
  • IndexDefinition Objects
    • Arguments

pyreindexer.rx_connector

RxConnector Objects

class RxConnector(RaiserMixin)

RxConnector provides a binding to Reindexer upon two shared libraries (hereinafter - APIs): 'rawpyreindexerb.so' and 'rawpyreindexerc.so'. The first one is aimed at built-in usage. That API embeds Reindexer, so it could be used right in-place as is. The second one acts as a lightweight client which establishes a connection to Reindexer server via RPC. The APIs interfaces are completely the same.

Arguments:

    dsn (string): The connection string which contains a protocol
        Examples: 'builtin:///tmp/pyrx', 'cproto://127.0.0.1:6534/pyrx'

    cproto options:
         fetch_amount (int): The number of items that will be fetched by one operation
         reconnect_attempts (int): Number of reconnection attempts when connection is lost
         net_timeout (`datetime.timedelta`): Connection and database login timeout value [milliseconds]
         enable_compression (bool): Flag enable/disable traffic compression
         start_special_thread (bool): Determines whether to request a special thread of execution
            on the server for this connection
         client_name (string): Proper name of the application (as a client for Reindexer-server)
         sync_rxcoro_count (int): Client concurrency per connection [1..10'000], default 10

    built-in options:
        max_replication_updates_size (int): Max pended replication updates size in bytes
        allocator_cache_limit (int): Recommended maximum free cache size of tcmalloc memory allocator in bytes
        allocator_cache_part (float): Recommended maximum free cache size of tcmalloc memory allocator in
            relation to total Reindexer allocated memory size, in units

Attributes:

api (module): An API module loaded dynamically for Reindexer calls
rx (int): A memory pointer to the Reindexer instance
err_code (int): The API error code
err_msg (string): The API error message

RxConnector.close

def close() -> None

Closes the API instance and frees Reindexer resources

Raises:

ConnectionError: Raises with an error message when Reindexer instance is not initialized yet

RxConnector.namespace_open

def namespace_open(
    namespace: str, timeout: timedelta = timedelta(milliseconds=0)) -> None

Opens a namespace specified or creates a namespace if it does not exist

Arguments:

namespace (string): The name of the namespace
timeout (`datetime.timedelta`): Optional timeout for performing a server-side operation.
    Minimum is 1 millisecond; if set to a lower value, it corresponds to disabling the timeout.
    A value of 0 disables the timeout (default value)

Raises:

ConnectionError: Raises with an error message when Reindexer instance is not initialized yet
ApiError: Raises with an error message of API return on non-zero error code

RxConnector.namespace_close

def namespace_close(
    namespace: str, timeout: timedelta = timedelta(milliseconds=0)) -> None

Closes the specified namespace

Arguments:

namespace (string): The name of the namespace
timeout (`datetime.timedelta`): Optional timeout for performing a server-side operation.
    Minimum is 1 millisecond; if set to a lower value, it corresponds to disabling the timeout.
    A value of 0 disables the timeout (default value)

Raises:

ConnectionError: Raises with an error message when Reindexer instance is not initialized yet
ApiError: Raises with an error message of API return on non-zero error code

RxConnector.namespace_drop

def namespace_drop(
    namespace: str, timeout: timedelta = timedelta(milliseconds=0)) -> None

Drops the specified namespace

Arguments:

namespace (string): The name of the namespace
timeout (`datetime.timedelta`): Optional timeout for performing a server-side operation.
    Minimum is 1 millisecond; if set to a lower value, it corresponds to disabling the timeout.
    A value of 0 disables the timeout (default value)

Raises:

Exception: Raises with an error message when Reindexer instance is not initialized yet
Exception: Raises with an error message of API return on non-zero error code

RxConnector.namespaces_enum

def namespaces_enum(
    enum_not_opened: bool = False,
    timeout: timedelta = timedelta(milliseconds=0)
) -> List[Dict[str, str]]

Gets a list of namespaces available

Arguments:

enum_not_opened (bool, optional): An enumeration mode flag. If it is
    set then closed namespaces are in result list too. Defaults to False
timeout (`datetime.timedelta`): Optional timeout for performing a server-side operation.
    Minimum is 1 millisecond; if set to a lower value, it corresponds to disabling the timeout.
    A value of 0 disables the timeout (default value)

Returns:

(:obj:`list` of :obj:`dict`): A list of dictionaries which describe each namespace

Raises:

ConnectionError: Raises with an error message when Reindexer instance is not initialized yet
ApiError: Raises with an error message of API return on non-zero error code

RxConnector.index_add

def index_add(
    namespace: str,
    index_def: Dict,
    timeout: timedelta = timedelta(milliseconds=0)) -> None

Adds an index to the specified namespace

Arguments:

namespace (string): The name of the namespace
index_def (dict): A dictionary of index definition
timeout (`datetime.timedelta`): Optional timeout for performing a server-side operation.
    Minimum is 1 millisecond; if set to a lower value, it corresponds to disabling the timeout.
    A value of 0 disables the timeout (default value)

Raises:

ConnectionError: Raises with an error message when Reindexer instance is not initialized yet
ApiError: Raises with an error message of API return on non-zero error code

RxConnector.index_update

def index_update(
    namespace: str,
    index_def: Dict,
    timeout: timedelta = timedelta(milliseconds=0)) -> None

Updates an index in the specified namespace

Arguments:

namespace (string): The name of the namespace
index_def (dict): A dictionary of index definition
timeout (`datetime.timedelta`): Optional timeout for performing a server-side operation.
    Minimum is 1 millisecond; if set to a lower value, it corresponds to disabling the timeout.
    A value of 0 disables the timeout (default value)

Raises:

ConnectionError: Raises with an error message when Reindexer instance is not initialized yet
ApiError: Raises with an error message of API return on non-zero error code

RxConnector.index_drop

def index_drop(
    namespace: str,
    index_name: str,
    timeout: timedelta = timedelta(milliseconds=0)) -> None

Drops an index from the specified namespace

Arguments:

namespace (string): The name of the namespace
index_name (string): A name of an index
timeout (`datetime.timedelta`): Optional timeout for performing a server-side operation.
    Minimum is 1 millisecond; if set to a lower value, it corresponds to disabling the timeout.
    A value of 0 disables the timeout (default value)

Raises:

ConnectionError: Raises with an error message when Reindexer instance is not initialized yet
ApiError: Raises with an error message of API return on non-zero error code

RxConnector.item_insert

def item_insert(
    namespace: str,
    item_def: Dict,
    precepts: List[str] = None,
    timeout: timedelta = timedelta(milliseconds=0)
) -> None

Inserts an item with its precepts into the specified namespace

Arguments:

namespace (string): The name of the namespace
item_def (dict): A dictionary of item definition
precepts (:obj:`list` of :obj:`str`): A dictionary of index definition
timeout (`datetime.timedelta`): Optional timeout for performing a server-side operation.
    Minimum is 1 millisecond; if set to a lower value, it corresponds to disabling the timeout.
    A value of 0 disables the timeout (default value)

Raises:

ConnectionError: Raises with an error message when Reindexer instance is not initialized yet
ApiError: Raises with an error message of API return on non-zero error code

RxConnector.item_update

def item_update(
    namespace: str,
    item_def: Dict,
    precepts: List[str] = None,
    timeout: timedelta = timedelta(milliseconds=0)
) -> None

Updates an item with its precepts in the specified namespace

Arguments:

namespace (string): The name of the namespace
item_def (dict): A dictionary of item definition
precepts (:obj:`list` of :obj:`str`): A dictionary of index definition
timeout (`datetime.timedelta`): Optional timeout for performing a server-side operation.
    Minimum is 1 millisecond; if set to a lower value, it corresponds to disabling the timeout.
    A value of 0 disables the timeout (default value)

Raises:

ConnectionError: Raises with an error message when Reindexer instance is not initialized yet
ApiError: Raises with an error message of API return on non-zero error code

RxConnector.item_upsert

def item_upsert(
    namespace: str,
    item_def: Dict,
    precepts: List[str] = None,
    timeout: timedelta = timedelta(milliseconds=0)
) -> None

Updates an item with its precepts in the specified namespace. Creates the item if it does not exist

Arguments:

namespace (string): The name of the namespace
item_def (dict): A dictionary of item definition
precepts (:obj:`list` of :obj:`str`): A dictionary of index definition
timeout (`datetime.timedelta`): Optional timeout for performing a server-side operation.
    Minimum is 1 millisecond; if set to a lower value, it corresponds to disabling the timeout.
    A value of 0 disables the timeout (default value)

Raises:

ConnectionError: Raises with an error message when Reindexer instance is not initialized yet
ApiError: Raises with an error message of API return on non-zero error code

RxConnector.item_delete

def item_delete(
    namespace: str,
    item_def: Dict,
    timeout: timedelta = timedelta(milliseconds=0)) -> None

Deletes an item from the namespace specified

Arguments:

namespace (string): The name of the namespace
item_def (dict): A dictionary of item definition
timeout (`datetime.timedelta`): Optional timeout for performing a server-side operation.
    Minimum is 1 millisecond; if set to a lower value, it corresponds to disabling the timeout.
    A value of 0 disables the timeout (default value)

Raises:

ConnectionError: Raises with an error message when Reindexer instance is not initialized yet
ApiError: Raises with an error message of API return on non-zero error code

RxConnector.meta_put

def meta_put(
    namespace: str,
    key: str,
    value: str,
    timeout: timedelta = timedelta(milliseconds=0)) -> None

Puts metadata to a storage of Reindexer by key

Arguments:

namespace (string): The name of the namespace
key (string): A key in a storage of Reindexer for metadata keeping
value (string): A metadata for storage
timeout (`datetime.timedelta`): Optional timeout for performing a server-side operation.
    Minimum is 1 millisecond; if set to a lower value, it corresponds to disabling the timeout.
    A value of 0 disables the timeout (default value)

Raises:

ConnectionError: Raises with an error message when Reindexer instance is not initialized yet
ApiError: Raises with an error message of API return on non-zero error code

RxConnector.meta_get

def meta_get(namespace: str,
             key: str,
             timeout: timedelta = timedelta(milliseconds=0)) -> str

Gets metadata from a storage of Reindexer by key specified

Arguments:

namespace (string): The name of the namespace
key (string): A key in a storage of Reindexer where metadata is kept
timeout (`datetime.timedelta`): Optional timeout for performing a server-side operation.
    Minimum is 1 millisecond; if set to a lower value, it corresponds to disabling the timeout.
    A value of 0 disables the timeout (default value)

Returns:

string: A metadata value

Raises:

ConnectionError: Raises with an error message when Reindexer instance is not initialized yet
ApiError: Raises with an error message of API return on non-zero error code

RxConnector.meta_delete

def meta_delete(
    namespace: str, key: str,
    timeout: timedelta = timedelta(milliseconds=0)) -> None

Deletes metadata from a storage of Reindexer by key specified

Arguments:

namespace (string): The name of the namespace
key (string): A key in a storage of Reindexer where metadata is kept
timeout (`datetime.timedelta`): Optional timeout for performing a server-side operation.
    Minimum is 1 millisecond; if set to a lower value, it corresponds to disabling the timeout.
    A value of 0 disables the timeout (default value)

Raises:

ConnectionError: Raises with an error message when Reindexer instance is not initialized yet
ApiError: Raises with an error message of API return on non-zero error code

RxConnector.meta_enum

def meta_enum(
    namespace: str,
    timeout: timedelta = timedelta(milliseconds=0)) -> List[str]

Gets a list of metadata keys from a storage of Reindexer

Arguments:

namespace (string): The name of the namespace
timeout (`datetime.timedelta`): Optional timeout for performing a server-side operation.
    Minimum is 1 millisecond; if set to a lower value, it corresponds to disabling the timeout.
    A value of 0 disables the timeout (default value)

Returns:

(:obj:`list` of :obj:`str`): A list of all metadata keys

Raises:

ConnectionError: Raises with an error message when Reindexer instance is not initialized yet
ApiError: Raises with an error message of API return on non-zero error code

RxConnector.exec_sql

def exec_sql(
    query: str,
    timeout: timedelta = timedelta(milliseconds=0)) -> QueryResults

Executes an SQL query and returns query results

Arguments:

query (string): An SQL query
timeout (`datetime.timedelta`): Optional timeout for performing a server-side operation.
    Minimum is 1 millisecond; if set to a lower value, it corresponds to disabling the timeout.
    A value of 0 disables the timeout (default value)

Returns:

(:obj:`QueryResults`): A QueryResults iterator

Raises:

ConnectionError: Raises with an error message when Reindexer instance is not initialized yet
ApiError: Raises with an error message of API return on non-zero error code

RxConnector.new_transaction

def new_transaction(
    namespace: str,
    timeout: timedelta = timedelta(milliseconds=0)) -> Transaction

Starts a new transaction and return the transaction object to processing. Warning: once a timeout is set, it will apply to all subsequent steps in the transaction

Arguments:

namespace (string): The name of the namespace
timeout (`datetime.timedelta`): Optional timeout for performing a server-side operation.
    Minimum is 1 millisecond; if set to a lower value, it corresponds to disabling the timeout.
    A value of 0 disables the timeout (default value)

Returns:

(:obj:`Transaction`): A new transaction

Raises:

ConnectionError: Raises with an error message when Reindexer instance is not initialized yet
ApiError: Raises with an error message of API return on non-zero error code

RxConnector.new_query

def new_query(namespace: str) -> Query

Creates a new query and return the query object to processing

Arguments:

namespace (string): The name of the namespace

Returns:

(:obj:`Query`): A new query

Raises:

ConnectionError: Raises with an error message when Reindexer instance is not initialized yet

pyreindexer.query_results

QueryResults Objects

class QueryResults()

QueryResults is a disposable iterator of Reindexer results for such queries as SELECT etc. When the results are fetched the iterator closes and frees a memory of results buffer of Reindexer

Attributes:

api (module): An API module for Reindexer calls
err_code (int): The API error code
err_msg (string): The API error message
qres_wrapper_ptr (int): A memory pointer to Reindexer iterator object
qres_iter_count (int): A count of results for iterations
pos (int): The current result position in iterator

QueryResults.status

def status() -> None

Check status

Raises:

ApiError: Raises with an error message of API return on non-zero error code

QueryResults.count

def count() -> int

Returns a count of results for iterations

Returns

int: A count of results

QueryResults.total_count

def total_count() -> int

Returns a total or cached count of results

Returns

int: A total or cached count of results

QueryResults.get_agg_results

def get_agg_results() -> dict

Returns aggregation results for the current query

Returns

(:obj:`dict`): Dictionary with all results for the current query

Raises:

ApiError: Raises with an error message of API return on non-zero error code

QueryResults.get_explain_results

def get_explain_results() -> str

Returns explain results for the current query

Returns

(string): Formatted string with explain of results for the current query

Raises:

ApiError: Raises with an error message of API return on non-zero error code

pyreindexer.transaction

Transaction Objects

class Transaction()

An object representing the context of a Reindexer transaction

Attributes:

api (module): An API module for Reindexer calls
transaction_wrapper_ptr (int): A memory pointer to Reindexer transaction object
err_code (int): The API error code
err_msg (string): The API error message

Transaction.insert

def insert(item_def: Dict, precepts: List[str] = None) -> None

Inserts an item with its precepts to the transaction Warning: the timeout set when the transaction was created is used

Arguments:

item_def (dict): A dictionary of item definition
precepts (:obj:`list` of :obj:`str`): A dictionary of index definition

Raises:

TransactionError: Raises with an error message of API return if Transaction is over
ApiError: Raises with an error message of API return on non-zero error code

Transaction.update

def update(item_def: Dict, precepts: List[str] = None) -> None

Updates an item with its precepts to the transaction Warning: the timeout set when the transaction was created is used

Arguments:

item_def (dict): A dictionary of item definition
precepts (:obj:`list` of :obj:`str`): A dictionary of index definition

Raises:

TransactionError: Raises with an error message of API return if Transaction is over
ApiError: Raises with an error message of API return on non-zero error code

Transaction.update_query

def update_query(query: Query) -> None

Updates items with the transaction Read-committed isolation is available for read operations. Changes made in active transaction is invisible to current and another transactions.

Arguments:

query (:obj:`Query`): A query object to modify

Raises:

TransactionError: Raises with an error message of API return if Transaction is over
ApiError: Raises with an error message of API return on non-zero error code

Transaction.upsert

def upsert(item_def: Dict, precepts: List[str] = None) -> None

Updates an item with its precepts to the transaction. Creates the item if it does not exist Warning: the timeout set when the transaction was created is used

Arguments:

item_def (dict): A dictionary of item definition
precepts (:obj:`list` of :obj:`str`): A dictionary of index definition

Raises:

TransactionError: Raises with an error message of API return if Transaction is over
ApiError: Raises with an error message of API return on non-zero error code

Transaction.delete

def delete(item_def: Dict) -> None

Deletes an item from the transaction Warning: the timeout set when the transaction was created is used

Arguments:

item_def (dict): A dictionary of item definition

Raises:

TransactionError: Raises with an error message of API return if Transaction is over
ApiError: Raises with an error message of API return on non-zero error code

Transaction.delete_query

def delete_query(query: Query)

Deletes items with the transaction Read-committed isolation is available for read operations. Changes made in active transaction is invisible to current and another transactions.

Arguments:

query (:obj:`Query`): A query object to modify

Raises:

TransactionError: Raises with an error message of API return if Transaction is over
ApiError: Raises with an error message of API return on non-zero error code

Transaction.commit

def commit(timeout: timedelta = timedelta(milliseconds=0)) -> None

Applies changes

Arguments:

timeout (`datetime.timedelta`): Optional timeout for performing a server-side operation.
    Minimum is 1 millisecond; if set to a lower value, it corresponds to disabling the timeout.
    A value of 0 disables the timeout (default value)

Raises:

TransactionError: Raises with an error message of API return if Transaction is over
ApiError: Raises with an error message of API return on non-zero error code

Transaction.commit_with_count

def commit_with_count(timeout: timedelta = timedelta(milliseconds=0)) -> int

Applies changes and return the number of count of changed items

Arguments:

timeout (`datetime.timedelta`): Optional timeout for performing a server-side operation.
    Minimum is 1 millisecond; if set to a lower value, it corresponds to disabling the timeout.
    A value of 0 disables the timeout (default value)

Raises:

TransactionError: Raises with an error message of API return if Transaction is over
ApiError: Raises with an error message of API return on non-zero error code

Transaction.rollback

def rollback(timeout: timedelta = timedelta(milliseconds=0)) -> None

Rollbacks changes

Arguments:

timeout (`datetime.timedelta`): Optional timeout for performing a server-side operation.
    Minimum is 1 millisecond; if set to a lower value, it corresponds to disabling the timeout.
    A value of 0 disables the timeout (default value)

Raises:

TransactionError: Raises with an error message of API return if Transaction is over
ApiError: Raises with an error message of API return on non-zero error code

pyreindexer.point

Point Objects

class Point()

An object representing the context of a Reindexer 2D point

Attributes:

x (float): x coordinate of the point
y (float): y coordinate of the point

pyreindexer.query

Query Objects

class Query()

An object representing the context of a Reindexer query

Attributes:

api (module): An API module for Reindexer calls
query_wrapper_ptr (int): A memory pointer to Reindexer query object
err_code (int): The API error code
err_msg (string): The API error message
root (:object: Optional[`Query`]): The root query of the Reindexer query
join_queries (list[:object:`Query`]): The list of join Reindexer query objects
merged_queries (list[:object:`Query`]): The list of merged Reindexer query objects

Query.where

def where(
        index: str,
        condition: CondType,
        keys: Union[simple_types, tuple[list[simple_types],
                                        ...]] = None) -> Query

Adds where condition to DB query with args

Arguments:

index (string): Field name used in condition clause
condition (:enum:`CondType`): Type of condition
keys (union[simple_types, (list[simple_types], ...)]):
    Value of index to be compared with. For composite indexes keys must be list,
    with value of each sub-index

Returns:

(:obj:`Query`): Query object for further customizations

Raises:

ApiError: Raises with an error message of API return on non-zero error code

Query.where_query

def where_query(
        sub_query: Query,
        condition: CondType,
        keys: Union[simple_types, tuple[list[simple_types],
                                        ...]] = None) -> Query

Adds sub-query where condition to DB query with args

Arguments:

sub_query (:obj:`Query`): Field name used in condition clause
condition (:enum:`CondType`): Type of condition
keys (union[simple_types, (list[simple_types], ...)]):
    Value of index to be compared with. For composite indexes keys must be list,
    with value of each sub-index

Returns:

(:obj:`Query`): Query object for further customizations

Raises:

ApiError: Raises with an error message of API return on non-zero error code

Query.where_subquery

def where_subquery(index: str, condition: CondType, sub_query: Query) -> Query

Adds sub-query where condition to DB query

Arguments:

index (string): Field name used in condition clause
condition (:enum:`CondType`): Type of condition
sub_query (:obj:`Query`): Field name used in condition clause

Returns:

(:obj:`Query`): Query object for further customizations

Query.where_composite

def where_composite(index: str, condition: CondType,
                    keys: tuple[list[simple_types], ...]) -> Query

Adds where condition to DB query with interface args for composite indexes

Arguments:

index (string): Field name used in condition clause
condition (:enum:`CondType`): Type of condition
keys (list[simple_types], ...): Values of composite index to be compared with (value of each sub-index).
    Supported variants:
        ([1, "test1"], [2, "test2"])
        [[1, "test1"], [2, "test2"]])
        ([1, "testval1"], )
        [[1, "testval1"]]
        (1, "testval1")

Returns:

(:obj:`Query`): Query object for further customizations

Raises:

ApiError: Raises with an error message of API return on non-zero error code

Query.where_uuid

def where_uuid(index: str, condition: CondType, *uuids: UUID) -> Query

Adds where condition to DB query with UUID. index MUST be declared as uuid-string index in this case

Arguments:

index (string): Field name used in condition clause
condition (:enum:`CondType`): Type of condition
uuids (*:obj:`UUID`): Value of index to be compared with. For composite indexes uuids must be list,
    with value of each sub-index

Returns:

(:obj:`Query`): Query object for further customizations

Raises:

ApiError: Raises with an error message of API return on non-zero error code

Query.where_between_fields

def where_between_fields(first_field: str, condition: CondType,
                         second_field: str) -> Query

Adds comparing two fields where condition to DB query

Arguments:

first_field (string): First field name used in condition clause
condition (:enum:`CondType`): Type of condition
second_field (string): Second field name used in condition clause

Returns:

(:obj:`Query`): Query object for further customizations

Query.where_knn

def where_knn(
    index: str, vec: List[float],
    param: Union[IndexSearchParamBruteForce | IndexSearchParamHnsw | IndexSearchParamIvf]
) -> Query

Adds where condition to DB query with float_vector as args. index MUST be declared as float_vector index in this case

Arguments:

index (string): Field name used in condition clause (only float_vector)
vec (list[float]): KNN value of index to be compared with
param (:obj:`union[IndexSearchParamBruteForce|IndexSearchParamHnsw|IndexSearchParamIvf]`): KNN search parameters

Returns:

(:obj:`Query`): Query object for further customizations

Raises:

QueryError: Raises with an error message if no vec are specified
QueryError: Raises with an error message if no param are specified or have an invalid value
ApiError: Raises with an error message of API return on non-zero error code

Query.where_knn_string

def where_knn_string(
    index: str, value: str,
    param: Union[IndexSearchParamBruteForce | IndexSearchParamHnsw | IndexSearchParamIvf]
) -> Query

Adds where condition to DB query with string as args. index MUST be declared as float_vector index in this case. WARNING: Only relevant if automatic embedding is configured for this float_vector index

Arguments:

index (string): Field name used in condition clause (only float_vector)
value (string): value to be generated using automatic embedding of KNN index value to be compared to
param (:obj:`union[IndexSearchParamBruteForce|IndexSearchParamHnsw|IndexSearchParamIvf]`): KNN search parameters

Returns:

(:obj:`Query`): Query object for further customizations

Raises:

QueryError: Raises with an error message if no value are specified
QueryError: Raises with an error message if no param are specified or have an invalid value
ApiError: Raises with an error message of API return on non-zero error code

Query.open_bracket

def open_bracket() -> Query

Opens bracket for where condition to DB query

Returns:

(:obj:`Query`): Query object for further customizations

Raises:

ApiError: Raises with an error message of API return on non-zero error code

Query.close_bracket

def close_bracket() -> Query

Closes bracket for where condition to DB query

Returns:

(:obj:`Query`): Query object for further customizations

Raises:

ApiError: Raises with an error message of API return on non-zero error code

Query.match

def match(index: str, *keys: str) -> Query

Adds string EQ-condition to DB query with string args

Arguments:

index (string): Field name used in condition clause
keys (*string): Value of index to be compared with. For composite indexes keys must be list,
    with value of each sub-index

Returns:

(:obj:`Query`): Query object for further customizations

Raises:

ApiError: Raises with an error message of API return on non-zero error code

Query.dwithin

def dwithin(index: str, point: Point, distance: float) -> Query

Adds DWithin condition to DB query

Arguments:

index (string): Field name used in condition clause
point (:obj:`Point`): Point object used in condition clause
distance (float): Distance in meters between point

Returns:

(:obj:`Query`): Query object for further customizations

Query.distinct

def distinct(index: str) -> Query

Performs distinct for a certain index. Return only items with uniq value of field

Arguments:

index (string): Field name for distinct operation

Returns:

(:obj:`Query`): Query object for further customizations

Query.aggregate_sum

def aggregate_sum(index: str) -> Query

Performs a summation of values for a specified index

Arguments:

index (string): Field name for sum operation

Returns:

(:obj:`Query`): Query object for further customizations

Query.aggregate_avg

def aggregate_avg(index: str) -> Query

Finds for the average at the specified index

Arguments:

index (string): Field name for sum operation

Returns:

(:obj:`Query`): Query object for further customizations

Query.aggregate_min

def aggregate_min(index: str) -> Query

Finds for the minimum at the specified index

Arguments:

index (string): Field name for sum operation

Returns:

(:obj:`Query`): Query object for further customizations

Query.aggregate_max

def aggregate_max(index: str) -> Query

Finds for the maximum at the specified index

Arguments:

index (string): Field name for sum operation

Returns:

(:obj:`Query`): Query object for further customizations

Query.aggregate_facet

def aggregate_facet(*fields: str) -> Query._AggregateFacet

Gets fields facet value. Applicable to multiple data fields and the result of that could be sorted by any data column or count and cut off by offset and limit. In order to support this functionality this method returns AggregationFacetRequest which has methods sort, limit and offset

Arguments:

fields (*string): Fields any data column name or `count`, fields should not be empty

Returns:

(:obj:`_AggregateFacet`): Request object for further customizations

Query.sort

def sort(
    index: str,
    desc: bool = False,
    forced_sort_values: Union[simple_types, tuple[list[simple_types],
                                                  ...]] = None
) -> Query

Applies sort order to return from query items. If forced_sort_values argument specified, then items equal to values, if found will be placed in the top positions. Forced sort is support for the first sorting field only

Arguments:

index (string): The index name
desc (bool): Sort in descending order
forced_sort_values (union[simple_types, (list[simple_types], ...)]):
    Value of index to match. For composite indexes keys must be list, with value of each sub-index

Returns:

(:obj:`Query`): Query object for further customizations

Raises:

ApiError: Raises with an error message of API return on non-zero error code

Query.sort_stpoint_distance

def sort_stpoint_distance(index: str, point: Point, desc: bool) -> Query

Applies geometry sort order to return from query items. Wrapper for geometry sorting by shortest distance between geometry field and point (ST_Distance)

Arguments:

index (string): The index name
point (:obj:`Point`): Point object used in sorting operation
desc (bool): Sort in descending order

Returns:

(:obj:`Query`): Query object for further customizations

Query.sort_stfield_distance

def sort_stfield_distance(first_field: str, second_field: str,
                          desc: bool) -> Query

Applies geometry sort order to return from query items. Wrapper for geometry sorting by shortest distance between 2 geometry fields (ST_Distance)

Arguments:

first_field (string): First field name used in condition
second_field (string): Second field name used in condition
desc (bool): Sort in descending order

Returns:

(:obj:`Query`): Query object for further customizations

Raises:

ApiError: Raises with an error message of API return on non-zero error code

Query.op_and

def op_and() -> Query

Next condition will be added with AND. This is the default operation for WHERE statement. Do not have to be called explicitly in user's code. Used in DSL conversion

Returns:

(:obj:`Query`): Query object for further customizations

Query.op_or

def op_or() -> Query

Next condition will be added with OR. Implements short-circuiting: if the previous condition is successful the next will not be evaluated, but except Join conditions

Returns:

(:obj:`Query`): Query object for further customizations

Query.op_not

def op_not() -> Query

Next condition will be added with NOT AND. Implements short-circuiting: if the previous condition is failed the next will not be evaluated

Returns:

(:obj:`Query`): Query object for further customizations

Query.request_total

def request_total() -> Query

Requests total items calculation

Arguments:

total_name (string, optional): Name to be requested

Returns:

(:obj:`Query`): Query object for further customizations

Query.cached_total

def cached_total() -> Query

Requests cached total items calculation

Arguments:

total_name (string, optional): Name to be requested

Returns:

(:obj:`Query`): Query object for further customizations

Query.limit

def limit(limit_items: int) -> Query

Sets a limit (count) of returned items. Analog to sql LIMIT rowsNumber

Arguments:

limit_items (int): Number of rows to get from result set

Returns:

(:obj:`Query`): Query object for further customizations

Query.offset

def offset(start_offset: int) -> Query

Sets the number of the first selected row from result query

Arguments:

limit_items (int): Index of the first row to get from result set

Returns:

(:obj:`Query`): Query object for further customizations

Query.debug

def debug(level: LogLevel) -> Query

Changes debug log level on server

Arguments:

level (:enum:`LogLevel`): Debug log level on server

Returns:

(:obj:`Query`): Query object for further customizations

Query.strict

def strict(mode: StrictMode) -> Query

Changes strict mode

Arguments:

mode (:enum:`StrictMode`): Strict mode

Returns:

(:obj:`Query`): Query object for further customizations

Query.explain

def explain() -> Query

Enables explain query

Returns:

(:obj:`Query`): Query object for further customizations

Query.with_rank

def with_rank() -> Query

Outputs fulltext/float_vector rank. Allowed only with fulltext and KNN query

Returns:

(:obj:`Query`): Query object for further customizations

Query.execute

def execute(timeout: timedelta = timedelta(milliseconds=0)) -> QueryResults

Executes a select query

Arguments:

timeout (`datetime.timedelta`): Optional timeout for performing a server-side operation.
    Minimum is 1 millisecond; if set to a lower value, it corresponds to disabling the timeout.
    A value of 0 disables the timeout (default value)

Returns:

(:obj:`QueryResults`): A QueryResults iterator

Raises:

ApiError: Raises with an error message when query is in an invalid state
ApiError: Raises with an error message of API return on non-zero error code

Query.delete

def delete(timeout: timedelta = timedelta(milliseconds=0)) -> int

Executes a query, and delete items, matches query

Arguments:

timeout (`datetime.timedelta`): Optional timeout for performing a server-side operation.
    Minimum is 1 millisecond; if set to a lower value, it corresponds to disabling the timeout.
    A value of 0 disables the timeout (default value)

Returns:

(int): Number of deleted elements

Raises:

QueryError: Raises with an error message when query is in an invalid state
ApiError: Raises with an error message of API return on non-zero error code

Query.set_object

def set_object(field: str, values: list[simple_types]) -> Query

Adds an update query to an object field for an update query

Arguments:

field (string): Field name
values (list[simple_types]): List of values to add

Returns:

(:obj:`Query`): Query object for further customizations

Raises:

QueryError: Raises with an error message if no values are specified
ApiError: Raises with an error message of API return on non-zero error code

Query.set

def set(field: str, values: list[simple_types]) -> Query

Adds a field update request to the update request

Arguments:

field (string): Field name
values (list[simple_types]): List of values to add

Returns:

(:obj:`Query`): Query object for further customizations

Raises:

ApiError: Raises with an error message of API return on non-zero error code

Query.drop

def drop(index: str) -> Query

Drops a value for a field

Arguments:

index (string): Field name for drop operation

Returns:

(:obj:`Query`): Query object for further customizations

Query.expression

def expression(field: str, value: str) -> Query

Updates indexed field by arithmetical expression

Arguments:

field (string): Field name
value (string): New value expression for field

Returns:

(:obj:`Query`): Query object for further customizations

Query.update

def update(timeout: timedelta = timedelta(milliseconds=0)) -> QueryResults

Executes update query, and update fields in items, which matches query

Arguments:

timeout (`datetime.timedelta`): Optional timeout for performing a server-side operation.
    Minimum is 1 millisecond; if set to a lower value, it corresponds to disabling the timeout.
    A value of 0 disables the timeout (default value)

Returns:

(:obj:`QueryResults`): A QueryResults iterator

Raises:

QueryError: Raises with an error message when query is in an invalid state
ApiError: Raises with an error message of API return on non-zero error code

Query.must_execute

def must_execute(timeout: timedelta = timedelta(
    milliseconds=0)) -> QueryResults

Executes a query, and update fields in items, which matches query, with status check

Arguments:

timeout (`datetime.timedelta`): Optional timeout for performing a server-side operation.
    Minimum is 1 millisecond; if set to a lower value, it corresponds to disabling the timeout.
    A value of 0 disables the timeout (default value)

Returns:

(:obj:`QueryResults`): A QueryResults iterator

Raises:

ApiError: Raises with an error message when query is in an invalid state
ApiError: Raises with an error message of API return on non-zero error code

Query.get

def get(timeout: timedelta = timedelta(milliseconds=0)) -> (str, bool)

Executes a query, and return 1 JSON item

Arguments:

timeout (`datetime.timedelta`): Optional timeout for performing a server-side operation.
    Minimum is 1 millisecond; if set to a lower value, it corresponds to disabling the timeout.
    A value of 0 disables the timeout (default value)

Returns:

(:tuple:string,bool): 1st string item and found flag

Raises:

ApiError: Raises with an error message when query is in an invalid state
ApiError: Raises with an error message of API return on non-zero error code

Query.inner_join

def inner_join(query: Query, field: str) -> Query

Joins 2 queries. Items from the 1-st query are filtered by and expanded with the data from the 2-nd query

Arguments:

query (:obj:`Query`): Query object to left join
field (string): Joined field name. As unique identifier for the join between this query and `join_query`.
    Parameter in order for InnerJoin to work: namespace of `query` contains `field` as one of its fields
    marked as `joined`

Returns:

(:obj:`Query`): Query object for further customizations

Query.join

def join(query: Query, field: str) -> Query

Join is an alias for LeftJoin. Joins 2 queries. Items from this query are expanded with the data from the query

Arguments:

query (:obj:`Query`): Query object to left join
field (string): Joined field name. As unique identifier for the join between this query and `join_query`

Returns:

(:obj:`Query`): Query object for further customizations

Query.left_join

def left_join(join_query: Query, field: str) -> Query

Joins 2 queries. Items from this query are expanded with the data from the join_query. One of the conditions below must hold for field parameter in order for LeftJoin to work: namespace of join_query contains field as one of its fields marked as joined

Arguments:

query (:obj:`Query`): Query object to left join
field (string): Joined field name. As unique identifier for the join between this query and `join_query`

Returns:

(:obj:`Query`): Query object for further customizations

Query.merge

def merge(query: Query) -> Query

Merges queries of the same type

Arguments:

query (:obj:`Query`): Query object to merge

Returns:

(:obj:`Query`): Query object for further customizations

Query.on

def on(index: str, condition: CondType, join_index: str) -> Query

On specifies join condition

Arguments:

index (string): Field name from `Query` namespace should be used during join
condition (:enum:`CondType`): Type of condition, specifies how `Query` will be joined with the latest join query issued on `Query` (e.g. `EQ`/`GT`/`SET`/...)
join_index (string): Index-field name from namespace for the latest join query issued on `Query` should be used during join

Returns:

(:obj:`Query`): Query object for further customizations

Raises:

QueryError: Raises with an error message when query is in an invalid state

Query.select_fields

def select_fields(*fields: str) -> Query

Sets list of columns in this namespace to be finally selected. The columns should be specified in the same case as the jsonpaths corresponding to them. Non-existent fields and fields in the wrong case are ignored. If there are no fields in this list that meet these conditions, then the filter works as "*"

Arguments:

fields (*string): List of columns to be selected

Returns:

(:obj:`Query`): Query object for further customizations

Raises:

ApiError: Raises with an error message of API return on non-zero error code

Query.functions

def functions(*functions: str) -> Query

Adds sql-functions to query

Arguments:

functions (*string): Functions declaration

Returns:

(:obj:`Query`): Query object for further customizations

Raises:

ApiError: Raises with an error message of API return on non-zero error code

Query.equal_position

def equal_position(*equal_position: str) -> Query

Adds equal position fields to arrays queries

Arguments:

equal_poses (*string): Equal position fields to arrays queries

Returns:

(:obj:`Query`): Query object for further customizations

Raises:

ApiError: Raises with an error message of API return on non-zero error code

pyreindexer.index_search_params

IndexSearchParamBruteForce Objects

class IndexSearchParamBruteForce()

Index search param for brute force index. Equal to basic parameters

Attributes:

k (int): Expected size of KNN index results. Should not be less than 1
radius (float): In addition to the parameter `k`, the query results can also be filtered by a `rank` -
  value using the parameter, witch called `radius`. It's named so because, under the `L2`-metric,
  it restricts vectors from query result to a sphere of the specified radius. [More about `radius`]
  (https://github.com/Restream/reindexer/blob/master/float_vector.md)

IndexSearchParamHnsw Objects

class IndexSearchParamHnsw()

Index search param for HNSW index.

Attributes:

k (int): Expected size of KNN index results. Should not be less than 1
ef (int): Size of nearest neighbor buffer that will be filled during fetching. Should not be less than 'k',
good story when `ef` ~= 1.5 * `k`
radius (float): In addition to the parameter `k`, the query results can also be filtered by a `rank` -
  value using the parameter, witch called `radius`. It's named so because, under the `L2`-metric,
  it restricts vectors from query result to a sphere of the specified radius. [More about `radius`]
  (https://github.com/Restream/reindexer/blob/master/float_vector.md)

IndexSearchParamIvf Objects

class IndexSearchParamIvf()

Index search param for IVF index.

Attributes:

k (int): Expected size of KNN index results. Should not be less than 1
nprobe (int): Number of centroids that will be scanned in where. Should not be less than 1
radius (float): In addition to the parameter `k`, the query results can also be filtered by a `rank` -
  value using the parameter, witch called `radius`. It's named so because, under the `L2`-metric,
  it restricts vectors from query result to a sphere of the specified radius. [More about `radius`]
  (https://github.com/Restream/reindexer/blob/master/float_vector.md)

pyreindexer.index_definition

IndexDefinition Objects

class IndexDefinition(dict)

IndexDefinition is a dictionary subclass which allows to construct and manage indexes more efficiently. NOT IMPLEMENTED YET. USE FIELDS DESCRIPTION ONLY.

Arguments:

name (str): An index name.
json_paths (:obj:`list` of :obj:`str`): A name for mapping a value to a json field.
field_type (str): A type of field. Possible values are: `int`, `int64`, `double`, `string`, `bool`,
`composite`, `float_vector`.
index_type (str): An index type. Possible values are: `hash`, `tree`, `text`, `-`, `hnsw`, `vec_bf`, `ivf`.
is_pk (bool): True if a field is a primary key.
is_array (bool): True if an index is an array.
is_dense (bool): True if an index is dense. Reduce the index size. Saves 8 bytes per unique key value for 'hash'
    and 'tree' index types. For '-' index type saves 4-8 bytes per each element. Useful for indexes with
    high selectivity, but for tree and hash indexes with low selectivity can seriously decrease update
    performance.
is_no_column (bool): True if allows to disable column subindex. Reduces the index size.
    Allows to save ~(`stored_type_size` * `namespace_items_count`) bytes, where `stored_type_size` is the size
    of the type stored in the index, and `namespace_items_count` is the number of items in the namespace.
    May reduce performance.
is_sparse (bool): True if a value of an index may be not presented.
collate_mode (str): Sets an order of values by collate mode. Possible values are:
    `none`, `ascii`, `utf8`, `numeric`, `custom`.
sort_order_letters (str): Order for a sort sequence for a custom collate mode.
config (dict): A config for a fulltext and float_vector engine.
[More about `fulltext`](https://github.com/Restream/reindexer/blob/master/fulltext.md) or
[More about `float_vector`](https://github.com/Restream/reindexer/blob/master/float_vector.md).