SmartRedis API

SmartRedis API#

Python#

The following page provides a comprehensive overview of the SmartRedis Python Client, DataSet and Logging APIs. Further explanation and details of each are presented below.

Client API#

The Client API is purpose-built for interaction with the backend database, which extends the capabilities of the Redis in-memory data store. It’s important to note that the SmartRedis Client API is the exclusive means for altering, transmitting, and receiving data within the backend database. More specifically, the Client API is responsible for both creating and modifying data structures, which encompass Models, Scripts, and Tensors. It also handles the transmission and reception of the aforementioned data structures in addition to Dataset data structure. Creating and modifying the DataSet object is confined to local operation by the DataSet API.

Client Class Method Overview#

`Client.__init__`(a, *kw)	Initialize a SmartRedis client
`Client.__str__`()	Create a string representation of the client
`Client.put_tensor`(name, data)	Put a tensor to a Redis database
`Client.get_tensor`(name)	Get a tensor from the database
`Client.delete_tensor`(name)	Delete a tensor from the database
`Client.copy_tensor`(src_name, dest_name)	Copy a tensor at one name to another name
`Client.rename_tensor`(old_name, new_name)	Rename a tensor in the database
`Client.tensor_exists`(name)	Check if a tensor exists in the database
`Client.poll_tensor`(name, poll_frequency_ms, ...)	Check if a tensor exists in the database
`Client.put_dataset`(dataset)	Put a Dataset instance into the database
`Client.get_dataset`(name)	Get a dataset from the database
`Client.delete_dataset`(name)	Delete a dataset within the database
`Client.copy_dataset`(src_name, dest_name)	Copy a dataset from one key to another
`Client.rename_dataset`(old_name, new_name)	Rename a dataset in the database
`Client.dataset_exists`(name)	Check if a dataset exists in the database
`Client.poll_dataset`(name, poll_frequency_ms, ...)	Check if a dataset exists in the database
`Client.set_function`(name, function[, device])	Set a callable function into the database
`Client.set_function_multigpu`(name, function, ...)	Set a callable function into the database for use in a multi-GPU system
`Client.set_script`(name, script[, device])	Store a TorchScript at a key in the database
`Client.set_script_multigpu`(name, script, ...)	Store a TorchScript at a key in the database
`Client.set_script_from_file`(name, file[, device])	Same as Client.set_script, but from file
`Client.set_script_from_file_multigpu`(name, ...)	Same as Client.set_script_multigpu, but from file
`Client.get_script`(name)	Retrieve a Torchscript stored in the database
`Client.run_script`(name, fn_name, inputs, outputs)	Execute TorchScript stored inside the database
`Client.run_script_multigpu`(name, fn_name, ...)	Execute TorchScript stored inside the database
`Client.delete_script`(name)	Remove a script from the database
`Client.delete_script_multigpu`(name, ...)	Remove a script from the database
`Client.set_model`(name, model, backend[, ...])	Put a TF, TF-lite, PT, or ONNX model in the database
`Client.set_model_multigpu`(name, model, ...)	Put a TF, TF-lite, PT, or ONNX model in the database for use in a multi-GPU system
`Client.set_model_from_file`(name, model_file, ...)	Put a TF, TF-lite, PT, or ONNX model from file in the database
`Client.set_model_from_file_multigpu`(name, ...)	Put a TF, TF-lite, PT, or ONNX model from file in the database for use in a multi-GPU system
`Client.get_model`(name)	Get a stored model
`Client.run_model`(name[, inputs, outputs])	Execute a stored model
`Client.run_model_multigpu`(name, offset, ...)	Execute a model stored for a multi-GPU system
`Client.delete_model`(name)	Remove a model from the database
`Client.delete_model_multigpu`(name, ...)	Remove a model from the database that was stored for use with multiple GPUs
`Client.model_exists`(name)	Check if a model or script exists in the database
`Client.poll_model`(name, poll_frequency_ms, ...)	Check if a model or script exists in the database
`Client.key_exists`(key)	Check if the key exists in the database
`Client.poll_key`(key, poll_frequency_ms, ...)	Check if the key exists in the database
`Client.set_data_source`(source_id)	Set the data source, a key prefix for future operations
`Client.use_tensor_ensemble_prefix`(use_prefix)	Control whether tensor keys are prefixed (e.g.
`Client.use_dataset_ensemble_prefix`(use_prefix)	Control whether dataset keys are prefixed (e.g. in an ensemble)
`Client.use_model_ensemble_prefix`(use_prefix)	Control whether model and script keys are
`Client.use_list_ensemble_prefix`(use_prefix)	Control whether aggregation lists are prefixed
`Client.get_db_node_info`(addresses)	Returns information about given database nodes
`Client.get_db_cluster_info`(addresses)	Returns cluster information from a specified db node.
`Client.get_ai_info`(address, key[, reset_stat])	Returns AI.INFO command reply information for the script or model key at the provided addresses.
`Client.flush_db`(addresses)	Removes all keys from a specified db node.
`Client.config_get`(expression, address)	Read the configuration parameters of a running server.
`Client.config_set`(config_param, value, address)	Reconfigure the server.
`Client.save`(addresses)	Performs a synchronous save of the database shard producing a point in time snapshot of all the data inside the Redis instance, in the form of an RBD file.
`Client.append_to_list`(list_name, dataset)	Appends a dataset to the aggregation list
`Client.delete_list`(list_name)	Delete an aggregation list
`Client.copy_list`(src_name, dest_name)	Copy an aggregation list
`Client.rename_list`(src_name, dest_name)	Rename an aggregation list
`Client.get_list_length`(list_name)	Get the number of entries in the list
`Client.poll_list_length`(name, list_length, ...)	Poll list length until length is equal to the provided length.
`Client.poll_list_length_gte`(name, ...)	Poll list length until length is greater than or equal to the user-provided length.
`Client.poll_list_length_lte`(name, ...)	Poll list length until length is less than or equal to the user-provided length.
`Client.get_datasets_from_list`(list_name)	Get datasets from an aggregation list
`Client.get_dataset_list_range`(list_name, ...)	Get a range of datasets (by index) from an aggregation list

Client Class Method Detailed View#

class Client(*a: Any, **kw: Any)[source]#

Bases: SRObject

Initialize a SmartRedis client

At this time, the Client can be initialized with one of two signatures. The first version is preferred, though the second is supported (primarily for use in driver scripts). Note that the order was swapped for first two parameters in the second signature relative to previous releases of SmartRedis; this was necessary to remove ambiguity.

Client(config_options: ConfigOptions=None,
logger_name: str=”Default”)

Client(cluster: bool, address: optional(str)=None,
logger_name: str=”Default”)

For detailed information on the first signature, please refer to the __standard_construction() method below.

For detailed information on the second signature, please refer to the __address_construction() method below.

Parameters:

a (tuple[any]; see above for valid options) – The positional arguments supplied to this method; see above for valid options
kw (dict[string, any]; see above for valid options) – Keyword arguments supplied to this method; see above for valid options

Raises:

RedisConnectionError – if connection initialization fails

append_to_list(list_name: str, dataset: smartredis.dataset.Dataset) → None[source]#

Appends a dataset to the aggregation list

When appending a dataset to an aggregation list, the list will automatically be created if it does not exist (i.e. this is the first entry in the list). Aggregation lists work by referencing the dataset by storing its key, so appending a dataset to an aggregation list does not create a copy of the dataset. Also, for this reason, the dataset must have been previously placed into the database with a separate call to put_dataset().

Parameters:

list_name (str) – The name of the aggregation list
dataset (Dataset) – The DataSet to append

Raises:

TypeError – if argument is not a Dataset
RedisReplyError – if there is an error in command execution.

Return type:

None

config_get(expression: str, address: List[str]) → Dict[source]#

Read the configuration parameters of a running server. If the address does not correspond to a cluster node, an empty dictionary is returned.

Parameters:

expression (str) – Parameter used in the configuration or a glob pattern (Use ‘*’ to retrieve all configuration parameters)
address (str) – The address of the database node

Returns:

A dictionary that maps configuration parameters to their values. If the provided expression does not exist, then an empty dictionary is returned.

Return type:

dict

Raises:

RedisReplyError – if there is an error in command execution or the address is not reachable by the client. In the case of using a cluster of database nodes, it is best practice to bind each node in the cluster to a specific address to avoid inconsistencies in addresses retrieved with the CLUSTER SLOTS command. Inconsistencies in node addresses across CLUSTER SLOTS commands can lead to RedisReplyError being thrown.

config_set(config_param: str, value: str, address: str) → None[source]#

Reconfigure the server. It can change both trivial parameters or switch from one to another persistence option. All the configuration parameters set using this command are immediately loaded by Redis and will take effect starting with the next command executed. If the address does not correspond to a cluster node, an empty dictionary is returned.

Parameters:

config_param (str) – A configuration parameter to set
value (str) – The value to assign to the configuration parameter
address (str) – The address of the database node

Raises:

RedisReplyError – if there is an error in command execution or the address is not reachable by the client or if the config_param is unsupported. In the case of using a cluster of database nodes, it is best practice to bind each node in the cluster to a specific address to avoid inconsistencies in addresses retrieved with the CLUSTER SLOTS command. Inconsistencies in node addresses across CLUSTER SLOTS commands can lead to RedisReplyError being thrown.

Return type:

None

copy_dataset(src_name: str, dest_name: str) → None[source]#

Copy a dataset from one key to another

The source and destination dataset keys used to locate the dataset may be formed by applying prefixes to the supplied src_name and dest_name. See set_data_source() and use_dataset_ensemble_prefix() for more details.

Parameters:

src_name (str) – source name for dataset to be copied
dest_name (str) – new name of dataset

Raises:

RedisReplyError – if copy operation fails

Return type:

None

copy_list(src_name: str, dest_name: str) → None[source]#

Copy an aggregation list

The source and destination aggregation list keys used to locate and store the aggregation list may be formed by applying prefixes to the supplied src_name and dest_name. See set_data_source() and use_list_ensemble_prefix() for more details.

Parameters:

src_name (str) – The source list name
dest_name (str) – The destination list name

Raises:

RedisReplyError – if there is an error in command execution.

Return type:

None

copy_tensor(src_name: str, dest_name: str) → None[source]#

Copy a tensor at one name to another name

The source and destination tensor keys used to locate and store the tensor may be formed by applying prefixes to the supplied src_name and dest_name. See set_data_source() and use_tensor_ensemble_prefix() for more details.

Parameters:

src_name (str) – source name of tensor to be copied
dest_name (str) – name to store new copy at

Raises:

RedisReplyError – if copy operation fails

Return type:

None

dataset_exists(name: str) → bool[source]#

Check if a dataset exists in the database

The dataset key used to check for existence may be formed by applying a prefix to the supplied name. See set_data_source() and use_dataset_ensemble_prefix() for more details.

Parameters:: name (str) – The dataset name that will be checked in the database
Returns:: Returns true if the dataset exists in the database
Return type:: bool
Raises:: RedisReplyError – if dataset_exists fails (i.e. causes an error)

delete_dataset(name: str) → None[source]#

Delete a dataset within the database

The dataset key used to locate the dataset to be deleted may be formed by applying a prefix to the supplied name. See set_data_source() and use_dataset_ensemble_prefix() for more details.

Parameters:: name (str) – name of the dataset
Raises:: RedisReplyError – if deletion fails
Return type:: None

delete_list(list_name: str) → None[source]#

Delete an aggregation list

The key used to locate the aggregation list to be deleted may be formed by applying a prefix to the supplied name. See set_data_source() and use_list_ensemble_prefix() for more details.

Parameters:: list_name (str) – The name of the aggregation list
Raises:: RedisReplyError – if there is an error in command execution.
Return type:: None

delete_model(name: str) → None[source]#

Remove a model from the database

The model key used to locate the script to be run may be formed by applying a prefix to the supplied name. See set_data_source() and use_model_ensemble_prefix() for more details

Parameters:: name (str) – the name the model is stored under
Raises:: RedisReplyError – if model deletion fails
Return type:: None

delete_model_multigpu(name: str, first_gpu: int, num_gpus: str) → None[source]#

Remove a model from the database that was stored for use with multiple GPUs

The model key used to locate the script to be run may be formed by applying a prefix to the supplied name. See set_data_source() and use_model_ensemble_prefix() for more details

Parameters:

name (str) – the name the model is stored under
first_gpu (int) – the first GPU (zero-based) to use in processing this model
num_gpus (int) – the number of gpus for which the model was stored

Raises:

RedisReplyError – if model deletion fails

Return type:

None

delete_script(name: str) → None[source]#

Remove a script from the database

The script key used to locate the script to be run may be formed by applying a prefix to the supplied name. See set_data_source() and use_model_ensemble_prefix() for more details

Parameters:: name (str) – the name the script is stored under
Raises:: RedisReplyError – if script deletion fails
Return type:: None

delete_script_multigpu(name: str, first_gpu: int, num_gpus: int) → None[source]#

Remove a script from the database

The script key used to locate the script to be run may be formed by applying a prefix to the supplied name. See set_data_source() and use_model_ensemble_prefix() for more details

Parameters:

name (str) – the name the script is stored under
first_gpu (int) – the first GPU (zero-based) to use in processing this script
num_gpus (int) – the number of gpus for which the script was stored

Raises:

RedisReplyError – if script deletion fails

Return type:

None

delete_tensor(name: str) → None[source]#

Delete a tensor from the database

The tensor key used to locate the tensor to be deleted may be formed by applying a prefix to the supplied name. See set_data_source() and use_tensor_ensemble_prefix() for more details.

Parameters:: name (str) – name tensor is stored at
Raises:: RedisReplyError – if deletion fails
Return type:: None

flush_db(addresses: List[str]) → None[source]#

Removes all keys from a specified db node.

Parameters:: addresses (List[str]) – The addresses of the database nodes
Raises:: RedisReplyError – if there is an error in command execution or the address is not reachable by the client. In the case of using a cluster of database nodes, it is best practice to bind each node in the cluster to a specific address to avoid inconsistencies in addresses retrieved with the CLUSTER SLOTS command. Inconsistencies in node addresses across CLUSTER SLOTS commands can lead to RedisReplyError being thrown.
Return type:: None

get_ai_info(address: List[str], key: str, reset_stat: bool = False) → List[Dict][source]#

Returns AI.INFO command reply information for the script or model key at the provided addresses.

Parameters:

addresses – The addresses of the database nodes
key (str) – The key associated with the model or script
reset_stat (bool) – Boolean indicating if the statistics for the model or script should be reset.

Returns:

A list of dictionaries with each entry in the list corresponding to an address reply

Return type:

list[dict]

Raises:

RedisReplyError – if there is an error in command execution or parsing the command reply.

get_dataset(name: str) → smartredis.dataset.Dataset[source]#

Get a dataset from the database

The dataset key used to locate the dataset may be formed by applying a prefix to the supplied name. See set_data_source() and use_dataset_ensemble_prefix() for more details.

Parameters:: name (str) – name the dataset is stored under
Raises:: RedisReplyError – if retrieval fails
Returns:: Dataset instance
Return type:: Dataset

get_dataset_list_range(list_name: str, start_index: int, end_index: int) → List[smartredis.dataset.Dataset][source]#

Get a range of datasets (by index) from an aggregation list

The aggregation list key used to retrieve datasets may be formed by applying a prefix to the supplied name. See set_data_source() and use_list_ensemble_prefix() for more details. An empty or nonexistant aggregation list returns an empty vector. If the provided end_index is beyond the end of the list, that index will be treated as the last index of the list. If start_index and end_index are inconsistent (e.g. end_index is less than start_index), an empty list of datasets will be returned.

Parameters:

list_name (str) – The name of the list
start_index (int) – The starting index of the range (inclusive, starting at zero). Negative values are supported. A negative value indicates offsets starting at the end of the list. For example, -1 is the last element of the list.
end_index (int) – The ending index of the range (inclusive, starting at zero). Negative values are supported. A negative value indicates offsets starting at the end of the list. For example, -1 is the last element of the list.

Returns:

A list of DataSet objects.

Return type:

list[DataSet]

Raises:

RedisReplyError – if there is an error in command execution.

get_datasets_from_list(list_name: str) → List[smartredis.dataset.Dataset][source]#

Get datasets from an aggregation list

The aggregation list key used to retrieve datasets may be formed by applying a prefix to the supplied name. See set_data_source() and use_list_ensemble_prefix() for more details. An empty or nonexistant aggregation list returns an empty vector.

Parameters:: list_name (str) – The name of the list
Returns:: A list of DataSet objects.
Return type:: list[DataSet]
Raises:: RedisReplyError – if there is an error in command execution.

get_db_cluster_info(addresses: List[str]) → List[Dict][source]#

Returns cluster information from a specified db node. If the address does not correspond to a cluster node, an empty dictionary is returned.

Parameters:: addresses (List[str]) – The addresses of the database nodes
Returns:: A list of dictionaries with each entry in the list corresponding to an address reply
Return type:: list[dict]
Raises:: RedisReplyError – if there is an error in command execution or the address is not reachable by the client or if on a non-cluster environment. In the case of using a cluster of database nodes, it is best practice to bind each node in the cluster to a specific address to avoid inconsistencies in addresses retrieved with the CLUSTER SLOTS command. Inconsistencies in node addresses across CLUSTER SLOTS commands can lead to RedisReplyError being thrown.

get_db_node_info(addresses: List[str]) → List[Dict][source]#

Returns information about given database nodes

Parameters:: addresses (List[str]) – The addresses of the database nodes
Returns:: A list of dictionaries with each entry in the list corresponding to an address reply
Return type:: list[dict]
Raises:: RedisReplyError – if there is an error in command execution or the address is not reachable by the client. In the case of using a cluster of database nodes, it is best practice to bind each node in the cluster to a specific address to avoid inconsistencies in addresses retrieved with the CLUSTER SLOTS command. Inconsistencies in node addresses across CLUSTER SLOTS commands can lead to RedisReplyError being thrown.

get_list_length(list_name: str) → int[source]#

Get the number of entries in the list

Parameters:: list_name (str) – The list name
Returns:: The length of the list
Return type:: int
Raises:: RedisReplyError – if there is an error in command execution.

get_model(name: str) → bytes[source]#

Get a stored model

The model key used to locate the model may be formed by applying a prefix to the supplied name. See set_data_source() and use_model_ensemble_prefix() for more details.

Parameters:: name (str) – name of stored model
Raises:: RedisReplyError – if retrieval fails
Returns:: model
Return type:: bytes

get_script(name: str) → str[source]#

Retrieve a Torchscript stored in the database

The script key used to locate the script may be formed by applying a prefix to the supplied name. See set_data_source() and use_model_ensemble_prefix() for more details.

Parameters:: name (str) – the name at which script is stored
Raises:: RedisReplyError – if script retrieval fails
Returns:: TorchScript stored at name
Return type:: str

get_tensor(name: str) → numpy.ndarray[source]#

Get a tensor from the database

The tensor key used to locate the tensor may be formed by applying a prefix to the supplied name. See set_data_source() and use_tensor_ensemble_prefix() for more details.

Parameters:: name (str) – name to get tensor from
Raises:: RedisReplyError – if get fails
Returns:: numpy array of tensor data
Return type:: np.array

key_exists(key: str) → bool[source]#

Check if the key exists in the database

Parameters:: key (str) – The key that will be checked in the database
Returns:: Returns true if the key exists in the database
Return type:: bool
Raises:: RedisReplyError – if key_exists fails

model_exists(name: str) → bool[source]#

Check if a model or script exists in the database

The model or script key used to check for existence may be formed by applying a prefix to the supplied name. See set_data_source() and use_model_ensemble_prefix() for more details.

Parameters:: name (str) – The model or script name that will be checked in the database
Returns:: Returns true if the model exists in the database
Return type:: bool
Raises:: RedisReplyError – if model_exists fails (i.e. causes an error)

poll_dataset(name: str, poll_frequency_ms: int, num_tries: int) → bool[source]#

Check if a dataset exists in the database

The check is repeated at a specified polling interval and for a specified number of retries. The dataset key used to check for existence may be formed by applying a prefix to the supplied name. See set_data_source() and use_dataset_ensemble_prefix() for more details.

Parameters:

name (str) – The dataset name that will be checked in the database
poll_frequency_ms (int) – The polling interval, in milliseconds
num_tries (int) – The total number of retries for the check

Returns:

Returns true if the key is found within the specified number of tries, otherwise false.

Return type:

bool

Raises:

RedisReplyError – if an error occurs while polling

poll_key(key: str, poll_frequency_ms: int, num_tries: int) → bool[source]#

Check if the key exists in the database

The check is repeated at a specified polling interval and for a specified number of retries.

Parameters:

key (str) – The key that will be checked in the database
poll_frequency_ms (int) – The polling interval, in milliseconds
num_tries (int) – The total number of retries for the check

Returns:

Returns true if the key is found within the specified number of tries, otherwise false.

Return type:

bool

Raises:

RedisReplyError – if an error occurs while polling

poll_list_length(name: str, list_length: int, poll_frequency_ms: int, num_tries: int) → bool[source]#

Poll list length until length is equal to the provided length. If maximum number of attempts is exceeded, returns False

The aggregation list key used to check for list length may be formed by applying a prefix to the supplied name. See set_data_source() and use_list_ensemble_prefix() for more details.

Parameters:

name (str) – The name of the list
list_length (int) – The desired length of the list
poll_frequency_ms (int) – The time delay between checks, in milliseconds
num_tries (int) – The total number of times to check for the name

Returns:

Returns true if the list is found with a length greater than or equal to the provided length, otherwise false

Return type:

bool

Raises:

RedisReplyError – if there is an error in command execution.

poll_list_length_gte(name: str, list_length: int, poll_frequency_ms: int, num_tries: int) → bool[source]#

Poll list length until length is greater than or equal to the user-provided length. If maximum number of attempts is exceeded, false is returned.

The aggregation list key used to check for list length may be formed by applying a prefix to the supplied name. See set_data_source() and use_list_ensemble_prefix() for more details.

Parameters:

name (str) – The name of the list
list_length (int) – The desired minimum length of the list
poll_frequency_ms (int) – The time delay between checks, in milliseconds
num_tries (int) – The total number of times to check for the name

Returns:

Returns true if the list is found with a length greater than or equal to the provided length, otherwise false

Return type:

bool

Raises:

RedisReplyError – if there is an error in command execution.

poll_list_length_lte(name: str, list_length: int, poll_frequency_ms: int, num_tries: int) → bool[source]#

Poll list length until length is less than or equal to the user-provided length. If maximum number of attempts is exceeded, false is returned.

The aggregation list key used to check for list length may be formed by applying a prefix to the supplied name. See set_data_source() and use_list_ensemble_prefix() for more details.

Parameters:

name (str) – The name of the list
list_length (int) – The desired maximum length of the list
poll_frequency_ms (int) – The time delay between checks, in milliseconds
num_tries (int) – The total number of times to check for the name

Returns:

Returns true if the list is found with a length less than or equal to the provided length, otherwise false

Return type:

bool

Raises:

RedisReplyError – if there is an error in command execution.

poll_model(name: str, poll_frequency_ms: int, num_tries: int) → bool[source]#

Check if a model or script exists in the database

The check is repeated at a specified polling interval and for a specified number of retries. The model or script key used to check for existence may be formed by applying a prefix to the supplied name. See set_data_source() and use_model_ensemble_prefix() for more details.

Parameters:

name (str) – The model or script name that will be checked in the database
poll_frequency_ms (int) – The polling interval, in milliseconds
num_tries (int) – The total number of retries for the check

Returns:

Returns true if the key is found within the specified number of tries, otherwise false.

Return type:

bool

Raises:

RedisReplyError – if an error occurs while polling

poll_tensor(name: str, poll_frequency_ms: int, num_tries: int) → bool[source]#

Check if a tensor exists in the database

The check is repeated at a specified polling interval and for a specified number of retries. The tensor key used to check for existence may be formed by applying a prefix to the supplied name. See set_data_source() and use_tensor_ensemble_prefix() for more details.

Parameters:

name (str) – The tensor name that will be checked in the database
poll_frequency_ms (int) – The polling interval, in milliseconds
num_tries (int) – The total number of retries for the check

Returns:

Returns true if the tensor key is found within the specified number of tries, otherwise false.

Return type:

bool

Raises:

RedisReplyError – if an error occurs while polling

put_dataset(dataset: smartredis.dataset.Dataset) → None[source]#

Put a Dataset instance into the database

The final dataset key under which the dataset is stored is generated from the name that was supplied when the dataset was created and may be prefixed. See use_dataset_ensemble_prefix() for more details.

All associated tensors and metadata within the Dataset instance will also be stored.

Parameters:

dataset (Dataset) – a Dataset instance

Raises:

TypeError – if argument is not a Dataset
RedisReplyError – if update fails

Return type:

None

put_tensor(name: str, data: numpy.ndarray) → None[source]#

Put a tensor to a Redis database

The final tensor key under which the tensor is stored may be formed by applying a prefix to the supplied name. See use_tensor_ensemble_prefix() for more details.

Parameters:

name (str) – name for tensor for be stored at
data (np.array) – numpy array of tensor data

Raises:

RedisReplyError – if put fails

Return type:

None

rename_dataset(old_name: str, new_name: str) → None[source]#

Rename a dataset in the database

The old and new dataset keys used to find and relocate the dataset may be formed by applying prefixes to the supplied old_name and new_name. See set_data_source() and use_dataset_ensemble_prefix() for more details.

Parameters:

old_name (str) – original name of the dataset to be renamed
new_name (str) – new name for the dataset

Raises:

RedisReplyError – if rename operation fails

Return type:

None

rename_list(src_name: str, dest_name: str) → None[source]#

Rename an aggregation list

The old and new aggregation list key used to find and relocate the list may be formed by applying prefixes to the supplied old_name and new_name. See set_data_source() and use_list_ensemble_prefix() for more details.

Parameters:

src_name (str) – The source list name
dest_name (str) – The destination list name

Raises:

RedisReplyError – if there is an error in command execution.

Return type:

None

rename_tensor(old_name: str, new_name: str) → None[source]#

Rename a tensor in the database

The old and new tensor keys used to find and relocate the tensor may be formed by applying prefixes to the supplied old_name and new_name. See set_data_source() and use_tensor_ensemble_prefix() for more details.

Parameters:

old_name (str) – original name of tensor to be renamed
new_name (str) – new name for the tensor

Raises:

RedisReplyError – if rename operation fails

Return type:

None

run_model(name: str, inputs: str | List[str] | None = None, outputs: str | List[str] | None = None) → None[source]#

Execute a stored model

The model key used to locate the model to be run may be formed by applying a prefix to the supplied name. See set_data_source() and use_model_ensemble_prefix() for more details.

Parameters:

name (str) – name for stored model
inputs (str | list[str] | None) – names of stored inputs to provide model, defaults to None
outputs (str | list[str] | None) – names to store outputs under, defaults to None

Raises:

RedisReplyError – if model execution fails

Return type:

None

run_model_multigpu(name: str, offset: int, first_gpu: int, num_gpus: int, inputs: str | List[str] | None = None, outputs: str | List[str] | None = None) → None[source]#

Execute a model stored for a multi-GPU system

The model key used to locate the model to be run may be formed by applying a prefix to the supplied name. See set_data_source() and use_model_ensemble_prefix() for more details.

Parameters:

name (str) – name for stored model
offset (int) – index of the current image, such as a processor ID or MPI rank
first_gpu (int) – the first GPU (zero-based) to use in processing this model
num_gpus (int) – the number of gpus for which the model was stored
inputs (str | list[str] | None) – names of stored inputs to provide model, defaults to None
outputs (str | list[str] | None) – names to store outputs under, defaults to None

Raises:

RedisReplyError – if model execution fails

Return type:

None

run_script(name: str, fn_name: str, inputs: str | List[str], outputs: str | List[str]) → None[source]#

Execute TorchScript stored inside the database

The script key used to locate the script to be run may be formed by applying a prefix to the supplied name. Similarly, the tensor names in the input and output lists may be prefixed. See set_data_source(), use_model_ensemble_prefix(), and use_tensor_ensemble_prefix() for more details

Parameters:

name (str) – the name the script is stored under
fn_name (str) – name of a function within the script to execute
inputs (str | list[str]) – database tensor names to use as script inputs
outputs (str | list[str]) – database tensor names to receive script outputs

Raises:

RedisReplyError – if script execution fails

Return type:

None

run_script_multigpu(name: str, fn_name: str, inputs: str | List[str], outputs: str | List[str], offset: int, first_gpu: int, num_gpus: int) → None[source]#

Execute TorchScript stored inside the database

The script key used to locate the script to be run may be formed by applying a prefix to the supplied name. Similarly, the tensor names in the input and output lists may be prefixed. See set_data_source(), use_model_ensemble_prefix(), and use_tensor_ensemble_prefix() for more details

Parameters:

name (str) – the name the script is stored under
fn_name (str) – name of a function within the script to execute
inputs (str | list[str]) – database tensor names to use as script inputs
outputs (str | list[str]) – database tensor names to receive script outputs
offset (int) – index of the current image, such as a processor ID or MPI rank
first_gpu (int) – the first GPU (zero-based) to use in processing this script
num_gpus (int) – the number of gpus for which the script was stored

Raises:

RedisReplyError – if script execution fails

Return type:

None

save(addresses: List[str]) → None[source]#

Performs a synchronous save of the database shard producing a point in time snapshot of all the data inside the Redis instance, in the form of an RBD file.

Parameters:: addresses (list[str]) – The addresses of the database nodes
Raises:: RedisReplyError – if there is an error in command execution or the address is not reachable by the client. In the case of using a cluster of database nodes, it is best practice to bind each node in the cluster to a specific address to avoid inconsistencies in addresses retrieved with the CLUSTER SLOTS command. Inconsistencies in node addresses across CLUSTER SLOTS commands can lead to RedisReplyError being thrown.
Return type:: None

set_data_source(source_id: str) → None[source]#

Set the data source, a key prefix for future operations

When running multiple applications, such as an ensemble computation, there is a risk that the same name is used for a tensor, dataset, script, or model by more than one executing entity. In order to prevent this sort of collision, SmartRedis affords the ability to add a prefix to names, thereby associating them with the name of the specific entity that the prefix corresponds to. For writes to the database when prefixing is activated, the prefix used is taken from the SSKEYOUT environment variable. For reads from the database, the default is to use the first prefix from SSKEYIN. If this is the same as the prefix from SSKEYOUT, the entity will read back the same data it wrote; however, this function allows an entity to read from data written by another entity (i.e. use the other entity’s key.)

Parameters:: source_id (str) – The prefix for read operations; must have previously been set via the SSKEYIN environment variable
Raises:: RedisReplyError – if set data
Return type:: None

set_function(name: str, function: Callable, device: str = 'CPU') → None[source]#

Set a callable function into the database

The final script key used to store the function may be formed by applying a prefix to the supplied name. See use_model_ensemble_prefix() for more details.

Function must be a callable TorchScript function and have at least one input and one output. Call the function with the Client.run_script method. Device selection is either “GPU” or “CPU”. If many GPUs are present, a zero-based index can be passed for specification e.g. “GPU:1”.

Parameters:

name (str) – name to store function at
function (callable) – callable function
device (str, optional) – device to run function on, defaults to “CPU”

Raises:

TypeError – if argument was not a callable function
RedisReplyError – if function failed to set

Return type:

None

set_function_multigpu(name: str, function: Callable, first_gpu: int, num_gpus: int) → None[source]#

Set a callable function into the database for use in a multi-GPU system

The final script key used to store the function may be formed by applying a prefix to the supplied name. See use_model_ensemble_prefix() for more details.

Function must be a callable TorchScript function and have at least one input and one output. Call the function with the Client.run_script method.

Parameters:

name (str) – name to store function at
function (callable) – callable function
first_gpu (int) – the first GPU (zero-based) to use in processing this function
num_gpus (int) – the number of GPUs to use for this function

Raises:

TypeError – if argument was not a callable function
RedisReplyError – if function failed to set

Return type:

None

set_model(name: str, model: bytes, backend: str, device: str = 'CPU', batch_size: int = 0, min_batch_size: int = 0, min_batch_timeout: int = 0, tag: str = '', inputs: str | List[str] | None = None, outputs: str | List[str] | None = None) → None[source]#

Put a TF, TF-lite, PT, or ONNX model in the database

The final model key used to store the model may be formed by applying a prefix to the supplied name. Similarly, the tensor names in the input and output nodes for TF models may be prefixed. See set_data_source(), use_model_ensemble_prefix(), and use_tensor_ensemble_prefix() for more details. Device selection is either “GPU” or “CPU”. If many GPUs are present, a zero-based index can be passed for specification e.g. “GPU:1”.

Parameters:

name (str) – name to store model under
model (bytes) – serialized model
backend (str) – name of the backend (TORCH, TF, TFLITE, ONNX)
device (str, optional) – name of device for execution, defaults to “CPU”
batch_size (int, optional) – batch size for execution, defaults to 0
min_batch_size (int, optional) – minimum batch size for model execution, defaults to 0
min_batch_timeout (int, optional) – Max time (ms) to wait for min batch size
tag (str, optional) – additional tag for model information, defaults to “”
inputs (str | list[str] | None) – model inputs (TF only), defaults to None
outputs (str | list[str] | None) – model outputs (TF only), defaults to None

Raises:

RedisReplyError – if model fails to set

Return type:

None

set_model_chunk_size(chunk_size: int) → None[source]#

Reconfigures the chunking size that Redis uses for model

serialization, replication, and the model_get command. This method triggers the AI.CONFIG method in the Redis database to change the model chunking size.

NOTE: The default size of 511MB should be fine for most applications, so it is expected to be very rare that a client calls this method. It is not necessary to call this method for a model to be chunked.

Parameters:: chunk_size (int) – The new chunk size in bytes
Raises:: RedisReplyError – if there is an error in command execution.
Return type:: None

set_model_from_file(name: str, model_file: str, backend: str, device: str = 'CPU', batch_size: int = 0, min_batch_size: int = 0, min_batch_timeout: int = 0, tag: str = '', inputs: str | List[str] | None = None, outputs: str | List[str] | None = None) → None[source]#

Put a TF, TF-lite, PT, or ONNX model from file in the database

The final model key used to store the model may be formed by applying a prefix to the supplied name. Similarly, the tensor names in the input and output nodes for TF models may be prefixed. See set_data_source(), use_model_ensemble_prefix(), and use_tensor_ensemble_prefix() for more details. Device selection is either “GPU” or “CPU”. If many GPUs are present, a zero-based index can be passed for specification e.g. “GPU:1”.

Parameters:

name (str) – name to store model under
model_file (file path to model) – serialized model
backend (str) – name of the backend (TORCH, TF, TFLITE, ONNX)
device (str, optional) – name of device for execution, defaults to “CPU”
batch_size (int, optional) – batch size for execution, defaults to 0
min_batch_size (int, optional) – minimum batch size for model execution, defaults to 0
min_batch_timeout (int, optional) – Max time (ms) to wait for min batch size
tag (str, optional) – additional tag for model information, defaults to “”
inputs (str | list[str] | None) – model inputs (TF only), defaults to None
outputs (str | list[str] | None) – model outupts (TF only), defaults to None

Raises:

RedisReplyError – if model fails to set

Return type:

None

set_model_from_file_multigpu(name: str, model_file: str, backend: str, first_gpu: int, num_gpus: int, batch_size: int = 0, min_batch_size: int = 0, min_batch_timeout: int = 0, tag: str = '', inputs: str | List[str] | None = None, outputs: str | List[str] | None = None) → None[source]#

Put a TF, TF-lite, PT, or ONNX model from file in the database for use in a multi-GPU system

The final model key used to store the model may be formed by applying a prefix to the supplied name. Similarly, the tensor names in the input and output nodes for TF models may be prefixed. See set_data_source(), use_model_ensemble_prefix(), and use_tensor_ensemble_prefix() for more details.

Parameters:

name (str) – name to store model under
model_file (file path to model) – serialized model
backend (str) – name of the backend (TORCH, TF, TFLITE, ONNX)
first_gpu (int) – the first GPU (zero-based) to use in processing this model
num_gpus (int) – the number of GPUs to use in processing this model
batch_size (int, optional) – batch size for execution, defaults to 0
min_batch_size (int, optional) – minimum batch size for model execution, defaults to 0
min_batch_timeout (int, optional) – Max time (ms) to wait for min batch size
tag (str, optional) – additional tag for model information, defaults to “”
inputs (str | list[str] | None) – model inputs (TF only), defaults to None
outputs (str | list[str] | None) – model outupts (TF only), defaults to None

Raises:

RedisReplyError – if model fails to set

Return type:

None

set_model_multigpu(name: str, model: bytes, backend: str, first_gpu: int, num_gpus: int, batch_size: int = 0, min_batch_size: int = 0, min_batch_timeout: int = 0, tag: str = '', inputs: str | List[str] | None = None, outputs: str | List[str] | None = None) → None[source]#

Put a TF, TF-lite, PT, or ONNX model in the database for use in a multi-GPU system

The final model key used to store the model may be formed by applying a prefix to the supplied name. Similarly, the tensor names in the input and output nodes for TF models may be prefixed. See set_data_source(), use_model_ensemble_prefix(), and use_tensor_ensemble_prefix() for more details.

Parameters:

name (str) – name to store model under
model (bytes) – serialized model
backend (str) – name of the backend (TORCH, TF, TFLITE, ONNX)
first_gpu (int) – the first GPU (zero-based) to use in processing this model
num_gpus (int) – the number of GPUs to use in processing this model
batch_size (int, optional) – batch size for execution, defaults to 0
min_batch_size (int, optional) – minimum batch size for model execution, defaults to 0
min_batch_timeout (int, optional) – Max time (ms) to wait for min batch size
tag (str, optional) – additional tag for model information, defaults to “”
inputs (str | list[str] | None) – model inputs (TF only), defaults to None
outputs (str | list[str] | None) – model outputs (TF only), defaults to None

Raises:

RedisReplyError – if model fails to set

Return type:

None

set_script(name: str, script: str, device: str = 'CPU') → None[source]#

Store a TorchScript at a key in the database

The final script key used to store the script may be formed by applying a prefix to the supplied name. See use_model_ensemble_prefix() for more details.

Device selection is either “GPU” or “CPU”. If many GPUs are present, a zero-based index can be passed for specification e.g. “GPU:1”.

Parameters:

name (str) – name to store the script under
script (str) – TorchScript code
device (str, optional) – device for script execution, defaults to “CPU”

Raises:

RedisReplyError – if script fails to set

Return type:

None

set_script_from_file(name: str, file: str, device: str = 'CPU') → None[source]#

Same as Client.set_script, but from file

The final script key used to store the script may be formed by applying a prefix to the supplied name. See use_model_ensemble_prefix() for more details.

Parameters:

name (str) – key to store script under
file (str) – path to text file containing TorchScript code
device (str, optional) – device for script execution, defaults to “CPU”

Raises:

RedisReplyError – if script fails to set

Return type:

None

set_script_from_file_multigpu(name: str, file: str, first_gpu: int, num_gpus: int) → None[source]#

Same as Client.set_script_multigpu, but from file

The final script key used to store the script may be formed by applying a prefix to the supplied name. See use_model_ensemble_prefix() for more details.

Parameters:

name (str) – key to store script under
file (str) – path to text file containing TorchScript code
first_gpu (int) – the first GPU (zero-based) to use in processing this script
num_gpus (int) – the number of GPUs to use in processing this script

Raises:

RedisReplyError – if script fails to set

Return type:

None

set_script_multigpu(name: str, script: str, first_gpu: int, num_gpus: int) → None[source]#

Store a TorchScript at a key in the database

The final script key used to store the script may be formed by applying a prefix to the supplied name. See use_model_ensemble_prefix() for more details.

Parameters:

name (str) – name to store the script under
script (str) – TorchScript code
first_gpu (int) – the first GPU (zero-based) to use in processing this script
num_gpus (int) – the number of GPUs to use in processing this script

Raises:

RedisReplyError – if script fails to set

Return type:

None

tensor_exists(name: str) → bool[source]#

Check if a tensor exists in the database

The tensor key used to check for existence may be formed by applying a prefix to the supplied name. See set_data_source() and use_tensor_ensemble_prefix() for more details.

Parameters:: name (str) – The tensor name that will be checked in the database
Returns:: Returns true if the tensor exists in the database
Return type:: bool
Raises:: RedisReplyError – if checking for tensor existence causes an error

use_dataset_ensemble_prefix(use_prefix: bool) → None[source]#

Control whether dataset keys are prefixed (e.g. in an ensemble): when forming database keys

This function can be used to avoid key collisions in an ensemble by prepending the string value from the environment variable SSKEYIN to dataset names. Prefixes will only be used if they were previously set through environment variables SSKEYIN and SSKEYOUT. Keys for entities created before this function is called will not be retroactively prefixed. By default, the client prefixes dataset keys when a prefix is available.

Parameters:: use_prefix (bool) – If set to true, all future operations on datasets will use a prefix, if available.
Return type:: None

use_list_ensemble_prefix(use_prefix: bool) → None[source]#

Control whether aggregation lists are prefixed: when forming database keys

This function can be used to avoid key collisions in an ensemble by prepending the string value from the environment variable SSKEYIN and/or SSKEYOUT to aggregation list names. Prefixes will only be used if they were previously set through the environment variables SSKEYOUT and SSKEYIN. Keys for aggregation lists created before this function is called will not be retroactively prefixed. By default, the client prefixes aggregation list keys with the first prefix specified with the SSKEYIN and SSKEYOUT environment variables. Note that use_dataset_ensemble_prefix() controls prefixing for the entities in the aggregation list, and use_dataset_ensemble_prefix() should be given the same value that was used during the initial setting of the DataSet into the database.

Parameters:: use_prefix (bool) – If set to true, all future operations on aggregation lists will use a prefix, if available.
Return type:: None

use_model_ensemble_prefix(use_prefix: bool) → None[source]#

Control whether model and script keys are: prefixed (e.g. in an ensemble) when forming database keys

This function can be used to avoid key collisions in an ensemble by prepending the string value from the environment variable SSKEYIN to model and script names. Prefixes will only be used if they were previously set through environment variables SSKEYIN and SSKEYOUT. Keys for entities created before this function is called will not be retroactively prefixed. By default, the client does not prefix model and script keys.

Parameters:: use_prefix (bool) – If set to true, all future operations on models and scripts will use a prefix, if available.
Return type:: None

use_tensor_ensemble_prefix(use_prefix: bool) → None[source]#

Control whether tensor keys are prefixed (e.g. in an ensemble) when forming database keys

This function can be used to avoid key collisions in an ensemble by prepending the string value from the environment variable SSKEYIN to tensor names. Prefixes will only be used if they were previously set through environment variables SSKEYIN and SSKEYOUT. Keys for entities created before this function is called will not be retroactively prefixed. By default, the client prefixes tensor keys when a prefix is available.

Parameters:: use_prefix (bool) – If set to true, all future operations on tensors will use a prefix, if available.
Return type:: None

DataSet API#

The Python DataSet API enables a user to manage a group of tensors and associated metadata within a datastructure called a DataSet object. The DataSet API operates independently of the database and solely maintains the dataset object in-memory. The actual interaction with the Redis database, where a snapshot of the DataSet object is sent, is handled by the Client API. For more information on the DataSet object, click here.

Dataset Class Method Overview#

`Dataset.__init__`(name)	Initialize a Dataset object
`Dataset.__str__`()	Create a string representation of the client
`Dataset.add_tensor`(name, data)	Add a named multi-dimensional data array (tensor) to this dataset
`Dataset.get_tensor`(name)	Get a tensor from the Dataset
`Dataset.add_meta_scalar`(name, data)	Add scalar (non-string) metadata to a field name if it exists; otherwise, create and add
`Dataset.get_meta_scalars`(name)	Get the scalar values from the DataSet assigned to a field name
`Dataset.add_meta_string`(name, data)	Add string metadata to a field name if it exists; otherwise, create and add
`Dataset.get_meta_strings`(name)	Get the string values from the DataSet assigned to a field name
`Dataset.get_metadata_field_names`()	Get all field names from the DataSet
`Dataset.get_metadata_field_type`(name)	Get the type of metadata for a field name (scalar or string)
`Dataset.get_name`()	Get the name of a Dataset
`Dataset.get_tensor_type`(name)	Get the type of a tensor in the DataSet
`Dataset.get_tensor_names`()	Get the names of all tensors in the DataSet
`Dataset.get_tensor_dims`(name)	Get the dimensions of a tensor in the DataSet

Dataset Class Method Detailed View#

class Dataset(name: str) → None[source]#

Bases: SRObject

Initialize a Dataset object

Parameters:: name (str) – name of dataset

add_meta_scalar(name: str, data: int | float) → None[source]#

Add scalar (non-string) metadata to a field name if it exists; otherwise, create and add

If the field name exists, append the scalar metadata; otherwise, create the field within the DataSet object and add the scalar metadata.

Parameters:

name (str) – The name used to reference the scalar metadata field
data (int | float) – scalar metadata input

Return type:

None

add_meta_string(name: str, data: str) → None[source]#

Add string metadata to a field name if it exists; otherwise, create and add

If the field name exists, append the string metadata; otherwise, create the field within the DataSet object and add the string metadata.

Parameters:

name (str) – The name used to reference the string metadata field
data (str) – string metadata input

Return type:

None

add_tensor(name: str, data: numpy.ndarray) → None[source]#

Add a named multi-dimensional data array (tensor) to this dataset

Parameters:

name (str) – name associated to the tensor data
data (np.ndarray) – tensor data

Return type:

None

static from_pybind(dataset: smartredis.smartredisPy.PyDataset) → smartredis.dataset.Dataset[source]#

Initialize a Dataset object from a PyDataset object

Create a new Dataset object using the data and properties of a PyDataset object as the initial values.

Parameters:: dataset (PyDataset) – The pybind PyDataset object to use for construction
Returns:: The newly constructed Dataset object
Return type:: Dataset object

get_data() → smartredis.smartredisPy.PyDataset[source]#

Return the PyDataset attribute

Returns:: The PyDataset attribute containing the dataset information
Return type:: PyDataset

get_meta_scalars(name: str) → List[int] | List[float][source]#

Get the scalar values from the DataSet assigned to a field name

Parameters:: name (str) – The field name to retrieve from
Return type:: list[int] | list[float]

get_meta_strings(name: str) → List[str][source]#

Get the string values from the DataSet assigned to a field name

Parameters:: name (str) – The field name to retrieve from
Return type:: list[str]

get_metadata_field_names() → List[str][source]#

Get all field names from the DataSet

Returns:: a list of all metadata field names
Return type:: list[str]

get_metadata_field_type(name: str) → Type[source]#

Get the type of metadata for a field name (scalar or string)

Parameters:: name (str) – The name used to reference the metadata field in the DataSet
Returns:: the numpy type for the metadata field
Return type:: type

get_name() → str[source]#

Get the name of a Dataset

Returns:: the name of the in-memory dataset
Return type:: str

get_tensor(name: str) → numpy.ndarray[source]#

Get a tensor from the Dataset

Parameters:: name (str) – name of the tensor to get
Returns:: a numpy array of tensor data
Return type:: np.ndarray

get_tensor_dims(name: str) → List[int][source]#

Get the dimensions of a tensor in the DataSet

Parameters:: name (str) – name associated to the tensor data
Returns:: a list of the tensor dimensions
Return type:: list[int]

get_tensor_names() → List[str][source]#

Get the names of all tensors in the DataSet

Returns:: a list of tensor names
Return type:: list[str]

get_tensor_type(name: str) → Type[source]#

Get the type of a tensor in the DataSet

Parameters:: name (str) – The name used to reference the tensor in the DataSet
Returns:: the numpy type for the tensor
Return type:: type

set_data(dataset: smartredis.smartredisPy.PyDataset) → None[source]#

Set the PyDataset attribute

Parameters:: dataset (PyDataset) – The PyDataset object
Return type:: None

Logging API#

The SmartRedis logging functionality is split across multiple classes as well as three standalone methods. All logging requires a context, which is the text that is attached to a log message so that when reading the log, one can tell which part of their program generated the log message. A context can be a Client object, a DataSet object, or a LogContext object (which only contains the string for identifying context); or it can be a simple text string. The three classes all derive from the SRObject class, which contains logging methods. Three standalone methods support logging against a string context.

Logging Functionality Overview#

`SRObject.log_data`(level, data)	Conditionally log data if the logging level is high enough
`SRObject.log_warning`(level, data)	Conditionally log warning data if the logging level is high enough
`SRObject.log_error`(level, data)	Conditionally log error data if the logging level is high enough
`LogContext.__init__`(context)	Initialize a LogContext object
`log_data`(context, level, data)	Log data to the SmartRedis logfile
`log_warning`(context, level, data)	Log a warning to the SmartRedis logfile
`log_error`(context, level, data)	Log an error to the SmartRedis logfile

LogContext Class Method Detailed View#

class LogContext(context: str) → None[source]#

Bases: SRObject

Initialize a LogContext object

Parameters:: context (str) – logging context

static from_pybind(logcontext: smartredis.smartredisPy.PyLogContext) → smartredis.logcontext.LogContext[source]#

Initialize a LogContext object from a PyLogContext object

Parameters:: logcontext (PyLogContext) – The pybind PyLogContext object to use for construction
Returns:: The newly constructor LogContext from the PyLogContext
Return type:: LogContext

get_context() → smartredis.smartredisPy.PyLogContext[source]#

Return the PyLogContext attribute

Returns:: The PyLogContext attribute containing the logcontext information
Return type:: PyLogContext

set_context(logcontext: smartredis.smartredisPy.PyLogContext) → None[source]#

Set the PyLogContext attribute

Parameters:: logcontext (PyLogContext) – The PyLogContext object
Return type:: None

SRObject Class Method Detailed View#

class SRObject(context: str) → None[source]#

Bases: object

Initialize a SRObject object

Parameters:: context (str) – logging context

log_data(level: smartredis.smartredisPy.SRLoggingLevel, data: str) → None[source]#

Conditionally log data if the logging level is high enough

Parameters:

level (SRLoggingLevel) – Minimum logging level for data to be logged
data (str) – Text of data to be logged

Raises:

RedisReplyError – if logging fails

Return type:

None

log_error(level: smartredis.smartredisPy.SRLoggingLevel, data: str) → None[source]#

Conditionally log error data if the logging level is high enough

Parameters:

level (SRLoggingLevel) – Minimum logging level for data to be logged
data (str) – Text of data to be logged

Raises:

RedisReplyError – if logging fails

Return type:

None

log_warning(level: smartredis.smartredisPy.SRLoggingLevel, data: str) → None[source]#

Conditionally log warning data if the logging level is high enough

Parameters:

level (SRLoggingLevel) – Minimum logging level for data to be logged
data (str) – Text of data to be logged

Raises:

RedisReplyError – if logging fails

Return type:

None

Standalone Logging Method Detailed View#

log_data(context: str, level: smartredis.smartredisPy.SRLoggingLevel, data: str) → None[source]#

Log data to the SmartRedis logfile

Parameters:

context (str) – Logging context (string to prefix the log entry with)
level (SRLoggingLevel) – minimum logging level for data to be logged with
data (str) – message data to log

Raises:

RedisReplyError – if logging fails

Return type:

None

log_warning(context: str, level: smartredis.smartredisPy.SRLoggingLevel, data: str) → None[source]#

Log a warning to the SmartRedis logfile

Parameters:

context (str) – Logging context (string to prefix the log entry with)
level (SRLoggingLevel) – minimum logging level for data to be logged with
data (str) – message data to log

Raises:

RedisReplyError – if logging fails

Return type:

None

log_error(context: str, level: smartredis.smartredisPy.SRLoggingLevel, data: str) → None[source]#

Log an error to the SmartRedis logfile

Parameters:

context (str) – Logging context (string to prefix the log entry with)
level (SRLoggingLevel) – minimum logging level for data to be logged with
data (str) – message data to log

Raises:

RedisReplyError – if logging fails

Return type:

None

C++#

The following page provides a comprehensive overview of the SmartRedis C++ Client and Dataset APIs. Further explanation and details of each are presented below.

Client API#

The Client API is purpose-built for interaction with the backend database, which extends the capabilities of the Redis in-memory data store. It’s important to note that the SmartRedis Client API is the exclusive means for altering, transmitting, and receiving data within the backend database. More specifically, the Client API is responsible for both creating and modifying data structures, which encompass Models, Scripts, and Tensors. It also handles the transmission and reception of the aforementioned data structures in addition to Dataset data structure. Creating and modifying the DataSet object is confined to local operation by the DataSet API.

class Client : public SmartRedis::SRObject#

The Client class is the primary user-facing class for executing server commands.

Public Functions

Client(const char *logger_name)#

Simple Client constructor with default configuration: environment variables, no suffix.

Parameters:: logger_name – Name to use for this client when logging
Throws:: SmartRedis::Exception – if client connection or object initialization fails

inline Client(const std::string &logger_name = "default")#

Simple Client constructor with default configuration: environment variables, no suffix.

Parameters:: logger_name – Name to use for this client when logging
Throws:: SmartRedis::Exception – if client connection or object initialization fails

Client(ConfigOptions *cfgopts, const std::string &logger_name = "default")#

Client constructor.

Parameters:

cfgopts – source from which to access runtime settings
logger_name – Name to use for this client when logging

Throws:

SmartRedis::Exception – if client connection or object initialization fails

Client(bool cluster, const std::string &logger_name = "default")#

Client constructor (deprecated)

Parameters:

cluster – Flag for if a database cluster is being used
logger_name – Name to use for this client when logging

Throws:

SmartRedis::Exception – if client connection or object initialization fails

Client(const Client &client) = delete#: Client copy constructor is not available.

Client(Client &&client) = default#: Client move constructor.

Client &operator=(const Client &client) = delete#: Client copy assignment operator is not available.

Client &operator=(Client &&client) = default#: Client move assignment operator.

virtual ~Client()#: Client destructor.

void put_dataset(DataSet &dataset)#

Send a DataSet object to the database.

The final dataset key under which the dataset is stored is generated from the name that was supplied when the dataset was created and may be prefixed. See use_dataset_ensemble_prefix() for more details.

Parameters:: dataset – The DataSet object to send to the database
Throws:: SmartRedis::Exception – if put dataset command fails

DataSet get_dataset(const std::string &name)#

Get a DataSet object from the database.

The dataset key used to locate the dataset may be formed by applying a prefix to the supplied name. See set_data_source() and use_dataset_ensemble_prefix() for more details.

Parameters:: name – The name of the dataset to retrieve
Throws:: SmartRedis::Exception – if get dataset command fails
Returns:: DataSet object retrieved from the database

void rename_dataset(const std::string &old_name, const std::string &new_name)#

Move a dataset to a new name. All tensors and metdata in the dataset will be moved with it.

The old and new dataset keys used to find and relocate the dataset may be formed by applying prefixes to the supplied old_name and new_name. See set_data_source() and use_dataset_ensemble_prefix() for more details.

Parameters:

old_name – The original dataset key for the dataset
new_name – The new dataset key for the dataset

Throws:

SmartRedis::Exception – if dataset rename command fails

void copy_dataset(const std::string &src_name, const std::string &dest_name)#

Copy a dataset to a new name. All tensors and metadata in the DataSet will be copied as well.

The source and destination dataset keys used to locate and store the dataset may be formed by applying prefix to the supplied src_name and dest_name. See set_data_source() and use_dataset_ensemble_prefix() for more details.

Parameters:

src_name – The source dataset key
dest_name – The destination dataset key

Throws:

SmartRedis::Exception – if copy dataset command fails

void delete_dataset(const std::string &name)#

Delete a dataset from the database. All tensors and metdata in the dataset will be deleted.

The dataset key used to locate the dataset to be deleted may be formed by applying a prefix to the supplied name. See set_data_source() and use_dataset_ensemble_prefix() for more details.

Parameters:: name – The dataset key for the dataset to be deleted.
Throws:: SmartRedis::Exception – if delete dataset command fails

void put_tensor(const std::string &name, const void *data, const std::vector<size_t> &dims, const SRTensorType type, const SRMemoryLayout mem_layout)#

Put a tensor into the database.

The final tensor key under which the tensor is stored may be formed by applying a prefix to the supplied name. See use_tensor_ensemble_prefix() for more details.

Parameters:

name – The tensor name for this tensor in the database
data – The data for this tensor
dims – The number of elements for each dimension of the tensor
type – The data type for the tensor
mem_layout – The memory layout of the provided tensor data

Throws:

SmartRedis::Exception – if put tensor command fails

void get_tensor(const std::string &name, void *&data, std::vector<size_t> &dims, SRTensorType &type, const SRMemoryLayout mem_layout)#

Retrieve the tensor data, dimensions, and type for the provided tensor key. This function will allocate and retain management of the memory for the tensor data.

The key used to locate the tensor may be formed by applying a prefix to the supplied name. See set_data_source() and use_tensor_ensemble_prefix() for more details.

The memory of the data pointer is valid until the Client is destroyed. This method is meant to be used when the dimensions and type of the tensor are unknown or the user does not want to manage memory. However, given that the memory associated with the return data is valid until Client destruction, this method should not be used repeatedly for large tensor data. Instead it is recommended that the user use unpack_tensor() for large tensor data and to limit memory use by the Client.

Parameters:

name – The tensor name for the tensor
data – Receives tensor data
dims – Receives the number of elements in each dimension of the tensor data
type – Receives the type for the tensor data
mem_layout – The memory layout into which tensor data should be written

Throws:

SmartRedis::Exception – if get tensor command fails

void get_tensor(const std::string &name, void *&data, size_t *&dims, size_t &n_dims, SRTensorType &type, const SRMemoryLayout mem_layout)#

Retrieve the tensor data, dimensions, and type for the provided tensor key. This function will allocate and retain management of the memory for the tensor data. This is a c-style interface for the tensor dimensions. Another function exists for std::vector dimensions.

The key used to locate the tensor may be formed by applying a prefix to the supplied name. See set_data_source() and use_tensor_ensemble_prefix() for more details.

The memory of the data pointer is valid until the Client is destroyed. This method is meant to be used when the dimensions and type of the tensor are unknown or the user does not want to manage memory. However, given that the memory associated with the return data is valid until Client destruction, this method should not be used repeatedly for large tensor data. Instead it is recommended that the user use unpack_tensor() for large tensor data and to limit memory use by the Client.

Parameters:

name – The name for the tensor
data – Receives tensor data
dims – Receives the number of elements in each dimension of the tensor data
n_dims – Receives the number tensor dimensions
type – Receives the type for the tensor data
mem_layout – The memory layout into which tensor data should be written

Throws:

SmartRedis::Exception – if get tensor command fails

void unpack_tensor(const std::string &name, void *data, const std::vector<size_t> &dims, const SRTensorType type, const SRMemoryLayout mem_layout)#

Retrieve a tensor from the database into memory provided by the caller.

The tensor key used to locate the tensor may be formed by applying a prefix to the supplied name. See set_data_source() and use_tensor_ensemble_prefix() for more details.

Parameters:

name – The tensor name for the tensor
data – A buffer into which to place tensor data
dims – The dimensions for the provided data buffer
type – The tensor type for the provided data buffer
mem_layout – The memory layout for the provided data buffer

Throws:

SmartRedis::Exception – if unpack tensor command fails

void rename_tensor(const std::string &old_name, const std::string &new_name)#

Move a tensor to a new name.

The old and new tensor keys used to find and relocate the tensor may be formed by applying prefixes to the supplied old_name and new_name. See set_data_source() and use_tensor_ensemble_prefix() for more details.

Parameters:

old_name – The original tensor name
new_name – The new tensor name

Throws:

SmartRedis::Exception – if rename tensor command fails

void delete_tensor(const std::string &name)#

Delete a tensor from the database.

The tensor key used to locate the tensor to be deleted may be formed by applying a prefix to the supplied name. See set_data_source() and use_tensor_ensemble_prefix() for more details.

Parameters:: name – The name of the tensor to delete
Throws:: SmartRedis::Exception – if delete tensor command fails

void copy_tensor(const std::string &src_name, const std::string &dest_name)#

Copy a tensor to a destination tensor name.

The source and destination tensor keys used to locate and store the tensor may be formed by applying prefixes to the supplied src_name and dest_name. See set_data_source() and use_tensor_ensemble_prefix() for more details.

Parameters:

src_name – The source tensor name
dest_name – The destination tensor name

Throws:

SmartRedis::Exception – if copy tensor command fails

void set_model_from_file(const std::string &name, const std::string &model_file, const std::string &backend, const std::string &device, int batch_size = 0, int min_batch_size = 0, int min_batch_timeout = 0, const std::string &tag = "", const std::vector<std::string> &inputs = std::vector<std::string>(), const std::vector<std::string> &outputs = std::vector<std::string>())#

Set a model (from file) in the database for future execution.

The final model key used to store the model may be formed by applying a prefix to the supplied name. Similarly, the tensor names in the input and output node vectors for TF models may be prefixed. See set_data_source(), use_model_ensemble_prefix(), and use_tensor_ensemble_prefix() for more details

Parameters:

name – The model name for this model
model_file – The source file for the model
backend – The name of the backend (TF, TFLITE, TORCH, ONNX)
device – The name of the device for execution. May be either CPU or GPU. If multiple GPUs are present, a specific GPU can be targeted by appending its zero-based index, i.e. “GPU:1”
batch_size – The batch size for model execution
min_batch_size – The minimum batch size for model execution
min_batch_timeout – Max time (ms) to wait for min batch size
tag – A tag to attach to the model for information purposes
inputs – One or more names of model input nodes (TF models only). For other models, provide an empty vector
outputs – One or more names of model output nodes (TF models only). For other models, provide an empty vector

Throws:

SmartRedis::Exception – if set model from file fails

void set_model_from_file_multigpu(const std::string &name, const std::string &model_file, const std::string &backend, int first_gpu, int num_gpus, int batch_size = 0, int min_batch_size = 0, int min_batch_timeout = 0, const std::string &tag = "", const std::vector<std::string> &inputs = std::vector<std::string>(), const std::vector<std::string> &outputs = std::vector<std::string>())#

Set a model from file in the database for future execution in a multi-GPU system.

The final model key used to store the model may be formed by applying a prefix to the supplied name. Similarly, the tensor names in the input and output node vectors for TF models may be prefixed. See set_data_source(), use_model_ensemble_prefix(), and use_tensor_ensemble_prefix() for more details

Parameters:

name – The name to associate with the model
model_file – The source file for the model
backend – The name of the backend (TF, TFLITE, TORCH, ONNX)
first_gpu – the first GPU (zero-based) to use with the model
num_gpus – The number of GPUs to use with the model
batch_size – The batch size for model execution
min_batch_size – The minimum batch size for model execution
min_batch_timeout – Max time (ms) to wait for min batch size
tag – A tag to attach to the model for information purposes
inputs – One or more names of model input nodes (TF models only)
outputs – One or more names of model output nodes (TF models only)

Throws:

SmartRedis::Exception – if multiGPU set model command fails

void set_model(const std::string &name, const std::string_view &model, const std::string &backend, const std::string &device, int batch_size = 0, int min_batch_size = 0, int min_batch_timeout = 0, const std::string &tag = "", const std::vector<std::string> &inputs = std::vector<std::string>(), const std::vector<std::string> &outputs = std::vector<std::string>())#

Set a model (from a buffer) in the database for future execution.

The final model key used to store the model may be formed by applying a prefix to the supplied name. Similarly, the tensor names in the input and output node vectors for TF models may be prefixed. See set_data_source(), use_model_ensemble_prefix(), and use_tensor_ensemble_prefix() for more details

Parameters:

name – The model name to associate with the model
model – The model as a continuous buffer
backend – The name of the backend (TF, TFLITE, TORCH, ONNX)
device – The name of the device for execution. May be either CPU or GPU. If multiple GPUs are present, a specific GPU can be targeted by appending its zero-based index, i.e. “GPU:1”
batch_size – The batch size for model execution
min_batch_size – The minimum batch size for model execution
min_batch_timeout – Max time (ms) to wait for min batch size
tag – A tag to attach to the model for information purposes
inputs – One or more names of model input nodes (TF models only). For other models, provide an empty vector
outputs – One or more names of model output nodes (TF models only). For other models, provide an empty vector

Throws:

SmartRedis::Exception – if set model command fails

void set_model_multigpu(const std::string &name, const std::string_view &model, const std::string &backend, int first_gpu, int num_gpus, int batch_size = 0, int min_batch_size = 0, int min_batch_timeout = 0, const std::string &tag = "", const std::vector<std::string> &inputs = std::vector<std::string>(), const std::vector<std::string> &outputs = std::vector<std::string>())#

Set a model from std::string_view buffer in the database for future execution in a multi-GPU system.

The final model key used to store the model may be formed by applying a prefix to the supplied name. Similarly, the tensor names in the input and output node vectors for TF models may be prefixed. See set_data_source(), use_model_ensemble_prefix(), and use_tensor_ensemble_prefix() for more details

Parameters:

name – The name to associate with the model
model – The model as a continuous buffer string_view
backend – The name of the backend (TF, TFLITE, TORCH, ONNX)
first_gpu – the first GPU (zero-based) to use with the model
num_gpus – The number of GPUs to use with the model
batch_size – The batch size for model execution
min_batch_size – The minimum batch size for model execution
min_batch_timeout – Max time (ms) to wait for min batch size
tag – A tag to attach to the model for information purposes
inputs – One or more names of model input nodes (TF models only)
outputs – One or more names of model output nodes (TF models only)

Throws:

SmartRedis::Exception – if multi-GPU set model command fails

std::string_view get_model(const std::string &name)#

Retrieve a model from the database.

The model key used to locate the model may be formed by applying a prefix to the supplied name. See set_data_source() and use_model_ensemble_prefix() for more details.

Parameters:: name – The name associated with the model
Throws:: SmartRedis::Exception – if get model command fails
Returns:: A string buffer containing the model. The memory associated with the model is managed by this Client object and is valid until the Client’s destruction

void set_script_from_file(const std::string &name, const std::string &device, const std::string &script_file)#

Set a script (from file) in the database for future execution.

The final script key used to store the script may be formed by applying a prefix to the supplied name. See use_model_ensemble_prefix() for more details.

Parameters:

name – The name to associate with the script
device – The name of the device for execution. May be either CPU or GPU. If multiple GPUs are present, a specific GPU can be targeted by appending its zero-based index, i.e. “GPU:1”
script_file – The source file for the script

Throws:

SmartRedis::Exception – if set script command fails

void set_script_from_file_multigpu(const std::string &name, const std::string &script_file, int first_gpu, int num_gpus)#

Set a script from file in the database for future execution in a multi-GPU system.

The final script key used to store the script may be formed by applying a prefix to the supplied name. See use_model_ensemble_prefix() for more details.

Parameters:

name – The name to associate with the script
script_file – The source file for the script
first_gpu – the first GPU (zero-based) to use with the script
num_gpus – The number of GPUs to use with the script

Throws:

SmartRedis::Exception – if multi-GPU set script command fails

void set_script(const std::string &name, const std::string &device, const std::string_view &script)#

Set a script (from buffer) in the database for future execution.

The final script key used to store the script may be formed by applying a prefix to the supplied name. See use_model_ensemble_prefix() for more details.

Parameters:

name – The name to associate with the script
device – The name of the device for execution. May be either CPU or GPU. If multiple GPUs are present, a specific GPU can be targeted by appending its zero-based index, i.e. “GPU:1”
script – The script source in a string buffer

Throws:

SmartRedis::Exception – if set script command fails

void set_script_multigpu(const std::string &name, const std::string_view &script, int first_gpu, int num_gpus)#

Set a script from std::string_view buffer in the database for future execution in a multi-GPU system.

The final script key used to store the script may be formed by applying a prefix to the supplied name. See use_model_ensemble_prefix() for more details.

Parameters:

name – The name to associate with the script
script – The script source in a std::string_view
first_gpu – the first GPU (zero-based) to use with the script
num_gpus – The number of GPUs to use with the script

Throws:

SmartRedis::Exception – if multi-GPU set script command fails

std::string_view get_script(const std::string &name)#

Retrieve a script from the database.

The script key used to locate the script may be formed by applying a prefix to the supplied name. See set_data_source() and use_model_ensemble_prefix() for more details.

Parameters:: name – The name associated with the script
Throws:: SmartRedis::Exception – if get script command fails
Returns:: A string buffer containing the script. The memory associated with the model is managed by this Client object and is valid until the Client’s destruction

void run_model(const std::string &name, const std::vector<std::string> inputs, const std::vector<std::string> outputs)#

Run a model in the database using the specified input and output tensors.

The model key used to locate the model to be run may be formed by applying a prefix to the supplied name. Similarly, the tensor names in the input and output vectors may be prefixed. See set_data_source(), use_model_ensemble_prefix(), and use_tensor_ensemble_prefix() for more details. By default, models will run with a one hour timeout. To modify the length of time that a model is allowed to run, update the SR_MODEL_TIMEOUT to give a new value, in milliseconds.

Parameters:

name – The name associated with the model
inputs – The tensor keys for inputs tensors to use in the model
outputs – The tensor keys of output tensors to use to capture model results

Throws:

SmartRedis::Exception – if run model command fails

void run_model_multigpu(const std::string &name, const std::vector<std::string> inputs, const std::vector<std::string> outputs, int offset, int first_gpu, int num_gpus)#

Run a model in the database using the specified input and output tensors in a multi-GPU system.

The model key used to locate the model to be run may be formed by applying a prefix to the supplied name. Similarly, the tensor names in the input and output vectors may be prefixed. See set_data_source(), use_model_ensemble_prefix(), and use_tensor_ensemble_prefix() for more details. By default, models will run with a one hour timeout. To modify the length of time that a model is allowed to run, update the SR_MODEL_TIMEOUT to give a new value, in milliseconds.

Parameters:

name – The name associated with the model
inputs – The names of input tensors to use in the model
outputs – The names of output tensors that will be used to save model results
offset – index of the current image, such as a processor ID or MPI rank
first_gpu – the first GPU (zero-based) to use with the model
num_gpus – the number of gpus for which the script was stored

Throws:

SmartRedis::Exception – if run model command fails

void run_script(const std::string &name, const std::string &function, const std::vector<std::string> inputs, const std::vector<std::string> outputs)#

Run a script function in the database using the specified input and output tensors.

The script key used to locate the script to be run may be formed by applying a prefix to the supplied name. Similarly, the tensor names in the input and output vectors may be prefixed. See set_data_source(), use_model_ensemble_prefix(), and use_tensor_ensemble_prefix() for more details

Parameters:

name – The name associated with the script
function – The name of the function in the script to run
inputs – The tensor keys of inputs tensors to use in the script
outputs – The tensor keys of output tensors to use to capture script results

Throws:

SmartRedis::Exception – if run script command fails

void run_script_multigpu(const std::string &name, const std::string &function, const std::vector<std::string> inputs, const std::vector<std::string> outputs, int offset, int first_gpu, int num_gpus)#

Run a script function in the database using the specified input and output tensors in a multi-GPU system.

The script key used to locate the script to be run may be formed by applying a prefix to the supplied name. Similarly, the tensor names in the input and output vectors may be prefixed. See set_data_source(), use_model_ensemble_prefix(), and use_tensor_ensemble_prefix() for more details

Parameters:

name – The name associated with the script
function – The name of the function in the script to run
inputs – The names of input tensors to use in the script
outputs – The names of output tensors that will be used to save script results
offset – index of the current image, such as a processor ID or MPI rank
first_gpu – the first GPU (zero-based) to use with the script
num_gpus – the number of gpus for which the script was stored

Throws:

SmartRedis::Exception – if run script command fails

void delete_model(const std::string &name)#

Remove a model from the database.

The model key used to locate the model to be deleted may be formed by applying a prefix to the supplied name. See set_data_source() and use_model_ensemble_prefix() for more details.

Parameters:: name – The name associated with the model
Throws:: SmartRedis::Exception – if model deletion fails

void delete_model_multigpu(const std::string &name, int first_gpu, int num_gpus)#

Remove a model from the database that was stored for use with multiple GPUs.

The model key used to locate the model to be deleted may be formed by applying a prefix to the supplied name. See set_data_source() and use_model_ensemble_prefix() for more details. The first_gpu and num_gpus parameters must match those used when the model was stored.

Parameters:

name – The name associated with the model
first_gpu – the first GPU (zero-based) to use with the model
num_gpus – the number of gpus for which the model was stored

Throws:

SmartRedis::Exception – if model deletion fails

void delete_script(const std::string &name)#

Remove a script from the database.

The script key used to locate the script to be deleted may be formed by applying a prefix to the supplied name. See set_data_source() and use_model_ensemble_prefix() for more details.

Parameters:: name – The name associated with the script
Throws:: SmartRedis::Exception – if script deletion fails

void delete_script_multigpu(const std::string &name, int first_gpu, int num_gpus)#

Remove a script from the database that was stored for use with multiple GPUs.

The script key used to locate the script to be deleted may be formed by applying a prefix to the supplied name. See set_data_source() and use_model_ensemble_prefix() for more details. The first_gpu and num_gpus parameters must match those used when the script was stored.

Parameters:

name – The name associated with the script
first_gpu – the first GPU (zero-based) to use with the script
num_gpus – the number of gpus for which the script was stored

Throws:

SmartRedis::Exception – if script deletion fails

bool key_exists(const std::string &key)#

Check if a key exists in the database.

Parameters:: key – The key that will be checked in the database. No prefix will be added to key.
Throws:: SmartRedis::Exception – if key exists command fails
Returns:: Returns true if the key exists in the database

bool model_exists(const std::string &name)#

Check if a model (or script) key exists in the database.

The model or script key used to check for existence may be formed by applying a prefix to the supplied name. See set_data_source() and use_model_ensemble_prefix() for more details.

Parameters:: name – The model/script name to be checked in the database
Throws:: SmartRedis::Exception – if model exists command fails
Returns:: Returns true if the model exists in the database

bool tensor_exists(const std::string &name)#

Check if a tensor key exists in the database.

The tensor key used to check for existence may be formed by applying a prefix to the supplied name. See set_data_source() and use_tensor_ensemble_prefix() for more details.

Parameters:: name – The tensor name to be checked in the database
Throws:: SmartRedis::Exception – if tensor exists command fails
Returns:: Returns true if the tensor exists in the database

bool dataset_exists(const std::string &name)#

Check if a dataset exists in the database.

The dataset key used to check for existence may be formed by applying a prefix to the supplied name. See set_data_source() and use_dataset_ensemble_prefix() for more details.

Parameters:: name – The dataset name to be checked in the database
Throws:: SmartRedis::Exception – if dataset exists command fails
Returns:: Returns true if the dataset exists in the database

bool poll_key(const std::string &key, int poll_frequency_ms, int num_tries)#

Check if a key exists in the database, repeating the check at a specified polling interval.

Parameters:

key – The key to be checked in the database
poll_frequency_ms – The time delay between checks, in milliseconds
num_tries – The total number of times to check for the key

Throws:

SmartRedis::Exception – if poll key command fails

Returns:

Returns true if the key is found within the specified number of tries, otherwise false.

bool poll_tensor(const std::string &name, int poll_frequency_ms, int num_tries)#

Check if a tensor exists in the database, repeating the check at a specified polling interval.

The tensor key used to check for existence may be formed by applying a prefix to the supplied name. See set_data_source() and use_tensor_ensemble_prefix() for more details.

Parameters:

name – The tensor name to be checked in the database
poll_frequency_ms – The time delay between checks, in milliseconds
num_tries – The total number of times to check for the name

Throws:

SmartRedis::Exception – if poll tensor command fails

Returns:

Returns true if the tensor is found within the specified number of tries, otherwise false.

bool poll_dataset(const std::string &name, int poll_frequency_ms, int num_tries)#

Check if a dataset exists in the database, repeating the check at a specified polling interval.

The dataset key used to check for existence may be formed by applying a prefix to the supplied name. See set_data_source() and use_dataset_ensemble_prefix() for more details.

Parameters:

name – The dataset name to be checked in the database
poll_frequency_ms – The time delay between checks, in milliseconds
num_tries – The total number of times to check for the name

Throws:

SmartRedis::Exception – if poll dataset command fails

Returns:

Returns true if the dataset is found within the specified number of tries, otherwise false.

bool poll_model(const std::string &name, int poll_frequency_ms, int num_tries)#

Check if a model (or script) exists in the database, repeating the check at a specified polling interval.

The model or script key used to check for existence may be formed by applying a prefix to the supplied name. See set_data_source() and use_model_ensemble_prefix() for more details.

Parameters:

name – The model/script name to be checked in the database
poll_frequency_ms – The time delay between checks, in milliseconds
num_tries – The total number of times to check for the name

Throws:

SmartRedis::Exception – if poll model command fails

Returns:

Returns true if the model/script is found within the specified number of tries, otherwise false.

void set_data_source(std::string source_id)#

Set the data source, a key prefix for future operations.

When running multiple applications, such as an ensemble computation, there is a risk that the same name is used for a tensor, dataset, script, or model by more than one executing entity. In order to prevent this sort of collision, SmartRedis affords the ability to add a prefix to names, thereby associating them with the name of the specific entity that the prefix corresponds to. For writes to the database when prefixing is activated, the prefix used is taken from the SSKEYOUT environment variable. For reads from the database, the default is to use the first prefix from SSKEYIN. If this is the same as the prefix from SSKEYOUT, the entity will read back the same data it wrote; however, this function allows an entity to read from data written by another entity (i.e. use the other entity’s key.)

Parameters:: source_id – The prefix for read operations; must have previously been set via the SSKEYIN environment variable
Throws:: SmartRedis::Exception – for failed setting of data source

void use_tensor_ensemble_prefix(bool use_prefix)#

Control whether names of tensor keys are prefixed (e.g. in an ensemble) when forming database keys.

This function can be used to avoid key collisions in an ensemble by prepending the string value from the environment variable SSKEYIN to tensor names. Prefixes will only be used if they were previously set through the environment variables SSKEYOUT and SSKEYIN. Keys of entities created before this function is called will not be retroactively prefixed. By default, the client prefixes tensor keys with the first prefix specified with the SSKEYIN and SSKEYOUT environment variables.

Parameters:: use_prefix – If set to true, all future operations on tensors will use a prefix, if available.
Throws:: SmartRedis::Exception – for failed activation of tensor prefixing

void use_dataset_ensemble_prefix(bool use_prefix)#

Control whether names of dataset keys are prefixed (e.g. in an ensemble) when forming database keys.

This function can be used to avoid key collisions in an ensemble by prepending the string value from the environment variable SSKEYIN to dataset names. Prefixes will only be used if they were previously set through the environment variables SSKEYOUT and SSKEYIN. Keys of entities created before this function is called will not be retroactively prefixed. By default, the client prefixes dataset keys with the first prefix specified with the SSKEYIN and SSKEYOUT environment variables.

Parameters:: use_prefix – If set to true, all future operations on datasets will use a prefix, if available.
Throws:: SmartRedis::Exception – for failed activation of dataset prefixing

void use_model_ensemble_prefix(bool use_prefix)#

Control whether model and script keys are prefixed (e.g. in an ensemble) when forming database keys.

This function can be used to avoid key collisions in an ensemble by prepending the string value from the environment variable SSKEYIN to model and script names. Prefixes will only be used if they were previously set through the environment variables SSKEYOUT and SSKEYIN. Keys of entities created before this function is called will not be retroactively prefixed. By default, the client prefixes tensor and dataset keys with the first prefix specified with the SSKEYIN and SSKEYOUT environment variables.

Parameters:: use_prefix – If set to true, all future operations on models and scripts will use a prefix, if available.
Throws:: SmartRedis::Exception – for failed activation of model prefixing

void use_list_ensemble_prefix(bool use_prefix)#

Control whether aggregation lists are prefixed.

This function can be used to avoid key collisions in an ensemble by prepending the string value from the environment variable SSKEYIN and/or SSKEYOUT to aggregation list names. Prefixes will only be used if they were previously set through the environment variables SSKEYOUT and SSKEYIN. Keys for aggregation lists created before this function is called will not be retroactively prefixed. By default, the client prefixes aggregation list keys with the first prefix specified with the SSKEYIN and SSKEYOUT environment variables. Note that use_dataset_ensemble_prefix() controls prefixing for the entities in the aggregation list, and use_dataset_ensemble_prefix() should be given the same value that was used during the initial setting of the DataSet into the database.

Parameters:: use_prefix – If set to true, all future operations on aggregation lists will use a prefix, if available.
Throws:: SmartRedis::Exception – for failed activation of aggregation list prefixing

parsed_reply_nested_map get_db_node_info(const std::string address)#

Returns information about the given database node.

Parameters:: address – The address of the database node (host:port)
Throws:: SmartRedis::Exception – if the command fails or if the address is not addressable by this client. When using a cluster of database nodes, it is best practice to bind each node in the cluster to a specific address to avoid inconsistencies in addresses retrieved with the CLUSTER SLOTS command. Inconsistencies in node addresses across CLUSTER SLOTS commands will lead to SmartRedis::Exception being thrown.
Returns:: parsed_reply_nested_map containing the database node information

parsed_reply_map get_db_cluster_info(const std::string address)#

Returns the response from a CLUSTER INFO command addressed to a single cluster node.

Parameters:: address – The address of the database node (host:port)
Throws:: SmartRedis::Exception – if the command fails or if the address is not addressable by this client. When using a cluster of database nodes, it is best practice to bind each node in the cluster to a specific address to avoid inconsistencies in addresses retrieved with the CLUSTER SLOTS command. Inconsistencies in node addresses across CLUSTER SLOTS commands will lead to SmartRedis::Exception being thrown.
Returns:: parsed_reply_map containing the database cluster information.

parsed_reply_map get_ai_info(const std::string &address, const std::string &key, bool reset_stat)#

Returns the response from an AI.INFO command sent to the database shard at the provided address.

Parameters:

address – The address of the database node (host:port)
key – The model or script name
reset_stat – Boolean indicating if the counters associated with the model or script should be reset.

Throws:

SmartRedis::Exception – or derivative error object if command execution or reply parsing fails. When using a cluster of database nodes, it is best practice to bind each node in the cluster to a specific address to avoid inconsistencies in addresses retrieved with the CLUSTER SLOTS command. Inconsistencies in node addresses across CLUSTER SLOTS commands will lead to SmartRedis::Exception being thrown.

Returns:

parsed_reply_map containing the AI.INFO information.

void flush_db(const std::string address)#

Flush the database shard at the provided address.

Parameters:: address – The address of the database node (host:port)
Throws:: SmartRedis::Exception – if the command fails or if the address is not addressable by this client. When using a cluster of database nodes, it is best practice to bind each node in the cluster to a specific address to avoid inconsistencies in addresses retrieved with the CLUSTER SLOTS command. Inconsistencies in node addresses across CLUSTER SLOTS commands will lead to SmartRedis::Exception being thrown.

std::unordered_map<std::string, std::string> config_get(const std::string expression, const std::string address)#

Read the configuration parameters of a running server.

Parameters:

expression – Parameter used in the configuration or a glob pattern (Using ‘*’ retrieves all configuration parameters, though this is expensive)
address – The address of the database node (host:port)

Throws:

SmartRedis::Exception – if the command fails or if the address is not addressable by this client. When using a cluster of database nodes, it is best practice to bind each node in the cluster to a specific address to avoid inconsistencies in addresses retrieved with the CLUSTER SLOTS command. Inconsistencies in node addresses across CLUSTER SLOTS commands will lead to SmartRedis::Exception being thrown.

Returns:

An unordered map from configuration parameters to their values. If no configuration parameters correspond to the requested expression, the map is empty.

void config_set(const std::string config_param, const std::string value, const std::string address)#

Reconfigure the server. It can change both trivial parameters or switch from one to another persistence option. All configuration parameters set using this command are immediately loaded by Redis and will take effect starting with the next command executed.

Parameters:

config_param – A configuration parameter to set
value – The value to assign to the configuration parameter
address – The address of the database node (host:port)

Throws:

SmartRedis::Exception – if the command fails or if the address is not addressable by this client. When using a cluster of database nodes, it is best practice to bind each node in the cluster to a specific address to avoid inconsistencies in addresses retrieved with the CLUSTER SLOTS command. Inconsistencies in node addresses across CLUSTER SLOTS commands will lead to SmartRedis::Exception being thrown.

void save(const std::string address)#

Performs a synchronous save of the database shard, capturing a snapshot of all the data inside the Redis instance in the form of an RDB file.

Parameters:: address – The address of the database node (host:port)
Throws:: SmartRedis::Exception – if the command fails or if the address is not addressable by this client. When using a cluster of database nodes, it is best practice to bind each node in the cluster to a specific address to avoid inconsistencies in addresses retrieved with the CLUSTER SLOTS command. Inconsistencies in node addresses across CLUSTER SLOTS commands will lead to SmartRedis::Exception being thrown.

void append_to_list(const std::string &list_name, const DataSet &dataset)#

Appends a dataset to the aggregation list.

When appending a dataset to an aggregation list, the list will automatically be created if it does not exist (i.e. this is the first entry in the list). Aggregation lists work by referencing the dataset by storing its key, so appending a dataset to an aggregation list does not create a copy of the dataset. Also, for this reason, the dataset must have been previously placed into the database with a separate call to put_dataset().

Parameters:

list_name – The name of the aggregation list
dataset – The DataSet to append

Throws:

SmartRedis::Exception – if the command fails

void delete_list(const std::string &list_name)#

Delete an aggregation list.

The key used to locate the aggregation list to be deleted may be formed by applying a prefix to the supplied name. See set_data_source() and use_list_ensemble_prefix() for more details.

Parameters:: list_name – The name of the aggregation list
Throws:: SmartRedis::Exception – if the command fails

void copy_list(const std::string &src_name, const std::string &dest_name)#

Copy an aggregation list.

The source and destination aggregation list keys used to locate and store the aggregation list may be formed by applying prefixes to the supplied src_name and dest_name. See set_data_source() and use_list_ensemble_prefix() for more details.

Parameters:

src_name – The source list name
dest_name – The destination list name

Throws:

SmartRedis::Exception – if the command fails

void rename_list(const std::string &src_name, const std::string &dest_name)#

Rename an aggregation list.

The old and new aggregation list key used to find and relocate the list may be formed by applying prefixes to the supplied src_name and dest_name. See set_data_source() and use_list_ensemble_prefix() for more details.

Parameters:

src_name – The initial list name
dest_name – The target list name

Throws:

SmartRedis::Exception – if the command fails

int get_list_length(const std::string &list_name)#

Get the number of entries in the list.

Parameters:: list_name – The list name
Throws:: SmartRedis::Exception – if the command fails

bool poll_list_length(const std::string &name, int list_length, int poll_frequency_ms, int num_tries)#

Poll list length until length is equal to the provided length. If maximum number of attempts is exceeded, false is returned.

The aggregation list key used to check for list length may be formed by applying a prefix to the supplied name. See set_data_source() and use_list_ensemble_prefix() for more details.

Parameters:

name – The name of the list
list_length – The desired length of the list
poll_frequency_ms – The time delay between checks, in milliseconds
num_tries – The total number of times to check for the name

Throws:

SmartRedis::Exception – if poll list length command fails

Returns:

Returns true if the list is found with a length greater than or equal to the provided length, otherwise false

bool poll_list_length_gte(const std::string &name, int list_length, int poll_frequency_ms, int num_tries)#

Poll list length until length is greater than or equal to the user-provided length. If maximum number of attempts is exceeded, false is returned.

The aggregation list key used to check for list length may be formed by applying a prefix to the supplied name. See set_data_source() and use_list_ensemble_prefix() for more details.

Parameters:

name – The name of the list
list_length – The desired minimum length of the list
poll_frequency_ms – The time delay between checks, in milliseconds
num_tries – The total number of times to check for the name

Throws:

SmartRedis::Exception – if poll list length command fails

Returns:

Returns true if the list is found with a length greater than or equal to the provided length, otherwise false

bool poll_list_length_lte(const std::string &name, int list_length, int poll_frequency_ms, int num_tries)#

Poll list length until length is less than or equal to the user-provided length. If maximum number of attempts is exceeded, false is returned.

The aggregation list key used to check for list length may be formed by applying a prefix to the supplied name. See set_data_source() and use_list_ensemble_prefix() for more details.

Parameters:

name – The name of the list
list_length – The desired maximum length of the list
poll_frequency_ms – The time delay between checks, in milliseconds
num_tries – The total number of times to check for the name

Throws:

SmartRedis::Exception – if poll list length command fails

Returns:

Returns true if the list is found with a length less than or equal to the provided length, otherwise false

std::vector<DataSet> get_datasets_from_list(const std::string &list_name)#

Get datasets from an aggregation list.

The aggregation list key used to retrieve datasets may be formed by applying a prefix to the supplied name. See set_data_source() and use_list_ensemble_prefix() for more details. An empty or nonexistant aggregation list returns an empty vector.

Parameters:: list_name – The name of the aggregation list
Throws:: SmartRedis::Exception – if retrieval fails.
Returns:: A vector containing DataSet objects.

std::vector<DataSet> get_dataset_list_range(const std::string &list_name, int start_index, int end_index)#

Get a range of datasets (by index) from an aggregation list.

The aggregation list key used to retrieve datasets may be formed by applying a prefix to the supplied name. See set_data_source() and use_list_ensemble_prefix() for more details. An empty or nonexistant aggregation list returns an empty vector. If the provided end_index is beyond the end of the list, that index will be treated as the last index of the list. If start_index and end_index are inconsistent (e.g. end_index is less than start_index), an empty list of datasets will be returned.

Parameters:

list_name – The name of the aggregation list
start_index – The starting index of the range (inclusive, starting at zero). Negative values are supported. A negative value indicates offsets starting at the end of the list. For example, -1 is the last element of the list.
end_index – The ending index of the range (inclusive, starting at zero). Negative values are supported. A negative value indicates offsets starting at the end of the list. For example, -1 is the last element of the list.

Throws:

SmartRedis::Exception – if retrieval fails or input parameters are invalid

Returns:

A vector containing DataSet objects.

void set_model_chunk_size(int chunk_size)#

Reconfigure the chunking size that Redis uses for model serialization, replication, and the model_get command.

This method triggers the AI.CONFIG method in the Redis database to change the model chunking size.

NOTE: The default size of 511MB should be fine for most applications, so it is expected to be very rare that a client calls this method. It is not necessary to call this method a model to be chunked.

Parameters:: chunk_size – The new chunk size in bytes
Throws:: SmartRedis::Exception – if the command fails.

std::string to_string() const#

Create a string representation of the client.

Returns:: A string containing client details

Dataset API#

The C++ DataSet API enables a user to manage a group of tensors and associated metadata within a datastructure called a DataSet object. The DataSet API operates independently of the database and solely maintains the dataset object in-memory. The actual interaction with the Redis database, where a snapshot of the DataSet object is sent, is handled by the Client API. For more information on the DataSet object, click here.

class DataSet : public SmartRedis::SRObject#

The DataSet class aggregates tensors and metadata into a nested data structure for storage.

Tensors in the DataSet can be used in Client commands such as Client.run_model() and Client.run_script() as inputs or outputs by prefixing the input or output tensor with the DataSet name (e.g. {dataset_name}.tensor_name).

Public Functions

DataSet(const std::string &name)#

DataSet constructor.

Parameters:: name – The name used to reference the DataSet

DataSet(const DataSet &dataset) = default#

DataSet copy constructor.

Parameters:: dataset – The DataSet to copy

DataSet &operator=(const DataSet &dataset) = default#

DataSet copy assignment operator.

Parameters:: dataset – The DataSet to copy and assign

DataSet(DataSet &&dataset) = default#

DataSet move constructor.

Parameters:: dataset – The DataSet to move

DataSet &operator=(DataSet &&dataset) = default#

DataSet move assignment operator.

Parameters:: dataset – The DataSet to move and assign

virtual ~DataSet()#: DataSet destructor.

void add_tensor(const std::string &name, const void *data, const std::vector<size_t> &dims, const SRTensorType type, const SRMemoryLayout mem_layout)#

Add a tensor to the DataSet.

Parameters:

name – The name used to reference the tensor within the DataSet
data – The tensor data
dims – The number of elements in each dimension of the tensor
type – The data type of the provided tensor data
mem_layout – The memory layout of the provided tensor data

Throws:

SmartRedis::Exception – if add_tensor operation fails

void add_meta_scalar(const std::string &name, const void *data, const SRMetaDataType type)#

Append a metadata scalar value to a field in the DataSet. If the field does not exist, it will be created. For string scalars, use add_meta_string.

Parameters:

name – The name for the metadata field
data – The scalar data to be appended to the metadata field
type – The data type of the scalar data to be appended to the metadata field

Throws:

SmartRedis::Exception – if add_meta_scalar operation fails

void add_meta_string(const std::string &name, const std::string &data)#

Append a metadata string value to a field in the DataSet. If the field does not exist, it will be created.

Parameters:

name – The name for the metadata field
data – The string to be appended to the metadata field

Throws:

SmartRedis::Exception – if add_meta_string operation fails

void get_tensor(const std::string &name, void *&data, std::vector<size_t> &dims, SRTensorType &type, const SRMemoryLayout mem_layout) const#

Get the tensor data, dimensions, and type for the tensor in the DataSet. This function will allocate and retain management of the memory for the tensor data.

The memory of the data pointer is valid until the DataSet is destroyed. This method is meant to be used when the dimensions and type of the tensor are unknown or the user does not want to manage memory. However, given that the memory associated with the return data is valid until DataSet destruction, this method should not be used repeatedly for large tensor data. Instead, it is recommended that the user use unpack_tensor() for large tensor data and to limit memory use by the DataSet.

Parameters:

name – The name used to reference the tensor in the DataSet
data – Receives data for the tensor, allocated by the library
dims – Receives the number of elements in each dimension of the retrieved tensor data
type – Receives the data type for the tensor
mem_layout – The memory layout to which retrieved tensor data should conform

Throws:

SmartRedis::Exception – if tensor retrieval fails

void get_tensor(const std::string &name, void *&data, size_t *&dims, size_t &n_dims, SRTensorType &type, const SRMemoryLayout mem_layout) const#

Get the tensor data, dimensions, and type for the tensor in the DataSet. This function will allocate and retain management of the memory for the tensor data. This is a c-style interface for the tensor dimensions.

The memory of the data pointer is valid until the DataSet is destroyed. This method is meant to be used when the dimensions and type of the tensor are unknown or the user does not want to manage memory. However, given that the memory associated with the return data is valid until DataSet destruction, this method should not be used repeatedly for large tensor data. Instead, it is recommended that the user use unpack_tensor() for large tensor data and to limit memory use by the DataSet.

Parameters:

name – The name used to reference the tensor in the DataSet
data – Receives data for the tensor, allocated by the library
dims – Receives the number of elements in each dimension of the retrieved tensor data
n_dims – Receives the number of dimensions of tensor data retrieved
type – Receives the data type for the tensor
mem_layout – The memory layout to which retrieved tensor data should conform

Throws:

SmartRedis::Exception – if tensor retrieval fails

void unpack_tensor(const std::string &name, void *data, const std::vector<size_t> &dims, const SRTensorType type, const SRMemoryLayout mem_layout)#

Retrieve tensor data to a caller-supplied buffer. This method is the most memory efficient way to retrieve tensor data from a DataSet.

Parameters:

name – The name used to reference the tensor in the DataSet
data – Receives data for the tensor, allocated by the library
dims – The number of elemnents in each dimension of the provided data buffer
type – The tensor datatype for the provided data buffer
mem_layout – The memory layout for the provided data buffer

Throws:

SmartRedis::Exception – if tensor retrieval fails

void get_meta_scalars(const std::string &name, void *&data, size_t &length, SRMetaDataType &type) const#

Retrieve metadata scalar field values from the DataSet.

The memory of the data pointer is valid until the DataSet is destroyed.

Parameters:

name – The name for the metadata field in the DataSet
data – Receives scalar data from the metadata field
length – Receives the number of returned scalar data values
type – Receives the number data type of the returned scalar data

Throws:

SmartRedis::Exception – if metadata retrieval fails

std::vector<std::string> get_meta_strings(const std::string &name) const#

Retrieve metadata string field values from the DataSet. Because standard C++ containers are used, memory management is handled by the returned std::vector<std::string>.

Parameters:: name – The name of the metadata string field
Throws:: SmartRedis::Exception – if metadata retrieval fails
Returns:: The strings associated with the metadata field, or an empty vector if no field matches the supplied metadata field name

void get_meta_strings(const std::string &name, char **&data, size_t &n_strings, size_t *&lengths) const#

Retrieve metadata string field values from the DataSet.

The memory of the data pointer is valid until the DataSet is destroyed.

Parameters:

name – The name of the metadata field in the DataSet
data – Receives an array of strings associated with the metadata field
n_strings – Receives the number of strings found that match the supplied metadata field name
lengths – Receives an array of the lengths of the strings found that match the supplied metadata field name

Throws:

SmartRedis::Exception – if metadata retrieval fails

bool has_field(const std::string &field_name) const#

Check whether the dataset contains a field.

Parameters:: field_name – The name of the field to check
Returns:: True iff the DataSet contains the field

void clear_field(const std::string &field_name)#

Clear all entries from a DataSet field.

Parameters:: field_name – The name of the field to clear

inline std::string get_name() const#

Retrieve the name of the DataSet.

Returns:: The name of the DataSet

inline void set_name(std::string name)#

Change the name for the DataSet.

Parameters:: name – The name for the DataSet

std::vector<std::string> get_tensor_names() const#

Retrieve the names of tensors in the DataSet.

Throws:: SmartRedis::Exception – if metadata retrieval fails
Returns:: The name of the tensors in the DataSet

void get_tensor_names(char **&data, size_t &n_strings, size_t *&lengths) const#

Retrieve tensor names from the DataSet.

The memory of the data pointer is valid until the DataSet is destroyed.

Parameters:

data – Receives an array of tensor names
n_strings – Receives the number of tensor names
lengths – Receives an array of the lengths of the tensor names

Throws:

SmartRedis::Exception – if tensor name retrieval fails

SRTensorType get_tensor_type(const std::string &name) const#

Retrieve the data type of a Tensor in the DataSet.

Parameters:: name – The name of the tensor
Throws:: SmartRedis::Exception – if tensor name retrieval fails
Returns:: The data type for the tensor

const std::vector<size_t> get_tensor_dims(const std::string &name) const#

Retrieve the dimensions of a Tensor in the DataSet.

Parameters:: name – The name of the tensor
Throws:: SmartRedis::Exception – if tensor name retrieval fails
Returns:: A vector of the tensor’s dimensions

std::vector<std::string> get_metadata_field_names() const#

Retrieve the names of all metadata fields in the DataSet.

Returns:: A vector of metadata field names

void get_metadata_field_names(char **&data, size_t &n_strings, size_t *&lengths) const#

Retrieve metadata field names from the DataSet.

The memory of the data pointer is valid until the DataSet is destroyed.

Parameters:

data – Receives an array of metadata field names
n_strings – Receives the number of metadata field names
lengths – Receives an array of the lengths of the metadata field names

Throws:

SmartRedis::Exception – if metadata field name retrieval fails

SRMetaDataType get_metadata_field_type(const std::string &name) const#

Retrieve the data type of a metadata field in the DataSet.

Parameters:: name – The name of the metadata field
Throws:: SmartRedis::Exception – if metadata field name retrieval fails
Returns:: The data type for the metadata field

std::string to_string() const#

Create a string representation of the DataSet.

Returns:: A string containing DataSet details

Friends

friend class Client

friend class PyDataset

C#

The following page provides a comprehensive overview of the SmartRedis C Client and Dataset APIs. Further explanation and details of each are presented below.

Client API#

The Client API is purpose-built for interaction with the backend database, which extends the capabilities of the Redis in-memory data store. It’s important to note that the SmartRedis Client API is the exclusive means for altering, transmitting, and receiving data within the backend database. More specifically, the Client API is responsible for both creating and modifying data structures, which encompass Models, Scripts, and Tensors. It also handles the transmission and reception of the aforementioned data structures in addition to Dataset data structure. Creating and modifying the DataSet object is confined to local operation by the DataSet API.

C-wrappers for the C++ Client class.

Functions

SRError SimpleCreateClient(const char *logger_name, const size_t logger_name_length, void **new_client)#

C-client simple constructor that uses default environment variables to locate configuration settings.

Parameters:

logger_name – Identifier for the current client
logger_name_length – Length in characters of the logger_name string
new_client – Receives the new client

Returns:

Returns SRNoError on success or an error code on failure

SRError CreateClient(void *config_options, const char *logger_name, const size_t logger_name_length, void **new_client)#

C-client constructor that uses a ConfigOptions object to locate configuration settings.

Parameters:

config_options – The ConfigOptions object to use
logger_name – Identifier for the current client
logger_name_length – Length in characters of the logger_name string
new_client – Receives the new client

Returns:

Returns SRNoError on success or an error code on failure

SRError SmartRedisCClient(bool cluster, const char *logger_name, const size_t logger_name_length, void **new_client)#

C-client constructor.

C-client constructor (deprecated)

Parameters:

cluster – Flag to indicate if a database cluster is being used
logger_name – Identifier for the current client
logger_name_length – Length in characters of the logger_name string
new_client – Receives the new client

Returns:

Returns SRNoError on success or an error code on failure

SRError DeleteCClient(void **c_client)#

C-client destructor.

Parameters:: c_client – A pointer to a pointer to the c-client to destroy. The client is set to NULL on completion
Returns:: Returns SRNoError on success or an error code on failure

SRError put_dataset(void *c_client, void *dataset)#

Put a DataSet object into the database.

The final dataset key under which the dataset is stored is generated from the name that was supplied when the dataset was created and may be prefixed. See use_dataset_ensemble_prefix() for more details.

Parameters:

c_client – The client object to use for communication
dataset – The DataSet object to send

Returns:

Returns SRNoError on success or an error code on failure

SRError get_dataset(void *c_client, const char *name, const size_t name_length, void **dataset)#

Get a DataSet object from the database.

The final dataset key used to locate the dataset may be formed by applying a prefix to the supplied name. See set_data_source() and use_dataset_ensemble_prefix() for more details.

Parameters:

c_client – The client object to use for communication
name – The name of the dataset object to fetch
name_length – The length of the name string, excluding null terminating character
dataset – Receives the DataSet

Returns:

Returns SRNoError on success or an error code on failure

SRError rename_dataset(void *c_client, const char *old_name, const size_t old_name_length, const char *new_name, const size_t new_name_length)#

Move a DataSet to a new name.

The old and new dataset keys used to find and relocate the dataset may be formed by applying prefixes to the supplied old_name and new_name. See set_data_source() and use_dataset_ensemble_prefix() for more details.

Parameters:

c_client – The client object to use for communication
old_name – The current name key of the dataset object
old_name_length – The length of the current name string, excluding null terminating character
new_name – The new name key for the dataset object
new_name_length – The length of the new name string, excluding null terminating character

Returns:

Returns SRNoError on success or an error code on failure

SRError copy_dataset(void *c_client, const char *src_name, const size_t src_name_length, const char *dest_name, const size_t dest_name_length)#

Copy a DataSet to a new name.

The source and destination dataset keys used to locate and store the dataset may be formed by applying prefixes to the supplied src_name and dest_name. See set_data_source() and use_dataset_ensemble_prefix() for more details.

Parameters:

c_client – The client object to use for communication
src_name – The source name of the dataset object
src_name_length – The length of the src_name string, excluding null terminating character
dest_name – The destination name for the dataset object
dest_name_length – The length of the dest_name string, excluding null terminating character

Returns:

Returns SRNoError on success or an error code on failure

SRError delete_dataset(void *c_client, const char *name, const size_t name_length)#

Delete a DataSet.

The dataset key used to locate the dataset to be deleted may be formed by applying a prefix to the supplied name. See set_data_source() and use_dataset_ensemble_prefix() for more details.

Parameters:

c_client – The client object to use for communication
name – The name of the dataset object
name_length – The length of the name string, excluding null terminating character

Returns:

Returns SRNoError on success or an error code on failure

SRError put_tensor(void *c_client, const char *name, const size_t name_length, void *data, const size_t *dims, const size_t n_dims, SRTensorType type, SRMemoryLayout mem_layout)#

Put a tensor into the database.

The key under which the tensor is stored may be formed by applying a prefix to the supplied name. See use_tensor_ensemble_prefix() for more details.

Parameters:

c_client – The client object to use for communication
name – The name by which the tensor should be accessed
name_length – The length of the tensor name string, excluding null terminating character
data – The data to store with the tensor
dims – The number of elements for each dimension of the tensor
n_dims – The number of dimensions of the tensor
type – The data type of the tensor
mem_layout – The memory layout of the data

Returns:

Returns SRNoError on success or an error code on failure

SRError get_tensor(void *c_client, const char *name, const size_t name_length, void **data, size_t **dims, size_t *n_dims, SRTensorType *type, SRMemoryLayout mem_layout)#

Get the data, dimensions, and type for a tensor in the database. This function will allocate and retain management of the memory for the tensor data. The number of dimensions and the tensor type will be set based on the tensor retrieved from the database. The requested memory layout will be used to shape the returned memory space pointed to by the data pointer.

The final tensor key used to retrieve the tensor may be formed by applying a prefix to the supplied name. See set_data_source() and use_tensor_ensemble_prefix() for more details.

The memory returned in data is valid until the client is destroyed. This method is meant to be used when the dimensions and type of the tensor are unknown or the user does not want to manage memory. However, given that the memory associated with the return data is valid until client destruction, this method should not be used repeatedly for large tensor data. Instead it is recommended that the user use unpack_tensor() for large tensor data and to limit memory use by the client.

Parameters:

c_client – The client object to use for communication
name – The name by which the tensor should be accessed
name_length – The length of the supplied name string, excluding null terminating character
data – Receives tensor data in newly allocated memory
dims – Receives the number of elements in each dimension of the tensor in newly allocated memory
n_dims – Receives the number of dimensions for the tensor
type – Receives the data type for the tensor as retrieved from the database
mem_layout – The layout requested for the allocated memory space

Returns:

Returns SRNoError on success or an error code on failure

SRError unpack_tensor(void *c_client, const char *name, const size_t name_length, void *result, const size_t *dims, const size_t n_dims, SRTensorType type, SRMemoryLayout mem_layout)#

Retrieve a tensor from the database into memory provided by the caller.

The final tensor key used to retrieve the tensor may be formed by applying a prefix to the supplied name. See set_data_source() and use_tensor_ensemble_prefix() for more details.

Parameters:

c_client – The client object to use for communication
name – The name by which the tensor should be accessed
name_length – The length of the supplied name string, excluding null terminating character
result – The data buffer into which the tensor data should be written
dims – The number of elements in each dimension of the provided memory space
n_dims – The number of dimensions in the provided memory space
type – The data type for the provided memory space.
mem_layout – The memory layout for the provided memory space.

Returns:

Returns SRNoError on success or an error code on failure

SRError rename_tensor(void *c_client, const char *old_name, const size_t old_name_length, const char *new_name, const size_t new_name_length)#

Move a tensor to a new name.

The old and new tensor keys used to find and relocate the tensor may be formed by applying prefixes to the supplied old_name and new_name. See set_data_source() and use_tensor_ensemble_prefix() for more details.

Parameters:

c_client – The client object to use for communication
old_name – The original name by which the tensor should be accessed
old_name_length – The length of the old_name string, excluding null terminating character
new_name – The new tensor name
new_name_length – The length of the supplied new_name string, excluding null terminating characters

Returns:

Returns SRNoError on success or an error code on failure

SRError delete_tensor(void *c_client, const char *name, const size_t name_length)#

Delete a tensor from the database.

The final tensor key used to find the tensor to be deleted may be formed by applying a prefix to the supplied name. See set_data_source() and use_tensor_ensemble_prefix() for more details.

Parameters:

c_client – The client object to use for communication
name – The tensor name for the tensor to delete
name_length – The length of the name string, excluding null terminating character

Returns:

Returns SRNoError on success or an error code on failure

SRError copy_tensor(void *c_client, const char *src_name, const size_t src_name_length, const char *dest_name, const size_t dest_name_length)#

Copy a tensor to a destination tensor name.

The source and destination tensor keys used to locate and store the tensor may be formed by applying prefixes to the supplied src_name and dest_name. See set_data_source() and use_tensor_ensemble_prefix() for more details.

Parameters:

c_client – The client object to use for communication
src_name – The source name from which the tensor should be copied
src_name_length – The length of the src_name string, excluding null terminating character
dest_name – The destination name to which the tensor should be copied
dest_name_length – The length of the dest_name string, excluding null terminating character

Returns:

Returns SRNoError on success or an error code on failure

bool _isTensorFlow(const char *backend)#

Determine whether the backend is TensorFlow or TensorFlowLite.

Within the C SmartRedis Client, additional translation needs to be done to the input and output vectors for calls to run_model. This function checks that the backend doesn’t match TF or TFLITE

Parameters:: backend – The name of the backend (TF, TFLITE, TORCH, ONNX)

void _check_params_set_model(void *c_client, const char *name, const char *backend, const char **inputs, const size_t *input_lengths, const size_t n_inputs, const char **outputs, const size_t *output_lengths, const size_t n_outputs)#

Check parameters for all parameters common to set_model methods.

Make sure that all pointers are not void and that the size of the inputs and outputs is not zero

Parameters:

c_client – The client object to use for communication
name – The name to associate with the model
backend – The name of the backend (TF, TFLITE, TORCH, ONNX)
inputs – One or more names of model input nodes (TF models only)
input_lengths – The length of each input name string, excluding null terminating character
n_inputs – The number of inputs
outputs – One or more names of model output nodes (TF models only)
output_lengths – The length of each output name string, excluding null terminating character
n_outputs – The number of outputs

SRError set_model_from_file(void *c_client, const char *name, const size_t name_length, const char *model_file, const size_t model_file_length, const char *backend, const size_t backend_length, const char *device, const size_t device_length, const int batch_size, const int min_batch_size, const int min_batch_timeout, const char *tag, const size_t tag_length, const char **inputs, const size_t *input_lengths, const size_t n_inputs, const char **outputs, const size_t *output_lengths, const size_t n_outputs)#

Set a model (from file) in the database for future execution.

The final model key used to store the model may be formed by applying a prefix to the supplied name. Similarly, the tensor names in the input and output nodes for TF models may be prefixed. See set_data_source(), use_model_ensemble_prefix(), and use_tensor_ensemble_prefix() for more details

Parameters:

c_client – The client object to use for communication
name – The name to associate with the model
name_length – The length of the name string, excluding null terminating character
model_file – The source file for the model
model_file_length – The length of the model_file string, excluding null terminating character
backend – The name of the backend (TF, TFLITE, TORCH, ONNX)
backend_length – The length of the backend string, excluding null terminating character
device – The name of the device for execution. May be either CPU or GPU. If multiple GPUs are present, a specific GPU can be targeted by appending its zero-based index, i.e. “GPU:1”
device_length – The length of the device string, excluding null terminating character
batch_size – The batch size for model execution
min_batch_size – The minimum batch size for model execution
min_batch_timeout – Max time (ms) to wait for min batch size
tag – A tag to attach to the model for information purposes
tag_length – The length of the tag string, excluding null terminating character
inputs – One or more names of model input nodes (TF models only)
input_lengths – The length of each input name string, excluding null terminating character
n_inputs – The number of inputs
outputs – One or more names of model output nodes (TF models only)
output_lengths – The length of each output name string, excluding null terminating character
n_outputs – The number of outputs

Returns:

Returns SRNoError on success or an error code on failure

SRError set_model_from_file_multigpu(void *c_client, const char *name, const size_t name_length, const char *model_file, const size_t model_file_length, const char *backend, const size_t backend_length, const int first_gpu, const int num_gpus, const int batch_size, const int min_batch_size, const int min_batch_timeout, const char *tag, const size_t tag_length, const char **inputs, const size_t *input_lengths, const size_t n_inputs, const char **outputs, const size_t *output_lengths, const size_t n_outputs)#

Set a model from file in the database for future execution in a multi-GPU system.

The final model key used to store the model may be formed by applying a prefix to the supplied name. Similarly, the tensor names in the input and output nodes for TF models may be prefixed. See set_data_source(), use_model_ensemble_prefix(), and use_tensor_ensemble_prefix() for more details

Parameters:

c_client – The client object to use for communication
name – The name to associate with the model
name_length – The length of the name string, excluding null terminating character
model_file – The source file for the model
model_file_length – The length of the model_file string, excluding null terminating character
backend – The name of the backend (TF, TFLITE, TORCH, ONNX)
backend_length – The length of the backend string, excluding null terminating character
first_gpu – the first gpu (zero-based) to use with the model
num_gpus – the number of gpus to use with the model
batch_size – The batch size for model execution
min_batch_size – The minimum batch size for model execution
min_batch_timeout – Max time (ms) to wait for min batch size
tag – A tag to attach to the model for information purposes
tag_length – The length of the tag string, excluding null terminating character
inputs – One or more names of model input nodes (TF models only)
input_lengths – The length of each input name string, excluding null terminating character
n_inputs – The number of inputs
outputs – One or more names of model output nodes (TF models only)
output_lengths – The length of each output name string, excluding null terminating character
n_outputs – The number of outputs

Returns:

Returns SRNoError on success or an error code on failure

SRError set_model(void *c_client, const char *name, const size_t name_length, const char *model, const size_t model_length, const char *backend, const size_t backend_length, const char *device, const size_t device_length, const int batch_size, const int min_batch_size, const int min_batch_timeout, const char *tag, const size_t tag_length, const char **inputs, const size_t *input_lengths, const size_t n_inputs, const char **outputs, const size_t *output_lengths, const size_t n_outputs)#

Set a model (from buffer) in the database for future execution.

The final model key used to store the model may be formed by applying a prefix to the supplied name. Similarly, the tensor names in the input and output nodes for TF models may be prefixed. See set_data_source(), use_model_ensemble_prefix(), and use_tensor_ensemble_prefix() for more details

Parameters:

c_client – The client object to use for communication
name – The name to associate with the model
name_length – The length of the name string, excluding null terminating character
model – The model as a continuous buffer
model_length – The length of the model string, excluding null terminating character
backend – The name of the backend (TF, TFLITE, TORCH, ONNX)
backend_length – The length of the backend string, excluding null terminating character
device – The name of the device for execution. May be either CPU or GPU. If multiple GPUs are present, a specific GPU can be targeted by appending its zero-based index, i.e. “GPU:1”
device_length – The length of the device string, excluding null terminating character
batch_size – The batch size for model execution
min_batch_size – The minimum batch size for model execution
min_batch_timeout – Max time (ms) to wait for min batch size
tag – A tag to attach to the model for information purposes
tag_length – The length of the tag string, excluding null terminating character
inputs – One or more names of model input nodes (TF models only)
input_lengths – The length of each input name string, excluding null terminating character
n_inputs – The number of inputs
outputs – One or more names of model output nodes (TF models only)
output_lengths – The length of each output name string, excluding null terminating character
n_outputs – The number of outputs

Returns:

Returns SRNoError on success or an error code on failure

SRError set_model_multigpu(void *c_client, const char *name, const size_t name_length, const char *model, const size_t model_length, const char *backend, const size_t backend_length, const int first_gpu, const int num_gpus, const int batch_size, const int min_batch_size, const int min_batch_timeout, const char *tag, const size_t tag_length, const char **inputs, const size_t *input_lengths, const size_t n_inputs, const char **outputs, const size_t *output_lengths, const size_t n_outputs)#

Set a model (from buffer) in the database for future execution in a multi-GPU system.

The final model key used to store the model may be formed by applying a prefix to the supplied name. Similarly, the tensor names in the input and output nodes for TF models may be prefixed. See set_data_source(), use_model_ensemble_prefix(), and use_tensor_ensemble_prefix() for more details

Parameters:

c_client – The client object to use for communication
name – The name to associate with the model
name_length – The length of the name string, excluding null terminating character
model – The model as a continuous buffer
model_length – The length of the model string, excluding null terminating character
backend – The name of the backend (TF, TFLITE, TORCH, ONNX)
backend_length – The length of the backend string, excluding null terminating character
first_gpu – the first GPU (zero-based) to use with the model
num_gpus – The number of GPUs to use with the model
batch_size – The batch size for model execution
min_batch_size – The minimum batch size for model execution
min_batch_timeout – Max time (ms) to wait for min batch size
tag – A tag to attach to the model for information purposes
tag_length – The length of the tag string, excluding null terminating character
inputs – One or more names of model input nodes (TF models only)
input_lengths – The length of each input name string, excluding null terminating character
n_inputs – The number of inputs
outputs – One or more names of model output nodes (TF models only)
output_lengths – The length of each output name string, excluding null terminating character
n_outputs – The number of outputs

Returns:

Returns SRNoError on success or an error code on failure

SRError get_model(void *c_client, const char *name, const size_t name_length, size_t *model_length, const char **model)#

Get a model in the database. The memory associated with the model string is valid until the client is destroyed.

The model key used to locate the model may be formed by applying a prefix to the supplied name. See set_data_source() and use_model_ensemble_prefix() for more details.

Parameters:

c_client – The client object to use for communication
name – The name to use to get the model
name_length – The length of the name string, excluding null terminating character
model_length – The length of the model buffer string, excluding null terminating character
model – Receives the model as a string

Returns:

Returns SRNoError on success or an error code on failure

SRError set_script_from_file(void *c_client, const char *name, const size_t name_length, const char *device, const size_t device_length, const char *script_file, const size_t script_file_length)#

Set a script from file in the database for future execution.

The final script key used to store the script may be formed by applying a prefix to the supplied name. See use_model_ensemble_prefix() for more details

Parameters:

c_client – The client object to use for communication
name – The name to associate with the script
name_length – The length of the name string, excluding null terminating character
device – The name of the device for execution. May be either CPU or GPU. If multiple GPUs are present, a specific GPU can be targeted by appending its zero-based index, i.e. “GPU:1”
device_length – The length of the device name string, excluding null terminating character
script_file – The source file for the script
script_file_length – The length of the script file name string, excluding null terminating character

Returns:

Returns SRNoError on success or an error code on failure

SRError set_script_from_file_multigpu(void *c_client, const char *name, const size_t name_length, const char *script_file, const size_t script_file_length, const int first_gpu, const int num_gpus)#

Set a script from file in the database for future execution in a multi-GPU system.

The final script key used to store the script may be formed by applying a prefix to the supplied name. See use_model_ensemble_prefix() for more details

Parameters:

c_client – The client object to use for communication
name – The name to associate with the script
name_length – The length of the name string, excluding null terminating character
script_file – The source file for the script
script_file_length – The length of the script file name string, excluding null terminating character
first_gpu – the first gpu (zero-based) to use with the model
num_gpus – the number of gpus to use with the model

Returns:

Returns SRNoError on success or an error code on failure

SRError set_script(void *c_client, const char *name, const size_t name_length, const char *device, const size_t device_length, const char *script, const size_t script_length)#

Set a script (from buffer) in the database for future execution in a multi-GPU system.

The final script key used to store the script may be formed by applying a prefix to the supplied name. See use_model_ensemble_prefix() for more details

Parameters:

c_client – The client object to use for communication
name – The name to associate with the script
name_length – The length of the name string, excluding null terminating character
device – The name of the device for execution. May be either CPU or GPU. If multiple GPUs are present, a specific GPU can be targeted by appending its zero-based index, i.e. “GPU:1”
device_length – The length of the device name string, excluding null terminating character
script – The script as a string buffer
script_length – The length of the script string, excluding null terminating character

Returns:

Returns SRNoError on success or an error code on failure

SRError set_script_multigpu(void *c_client, const char *name, const size_t name_length, const char *script, const size_t script_length, const int first_gpu, const int num_gpus)#

Set a script (from buffer) in the database for future execution execution in a multi-GPU system.

The final script key used to store the script may be formed by applying a prefix to the supplied name. See use_model_ensemble_prefix() for more details

Parameters:

c_client – The client object to use for communication
name – The name to associate with the script
name_length – The length of the name string, excluding null terminating character
first_gpu – the first gpu (zero-based) to use with the model
num_gpus – the number of gpus to use with the model
script – The script as a string buffer
script_length – The length of the script string, excluding null terminating character

Returns:

Returns SRNoError on success or an error code on failure

SRError get_script(void *c_client, const char *name, const size_t name_length, const char **script, size_t *script_length)#

Get a script from the database. The memory associated with the script string is valid until the client is destroyed.

The script key used to locate the script may be formed by applying a prefix to the supplied name. See set_data_source() and use_model_ensemble_prefix() for more details.

Parameters:

c_client – The client object to use for communication
name – The name to use to get the script
name_length – The length of the name string, excluding null terminating character
script – Receives the script in an allocated memory buffer
script_length – The length of the script buffer string, excluding null terminating character

Returns:

Returns SRNoError on success or an error code on failure

void _check_params_run_script(void *c_client, const char *name, const char *function, const char **inputs, const size_t *input_lengths, const size_t n_inputs, const char **outputs, const size_t *output_lengths, const size_t n_outputs)#

Check parameters for all parameters common to set_model methods.

Make sure that all pointers are not void and that the size of the inputs and outputs is not zero

Parameters:

c_client – The client object to use for communication
name – The name associated with the script
function – The name of the function in the script to run
inputs – The tensor keys of inputs tensors to use in the script
input_lengths – The length of each input name string, excluding null terminating character
n_inputs – The number of inputs
outputs – The tensor keys of output tensors that will be used to save script results
output_lengths – The length of each output name string, excluding null terminating character
n_outputs – The number of outputs

SRError run_script(void *c_client, const char *name, const size_t name_length, const char *function, const size_t function_length, const char **inputs, const size_t *input_lengths, const size_t n_inputs, const char **outputs, const size_t *output_lengths, const size_t n_outputs)#

Run a script function in the database using the specificed input and output tensors.

Run a script function in the database using the specified input and output tensors.

The script key used to locate the script to be run may be formed by applying a prefix to the supplied name. Similarly, the tensor names in the input and output arrays may be prefixed. See set_data_source(), use_model_ensemble_prefix(), and use_tensor_ensemble_prefix() for more details

Parameters:

c_client – The client object to use for communication
name – The name associated with the script
name_length – The length of the name string, excluding null terminating character
function – The name of the function in the script to run
function_length – The length of the function name string, excluding null terminating character
inputs – The tensor keys of inputs tensors to use in the script
input_lengths – The length of each input name string, excluding null terminating character
n_inputs – The number of inputs
outputs – The tensor keys of output tensors that will be used to save script results
output_lengths – The length of each output name string, excluding null terminating character
n_outputs – The number of outputs

Returns:

Returns SRNoError on success or an error code on failure

SRError run_script_multigpu(void *c_client, const char *name, const size_t name_length, const char *function, const size_t function_length, const char **inputs, const size_t *input_lengths, const size_t n_inputs, const char **outputs, const size_t *output_lengths, const size_t n_outputs, const int offset, const int first_gpu, const int num_gpus)#

Run a script function in the database using the specified input and output tensors in a multi-GPU system.

The script key used to locate the script to be run may be formed by applying a prefix to the supplied name. Similarly, the tensor names in the input and output arrays may be prefixed. See set_data_source(), use_model_ensemble_prefix(), and use_tensor_ensemble_prefix() for more details

Parameters:

c_client – The client object to use for communication
name – The name associated with the script
name_length – The length of the name string, excluding null terminating character
function – The name of the function in the script to run
function_length – The length of the function name string, excluding null terminating character
inputs – The tensor keys of inputs tensors to use in the script
input_lengths – The length of each input name string, excluding null terminating character
n_inputs – The number of inputs
outputs – The tensor keys of output tensors that will be used to save script results
output_lengths – The length of each output name string, excluding null terminating character
n_outputs – The number of outputs
offset – index of the current image, such as a processor ID or MPI rank
first_gpu – the first GPU (zero-based) to use with the script
num_gpus – the number of gpus for which the script was stored

Returns:

Returns SRNoError on success or an error code on failure

void _check_params_run_model(void *c_client, const char *name, const char **inputs, const size_t *input_lengths, const size_t n_inputs, const char **outputs, const size_t *output_lengths, const size_t n_outputs)#

Check parameters for all parameters common to run_model methods.

Make sure that all pointers are not void and that the size of the inputs and outputs is not zero

Parameters:

c_client – The client object to use for communication
name – The name to associate with the model
inputs – One or more names of model input nodes (TF models only)
input_lengths – The length of each input name string, excluding null terminating character
n_inputs – The number of inputs
outputs – One or more names of model output nodes (TF models only)
output_lengths – The length of each output name string, excluding null terminating character
n_outputs – The number of outputs

SRError run_model(void *c_client, const char *name, const size_t name_length, const char **inputs, const size_t *input_lengths, const size_t n_inputs, const char **outputs, const size_t *output_lengths, const size_t n_outputs)#

Run a model in the database using the specified input and output tensors.

The model key used to locate the model to be run may be formed by applying a prefix to the supplied name. See set_data_source() and use_model_ensemble_prefix() for more details.

Parameters:

c_client – The client object to use for communication
name – The name associated with the model
name_length – The length of the name string, excluding null terminating character
inputs – The names of inputs tensors to use in the script
input_lengths – The length of each input name string, excluding null terminating character
n_inputs – The number of inputs
outputs – The names of output tensors to be used to save script results
output_lengths – The length of each output name string, excluding null terminating character
n_outputs – The number of outputs

Returns:

Returns SRNoError on success or an error code on failure

SRError run_model_multigpu(void *c_client, const char *name, const size_t name_length, const char **inputs, const size_t *input_lengths, const size_t n_inputs, const char **outputs, const size_t *output_lengths, const size_t n_outputs, const int offset, const int first_gpu, const int num_gpus)#

Run a model in the database using the specificed input and output tensors in a multi-GPU system.

The model key used to locate the model to be run may be formed by applying a prefix to the supplied name. See set_data_source() and use_model_ensemble_prefix() for more details.

Parameters:

c_client – The client object to use for communication
name – The name associated with the model
name_length – The length of the name string, excluding null terminating character
inputs – The names of inputs tensors to use in the script
input_lengths – The length of each input name string, excluding null terminating character
n_inputs – The number of inputs
outputs – The names of output tensors to be used to save script results
output_lengths – The length of each output name string, excluding null terminating character
n_outputs – The number of outputs
offset – index of the current image, such as a processor ID or MPI rank
first_gpu – the first GPU (zero-based) to use with the model
num_gpus – the number of gpus for which the script was stored

Returns:

Returns SRNoError on success or an error code on failure

SRError delete_model(void *c_client, const char *name, const size_t name_length)#

Remove a model from the database.

Parameters:

c_client – The client object to use for communication
name – The name associated with the model
name_length – The length of the name string,

Returns:

Returns SRNoError on success or an error code on failure

SRError delete_model_multigpu(void *c_client, const char *name, const size_t name_length, const int first_gpu, const int num_gpus)#

Remove a model from the database.

The model key used to locate the model to be deleted may be formed by applying a prefix to the supplied name. See set_data_source() and use_model_ensemble_prefix() for more details. The first_gpu and num_gpus parameters must match those used when the model was stored.

Parameters:

c_client – The client object to use for communication
name – The name associated with the model
name_length – The length of the name string,
first_gpu – the first GPU (zero-based) to use with the model
num_gpus – the number of gpus for which the model was stored

Returns:

Returns SRNoError on success or an error code on failure

SRError delete_script(void *c_client, const char *name, const size_t name_length)#

Remove a script from the database.

Parameters:

c_client – The client object to use for communication
name – The name associated with the script
name_length – The length of the name string,

Returns:

Returns SRNoError on success or an error code on failure

SRError delete_script_multigpu(void *c_client, const char *name, const size_t name_length, const int first_gpu, const int num_gpus)#

Remove a script from the database that was stored for use with multiple GPUs.

The script key used to locate the script to be deleted may be formed by applying a prefix to the supplied name. See set_data_source() and use_model_ensemble_prefix() for more details. The first_gpu and num_gpus parameters must match those used when the script was stored.

Parameters:

c_client – The client object to use for communication
name – The name associated with the model
name_length – The length of the name string,
first_gpu – the first GPU (zero-based) to use with the model
num_gpus – the number of gpus for which the model was stored

Returns:

Returns SRNoError on success or an error code on failure

SRError key_exists(void *c_client, const char *key, const size_t key_length, bool *exists)#

Check if a key exists in the database.

The key to be checked is not prefixed in any way. If prefixing is enabled, callers must manually prefix names to form keys to be checked.

Parameters:

c_client – The client object to use for communication
key – The key that will be checked in the database
key_length – The length of the key string, excluding null terminating character
exists – Receives whether the key exists

Returns:

Returns SRNoError on success or an error code on failure

SRError tensor_exists(void *c_client, const char *name, const size_t name_length, bool *exists)#

Check if a tensor exists in the database.

The tensor key used to check for tensor existence may be formed by applying a prefix to the supplied name. See set_data_source() and use_tensor_ensemble_prefix() for more details.

Parameters:

c_client – The client object to use for communication
name – The name of the tensor that will be checked in the database. The full tensor key corresponding to name will be formed in accordance with the current prefixing behavior
name_length – The length of the name string, excluding null terminating character
exists – Receives whether the tensor exists

Returns:

Returns SRNoError on success or an error code on failure

SRError model_exists(void *c_client, const char *name, const size_t name_length, bool *exists)#

Check if a model or script exists in the database.

The model or script key used to check for existence may be formed by applying a prefix to the supplied name. See set_data_source() and use_model_ensemble_prefix() for more details.

Parameters:

c_client – The client object to use for communication
name – The name of the entity that will be checked in the database. The full model/script key corresponding to name will be formed in accordance with the current prefixing behavior
name_length – The length of the name string, excluding null terminating character
exists – Receives whether the model/script exists

Returns:

Returns SRNoError on success or an error code on failure

SRError dataset_exists(void *c_client, const char *name, const size_t name_length, bool *exists)#

Check if a dataset exists in the database.

The dataset key used to check for dataset existence may be formed by applying a prefix to the supplied name. See set_data_source() and use_dataset_ensemble_prefix() for more details.

Parameters:

c_client – The client object to use for communication
name – The name of the dataset that will be checked in the database. The full key corresponding to name will be formed in accordance with the current prefixing behavior
name_length – The length of the name string, excluding null terminating character
exists – Receives whether the dataset exists

Returns:

Returns SRNoError on success or an error code on failure

SRError poll_key(void *c_client, const char *key, const size_t key_length, const int poll_frequency_ms, const int num_tries, bool *exists)#

Check if a key exists in the database, repeating the check at a specified frequency and number of repetitions.

The key to be checked is not prefixed in any way. If prefixing is enabled, callers must manually prefix names to form keys to be checked.

Parameters:

c_client – The client object to use for communication
key – The key to be checked in the database
key_length – The length of the key string, excluding null terminating character
poll_frequency_ms – The time delay between checks, in milliseconds
num_tries – The total number of times to check for the key
exists – Receives whether the key is found within the specified number of tries

Returns:

Returns SRNoError on success or an error code on failure

SRError poll_model(void *c_client, const char *name, const size_t name_length, const int poll_frequency_ms, const int num_tries, bool *exists)#

Check if a model or script exists in the database, repeating the check at a specified frequency and number of repetitions.

The model or script key used to check for existence may be formed by applying a prefix to the supplied name. See set_data_source() and use_model_ensemble_prefix() for more details.

Parameters:

c_client – The client object to use for communication
name – The name of the entity to be checked in the database. The full key associated to name will be formed according to the prefixing behavior
name_length – The length of the name string, excluding null terminating character
poll_frequency_ms – The time delay between checks, in milliseconds
num_tries – The total number of times to check for the model key
exists – Receives whether the model is found within the specified number of tries

Returns:

Returns SRNoError on success or an error code on failure

SRError poll_tensor(void *c_client, const char *name, const size_t name_length, const int poll_frequency_ms, const int num_tries, bool *exists)#

Check if a tensor exists in the database, repeating the check at a specified frequency and number of repetitions.

The tensor key used to check for tensor existence may be formed by applying a prefix to the supplied name. See set_data_source() and use_tensor_ensemble_prefix() for more details.

Parameters:

c_client – The client object to use for communication
name – The name of the entity to be checked in the database. The full key associated to name will be formed according to the prefixing behavior
name_length – The length of the name string, excluding null terminating character
poll_frequency_ms – The time delay between checks, in milliseconds
num_tries – The total number of times to check for the tensor key
exists – Receives whether the tensor is found within the specified number of tries

Returns:

Returns SRNoError on success or an error code on failure

SRError poll_dataset(void *c_client, const char *name, const size_t name_length, const int poll_frequency_ms, const int num_tries, bool *exists)#

Check if a dataset exists in the database, repeating the check at a specified frequency and number of repetitions.

The dataset key used to check for dataset existence may be formed by applying a prefix to the supplied name. See set_data_source() and use_dataset_ensemble_prefix() for more details.

Parameters:

c_client – The client object to use for communication
name – The name of the entity to be checked in the database. The full key associated to name will be formed according to the prefixing behavior
name_length – The length of the name string, excluding null terminating character
poll_frequency_ms – The time delay between checks, in milliseconds
num_tries – The total number of times to check for the dataset key
exists – Receives whether the tensor is found within the specified number of tries

Returns:

Returns sr_ok on success

SRError set_data_source(void *c_client, const char *source_id, const size_t source_id_length)#

Set the data source, a key prefix for future read operations.

When running multiple applications, such as an ensemble computation, there is a risk that the same name is used for a tensor, dataset, script, or model by more than one executing entity. In order to prevent this sort of collision, SmartRedis affords the ability to add a prefix to names, thereby associating them with the name of the specific entity that the prefix corresponds to. For writes to the database when prefixing is activated, the prefix used is taken from the SSKEYOUT environment variable. For reads from the database, the default is to use the first prefix from SSKEYIN. If this is the same as the prefix from SSKEYOUT, the entity will read back the same data it wrote; however, this function allows an entity to read from data written by another entity (i.e. use the other entity’s key.)

Parameters:

c_client – The client object to use for communication
source_id – The prefix for read operations; must have previously been set via the SSKEYIN environment variable
source_id_length – The length of the source_id string, excluding null terminating character

Returns:

Returns SRNoError on success or an error code on failure

SRError use_tensor_ensemble_prefix(void *c_client, bool use_prefix)#

Control whether tensor names are prefixed (e.g. in an ensemble) when forming database keys.

This function can be used to avoid key collisions in an ensemble by prepending the string value from the environment variable SSKEYIN to tensor names. Prefixes will only be used if they were previously set through Keys for entities created before this function is called the environment variables SSKEYOUT and SSKEYIN. will not be retroactively prefixed. By default, the client prefixes tensor keys with the first prefix specified with the SSKEYIN and SSKEYOUT environment variables.

Parameters:

c_client – The client object to use for communication
use_prefix – If true, all future operations on tensors and datasets will use a prefix, if available.

Returns:

Returns SRNoError on success or an error code on failure

SRError use_dataset_ensemble_prefix(void *c_client, bool use_prefix)#

Control whether dataset names are prefixed (e.g. in an ensemble) when forming database keys.

This function can be used to avoid key collisions in an ensemble by prepending the string value from the environment variable SSKEYIN to tensor and dataset names. Prefixes will only be used if they were previously set through Keys for entities created before this function is called the environment variables SSKEYOUT and SSKEYIN. will not be retroactively prefixed. By default, the client prefixes dataset keys with the first prefix specified with the SSKEYIN and SSKEYOUT environment variables.

Parameters:

c_client – The client object to use for communication
use_prefix – If true, all future operations on tensors and datasets will use a prefix, if available.

Returns:

Returns SRNoError on success or an error code on failure

SRError use_model_ensemble_prefix(void *c_client, bool use_prefix)#

Control whether model and script names are prefixed (e.g. in an ensemble) when forming database keys.

This function can be used to avoid key collisions in an ensemble by prepending the string value from the environment variable SSKEYIN to model and script names. Prefixes will only be used if they were previously set through Keys for entities created before this function is called the environment variables SSKEYOUT and SSKEYIN. will not be retroactively prefixed. By default, the client does not prefix model and script keys.

Parameters:

c_client – The client object to use for communication
use_prefix – If set to true, all future operations on models and scripts will use a prefix, if available.

Returns:

Returns SRNoError on success or an error code on failure

SRError use_list_ensemble_prefix(void *c_client, bool use_prefix)#

Control whether aggregation lists are prefixed.

<<<<<<< HEAD

This function can be used to avoid key collisions in an ensemble by prepending the string value from the environment variable SSKEYIN and/or SSKEYOUT to aggregation list names. Prefixes will only be used if they were previously set through the environment variables SSKEYOUT and SSKEYIN. Keys for aggregation lists created before this function is called will not be retroactively prefixed. By default, the client prefixes aggregation list keys with the first prefix specified with the SSKEYIN and SSKEYOUT environment variables. Note that use_dataset_ensemble_prefix() controls prefixing for the entities in the aggregation list, and use_dataset_ensemble_prefix() should be given the same value that was used during the initial setting of the DataSet into the database.

Parameters:

c_client – The client object to use for communication
use_prefix – If set to true, all future operations on aggregation lists will use a prefix, if available.

Returns:

Returns SRNoError on success or an error code on failure

SRError append_to_list(void *c_client, const char *list_name, const size_t list_name_length, const void *dataset)#

Appends a dataset to the aggregation list.

When appending a dataset to an aggregation list, the list will automatically be created if it does not exist (i.e. this is the first entry in the list). Aggregation lists work by referencing the dataset by storing its key, so appending a dataset to an aggregation list does not create a copy of the dataset. Also, for this reason, the dataset must have been previously placed into the database with a separate call to put_dataset().

Parameters:

c_client – The client object to use for communication
list_name – The name of the aggregation list
list_name_length – The size in characters of the list name, including null terminator
dataset – The DataSet to append

Returns:

Returns SRNoError on success or an error code on failure

SRError delete_list(void *c_client, const char *list_name, const size_t list_name_length)#

Delete an aggregation list.

The key used to locate the aggregation list to be deleted may be formed by applying a prefix to the supplied name. See set_data_source() and use_list_ensemble_prefix() for more details.

Parameters:

c_client – The client object to use for communication
list_name – The name of the aggregation list
list_name_length – The size in characters of the list name, including null terminator

Returns:

Returns SRNoError on success or an error code on failure

SRError copy_list(void *c_client, const char *src_name, const size_t src_name_length, const char *dest_name, const size_t dest_name_length)#

Copy an aggregation list.

The source and destination aggregation list keys used to locate and store the aggregation list may be formed by applying prefixes to the supplied src_name and dest_name. See set_data_source() and use_list_ensemble_prefix() for more details.

Parameters:

c_client – The client object to use for communication
src_name – The source list name
src_name_length – The size in characters of the source list name, including null terminator
dest_name – The destination list name
dest_name_length – The size in characters of the destination list name, including null terminator

Returns:

Returns SRNoError on success or an error code on failure

SRError rename_list(void *c_client, const char *src_name, const size_t src_name_length, const char *dest_name, const size_t dest_name_length)#

Rename an aggregation list.

The initial and target aggregation list key used to find and relocate the list may be formed by applying prefixes to the supplied src_name and dest_name. See set_data_source() and use_list_ensemble_prefix() for more details.

Parameters:

c_client – The client object to use for communication
src_name – The initial list name
src_name_length – The size in characters of the initial list name, including null terminator
dest_name – The target list name
dest_name_length – The size in characters of the target list name, including null terminator

Returns:

Returns SRNoError on success or an error code on failure

SRError get_list_length(void *c_client, const char *list_name, const size_t list_name_length, int *result_length)#

Get the number of entries in the list.

Parameters:

c_client – The client object to use for communication
list_name – The list name
list_name_length – The size in characters of the list name, including null terminator
result_length – Receives the length of the list

Returns:

Returns SRNoError on success or an error code on failure

SRError poll_list_length(void *c_client, const char *name, const size_t name_length, int list_length, int poll_frequency_ms, int num_tries, bool *poll_result)#

Poll list length until length is equal to the provided length. If maximum number of attempts is exceeded, false is returned.

The aggregation list key used to check for list length may be formed by applying a prefix to the supplied name. See set_data_source() and use_list_ensemble_prefix() for more details.

Parameters:

c_client – The client object to use for communication
name – The name of the list
name_length – The size in characters of the list name, including null terminator
list_length – The desired length of the list
poll_frequency_ms – The time delay between checks, in milliseconds
num_tries – The total number of times to check for the name
poll_result – Receives the result of the poll: true if the list is found with a length greater than or equal to the provided length, otherwise false

Returns:

Returns SRNoError on success or an error code on failure

SRError poll_list_length_gte(void *c_client, const char *name, const size_t name_length, int list_length, int poll_frequency_ms, int num_tries, bool *poll_result)#

Poll list length until length is greater than or equal to the user-provided length. If maximum number of attempts is exceeded, false is returned.

The aggregation list key used to check for list length may be formed by applying a prefix to the supplied name. See set_data_source() and use_list_ensemble_prefix() for more details.

Parameters:

c_client – The client object to use for communication
name – The name of the list
name_length – The size in characters of the list name, including null terminator
list_length – The desired length of the list
poll_frequency_ms – The time delay between checks, in milliseconds
num_tries – The total number of times to check for the name
poll_result – Receives the result of the poll: true if the list is found with a length greater than or equal to the provided length, otherwise false

Returns:

Returns SRNoError on success or an error code on failure

SRError poll_list_length_lte(void *c_client, const char *name, const size_t name_length, int list_length, int poll_frequency_ms, int num_tries, bool *poll_result)#

Poll list length until length is less than or equal to the user-provided length. If maximum number of attempts is exceeded, false is returned.

The aggregation list key used to check for list length may be formed by applying a prefix to the supplied name. See set_data_source() and use_list_ensemble_prefix() for more details.

Parameters:

c_client – The client object to use for communication
name – The name of the list
name_length – The size in characters of the list name, including null terminator
list_length – The desired length of the list
poll_frequency_ms – The time delay between checks, in milliseconds
num_tries – The total number of times to check for the name
poll_result – Receives the result of the poll: true if the list is found with a length less than or equal to the provided length, otherwise false

Returns:

Returns SRNoError on success or an error code on failure

SRError get_datasets_from_list(void *c_client, const char *list_name, const size_t list_name_length, void ***datasets, size_t *num_datasets)#

Get datasets from an aggregation list.

The aggregation list key used to retrieve datasets may be formed by applying a prefix to the supplied name. See set_data_source() and use_list_ensemble_prefix() for more details. An empty or nonexistant aggregation list returns an empty vector.

Parameters:

c_client – The client object to use for communication
list_name – The name of the aggregation list
list_name_length – The size in characters of the list name, including null terminator
datasets – Receives an array of datasets included in the list
num_datasets – Receives the number of datasets returned

Returns:

Returns SRNoError on success or an error code on failure

SRError get_dataset_list_range(void *c_client, const char *list_name, const size_t list_name_length, const int start_index, const int end_index, void ***datasets, size_t *num_datasets)#

Get a range of datasets (by index) from an aggregation list.

The aggregation list key used to retrieve datasets may be formed by applying a prefix to the supplied name. See set_data_source() and use_list_ensemble_prefix() for more details. An empty or nonexistant aggregation list returns an empty vector. If the provided end_index is beyond the end of the list, that index will be treated as the last index of the list. If start_index and end_index are inconsistent (e.g. end_index is less than start_index), an empty list of datasets will be returned.

Parameters:

c_client – The client object to use for communication
list_name – The name of the aggregation list
list_name_length – The size in characters of the list name, including null terminator
start_index – The starting index of the range (inclusive, starting at zero). Negative values are supported. A negative value indicates offsets starting at the end of the list. For example, -1 is the last element of the list.
end_index – The ending index of the range (inclusive, starting at zero). Negative values are supported. A negative value indicates offsets starting at the end of the list. For example, -1 is the last element of the list.
datasets – Receives an array of datasets included in the list
num_datasets – Receives the number of datasets returned

Returns:

Returns SRNoError on success or an error code on failure

SRError _get_dataset_list_range_allocated(void *c_client, const char *list_name, const size_t list_name_length, const int start_index, const int end_index, void **datasets)#

Get a range of datasets (by index) from an aggregation list and copy them into an already allocated vector of datasets. Note, while this method could be used by C clients, its primary use case is for the Fortran client.

The aggregation list key used to retrieve datasets may be formed by applying a prefix to the supplied name. See set_data_source() and use_list_ensemble_prefix() for more details. An empty or nonexistant aggregation list returns an empty vector. If the provided end_index is beyond the end of the list, that index will be treated as the last index of the list. If start_index and end_index are inconsistent (e.g. end_index is less than start_index), an empty list of datasets will be returned.

Parameters:

c_client – The client object to use for communication
list_name – The name of the aggregation list
list_name_length – The size in characters of the list name, including null terminator
start_index – The starting index of the range (inclusive, starting at zero). Negative values are supported. A negative value indicates offsets starting at the end of the list. For example, -1 is the last element of the list.
end_index – The ending index of the range (inclusive, starting at zero). Negative values are supported. A negative value indicates offsets starting at the end of the list. For example, -1 is the last element of the list.
datasets – Receives an array of datasets included in the list

Returns:

Returns SRNoError on success or an error code on failure

const char *client_to_string(void *c_client)#

Retrieve a string representation of the client.

Parameters:: c_client – The client object to use for communication
Returns:: A string with either the client representation or an error message

Dataset API#

The C DataSet API enables a user to manage a group of tensors and associated metadata within a datastructure called a DataSet object. The DataSet API operates independently of the database and solely maintains the dataset object in-memory. The actual interaction with the Redis database, where a snapshot of the DataSet object is sent, is handled by the Client API. For more information on the DataSet object, click here.

C-wrappers for the C++ DataSet class.

Functions

SRError CDataSet(const char *name, const size_t name_length, void **new_dataset)#

C-DataSet constructor.

Parameters:

name – The name of the dataset
name_length – The length of the dataset name string, excluding null terminating character
new_dataset – Receives the new dataset

Returns:

Returns SRNoError on success or an error code on failure

SRError DeallocateDataSet(void **dataset)#

C-DataSet destructor.

Parameters:: dataset – A pointer to the dataset to release. The dataset is set to NULL on completion
Returns:: Returns SRNoError on success or an error code on failure

SRError add_tensor(void *dataset, const char *name, const size_t name_length, void *data, const size_t *dims, const size_t n_dims, const SRTensorType type, const SRMemoryLayout mem_layout)#

Add a tensor to the DataSet.

Parameters:

dataset – The dataset to use for this operation
name – The name by which this tensor should be referenced in the DataSet
name_length – The length of the dataset name string, excluding null terminating character
data – Tensor data to be stored in the dataset
dims – The number of elements in each dimension of the tensor
n_dims – The number of dimensions for the tensor
type – The data type of the tensor data
mem_layout – Memory layout of the provided tensor data

Returns:

Returns SRNoError on success or an error code on failure

SRError add_meta_scalar(void *dataset, const char *name, const size_t name_length, const void *data, const SRMetaDataType type)#

Append a metadata scalar value to a field in the DataSet. If the field does not exist, it will be created. For string scalars, use add_meta_string.

Parameters:

dataset – The dataset to use for this operation
name – The name for the metadata field
name_length – The length of the dataset name string, excluding null terminating character
data – The scalar data to be appended to the metadata field
type – The data type of the metadata scalar

Returns:

Returns SRNoError on success or an error code on failure

SRError add_meta_string(void *dataset, const char *name, const size_t name_length, const char *data, const size_t data_length)#

Append a metadata string to a field the DataSet. If the field does not exist, it will be created.

Parameters:

dataset – The dataset to use for this operation
name – The name for the metadata field
name_length – The length of the dataset name string, excluding null terminating character
data – The string to add to the field
data_length – The length of the metadata string value, excluding null terminating character

Returns:

Returns SRNoError on success or an error code on failure

SRError get_dataset_tensor(void *dataset, const char *name, const size_t name_length, void **data, size_t **dims, size_t *n_dims, SRTensorType *type, const SRMemoryLayout mem_layout)#

Get the data, dimensions, and type for a tensor in the dataset.

The memory returned in data is valid until the dataset is destroyed. This method is meant to be used when the dimensions and type of the tensor are unknown or the user does not want to manage memory. However, given that the memory associated with the return data is valid until dataset destruction, this method should not be used repeatedly for large tensor data. Instead it is recommended that the user use unpack_dataset_tensor() for large tensor data and to limit memory use by the dataset.

Parameters:

dataset – The dataset to use for this operation
name – The name for the tensor in the dataset
name_length – The length of the dataset name string, excluding null terminating character
data – Receives data for the tensor, allocated by the library
dims – Receives the number of elements in each dimension of the tensor
n_dims – Receives the number of dimensions for the tensor
type – Receives the retrieved tensor type
mem_layout – The requested memory layout to which newly allocated memory should conform

Returns:

Returns SRNoError on success or an error code on failure

SRError unpack_dataset_tensor(void *dataset, const char *name, const size_t name_length, void *data, const size_t *dims, const size_t n_dims, const SRTensorType type, const SRMemoryLayout mem_layout)#

Retrieve tensor data into a caller-provided memory buffer with a specified MemoryLayout. This method is the most memory efficient way to retrieve tensor data from a dataset.

The provided type and dimensions are checked against retrieved values to ensure the provided memory space is sufficient.

Parameters:

dataset – The dataset to use for this operation
name – The name for the tensor in the dataset
name_length – The length of the dataset name string, excluding null terminating character
data – The buffer into which to receive tensor data
dims – The number of elements provided in each dimension of the supplied memory buffer
n_dims – The number of dimensions in the supplied memory buffer
type – The tensor type for the supplied memory buffer
mem_layout – The memory layout for the supplied memory buffer

Returns:

Returns SRNoError on success or an error code on failure

SRError get_meta_scalars(void *dataset, const char *name, const size_t name_length, size_t *length, SRMetaDataType *type, void **scalar_data)#

Retrieve metadata scalar field values from the DataSet. This function will allocate and retain management of the memory for the scalar data. For string scalar metadata, use the get_meta_strings() function.

Parameters:

dataset – The dataset to use for this operation
name – The name for the metadata field in the DataSet
name_length – The length of the name string, excluding null terminating character
length – Receives the number of values returned in scalar_data
type – Receives the data type for the metadata field
scalar_data – Receives an array of the metadata field values

Returns:

Returns SRNoError on success or an error code on failure

SRError get_meta_strings(void *dataset, const char *name, const size_t name_length, char ***data, size_t *n_strings, size_t **lengths)#

Retrieve metadata string field values from the dataset. This function will allocate and retain management of the memory for the scalar string data. object and remain valid until the DataSet object is destroyed.

Parameters:

dataset – The dataset to use for this operation
name – The name for the metadata field in the DataSet
name_length – The length of the name string, excluding null terminating character
data – Receives an array of string values
n_strings – Receives the number of strings returned in data
lengths – Receives an array containing the lengths of the strings returned in data

Returns:

Returns SRNoError on success or an error code on failure

SRError get_tensor_names(void *dataset, char ***data, size_t *n_strings, size_t **lengths)#

Retrieve the names of tensors in the DataSet.

Parameters:

dataset – The dataset to use for this operation
data – Receives an array of tensor names
n_strings – Receives the number of strings returned in data
lengths – Receives an array containing the lengths of the strings returned in data

Returns:

Returns SRNoError on success or an error code on failure

SRError get_tensor_type(void *dataset, const char *name, size_t name_len, SRTensorType *ttype)#

Retrieve the data type of a Tensor in the DataSet.

Parameters:

dataset – The dataset to use for this operation
name – The name of the tensor (null-terminated string)
name_len – The length in bytes of the tensor name
ttype – Receives the type for the specified tensor

Returns:

Returns SRNoError on success or an error code on failure

SRError get_tensor_dims(void *dataset, const char *name, size_t name_len, size_t **dims, size_t *ndims)#

Retrieve the dimensions of a Tensor in the DataSet.

Parameters:

dataset – The dataset to use for this operation
name – The name of the tensor (null-terminated string)
name_len – The length in bytes of the tensor name
dims – A buffer in which to receive the dimensions for the specified tensor.
ndims – The size of the buffer supplied in dims when this function is called; receives the number of dimensions supplied on exit. If the supplied the buffer isn’t large enough to contain all the tensor dimensions, ndims will still receive the needed size.

Returns:

Returns SRNoError on success or an error code on failure. If the buffer supplied in dims is too small, returns SRBadAllocError.

SRError get_metadata_field_names(void *dataset, char ***data, size_t *n_strings, size_t **lengths)#

Retrieve the names of all metadata fields in the DataSet.

Parameters:

dataset – The dataset to use for this operation
data – Receives an array of metadata field names
n_strings – Receives the number of strings returned in data
lengths – Receives an array containing the lengths of the strings returned in data

Returns:

Returns SRNoError on success or an error code on failure

SRError get_metadata_field_type(void *dataset, const char *name, size_t name_len, SRMetaDataType *mdtype)#

Retrieve the data type of a metadata field in the DataSet.

Parameters:

dataset – The dataset to use for this operation
name – The name of the metadata field (null-terminated string)
name_len – The length in bytes of the metadata field name
mdtype – Receives the type for the specified metadata field

Returns:

Returns SRNoError on success or an error code on failure

const char *dataset_to_string(void *dataset)#

Retrieve a string representation of the dataset.

Parameters:: dataset – The dataset to use for this operation
Returns:: A string with either the client representation or an error message

Fortran#

The following page provides a comprehensive overview of the SmartRedis Fortran Client and Dataset APIs. Further explanation and details of each are presented below.

Client API#

The Client API is purpose-built for interaction with the backend database, which extends the capabilities of the Redis in-memory data store. It’s important to note that the SmartRedis Client API is the exclusive means for altering, transmitting, and receiving data within the backend database. More specifically, the Client API is responsible for both creating and modifying data structures, which encompass Models, Scripts, and Tensors. It also handles the transmission and reception of the aforementioned data structures in addition to Dataset data structure. Creating and modifying the DataSet object is confined to local operation by the DataSet API.

The following are overloaded interfaces which support 32/64-bit real and 8, 16, 32, and 64-bit integer tensors

put_tensor
unpack_tensor

Quick access

Types:: client_type
Variables:: append_to_list, client_type, copy_dataset, copy_list, copy_tensor, dataset_exists, delete_dataset, delete_list, delete_model, delete_model_multigpu, delete_script, delete_script_multigpu, delete_tensor, get_dataset, get_datasets_from_list, get_datasets_from_list_range, get_list_length, get_model, get_script, initialize_client_cfgopts, initialize_client_deprecated, initialize_client_simple, isinitialized, key_exists, model_exists, poll_dataset, poll_key, poll_list_length, poll_list_length_gte, poll_list_length_lte, poll_model, poll_tensor, print_client, put_dataset, put_tensor_double, put_tensor_float, put_tensor_i16, put_tensor_i32, put_tensor_i64, put_tensor_i8, rename_dataset, rename_list, rename_tensor, run_model, run_model_multigpu, run_script, run_script_multigpu, set_data_source, set_model, set_model_from_file, set_model_from_file_multigpu, set_model_multigpu, set_script, set_script_from_file, set_script_from_file_multigpu, set_script_multigpu, sr_error_parser, tensor_exists, unpack_tensor_double, unpack_tensor_float, unpack_tensor_i16, unpack_tensor_i32, unpack_tensor_i64, unpack_tensor_i8, use_dataset_ensemble_prefix, use_list_ensemble_prefix, use_model_ensemble_prefix, use_tensor_ensemble_prefix

Needed modules

iso_c_binding (c_loc(), c_f_pointer())
smartredis_dataset (dataset_type())
smartredis_configoptions (configoptions_type())
fortran_c_interop (convert_char_array_to_c(), enum_kind(), c_max_string())

Types

type client_type#
Type fields:
% client_ptr [c_ptr,private/optional/default=c_null_ptr]

% is_initialized [logical,private/optional/default=.false.]

Variables

append_to_list [private]#
client_type [public]
copy_dataset [private]#
copy_list [private]#
copy_tensor [private]#
dataset_exists [private]#
delete_dataset [private]#
delete_list [private]#
delete_model [private]#
delete_model_multigpu [private]#
delete_script [private]#
delete_script_multigpu [private]#
delete_tensor [private]#
destructor [private]#
enum_kind [public]#

< The kind of integer equivalent to a C enum. According to C an Fortran
get_c_pointer [private]#
get_dataset [private]#
get_datasets_from_list [private]#
get_datasets_from_list_range [private]#
get_list_length [private]#
get_model [private]#
get_script [private]#
initialize_client_cfgopts [private]#
initialize_client_deprecated [private]#
initialize_client_simple [private]#
isinitialized [private]#
key_exists [private]#
make_str [private]#
model_exists [private]#
poll_dataset [private]#
poll_key [private]#
poll_list_length [private]#
poll_list_length_gte [private]#
poll_list_length_lte [private]#
poll_model [private]#
poll_tensor [private]#
print_client [private]#
put_dataset [private]#
put_tensor_double [private]#
put_tensor_float [private]#
put_tensor_i16 [private]#
put_tensor_i32 [private]#
put_tensor_i64 [private]#
put_tensor_i8 [private]#
rename_dataset [private]#
rename_list [private]#
rename_tensor [private]#
run_model [private]#
run_model_multigpu [private]#
run_script [private]#
run_script_multigpu [private]#
set_data_source [private]#
set_model [private]#
set_model_from_file [private]#
set_model_from_file_multigpu [private]#
set_model_multigpu [private]#
set_script [private]#
set_script_from_file [private]#
set_script_from_file_multigpu [private]#
set_script_multigpu [private]#
sr_error_parser [private]#
tensor_exists [private]#
to_string [private]#

< Text version of client
unpack_tensor_double [private]#
unpack_tensor_float [private]#
unpack_tensor_i16 [private]#
unpack_tensor_i32 [private]#
unpack_tensor_i64 [private]#
unpack_tensor_i8 [private]#
use_dataset_ensemble_prefix [private]#
use_list_ensemble_prefix [private]#
use_model_ensemble_prefix [private]#
use_tensor_ensemble_prefix [private]#

Dataset API#

The Fortran DataSet API enables a user to manage a group of tensors and associated metadata within a datastructure called a DataSet object. The DataSet API operates independently of the database and solely maintains the dataset object in-memory. The actual interaction with the Redis database, where a snapshot of the DataSet object is sent, is handled by the Client API. For more information on the DataSet object, click here.

The following are overloaded interfaces which support 32/64-bit real and 8, 16, 32, and 64-bit integer tensors

add_tensor
unpack_dataset_tensor

Similarly the following interfaces are overloaded to support 32/64-bit real and integer metadata

add_meta_scalar
get_meta_scalar

Quick access

Needed modules

iso_c_binding (c_loc(), c_f_pointer(), c_associated())
fortran_c_interop (enum_kind())

Types

type dataset_type#
Type fields:
% dataset_ptr [c_ptr]

Variables

add_meta_scalar_double [private]#
add_meta_scalar_float [private]#
add_meta_scalar_i32 [private]#
add_meta_scalar_i64 [private]#
add_meta_string [private]#
add_tensor_double [private]#
add_tensor_float [private]#
add_tensor_i16 [private]#
add_tensor_i32 [private]#
add_tensor_i64 [private]#
add_tensor_i8 [private]#
dataset_type [public]
destructor [private]#
enum_kind [public]#

< The kind of integer equivalent to a C enum. According to C an Fortran
final_destructor [private]#
get_c_pointer [private]#
get_meta_scalars_double [private]#
get_meta_scalars_float [private]#
get_meta_scalars_i32 [private]#
get_meta_scalars_i64 [private]#
get_metadata_field_type [private]#
get_tensor_dims [private]#
get_tensor_type [private]#
initialize_dataset [private]#
make_str [private]#
print_dataset [private]#
to_string [private]#

< Text version of dataset
unknown_interface [private]#
unpack_dataset_tensor_double [private]#
unpack_dataset_tensor_float [private]#
unpack_dataset_tensor_i16 [private]#
unpack_dataset_tensor_i32 [private]#
unpack_dataset_tensor_i64 [private]#
unpack_dataset_tensor_i8 [private]#

API Notes#

Fortran autodoc-ing in Sphinx is relatively primitive, however the code has been doxygenized and is built along with the rest of the documentation. They can be found in smartredis/doc/fortran_client/html.

Importing SmartRedis#

The public facing parts of SmartRedis-Fortran are contained in two modules smartredis_client and smartredis_dataset. These can be imported into Fortran code in the usual way:

program example
  use smartredis_dataset, only : dataset_type
  use smartredis_client,  only : client_type
end program example

Note

dataset_type and client_type are the only public elements of these modules

Using the Fortran Client#

The SmartRedis Fortran interface is centered around two Fortran modules: smartredis_client and smartredis_dataset. The only public element of these modules are, respectively, client_type and dataset_type. These derived types take advantage of Fortran object-oriented features by having procedure-bound methods that implement most of the SmartRedis functionality. (see Unsupported SmartRedis Features). Other than these derived types, all inputs and outputs from functions and subroutines are Fortran primitives (e.g. real, integer, character).

32-bit and 64-bit real and 8, 16, 32, and 64-bit signed integer arrays (tensors) are supported. All procedures are overloaded to avoid needing to specify the type-specific subroutine.

To communicate with the Redis client, SmartRedis-Fortran relies on Fortran/C/C++ interoperability to wrap the methods of the C++ client. All transformations from Fortran constructs to C constructs are handled within the SmartRedis client itself (e.g enforcing Fortran/C types and column-major to row-major arrays). No conversions need to be done within the application.

The example below shows the code required to send and receive data with the Fortran client.

! BSD 2-Clause License
!
! Copyright (c) 2021-2024, Hewlett Packard Enterprise
! All rights reserved.
!
! Redistribution and use in source and binary forms, with or without
! modification, are permitted provided that the following conditions are met:
!
! 1. Redistributions of source code must retain the above copyright notice, this
!    list of conditions and the following disclaimer.
!
! 2. Redistributions in binary form must reproduce the above copyright notice,
!    this list of conditions and the following disclaimer in the documentation
!    and/or other materials provided with the distribution.
!
! THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
! AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
! IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
! DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
! FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
! DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
! SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
! CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
! OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
! OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

program main

  use iso_c_binding
  use smartredis_client, only : client_type

  implicit none

#include "enum_fortran.inc"

  integer, parameter :: dim1 = 10
  integer, parameter :: dim2 = 20
  integer, parameter :: dim3 = 30

  real(kind=8),    dimension(dim1, dim2, dim3) :: recv_array_real_64
  real(kind=c_double),    dimension(dim1, dim2, dim3) :: send_array_real_64

  integer :: i, j, k, result
  type(client_type) :: client

  call random_number(send_array_real_64)

  ! Initialize a client
  result = client%initialize("smartredis_put_get_3D")
  if (result .ne. SRNoError) error stop 'client%initialize failed'

  ! Send a tensor to the database via the client and verify that we can retrieve it
  result = client%put_tensor("send_array", send_array_real_64, shape(send_array_real_64))
  if (result .ne. SRNoError) error stop 'client%put_tensor failed'
  result = client%unpack_tensor("send_array", recv_array_real_64, shape(recv_array_real_64))
  if (result .ne. SRNoError) error stop 'client%unpack_tensor failed'

  ! Done
  call exit()

end program main

Other examples are shown in the Fortran client examples sections.

Compiler Requirements#

Fortran compilers need to support the following features

Object-oriented programming support (Fortran 2003)
Fortran-C interoperability, iso_c_binding (Fortran 2003)

These language features are supported by Intel 19, GNU 9, and Cray 8.6 and later versions. Nvidia compilers have been shown to work, but should be considered a fragile feature for now

Unsupported SmartRedis features#

Due to limitations of C/Fortran interoperability, some of the features in the Python, C, and C++ clients have not been implemented. This includes

Retrieving metadata strings (Dataset: get_meta_strings)
Returning a dataset tensor or tensor from the database as an opaque type (Dataset: get_dataset_tensor, Client: get_tensor)
Getting tensors from the database as an opaque type (Client:get_tensor) (note unpacking tensors into allocated memory is supported, see the Fortran client examples section.

Source code organization#

SmartRedis-Fortran source code is contained within the following files

client.F90: Contains the client_type and all associated methods
dataset.F90 Contains the dataset_type and all associated methods
fortran_c_interop.F90: Routines to aid in Fortran/C interoperability

The client.F90 and dataset.F90 files are further broken down into a number of ‘included’ files to prevent duplicated code and organize the variety of methods included within each type. The naming conventions are prefixed by general functionality and suffixed by the type of code contained within.

<functionality>_interfaces.inc: Define the C-bound interfaces to the SmartRedis-C methods
<functionality>_methods_common.inc: Represents the source code that is exactly the same for all methods which share the same functionality, but differ only by the type of variable

For example, client/put_tensor_interfaces.inc define the Fortran-C interfaces to put a tensor into the database. client/put_tensor_methods_common.inc form the main body of the source code that handles the conversion and calling of the Fortran-C interfaces.

SmartRedis API

Contents

SmartRedis API#

Python#

Client API#

Client Class Method Overview#

Client Class Method Detailed View#

DataSet API#

Dataset Class Method Overview#

Dataset Class Method Detailed View#

Logging API#

Logging Functionality Overview#

LogContext Class Method Detailed View#

SRObject Class Method Detailed View#

Standalone Logging Method Detailed View#

C++#

Client API#

Dataset API#

C#

Client API#

Dataset API#

Fortran#

Client API#

Dataset API#

API Notes#

Importing SmartRedis#

Using the Fortran Client#

Compiler Requirements#

Unsupported SmartRedis features#

Source code organization#