pyignite.client module

This module contains Client class, that lets you communicate with Apache Ignite cluster node by the means of Ignite binary client protocol.

To start the communication, you may connect to the node of their choice by instantiating the Client object and calling connect() method with proper parameters.

The whole storage room of Ignite cluster is split up into named structures, called caches. For accessing the particular cache in key-value style (a-la Redis or memcached) you should first create the Cache object by calling create_cache() or get_or_create_cache() methods, than call Cache methods. If you wish to create a cache object without communicating with server, there is also a get_cache() method that does just that.

For using Ignite SQL, call sql() method. It returns a generator with result rows.

register_binary_type() and query_binary_type() methods operates the local (class-wise) registry for Ignite Complex objects.

class pyignite.client.Client(compact_footer: bool = None, *args, **kwargs)

Bases: pyignite.connection.Connection

This is a main pyignite class, that is build upon the Connection. In addition to the attributes, properties and methods of its parent class, Client implements the following features:

  • cache factory. Cache objects are used for key-value operations,
  • Ignite SQL endpoint,
  • binary types registration endpoint.
__init__(compact_footer: bool = None, *args, **kwargs)

Initialize client.

Parameters:compact_footer – (optional) use compact (True, recommended) or full (False) schema approach when serializing Complex objects. Default is to use the same approach the server is using (None). Apache Ignite binary protocol documentation on this topic: https://apacheignite.readme.io/docs/binary-client-protocol-data-format#section-schema

This property remembers Complex object schema encoding approach when decoding any Complex object, to use the same approach on Complex object encoding.

Returns:True if compact schema was used by server or no Complex object decoding has yet taken place, False if full schema was used.
create_cache(settings: Union[str, dict]) → pyignite.cache.Cache

Creates Ignite cache by name. Raises CacheError if such a cache is already exists.

Parameters:settings – cache name or dict of cache properties’ codes and values. All cache properties are documented here: Cache Properties. See also the cache creation example,
Returns:Cache object.
get_binary_type(binary_type: Union[str, int]) → dict

Gets the binary type information from the Ignite server. This is quite a low-level implementation of Ignite thin client protocol’s OP_GET_BINARY_TYPE operation. You would probably want to use query_binary_type() instead.

Parameters:binary_type – binary type name or ID,
Returns:binary type description − a dict with the following fields:
  • type_exists: True if the type is registered, False otherwise. In the latter case all the following fields are omitted,
  • type_id: Complex object type ID,
  • type_name: Complex object type name,
  • affinity_key_field: string value or None,
  • is_enum: False in case of Complex object registration,
  • schemas: a list, containing the Complex object schemas in format: OrderedDict[field name: field type hint]. A schema can be empty.
get_cache(settings: Union[str, dict]) → pyignite.cache.Cache

Creates Cache object with a given cache name without checking it up on server. If such a cache does not exist, some kind of exception (most probably CacheError) may be raised later.

Parameters:settings – cache name or cache properties (but only PROP_NAME property is allowed),
Returns:Cache object.
get_cache_names() → list

Gets existing cache names.

Returns:list of cache names.
get_or_create_cache(settings: Union[str, dict]) → pyignite.cache.Cache

Creates Ignite cache, if not exist.

Parameters:settings – cache name or dict of cache properties’ codes and values. All cache properties are documented here: Cache Properties. See also the cache creation example,
Returns:Cache object.
put_binary_type(type_name: str, affinity_key_field: str = None, is_enum=False, schema: dict = None)

Registers binary type information in cluster. Do not update binary registry. This is a literal implementation of Ignite thin client protocol’s OP_PUT_BINARY_TYPE operation. You would probably want to use register_binary_type() instead.

Parameters:
  • type_name – name of the data type being registered,
  • affinity_key_field – (optional) name of the affinity key field,
  • is_enum – (optional) register enum if True, binary object otherwise. Defaults to False,
  • schema – (optional) when register enum, pass a dict of enumerated parameter names as keys and an integers as values. When register binary type, pass a dict of field names: field types. Binary type with no fields is OK.
query_binary_type(binary_type: Union[int, str], schema: Union[int, dict] = None, sync: bool = True)

Queries the registry of Complex object classes.

Parameters:
  • binary_type – Complex object type name or ID,
  • schema – (optional) Complex object schema or schema ID,
  • sync – (optional) look up the Ignite server for registered Complex objects and create data classes for them if needed,
Returns:

found dataclass or None, if schema parameter is provided, a dict of {schema ID: dataclass} format otherwise.
register_binary_type(data_class: Type[CT_co], affinity_key_field: str = None)

Register the given class as a representation of a certain Complex object type. Discards autogenerated or previously registered class.

Parameters:
  • data_class – Complex object class,
  • affinity_key_field – (optional) affinity parameter.
sql(query_str: str, page_size: int = 1, query_args: Iterable[T_co] = None, schema: Union[int, str] = 'PUBLIC', statement_type: int = 0, distributed_joins: bool = False, local: bool = False, replicated_only: bool = False, enforce_join_order: bool = False, collocated: bool = False, lazy: bool = False, include_field_names: bool = False, max_rows: int = -1, timeout: int = 0)

Runs an SQL query and returns its result.

Parameters:
  • query_str – SQL query string,
  • page_size – (optional) cursor page size. Default is 1, which means that client makes one server call per row,
  • query_args – (optional) query arguments. List of values or (value, type hint) tuples,
  • schema – (optional) schema for the query. Defaults to PUBLIC,
  • statement_type –

    (optional) statement type. Can be:

    • StatementType.ALL − any type (default),
    • StatementType.SELECT − select,
    • StatementType.UPDATE − update.
  • distributed_joins – (optional) distributed joins. Defaults to False,
  • local – (optional) pass True if this query should be executed on local node only. Defaults to False,
  • replicated_only – (optional) whether query contains only replicated tables or not. Defaults to False,
  • enforce_join_order – (optional) enforce join order. Defaults to False,
  • collocated – (optional) whether your data is co-located or not. Defaults to False,
  • lazy – (optional) lazy query execution. Defaults to False,
  • include_field_names – (optional) include field names in result. Defaults to False,
  • max_rows – (optional) query-wide maximum of rows. Defaults to -1 (all rows),
  • timeout – (optional) non-negative timeout value in ms. Zero disables timeout (default),
Returns:

generator with result rows as a lists. If include_field_names was set, the first row will hold field names.