SmartRedis API¶

Python¶

Client API¶

`Client.__init__`([address, cluster])	Initialize a RedisAI client
`Client.put_tensor`(key, data)	Put a tensor to a Redis database
`Client.get_tensor`(key)	Get a tensor from the database
`Client.delete_tensor`(key)	Delete a tensor within the database
`Client.copy_tensor`(key, dest_key)	Copy a tensor at one key to another key
`Client.rename_tensor`(key, new_key)	Rename a tensor in the database
`Client.put_dataset`(dataset)	Put a Dataset instance into the database
`Client.get_dataset`(key)	Get a dataset from the database
`Client.delete_dataset`(key)	Delete a dataset within the database
`Client.copy_dataset`(key, dest_key)	Copy a dataset from one key to another
`Client.rename_dataset`(key, new_key)	Rename a dataset in the database
`Client.set_function`(key, function[, device])	Set a callable function into the database
`Client.set_script`(key, script[, device])	Store a TorchScript at key in the database
`Client.set_script_from_file`(key, file[, device])	Same as Client.set_script but from file
`Client.get_script`(key)	Get a Torchscript stored in the database
`Client.run_script`(key, fn_name, inputs, outputs)	Execute TorchScript stored inside the database remotely
`Client.set_model`(key, model, backend[, …])	Put a TF, TF-lite, PT, or ONNX model in the database
`Client.set_model_from_file`(key, model_file, …)	Put a TF, TF-lite, PT, or ONNX model from file in the database
`Client.get_model`(key)	Get a stored model
`Client.run_model`(key[, inputs, outputs])	Execute a stored model
`Client.model_exists`(name)	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.poll_tensor`(name, poll_frequency_ms, …)	Check if a tensor or dataset exists in the database
`Client.poll_model`(name, poll_frequency_ms, …)	Check if a model or script exists in the database
`Client.set_data_source`(source_id)	Set the data source (i.e.
`Client.use_model_ensemble_prefix`(use_prefix)	Set whether model and script keys should be prefixed
`Client.use_tensor_ensemble_prefix`(use_prefix)	Set whether tensor and dataset keys should be prefixed

class Client(address=None, cluster=False)[source]¶

Bases: smartredis.smartredisPy.PyClient

Initialize a RedisAI client

For clusters, the address can be a single tcp/ip address and port of a database node. The rest of the cluster will be discovered by the client itself. (e.g. address=”127.0.0.1:6379”)

If an address is not set, the client will look for the environment variable SSDB (e.g. SSDB=”127.0.0.1:6379;”)

Parameters

address – Address of the database
cluster (bool, optional) – True if connecting to a redis cluster, defaults to False

Raises

RedisConnectionError – if connection initialization fails

copy_dataset(key, dest_key)[source]¶

Copy a dataset from one key to another

Parameters

key (str) – name of dataset to be copied
dest_key (str) – new name of dataset

Raises

RedisReplyError – if copy operation fails

copy_tensor(key, dest_key)[source]¶

Copy a tensor at one key to another key

Parameters

key (str) – key of tensor to be copied
dest_key (str) – key to store new copy at

Raises

RedisReplyError – if copy operation fails

delete_dataset(key)[source]¶

Delete a dataset within the database

Parameters: key (str) – name of the dataset
Raises: RedisReplyError – if deletion fails

delete_tensor(key)[source]¶

Delete a tensor within the database

Parameters: key (str) – key tensor is stored at
Raises: RedisReplyError – if deletion fails

get_dataset(key)[source]¶

Get a dataset from the database

Parameters: key (str) – key the dataset is stored under
Raises: RedisConnectionError – if connection fails
Returns: Dataset instance
Return type: Dataset

get_db_cluster_info(addresses)[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 – 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 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 adddress to avoid inconsistencies in addresses retreived with the CLUSTER SLOTS command. Inconsistencies in node addresses across CLUSTER SLOTS comands will lead to RedisReplyError being thrown.

get_db_node_info(addresses)[source]¶

Returns information about given database nodes

Parameters: addresses – 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 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 adddress to avoid inconsistencies in addresses retreived with the CLUSTER SLOTS command. Inconsistencies in node addresses across CLUSTER SLOTS comands will lead to RedisReplyError being thrown.

get_model(key)[source]¶

Get a stored model

Parameters: key (str) – key of stored model
Raises: RedisReplyError – if get fails or model doesnt exist
Returns: model
Return type: bytes

get_script(key)[source]¶

Get a Torchscript stored in the database

Parameters: key (str) – key at which script is stored
Raises: RedisReplyError – if script doesn’t exist
Returns: TorchScript stored at key
Return type: str

get_tensor(key)[source]¶

Get a tensor from the database

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

key_exists(key)[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)[source]¶

Check if a model or script exists in the database

The key associated to the entity will be computed internally based on the current prefix behavior.

Parameters: key (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_key(key, poll_frequency_ms, num_tries)[source]¶

Check if the key exists in the database

The check is performed repeatedly at a specified frequency for a specified number of times.

Parameters

key (int) – The key that will be checked in the database
poll_frequency_ms (int) – The frequency of checks for the key in milliseconds
num_tries (int) – The total number of times to check for the specified number of keys. If the value is set to -1, the key will be polled indefinitely.

Returns

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

Return type

bool

Raises

RedisReplyError – if key poll fails

poll_model(name, poll_frequency_ms, num_tries)[source]¶

Check if a model or script exists in the database

The check will be performed at a specified frequency for a specified number of times. The key associated to the entity will be computed internally based on the current prefix behavior.

Parameters

key (int) – The key that will be checked in the database
poll_frequency_ms (int) – The frequency of checks for the key in milliseconds
num_tries (int) – The total number of times to check for the specified number of keys. If the value is set to -1, the key will be polled indefinitely.

Returns

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

Return type

bool

Raises

RedisReplyError – if poll_model fails

poll_tensor(name, poll_frequency_ms, num_tries)[source]¶

Check if a tensor or dataset exists in the database

The check will be performed at a specified frequency for a specified number of times. The key associated to the entity will be computed internally based on the current prefix behavior.

Parameters

key (int) – The key that will be checked in the database
poll_frequency_ms (int) – The frequency of checks for the key in milliseconds
num_tries (int) – The total number of times to check for the specified number of keys. If the value is set to -1, the key will be polled indefinitely.

Returns

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

Return type

bool

Raises

RedisReplyError – if poll_tensor fails

put_dataset(dataset)[source]¶

Put a Dataset instance into the database

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 connection fails

put_tensor(key, data)[source]¶

Put a tensor to a Redis database

Parameters

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

Raises

RedisReplyError – if put fails

rename_dataset(key, new_key)[source]¶

Rename a dataset in the database

Parameters

key (str) – name of the dataset to be renamed
new_key (str) – new name for the dataset

Raises

RedisReplyError – if rename operation fails

rename_tensor(key, new_key)[source]¶

Rename a tensor in the database

Parameters

key (str) – key of tensor to be renamed
new_key (str) – new name for the tensor

Raises

RedisReplyError – if rename operation fails

run_model(key, inputs=None, outputs=None)[source]¶

Execute a stored model

Parameters

key (str) – key for stored model
inputs (list[str], optional) – keys of stored inputs to provide model, defaults to None
outputs (list[str], optional) – keys to store outputs under, defaults to None

Raises

RedisReplyError – if model execution fails

run_script(key, fn_name, inputs, outputs)[source]¶

Execute TorchScript stored inside the database remotely

Parameters

key (str) – key script is stored under
fn_name (str) – name of the function within the script to execute
inputs (list[str]) – list of input tensors stored in database
outputs (list[str]) – list of output tensor names to store results under

Raises

RedisReplyError – if script execution fails

set_data_source(source_id)[source]¶

Set the data source (i.e. key prefix for get functions)

Parameters: source_id (str) – The prefix for retrieval commands
Raises: RedisReplyError – if set data

set_function(key, function, device='CPU')[source]¶

Set a callable function into the database

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 devices are present, a number can be passed for specification e.g. “GPU:1”.

Parameters

key (str) – key 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

set_model(key, model, backend, device='CPU', batch_size=0, min_batch_size=0, tag='', inputs=None, outputs=None)[source]¶

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

Parameters

key (str) – key 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
tag (str, optional) – additional tag for model information, defaults to “”
inputs (list[str], optional) – model inputs (TF only), defaults to None
outputs (list[str], optional) – model outupts (TF only), defaults to None

Raises

RedisReplyError – if model fails to set

set_model_from_file(key, model_file, backend, device='CPU', batch_size=0, min_batch_size=0, tag='', inputs=None, outputs=None)[source]¶

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

Parameters

key (str) – key 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
tag (str, optional) – additional tag for model information, defaults to “”
inputs (list[str], optional) – model inputs (TF only), defaults to None
outputs (list[str], optional) – model outupts (TF only), defaults to None

Raises

RedisReplyError – if model fails to set

set_script(key, script, device='CPU')[source]¶

Store a TorchScript at key in the database

Device selection is either “GPU” or “CPU”. If many devices are present, a number can be passed for specification e.g. “GPU:1”.

Parameters

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

Raises

RedisReplyError – if script fails to set

set_script_from_file(key, file, device='CPU')[source]¶

Same as Client.set_script but from file

Parameters

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

Raises

RedisReplyError – if script fails to set

tensor_exists(name)[source]¶

Check if a tensor or dataset exists in the database

The key associated to the entity will be computed internally based on the current prefix behavior.

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

use_model_ensemble_prefix(use_prefix)[source]¶

Set whether model and script keys should be prefixed

This function can be used to avoid key collisions in an ensemble. Prefixes will only be used if they were previously set through environment variables SSKEYIN and SSKEYOUT. 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.

use_tensor_ensemble_prefix(use_prefix)[source]¶

Set whether tensor and dataset keys should be prefixed

This function can be used to avoid key collisions in an ensemble. Prefixes will only be used if they were previously set through environment variables SSKEYIN and SSKEYOUT. By default, the client prefixes tensor and dataset keys when a prefix is available.

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

DataSet API¶

`Dataset.__init__`(name)	Initialize a Dataset object
`Dataset.add_tensor`(name, data)	Add a named tensor to this dataset
`Dataset.get_tensor`(name)	Get a tensor from the Dataset
`Dataset.add_meta_scalar`(name, data)	Add metadata scalar field (non-string) with value to the DataSet
`Dataset.get_meta_scalars`(name)	Get the metadata scalar field values from the DataSet
`Dataset.add_meta_string`(name, data)	Add metadata string field with value to the DataSet
`Dataset.get_meta_strings`(name)	Get the metadata scalar field values from the DataSet

class Dataset(name)[source]¶

Bases: smartredis.smartredisPy.PyDataset

Initialize a Dataset object

Parameters: name (str) – name of dataset

add_meta_scalar(name, data)[source]¶

Add metadata scalar field (non-string) with value to the DataSet

If the field does not exist, it will be created. If the field exists, the value will be appended to existing field.

Parameters

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

add_meta_string(name, data)[source]¶

Add metadata string field with value to the DataSet

If the field does not exist, it will be created If the field exists the value will be appended to existing field.

Parameters

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

add_tensor(name, data)[source]¶

Add a named tensor to this dataset

Parameters

name (str) – tensor name
data (np.array) – tensor data

get_meta_scalars(name)[source]¶

Get the metadata scalar field values from the DataSet

Parameters: name (str) – The name used to reference the metadata field in the DataSet

get_meta_strings(name)[source]¶

Get the metadata scalar field values from the DataSet

Parameters: name (str) – The name used to reference the metadata field in the DataSet

get_tensor(name)[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.array

C++¶

Client API¶

class SmartRedis::Client¶

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

Public Functions

Client(bool cluster)¶

Client constructor.

Parameters

cluster: Flag to indicate if a database cluster is being used

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.

~Client()¶: Client destructor.

void put_dataset(DataSet &dataset)¶

Send a DataSet object to the database.

Parameters

dataset: The DataSet object to send to the database

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

Get a DataSet object from the database.

Return

DataSet object retrieved from the database

Parameters

name: The name of the dataset to retrieve

void rename_dataset(const std::string &name, const std::string &new_name)¶

Move a DataSet to a new key. A tensors and metdata in the DataSet will be moved.

Parameters

name: The original key associated with the DataSet in the database
new_name: The new key to assign to the DataSet object

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

Copy a DataSet to a new key in the database. All tensors and metdata in the DataSet will be copied.

Parameters

src_name: The key associated with the DataSet that is to be copied
dest_name: The key in the database that will store the copied database.

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

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

Parameters

name: The name of the DataSet that should be deleted.

void put_tensor(const std::string &key, void *data, const std::vector<size_t> &dims, const TensorType type, const MemoryLayout mem_layout)¶

Put a tensor into the database.

Parameters

key: The key to associate with this tensor in the database
data: A c-ptr to the beginning of the tensor data
dims: The dimensions of the tensor
type: The data type of the tensor
mem_layout: The memory layout of the provided tensor data

void get_tensor(const std::string &key, void *&data, std::vector<size_t> &dims, TensorType &type, const MemoryLayout mem_layout)¶

Get 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 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

key: The name used to reference the tensor
data: A c-ptr reference that will be pointed to newly allocated memory
dims: A reference to a dimensions vector that will be filled with the retrieved tensor dimensions
type: A reference to a TensorType enum that will be set to the value of the retrieved tensor type
mem_layout: The MemoryLayout that the newly allocated memory should conform to

void get_tensor(const std::string &key, void *&data, size_t *&dims, size_t &n_dims, TensorType &type, const MemoryLayout mem_layout)¶

Get 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 and dimensions. This is a c-style interface for the tensor dimensions. Another function exists for std::vector dimensions.

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

key: The name used to reference the tensor
data: A c-ptr reference that will be pointed to newly allocated memory
dims: A reference to a c-ptr that will be pointed newly allocated memory that will be filled with the tensor dimensions
n_dims: A reference to type size_t variable that will be set to the number of tensor dimensions
type: A reference to a TensorType enum that will be set to the value of the retrieved tensor type
mem_layout: The MemoryLayout that the newly allocated memory should conform to

void unpack_tensor(const std::string &key, void *data, const std::vector<size_t> &dims, const TensorType type, const MemoryLayout mem_layout)¶

Get tensor data and fill an already allocated array memory space that has the specified MemoryLayout. The provided type and dimensions are checked against retrieved values to ensure the provided memory space is sufficient. This method is the most memory efficient way to retrieve tensor data.

Parameters

key: The name used to reference the tensor
data: A c-ptr to the memory space to be filled with tensor data
dims: The dimensions of the memory space
type: The TensorType matching the data type of the memory space
mem_layout: The MemoryLayout of the provided memory space.

void rename_tensor(const std::string &key, const std::string &new_key)¶

Move a tensor from one key to another key.

Parameters

key: The original tensor key
new_key: The new tensor key

void delete_tensor(const std::string &key)¶

Delete a tensor from the database.

Parameters

key: The key of tensor to delete

void copy_tensor(const std::string &src_key, const std::string &dest_key)¶

Copy the tensor from the source key to the destination key.

Parameters

src_key: The key of the tensor to copy
dest_key: The destination key of the tensor

void set_model_from_file(const std::string &key, const std::string &model_file, const std::string &backend, const std::string &device, int batch_size = 0, int min_batch_size = 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.

Parameters

key: The key to associate with the 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 (e.g. CPU or GPU)
batch_size: The batch size for model execution
min_batch_size: The minimum batch size for model execution
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)

void set_model(const std::string &key, const std::string_view &model, const std::string &backend, const std::string &device, int batch_size = 0, int min_batch_size = 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.

Parameters

key: The key to associate with the model
model: The model as a continuous buffer string_view
backend: The name of the backend (TF, TFLITE, TORCH, ONNX)
device: The name of the device for execution (e.g. CPU or GPU)
batch_size: The batch size for model execution
min_batch_size: The minimum batch size for model execution
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)

std::string_view get_model(const std::string &key)¶

Retrieve the model from the database.

Return

A std::string_view containing the model. The memory associated with the model is managed by the Client and is valid until the destruction of the Client.

Parameters

key: The key associated with the model

void set_script_from_file(const std::string &key, const std::string &device, const std::string &script_file)¶

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

Parameters

key: The key to associate with the script
device: The name of the device for execution (e.g. CPU or GPU)
script_file: The source file for the script

void set_script(const std::string &key, const std::string &device, const std::string_view &script)¶

Set a script from std::string_view buffer in the database for future execution.

Parameters

key: The key to associate with the script
device: The name of the device for execution (e.g. CPU or GPU)
script: The script source in a std::string_view

std::string_view get_script(const std::string &key)¶

Retrieve the script from the database.

Return

A std::string_view containing the script. The memory associated with the script is managed by the Client and is valid until the destruction of the Client.

Parameters

key: The key associated with the script

void run_model(const std::string &key, std::vector<std::string> inputs, std::vector<std::string> outputs)¶

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

Parameters

key: The key associated with the model
inputs: The keys of inputs tensors to use in the model
outputs: The keys of output tensors that will be used to save model results

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

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

Parameters

key: The key associated with the script
function: The name of the function in the script to run
inputs: The keys of inputs tensors to use in the script
outputs: The keys of output tensors that will be used to save script results

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

Check if the key exists in the database.

Return

Returns true if the key exists in the database

Parameters

key: The key that will be checked in the database. No prefix will be added to key.

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

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

Return

Returns true if the key exists in the database

Parameters

name: The name that will be checked in the database depending on the current prefixing behavior, the name could be automatically prefixed to form the corresponding key.

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

Check if the tensor (or the dataset) exists in the database.

Return

Returns true if the key exists in the database

Parameters

name: The name that will be checked in the database depending on the current prefixing behavior, the name could be automatically prefixed to form the corresponding key.

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

Check if the key exists in the database at a specified frequency for a specified number of times.

Return

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

Parameters

key: The key that will be checked in the database
poll_frequency_ms: The frequency of checks for the key in milliseconds
num_tries: The total number of times to check for the specified number of keys. If the value is set to -1, the key will be polled indefinitely.

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

Check if the tensor (or dataset) exists in the database at a specified frequency for a specified number of times.

Return

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

Parameters

name: The key that will be checked in the database Depending on the current prefixing behavior, the name could be automatically prefixed to form the corresponding key.
poll_frequency_ms: The frequency of checks for the key in milliseconds
num_tries: The total number of times to check for the specified number of keys. If the value is set to -1, the key will be polled indefinitely.

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

Check if the model (or script) exists in the database at a specified frequency for a specified number of times.

Return

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

Parameters

name: The name that will be checked in the database depending on the current prefixing behavior, the name could be automatically prefixed to form the corresponding key.
poll_frequency_ms: The frequency of checks for the key in milliseconds
num_tries: The total number of times to check for the specified number of keys. If the value is set to -1, the key will be polled indefinitely.

void set_data_source(std::string source_id)¶

Set the data source (i.e. key prefix for get functions)

Parameters

source_id: The prefix for retrieval commands

void use_tensor_ensemble_prefix(bool use_prefix)¶

Set whether names of tensor and dataset entities should be prefixed (e.g. in an ensemble) to form database keys. 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 affected. 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 tensors and datasets will use a prefix, if available.

void use_model_ensemble_prefix(bool use_prefix)¶

Set whether names of model and script entities should be prefixed (e.g. in an ensemble) to form database keys. 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 affected. By default, the client does not prefix model and script keys.

Parameters

use_prefix: If set to true, all future operations on models and scripts will use a prefix, if available.

parsed_reply_nested_map get_db_node_info(std::string address)¶

\brief Returns information about the given database node
\param address The address of the database node (host:port)
\returns parsed_reply_nested_map containing the database node information

Exceptions

std::runtime_error: if the address is not addressable by this 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 adddress to avoid inconsistencies in addresses retreived with the CLUSTER SLOTS command. Inconsistencies in node addresses across CLUSTER SLOTS comands will lead to std::runtime_error being thrown.

parsed_reply_map get_db_cluster_info(std::string address)¶

\brief Returns the CLUSTER INFO command reply addressed to a single
       cluster node.
\param address The address of the database node (host:port)
\returns parsed_reply_map containing the database cluster information.
         If this command is executed on a non-cluster database, an
         empty parsed_reply_map is returned.

Exceptions

std::runtime_error: if the address is not addressable by this 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 adddress to avoid inconsistencies in addresses retreived with the CLUSTER SLOTS command. Inconsistencies in node addresses across CLUSTER SLOTS comands will lead to std::runtime_error being thrown.

Dataset API¶

class SmartRedis::DataSet¶

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

Tensors in the DataSet can be used in Client commands like 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

void add_tensor(const std::string &name, void *data, const std::vector<size_t> &dims, const TensorType type, const MemoryLayout mem_layout)¶

Add a tensor to the DataSet.

Parameters

name: The name used to reference the tensor within the DataSet
data: A c-ptr to the tensor data memory location
dims: The dimensions of the tensor
type: The data type of the tensor data
mem_layout: The MemoryLayout enum describing the layout of the provided tensor data

void add_meta_scalar(const std::string &name, const void *data, const MetaDataType type)¶

Add metadata scalar field (non-string) with value to the DataSet. If the field does not exist, it will be created. If the field exists, the value will be appended to existing field.

Parameters

name: The name used to reference the metadata field
data: A c-ptr to the metadata field data
type: The data type of the metadata

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

Add metadata string field with value to the DataSet. If the field does not exist, it will be created. If the field exists the value will be appended to existing field.

Parameters

name: The name used to reference the metadata field
data: The string to add to the field

void get_tensor(const std::string &name, void *&data, std::vector<size_t> &dims, TensorType &type, const MemoryLayout mem_layout)¶

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: A c-ptr reference that will be pointed to newly allocated memory
dims: A reference to a dimensions vector that will be filled with the retrieved tensor dimensions
type: A reference to a TensorType enum that will be set to the value of the retrieved tensor type
mem_layout: The MemoryLayout that the newly allocated memory should conform to

void get_tensor(const std::string &name, void *&data, size_t *&dims, size_t &n_dims, TensorType &type, const MemoryLayout mem_layout)¶

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. Another function exists for std::vector 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: A c-ptr reference that will be pointed to newly allocated memory
dims: A reference to a dimensions vector that will be filled with the retrieved tensor dimensions
type: A reference to a TensorType enum that will be set to the value of the retrieved tensor type
mem_layout: The MemoryLayout that the newly allocated memory should conform to

void unpack_tensor(const std::string &name, void *data, const std::vector<size_t> &dims, const TensorType type, const MemoryLayout mem_layout)¶

Get tensor data and fill an already allocated array memory space that has the specified MemoryLayout. The provided type and dimensions are checked against retrieved values to ensure the provided memory space is sufficient. 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: A c-ptr to the memory space to be filled with tensor data
dims: The dimensions of the memory space
type: The TensorType matching the data type of the memory space
mem_layout: The MemoryLayout of the provided memory space.

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

Get the metadata scalar field values from the DataSet. The data pointer reference will be pointed to newly allocated memory that will contain all values in the metadata field. The length variable will be set to the number of entries in the allocated memory space to allow for iteration over the values. The TensorType enum will be set to the type of the MetaData field.

Parameters

name: The name used to reference the metadata field in the DataSet
data: A c-ptr to the memory space to be filled with the metadata field
length: The number of values in the metadata field
type: The MetadataType enum describing the data type of the metadata field

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

Get the strings in a metadata string field. 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

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

Get the metadata string field values from the DataSet. The data pointer reference will be pointed to newly allocated memory that will contain all values in the metadata field. The n_strings input variable reference will be set to the number of strings in the field. The lengths c-ptr variable will be pointed to a new memory space that contains the length of each field string. The memory for the data and lengths pointers will be managed by the DataSet object and remain valid until the DataSet object is destroyed.

Parameters

name: The name used to reference the metadata field in the DataSet
data: A c-ptr that will be pointed to a memory space filled with the metadata field strings
n_strings: A reference to a size_t variable that will be set to the number of strings in the field
lengths: A c-ptr that will be pointed to a memory space that contains the length of each field string

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

This function checks if the DataSet has a field.

Return

Boolean indicating if the DataSet has the field.

Parameters

field_name: The name of the field to check

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

This function clears all entries in a DataSet field.

Parameters

field_name: The name of the field to clear

std::vector<std::string> get_tensor_names()¶

Retrieve the names of the tensors in the DataSet.

Return: The name of the tensors in the DataSet

Public Members

std::string name¶: The name of the DataSet.

Friends

friend class Client

friend class PyDataset

C¶

Client API¶

C-wrappers for the C++ Client class.

Functions

void *SmartRedisCClient(bool cluster)¶

C-client constructor.

Return

Returns NULL on failure

Parameters

cluster: Flag to indicate if a database cluster is being used

void DeleteCClient(void *c_client)¶

C-client destructor.

Parameters

c_client: A pointer to the c-client to destroy

void put_dataset(void *c_client, void *dataset)¶

Put a DataSet object into the database.

Parameters

c_client: A pointer to c client to use for communication
dataset: The DataSet object to send

void *get_dataset(void *c_client, const char *name, const size_t name_length)¶

Get a DataSet object from the database.

Return

Returns NULL on bad parameters

Parameters

c_client: A pointer to c client to use for communication
name: The name of the dataset object to fetch
name_length: The length of the name c-string, excluding null terminating character

void rename_dataset(void *c_client, const char *name, const size_t name_length, const char *new_name, const size_t new_name_length)¶

Move a DataSet to a new key.

Parameters

c_client: A pointer to c client to use for communication
name: The name of the dataset object
name_length: The length of the name c-string, excluding null terminating character
new_name: The new name of the dataset object
new_name_length: The length of the new name c-string, excluding null terminating character

void 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 key.

Parameters

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

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

Delete a DataSet.

Parameters

c_client: A pointer to c client to use for communication
name: The name of the dataset object
name_length: The length of the name c-string, excluding null terminating character

void put_tensor(void *c_client, const char *key, const size_t key_length, void *data, const size_t *dims, const size_t n_dims, CTensorType type, CMemoryLayout mem_layout)¶

Put a tensor into the database.

Parameters

c_client: A pointer to c client to use for communication
key: The key to use to place the tensor
key_length: The length of the key c-string, excluding null terminating character
data: A c ptr to the beginning of the data
dims: Length along 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

void get_tensor(void *c_client, const char *key, const size_t key_length, void **data, size_t **dims, size_t *n_dims, CTensorType *type, CMemoryLayout mem_layout)¶

Get a tensor from the database. This method will allocate memory for the tensor data and dimensions. This memory will be valid until the c-client is destroyed. 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.

Parameters

c_client: A pointer to c client to use for communication
key: The key to use to fetch the tensor
key_length: The length of the key c-string, excluding null terminating character
data: A pointer to a c-ptr that will be set to the newly allocated memory space.
dims: A pointer to a size_t pointer that will be pointed to newly allocated memory that holds the dimensions of the tensor.
n_dims: The number of dimensions of the tensor
type: The data type of the tensor that is set by the c-client
mem_layout: The memory layout requested for the allocated memory space

void unpack_tensor(void *c_client, const char *key, const size_t key_length, void *result, const size_t *dims, const size_t n_dims, CTensorType type, CMemoryLayout mem_layout)¶

Get a tensor from the database and fill the provided memory space (result) that is layed out as defined by dims.

Parameters

c_client: A pointer to c client to use for communication
key: The key to use to fetch the tensor
key_length: The length of the key c-string, excluding null terminating character
result: A c ptr to the beginning of the memory space to fill.
dims: The dimensions of the provided memory space.
n_dims: The number of dimensions of the tensor
type: The data type of the provided memory space.
mem_layout: The memory layout of the provided memory space.

void rename_tensor(void *c_client, const char *key, const size_t key_length, const char *new_key, const size_t new_key_length)¶

Move a tensor to a new key.

Parameters

c_client: A pointer to c client to use for communication
key: The key to use to fetch the tensor
key_length: The length of the key c-string, excluding null terminating character
new_key: The new tensor key
new_key_length: The length of the new_key c-string, excluding null terminating characters

void delete_tensor(void *c_client, const char *key, const size_t key_length)¶

Delete a tensor.

Parameters

c_client: A pointer to c client to use for communication
key: The key of the tensor to delete
key_length: The length of the key c-string, excluding null terminating character

void 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)¶

This method will copy a tensor to the destination key.

Parameters

c_client: A pointer to c client to use for communication
src_name: The source name of the tensor
src_name_length: The length of the src_name c-string, excluding null terminating character
dest_name: The destination name of the tensor
dest_name_length: The length of the dest_name c-string, excluding null terminating character

void set_model_from_file(void *c_client, const char *key, const size_t key_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 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.

Parameters

c_client: A pointer to c client to use for communication
key: The key to associate with the model
key_length: The length of the key c-string, excluding null terminating character
model_file: The source file for the model
model_file_length: The length of the model_file c-string, excluding null terminating character
backend: The name of the backend (TF, TFLITE, TORCH, ONNX)
backend_length: The length of the backend c-string, excluding null terminating character
device: The name of the device for execution (e.g. CPU or GPU)
device_length: The length of the device c-string, excluding null terminating character
batch_size: The batch size for model execution
min_batch_size: The minimum batch size for model execution
tag: A tag to attach to the model for information purposes
tag_length: The length of the tag c-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 c-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 c-string, excluding null terminating character
n_outputs: The number of outputs

void set_model(void *c_client, const char *key, const size_t key_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 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.

Parameters

c_client: A pointer to c client to use for communication
key: The key to associate with the model
key_length: The length of the key c-string, excluding null terminating character
model: The model as a continuous buffer
model_length: The length of the model c-string, excluding null terminating character
backend: The name of the backend (TF, TFLITE, TORCH, ONNX)
backend_length: The length of the backend c-string, excluding null terminating character
device: The name of the device for execution (e.g. CPU or GPU)
device_length: The length of the device c-string, excluding null terminating character
batch_size: The batch size for model execution
min_batch_size: The minimum batch size for model execution
tag: A tag to attach to the model for information purposes
tag_length: The length of the tag c-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 c-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 c-string, excluding null terminating character
n_outputs: The number of outputs

const char *get_model(void *c_client, const char *key, const size_t key_length, size_t *model_length)¶

Get a model in the database.

Return

The model as a c-string or NULL on bad parameters

Parameters

c_client: A pointer to c client to use for communication
key: The key to use to get the model
key_length: The length of the key c-string, excluding null terminating character
model_length: The length of the model buffer c-string, excluding null terminating character

void set_script_from_file(void *c_client, const char *key, const size_t key_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.

Parameters

key: The key to associate with the script
key_length: The length of the key c-string, excluding null terminating character
device: The name of the device for execution (e.g. CPU or GPU)
device_length: The length of the device name c-string, excluding null terminating character
script_file: The source file for the script
script_file_length: The length of the script file name c-string, excluding null terminating character

void set_script(void *c_client, const char *key, const size_t key_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.

Parameters

key: The key to associate with the script
key_length: The length of the key c-string, excluding null terminating character
device: The name of the device for execution (e.g. CPU or GPU)
device_length: The length of the device name c-string, excluding null terminating character
script: The script as a c-string buffer
script_length: The length of the script c-string, excluding null terminating character

void get_script(void *c_client, const char *key, const size_t key_length, const char **script, size_t *script_length)¶

Get a script in the database. The memory associated with the script c-str is valid until the client is destroyed.

Parameters

c_client: A pointer to c client to use for communication
key: The key to use to get the script
key_length: The length of the key c-string, excluding null terminating character
script: A pointer that is pointed to newly allocated memory containing the script
script_length: The length of the script buffer c-string, excluding null terminating character

void run_script(void *c_client, const char *key, const size_t key_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.

Parameters

c_client: A pointer to c client to use for communication
key: The key associated with the script
key_length: The length of the key c-string, excluding null terminating character
function: The name of the function in the script to run
function_length: The length of the function name c-string, excluding null terminating character
inputs: The keys of inputs tensors to use in the script
input_lengths: The length of each input name c-string, excluding null terminating character
n_inputs: The number of inputs
outputs: The keys of output tensors that will be used to save script results
output_lengths: The length of each output name c-string, excluding null terminating character
n_outputs: The number of outputs

void run_model(void *c_client, const char *key, const size_t key_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 specificed input and output tensors.

Parameters

c_client: A pointer to c client to use for communication
key: The key associated with the model
key_length: The length of the key c-string, excluding null terminating character
inputs: The keys of inputs tensors to use in the script
input_lengths: The length of each input name c-string, excluding null terminating character
n_inputs: The number of inputs
outputs: The keys of output tensors that will be used to save script results
output_lengths: The length of each output name c-string, excluding null terminating character
n_outputs: The number of outputs

bool key_exists(void *c_client, const char *key, const size_t key_length)¶

Check if the key exists in the database.

Return

Returns true if the key exists in the database

Parameters

c_client: A pointer to c client to use for communication
key: The key that will be checked in the database
key_length: The length of the key c-string, excluding null terminating character

bool tensor_exists(void *c_client, const char *name, const size_t name_length)¶

Check if a tensor or dataset exists in the database.

Return

Returns true if the key exists in the database

Parameters

c_client: A pointer to c client to use for communication
name: The name of the entity that will be checked in the database. The full key associated to name will formed according to the prefixing behavior
name_length: The length of the name c-string, excluding null terminating character

bool model_exists(void *c_client, const char *name, const size_t name_length)¶

Check if a model or script exists in the database.

Return

Returns true if the key exists in the database

Parameters

c_client: A pointer to c client to use for communication
name: The name of the entity that will be checked in the database. The full key associated to name will formed according to the prefixing behavior
name_length: The length of the name c-string, excluding null terminating character

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

Check if the key exists in the database at a specified frequency for a specified number of times.

Return

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

Parameters

c_client: A pointer to c client to use for communication
key: The key that will be checked in the database
key_length: The length of the key c-string, excluding null terminating character
poll_frequency_ms: The frequency of checks for the key in milliseconds
num_tries: The total number of times to check for the specified number of keys. If the value is set to -1, the key will be polled indefinitely.

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

Check if a model or script exists in the database at a specified frequency for a specified number of times.

Return

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

Parameters

c_client: A pointer to c client to use for communication
name: The name of the entity that will be checked in the database. The full key associated to name will formed according to the prefixing behavior
name_length: The length of the name c-string, excluding null terminating character
poll_frequency_ms: The frequency of checks for the key in milliseconds
num_tries: The total number of times to check for the specified number of keys. If the value is set to -1, the key will be polled indefinitely.

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

Check if a tensor or dataset exists in the database at a specified frequency for a specified number of times.

Return

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

Parameters

c_client: A pointer to c client to use for communication
name: The name of the entity that will be checked in the database. The full key associated to name will formed according to the prefixing behavior
name_length: The length of the name c-string, excluding null terminating character
poll_frequency_ms: The frequency of checks for the key in milliseconds
num_tries: The total number of times to check for the specified number of keys. If the value is set to -1, the key will be polled indefinitely.

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

Set the data source (i.e. key prefix for get functions)

Parameters

source_id: The prefix for retrieval commands
source_id_length: The length of the source_id c-string, excluding null terminating character

void use_tensor_ensemble_prefix(void *c_client, bool use_prefix)¶

Set whether names of tensor and dataset entities should be prefixed (e.g. in an ensemble) to form database keys. 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 affected. 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 tensors and datasets will use a prefix, if available.

void use_model_ensemble_prefix(void *c_client, bool use_prefix)¶

Set whether names of model and script entities should be prefixed (e.g. in an ensemble) to form database keys. 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 affected. By default, the client does not prefix model and script keys.

Parameters

use_prefix: If set to true, all future operations on models and scripts will use a prefix, if available.

Dataset API¶

C-wrappers for the C++ DataSet class.

Functions

void *CDataSet(const char *name, const size_t name_length)¶

C-DataSet constructor.

Return

Returns NULL on failure

Parameters

name: The name of the dataset
name_length: The length of the dataset name c-string, excluding null terminating character

void DeallocateeDataSet(void *dataset)¶

C-DataSet destructor.

Parameters

dataset: A c-ptr to receive the dataset object

void add_tensor(void *dataset, const char *name, const size_t name_length, void *data, const size_t *dims, const size_t n_dims, const CTensorType type, const CMemoryLayout mem_layout)¶

Add a tensor to the DataSet.

Parameters

dataset: A c-ptr to the dataset object
name: The name used to reference the tensor within the DataSet
name_length: The length of the tensor name c-string, excluding null terminating character
data: A c-ptr to the tensor data memory location
dims: The dimensions of the tensor
n_dims: The number of dimensions of the tensor
type: The data type of the tensor data
mem_layout: The MemoryLayout enum describing the layout of the provided tensor data

void add_meta_scalar(void *dataset, const char *name, const size_t name_length, const void *data, const CMetaDataType type)¶

Add metadata scalar field (non-string) with value to the DataSet. If the field does not exist, it will be created. If the field exists, the value will be appended to existing field.

Parameters

dataset: A c-ptr to the dataset object
name: The name used to reference the metadata field
name_length: The length of the metadata name c-string, excluding null terminating character
data: A c-ptr to the metadata field data
type: The data type of the metadata

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

Add metadata string field with value to the DataSet. If the field does not exist, it will be created. If the field exists the value will be appended to existing field.

Parameters

dataset: A c-ptr to the dataset object
name: The name used to reference the metadata field
name_length: The length of the metadata name c-string, excluding null terminating character
data: The string to add to the field
data_length: The length of the metadata string value

void get_dataset_tensor(void *dataset, const char *name, const size_t name_length, void **data, size_t **dims, size_t *n_dims, CTensorType *type, const CMemoryLayout mem_layout)¶

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

dataset: A c-ptr to the dataset object
name: The name used to reference the tensor in the dataset
name_length: The length of the tensor name c-string, excluding null terminating character
data: A c-ptr reference that will be pointed to newly allocated memory
dims: A reference to a dimensions vector that will be filled with the retrieved tensor dimensions
n_dims: The number of dimensions of the tensor
type: A reference to a TensorType enum that will be set to the value of the retrieved tensor type
mem_layout: The MemoryLayout that the newly allocated memory should conform to

void 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 CTensorType type, const CMemoryLayout mem_layout)¶

Get tensor data and fill an already allocated array memory space that has the specified MemoryLayout. The provided type and dimensions are checked against retrieved values to ensure the provided memory space is sufficient. This method is the most memory efficient way to retrieve tensor data from a dataset.

Parameters

dataset: A c-ptr to the dataset object
name: The name used to reference the tensor in the dataset
name_length: The length of the tensor name c-string, excluding null terminating character
data: A c-ptr to the memory space to be filled with tensor data
dims: The dimensions of the memory space
n_dims: The number of dimensions of the tensor in the memory space
type: The TensorType matching the data type of the memory space
mem_layout: The MemoryLayout of the provided memory space.

void *get_meta_scalars(void *dataset, const char *name, const size_t name_length, size_t *length, CMetaDataType *type)¶

Get the metadata scalar field values from the DataSet. The data pointer reference will be pointed to newly allocated memory that will contain all values in the metadata field. The length variable will be set to the number of entries in the allocated memory space to allow for iteration over the values. The TensorType enum will be set to the type of the MetaData field.

Return

A c-ptr to newly allocated memory containing the metadata or NULL on bad parameters

Parameters

dataset: A c-ptr to the dataset object
name: The name used to reference the metadata field in the DataSet
name_length: The length of the metadata field name c-string, excluding null terminating character
length: The number of values in the metadata field
type: The MetadataType enum describing the data type of the metadata field

void get_meta_strings(void *dataset, const char *name, const size_t name_length, char ***data, size_t *n_strings, size_t **lengths)¶

Get the metadata string field values from the dataset. The data pointer reference will be pointed to newly allocated memory that will contain all values in the metadata field. The n_strings input variable reference will be set to the number of strings in the field. The lengths c-ptr variable will be pointed to a new memory space that contains the length of each field string. The memory for the data and lengths pointers will be managed by the DataSet object and remain valid until the DataSet object is destroyed.

Parameters

dataset: A c-ptr to the dataset object
name: The name used to reference the metadata field in the DataSet
name_length: The length of the metadata field name c-string, excluding null terminating character
data: A c-ptr to the char** pointer that will be redirected to the string values
n_strings: A reference to a size_t variable that will be set to the number of strings in the field
lengths: A c-ptr that will be pointed to a memory space that contains the length of each field string

Fortran¶

Client 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

Needed modules

iso_c_binding (c_loc(), c_f_pointer())
smartredis_dataset (dataset_type())
fortran_c_interop (convert_char_array_to_c())

Types

type unknown_type¶
Type fields
% client_ptr [c_ptr,private/optional/default=c_null_ptr]

% cluster [logical,private/optional/default=.false.]

% is_initialized [logical,private/optional/default=.false.]

Subroutines and functions

subroutine initialize_client(self[, cluster])¶

Parameters

self [real] :: < Receives the initialized client
cluster [logical,in,] :: < If true, client uses a database cluster (Default: .false.)

function isinitialized(this)¶

Parameters: this [real]
Return: isinitialized [logical]

subroutine destructor(self)¶

Parameters: self [real]

function key_exists(self, key)¶

Parameters

self [real] :: < The client
key [character,in] :: < The key to check

Return

key_exists [logical]

function model_exists(self, model_name)¶

Parameters

self [real] :: < The client
model_name [character,in] :: < The model to check

Return

model_exists [logical]

function tensor_exists(self, tensor_name)¶

Parameters

self [real] :: < The client
tensor_name [character,in] :: < The tensor to check

Return

tensor_exists [logical]

function poll_tensor(self, tensor_name, poll_frequency_ms, num_tries)¶

Parameters

self [real] :: < The client
tensor_name [character,in] :: < Key in the database to poll
poll_frequency_ms [integer,in] :: < Frequency at which to poll the database (ms)
num_tries [integer,in] :: < Number of times to poll the database before failing

Return

poll_tensor [logical]

function poll_model(self, model_name, poll_frequency_ms, num_tries)¶

Parameters

self [real] :: < The client
model_name [character,in] :: < Key in the database to poll
poll_frequency_ms [integer,in] :: < Frequency at which to poll the database (ms)
num_tries [integer,in] :: < Number of times to poll the database before failing

Return

poll_model [logical]

function poll_key(self, key, poll_frequency_ms, num_tries)¶

Parameters

self [real] :: < The client
key [character,in] :: < Key in the database to poll
poll_frequency_ms [integer,in] :: < Frequency at which to poll the database (ms)
num_tries [integer,in] :: < Number of times to poll the database before failing

Return

poll_key [logical]

subroutine put_tensor_i8(self, key, data, dims)¶

Parameters

self [real]
key [character,in]
data (..) [integer,in,target] :: < Data to be sent
dims (*) [integer,in]

subroutine put_tensor_i16(self, key, data, dims)¶

Parameters

self [real]
key [character,in]
data (..) [integer,in,target] :: < Data to be sent
dims (*) [integer,in]

subroutine put_tensor_i32(self, key, data, dims)¶

Parameters

self [real]
key [character,in]
data (..) [integer,in,target] :: < Data to be sent
dims (*) [integer,in]

subroutine put_tensor_i64(self, key, data, dims)¶

Parameters

self [real]
key [character,in]
data (..) [integer,in,target] :: < Data to be sent
dims (*) [integer,in]

subroutine put_tensor_float(self, key, data, dims)¶

Parameters

self [real]
key [character,in]
data (..) [real,in,target] :: < Data to be sent
dims (*) [integer,in]

subroutine put_tensor_double(self, key, data, dims)¶

Parameters

self [real]
key [character,in]
data (..) [real,in,target] :: < Data to be sent
dims (*) [integer,in]

subroutine unpack_tensor_i8(self, key, result, dims)¶

Parameters

self [real]
key [character,in]
result (..) [integer,out,target] :: < Data to be sent
dims (*) [integer,in]

subroutine unpack_tensor_i16(self, key, result, dims)¶

Parameters

self [real]
key [character,in]
result (..) [integer,out,target] :: < Data to be sent
dims (*) [integer,in]

subroutine unpack_tensor_i32(self, key, result, dims)¶

Parameters

self [real]
key [character,in]
result (..) [integer,out,target] :: < Data to be sent
dims (*) [integer,in]

subroutine unpack_tensor_i64(self, key, result, dims)¶

Parameters

self [real]
key [character,in]
result (..) [integer,out,target] :: < Data to be sent
dims (*) [integer,in]

subroutine unpack_tensor_float(self, key, result, dims)¶

Parameters

self [real]
key [character,in]
result (..) [real,out,target] :: < Data to be sent
dims (*) [integer,in]

subroutine unpack_tensor_double(self, key, result, dims)¶

Parameters

self [real]
key [character,in]
result (..) [real,out,target] :: < Data to be sent
dims (*) [integer,in]

subroutine rename_tensor(self, key, new_key)¶

Parameters

self [real] :: < The initialized Fortran SmartRedis client
key [character,in] :: < The current key for the tensor
new_key [character,in] :: < The new tensor key

subroutine delete_tensor(self, key)¶

Parameters

self [real] :: < The initialized Fortran SmartRedis client
key [character,in] :: < The key associated with the tensor

subroutine copy_tensor(self, src_name, dest_name)¶

Parameters

self [real] :: < The initialized Fortran SmartRedis client
src_name [character,in] :: < The key associated with the tensor
dest_name [character,in] :: < The new tensor key

subroutine get_model(self, key, model)¶

Parameters

self [real] :: < An initialized SmartRedis client
key [character,in] :: < The key associated with the model
model [character,out] :: < The model as a continuous buffer

subroutine set_model_from_file(self, key, model_file, backend, device[, batch_size[, min_batch_size[, tag[, inputs[, outputs]]]]])¶

Parameters

self [real] :: < An initialized SmartRedis client
key [character,in] :: < The key to use to place the model
model_file [character,in] :: < The file storing the model
backend [character,in] :: < The name of the backend (TF, TFLITE, TORCH, ONNX)
device [character,in] :: < The name of the device (CPU, GPU, GPU:0, GPU:1…)
batch_size [integer,in,] :: < The batch size for model execution
min_batch_size [integer,in,] :: < The minimum batch size for model execution
tag [character,in,] :: < A tag to attach to the model for
inputs (*) [character,in,] :: < One or more names of model input nodes (TF
outputs (*) [character,in,] :: < One or more names of model output nodes (TF models)

subroutine set_model(self, key, model, backend, device, batch_size, min_batch_size, tag, inputs, outputs)¶

Parameters

self [real] :: < An initialized SmartRedis client
key [character,in] :: < The key to use to place the model
model [character,in] :: < The binary representation of the model
backend [character,in] :: < The name of the backend (TF, TFLITE, TORCH, ONNX)
device [character,in] :: < The name of the device (CPU, GPU, GPU:0, GPU:1…)
batch_size [integer,in] :: < The batch size for model execution
min_batch_size [integer,in] :: < The minimum batch size for model execution
tag [character,in] :: < A tag to attach to the model for information purposes
inputs (*) [character,in] :: < One or more names of model input nodes (TF models)
outputs (*) [character,in] :: < One or more names of model output nodes (TF models)

subroutine run_model(self, key, inputs, outputs)¶

Parameters

self [real] :: < An initialized SmartRedis client
key [character,in] :: < The key to use to place the model
inputs (*) [character,in] :: < One or more names of model input nodes (TF models)
outputs (*) [character,in] :: < One or more names of model output nodes (TF models)

subroutine get_script(self, key, script)¶

Parameters

self [real] :: < An initialized SmartRedis client
key [character,in] :: < The key to use to place the script
script [character,out] :: < The script as a continuous buffer

subroutine set_script_from_file(self, key, device, script_file)¶

Parameters

self [real] :: < An initialized SmartRedis client
key [character,in] :: < The key to use to place the script
device [character,in] :: < The name of the device (CPU, GPU, GPU:0, GPU:1…)
script_file [character,in] :: < The file storing the script

subroutine set_script(self, key, device, script)¶

Parameters

self [real] :: < An initialized SmartRedis client
key [character,in] :: < The key to use to place the script
device [character,in] :: < The name of the device (CPU, GPU, GPU:0, GPU:1…)
script [character,in] :: < The file storing the script

subroutine run_script(self, key, func, inputs, outputs)¶

Parameters

self [real] :: < An initialized SmartRedis client
key [character,in] :: < The key to use to place the script
func [character,in] :: < The name of the function in the script to call
inputs (*) [character,in] :: < One or more names of script input nodes (TF scripts)
outputs (*) [character,in] :: < One or more names of script output nodes (TF scripts)

subroutine put_dataset(self, dataset)¶

Parameters

self [real] :: < An initialized SmartRedis client
dataset [dataset_type,in] :: < Dataset to store in the dataset

function get_dataset(self, name)¶

Parameters

self [real] :: < An initialized SmartRedis client
name [character,in] :: < Name of the dataset to get

Return

get_dataset [dataset_type]

subroutine rename_dataset(self, name, new_name)¶

Parameters

self [real] :: < An initialized SmartRedis client
name [character,in] :: < Original name of the dataset
new_name [character,in] :: < New name of the dataset

subroutine copy_dataset(self, name, new_name)¶

Parameters

self [real] :: < An initialized SmartRedis client
name [character,in] :: < Source name of the dataset
new_name [character,in] :: < Name of the new dataset

subroutine delete_dataset(self, name)¶

Parameters

self [real] :: < An initialized SmartRedis client
name [character,in] :: < Name of the dataset to delete

subroutine set_data_source(self, source_id)¶

Parameters

self [real] :: < An initialized SmartRedis client
source_id [character,in] :: < The key prefix

subroutine use_model_ensemble_prefix(self, use_prefix)¶

Parameters

self [real] :: < An initialized SmartRedis client
use_prefix [logical,in] :: < The prefix setting

subroutine use_tensor_ensemble_prefix(self, use_prefix)¶

Parameters

self [real] :: < An initialized SmartRedis client
use_prefix [logical,in] :: < The prefix setting

Dataset API¶

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())

Types

type unknown_type¶
Type fields
% dataset_ptr [c_ptr]

Subroutines and functions

subroutine initialize_dataset(self, name)¶

Parameters

self [real] :: < Receives the dataset
name [character,in] :: < Name of the dataset

subroutine add_tensor_i8(self, name, data, dims)¶

Parameters

self [real]
name [character,in]
data (..) [integer,in,target] :: < Data to be sent
dims (*) [integer,in]

subroutine add_tensor_i16(self, name, data, dims)¶

Parameters

self [real]
name [character,in]
data (..) [integer,in,target] :: < Data to be sent
dims (*) [integer,in]

subroutine add_tensor_i32(self, name, data, dims)¶

Parameters

self [real]
name [character,in]
data (..) [integer,in,target] :: < Data to be sent
dims (*) [integer,in]

subroutine add_tensor_i64(self, name, data, dims)¶

Parameters

self [real]
name [character,in]
data (..) [integer,in,target] :: < Data to be sent
dims (*) [integer,in]

subroutine add_tensor_float(self, name, data, dims)¶

Parameters

self [real]
name [character,in]
data (..) [real,in,target] :: < Data to be sent
dims (*) [integer,in]

subroutine add_tensor_double(self, name, data, dims)¶

Parameters

self [real]
name [character,in]
data (..) [real,in,target] :: < Data to be sent
dims (*) [integer,in]

subroutine unpack_dataset_tensor_i8(self, name, result, dims)¶

Parameters

self [real]
name [character,in]
result (..) [integer,out,target] :: < Array to be populated with data
dims (*) [integer,in]

subroutine unpack_dataset_tensor_i16(self, name, result, dims)¶

Parameters

self [real]
name [character,in]
result (..) [integer,out,target] :: < Array to be populated with data
dims (*) [integer,in]

subroutine unpack_dataset_tensor_i32(self, name, result, dims)¶

Parameters

self [real]
name [character,in]
result (..) [integer,out,target] :: < Array to be populated with data
dims (*) [integer,in]

subroutine unpack_dataset_tensor_i64(self, name, result, dims)¶

Parameters

self [real]
name [character,in]
result (..) [integer,out,target] :: < Array to be populated with data
dims (*) [integer,in]

subroutine unpack_dataset_tensor_float(self, name, result, dims)¶

Parameters

self [real]
name [character,in]
result (..) [real,out,target] :: < Array to be populated with data
dims (*) [integer,in]

subroutine unpack_dataset_tensor_double(self, name, result, dims)¶

Parameters

self [real]
name [character,in]
result (..) [real,out,target] :: < Array to be populated with data
dims (*) [integer,in]

subroutine get_meta_scalars_i32(self, name, meta)¶

Parameters

self [real] :: < The dataset
name [character,in] :: < The name of the metadata field
meta (*) [integer,pointer] :: < The actual metadata

subroutine get_meta_scalars_i64(self, name, meta)¶

Parameters

self [real] :: < The dataset
name [character,in] :: < The name of the metadata field
meta (*) [integer,pointer] :: < The actual metadata

subroutine get_meta_scalars_float(self, name, meta)¶

Parameters

self [real] :: < The dataset
name [character,in] :: < The name of the metadata field
meta (*) [real,pointer] :: < The actual metadata

subroutine get_meta_scalars_double(self, name, meta)¶

Parameters

self [real] :: < The dataset
name [character,in] :: < The name of the metadata field
meta (*) [real,pointer] :: < The actual metadata

subroutine add_meta_scalar_i32(self, name, meta)¶

Parameters

self [real] :: < The dataset
name [character,in] :: < The name of the metadata field
meta [integer,in,target] :: < The actual metadata

subroutine add_meta_scalar_i64(self, name, meta)¶

Parameters

self [real] :: < The dataset
name [character,in] :: < The name of the metadata field
meta [integer,in,target] :: < The actual metadata

subroutine add_meta_scalar_float(self, name, meta)¶

Parameters

self [real] :: < The dataset
name [character,in] :: < The name of the metadata field
meta [real,in,target] :: < The actual metadata

subroutine add_meta_scalar_double(self, name, meta)¶

Parameters

self [real] :: < The dataset
name [character,in] :: < The name of the metadata field
meta [real,in,target] :: < The actual metadata

subroutine add_meta_string(self, name, meta)¶

Parameters

self [real] :: < The dataset
name [character,in] :: < The name of the metadata field
meta [character,in] :: < The actual metadata

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.

program main

  use iso_c_binding
  use smartredis_client, only : client_type

  implicit none

  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
  type(client_type) :: client

  integer :: err_code, pe_id

  call random_number(send_array_real_64)

  call client%initialize(.false.) ! Change .true. to false if using a clustered database

  call client%put_tensor("send_array", send_array_real_64, shape(send_array_real_64))
  call client%unpack_tensor("send_array", recv_array_real_64, shape(recv_array_real_64))

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)
Assumed rank (dimension(..)) arrays (Fortran 2018)

These language features are supported by Intel 19, GNU 9, and Cray 8.6 and later versions.

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.