viam.app.data_client

Module Contents

Classes

DataClient

gRPC client for uploading and retrieving data from app.

Attributes

LOGGER

viam.app.data_client.LOGGER
class viam.app.data_client.DataClient(channel: grpclib.client.Channel, metadata: Mapping[str, str])[source]

gRPC client for uploading and retrieving data from app.

Constructor is used by ViamClient to instantiate relevant service stubs. Calls to DataClient methods should be made through ViamClient.

class TabularData(data: Mapping[str, Any], metadata: viam.proto.app.data.CaptureMetadata, time_requested: datetime.datetime, time_received: datetime.datetime)[source]

Class representing a piece of tabular data and associated metadata.

Parameters:

  • data (Mapping[str, Any]) – the requested data.

  • metadata (viam.proto.app.data.CaptureMetadata) – the metadata from the request.

  • time_requested (datetime) – the time the data request was sent.

  • time_received (datetime) – the time the requested data was received.

data: Mapping[str, Any]
metadata: viam.proto.app.data.CaptureMetadata
time_requested: datetime.datetime
time_received: datetime.datetime
__str__() → str[source]

Return str(self).

__eq__(other: DataClient) → bool[source]

Return self==value.

class BinaryData(data: bytes, metadata: viam.proto.app.data.BinaryMetadata)[source]

Class representing a piece of binary data and associated metadata.

Parameters:
data: bytes
metadata: viam.proto.app.data.BinaryMetadata
__str__() → str[source]

Return str(self).

__eq__(other: DataClient) → bool[source]

Return self==value.

async tabular_data_by_filter(filter: Optional[viam.proto.app.data.Filter] = None, dest: Optional[str] = None) → List[TabularData][source]

Filter and download tabular data.

Parameters:

  • filter (viam.proto.app.data.Filter) – Optional Filter specifying tabular data to retrieve. No Filter implies all tabular data.

  • dest (str) – Optional filepath for writing retrieved data.

Returns:

The tabular data.

Return type:

List[Mapping[str, Any]]

async binary_data_by_filter(filter: Optional[viam.proto.app.data.Filter] = None, dest: Optional[str] = None, include_file_data: bool = True, num_files: Optional[int] = None) → List[BinaryData][source]

Filter and download binary data.

Parameters:

  • filter (Optional[viam.proto.app.data.Filter]) – Optional Filter specifying binary data to retrieve. No Filter implies all binary data.

  • dest (Optional[str]) – Optional filepath for writing retrieved data.

  • include_file_data (bool) – Boolean specifying whether to actually include the binary file data with each retrieved file. Defaults to true (i.e., both the files’ data and metadata are returned).

  • num_files (Optional[str]) –

    Number of binary data to return. Passing 0 returns all binary data matching the filter no matter. Defaults to 100 if no binary data is requested, otherwise 10. All binary data or the first num_files will be returned,

    whichever comes first.

Raises:

ValueError – If num_files is less than 0.

Returns:

The binary data.

Return type:

List[bytes]

async binary_data_by_ids(binary_ids: List[viam.proto.app.data.BinaryID], dest: Optional[str] = None) → List[BinaryData][source]

Filter and download binary data.

Parameters:

  • binary_ids (List[viam.proto.app.data.BinaryID]) – BinaryID objects specifying the desired data. Must be non-empty.

  • dest (str) – Optional filepath for writing retrieved data.

Raises:

GRPCError – If no BinaryID objects are provided.

Returns:

The binary data.

Return type:

List[bytes]

async delete_tabular_data(organization_id: str, delete_older_than_days: int) → int[source]

Delete tabular data older than a specified number of days.

Parameters:

  • organization_id (str) – ID of organization to delete data from.

  • delete_older_than_days (int) – Delete data that was captured up to this many days ago. For example if delete_older_than_days is 10, this deletes any data that was captured up to 10 days ago. If it is 0, all existing data is deleted.

abstract async delete_tabular_data_by_filter(filter: Optional[viam.proto.app.data.Filter]) → int[source]

Deprecated: use delete_tabular_data instead.

async delete_binary_data_by_filter(filter: Optional[viam.proto.app.data.Filter]) → int[source]

Filter and delete binary data.

Parameters:

filter (viam.proto.app.data.Filter) – Optional Filter specifying binary data to delete. Passing an empty Filter will lead to all data being deleted. Exercise caution when using this option.

async delete_binary_data_by_ids(binary_ids: List[viam.proto.app.data.BinaryID]) → int[source]

Filter and delete binary data.

Parameters:

binary_ids (List[viam.proto.app.data.BinaryID]) – BinaryID objects specifying the data to be deleted. Must be non-empty.

Raises:

GRPCError – If no BinaryID objects are provided.

Returns:

The number of items deleted.

Return type:

int

async add_tags_to_binary_data_by_ids(tags: List[str], binary_ids: List[viam.proto.app.data.BinaryID]) → None[source]

Add tags to binary data.

Parameters:

  • tags (List[str]) – List of tags to add to specified binary data. Must be non-empty.

  • binary_ids (List[viam.app.proto.BinaryID]) – List of BinaryID objects specifying binary data to tag. Must be non-empty.

Raises:

GRPCError – If no BinaryID objects or tags are provided.

async add_tags_to_binary_data_by_filter(tags: List[str], filter: Optional[viam.proto.app.data.Filter] = None) → None[source]

Add tags to binary data.

Parameters:

  • tags (List[str]) – List of tags to add to specified binary data. Must be non-empty.

  • filter (viam.proto.app.data.Filter) – Filter specifying binary data to tag. If no Filter is provided, all data will be tagged.

Raises:

GRPCError – If no tags are provided.

async remove_tags_from_binary_data_by_ids(tags: List[str], binary_ids: List[viam.proto.app.data.BinaryID]) → int[source]

Remove tags from binary.

Parameters:

  • tags (List[str]) – List of tags to remove from specified binary data. Must be non-empty.

  • file_ids (List[str]) – List of BinaryID objects specifying binary data to untag. Must be non-empty.

Raises:

GRPCError – If no binary_ids or tags are provided.

Returns:

The number of tags removed.

Return type:

int

async remove_tags_from_binary_data_by_filter(tags: List[str], filter: Optional[viam.proto.app.data.Filter] = None) → int[source]

Remove tags from binary data.

Parameters:

  • tags (List[str]) – List of tags to remove from specified binary data.

  • filter (viam.proto.app.data.Filter) – Filter specifying binary data to untag. If no Filter is provided, all data will be untagged.

Raises:

GRPCError – If no tags are provided.

Returns:

The number of tags removed.

Return type:

int

async tags_by_filter(filter: Optional[viam.proto.app.data.Filter] = None) → List[str][source]

Get a list of tags using a filter.

Parameters:

filter (viam.proto.app.data.Filter) – Filter specifying data to retrieve from. If no Filter is provided, all data tags will return.

Returns:

The list of tags.

Return type:

List[str]

async add_bounding_box_to_image_by_id(binary_id: viam.proto.app.data.BinaryID, label: str, x_min_normalized: float, y_min_normalized: float, x_max_normalized: float, y_max_normalized: float) → str[source]

Add a bounding box to an image.

Parameters:

  • binary_id (viam.proto.app.data.BinaryID) – The ID of the image to add the bounding box to.

  • label (str) – A label for the bounding box.

  • x_min_normalized (float) – Min X value of the bounding box normalized from 0 to 1.

  • y_min_normalized (float) – Min Y value of the bounding box normalized from 0 to 1.

  • x_max_normalized (float) – Max X value of the bounding box normalized from 0 to 1.

  • y_max_normalized (float) – Max Y value of the bounding box normalized from 0 to 1.

Raises:

GRPCError – If the X or Y values are outside of the [0, 1] range.

Returns:

The bounding box ID

Return type:

str

async remove_bounding_box_from_image_by_id(bbox_id: str, binary_id: viam.proto.app.data.BinaryID) → None[source]

Removes a bounding box from an image.

Parameters:

  • bbox_id (str) – The ID of the bounding box to remove.

  • Binary_id (viam.proto.arr.data.BinaryID) – Binary ID of the image to to remove the bounding box from

async bounding_box_labels_by_filter(filter: Optional[viam.proto.app.data.Filter] = None) → List[str][source]

Get a list of bounding box labels using a Filter.

Parameters:

filter (viam.proto.app.data.Filter) – Filter specifying data to retrieve from. If no Filter is provided, all labels will return.

Returns:

The list of bounding box labels.

Return type:

List[str]

async get_database_connection(organization_id: str) → str[source]

Get a connection to access a MongoDB Atlas Data federation instance.

Parameters:

organization_id (str) – Organization to retrieve the connection for.

Returns:

The hostname of the federated database.

Return type:

str

abstract async configure_database_user(organization_id: str, password: str) → None[source]
async binary_data_capture_upload(binary_data: bytes, part_id: str, component_type: str, component_name: str, method_name: str, file_extension: str, method_parameters: Optional[Mapping[str, Any]] = None, tags: Optional[List[str]] = None, data_request_times: Optional[Tuple[datetime.datetime, datetime.datetime]] = None) → str[source]

Upload binary sensor data.

Upload binary data collected on a robot through a specific component (e.g., a motor) along with the relevant metadata to app.viam.com. Binary data can be found under the “Files” subtab of the Data tab on app.viam.com.

Parameters:

  • binary_data (bytes) – The data to be uploaded, represented in bytes.

  • part_id (str) – Part ID of the component used to capture the data.

  • component_type (str) – Type of the component used to capture the data (e.g., “movement_sensor”).

  • component_name (str) – Name of the component used to capture the data.

  • method_name (str) – Name of the method used to capture the data.

  • file_extension (str) – The file extension of binary data including the period, e.g. .jpg, .png, .pcd. The backend will route the binary to its corresponding mime type based on this extension. Files with a .jpeg, .jpg, or .png extension will be saved to the images tab.

  • method_parameters (Optional[Mapping[str, Any]]) – Optional dictionary of method parameters. No longer in active use.

  • tags (Optional[List[str]]) – Optional list of tags to allow for tag-based data filtering when retrieving data.

  • data_request_times (Optional[Tuple[datetime.datetime, datetime.datetime]]) – Optional tuple containing `datetime`s objects denoting the times this data was requested[0] by the robot and received[1] from the appropriate sensor.

Raises:

GRPCError – If an invalid part ID is passed.

async tabular_data_capture_upload(tabular_data: List[Mapping[str, Any]], part_id: str, component_type: str, component_name: str, method_name: str, method_parameters: Optional[Mapping[str, Any]] = None, tags: Optional[List[str]] = None, data_request_times: Optional[List[Tuple[datetime.datetime, datetime.datetime]]] = None) → str[source]

Upload tabular sensor data.

Upload tabular data collected on a robot through a specific component (e.g., a motor) along with the relevant metadata to app.viam.com. Tabular data can be found under the “Sensors” subtab of the Data tab on app.viam.com.

Parameters:

  • tabular_data (List[Mapping[str, Any]]) – List of the data to be uploaded, represented tabularly as a collection of dictionaries.

  • part_id (str) – Part ID of the component used to capture the data.

  • component_type (str) – Type of the component used to capture the data (e.g., “movement_sensor”).

  • component_name (str) – Name of the component used to capture the data.

  • method_name (str) – Name of the method used to capture the data.

  • method_parameters (Optional[Mapping[str, Any]]) – Optional dictionary of method parameters. No longer in active use.

  • tags (Optional[List[str]]) – Optional list of tags to allow for tag-based data filtering when retrieving data.

  • data_request_times (Optional[List[Tuple[datetime.datetime, datetime.datetime]]]) – Optional list of tuples, each containing datetime objects denoting the times this data was requested[0] by the robot and received[1] from the appropriate sensor.

Passing a list of tabular data and Timestamps with length n > 1 will result in n datapoints being uploaded, all tied to the same metadata.

Raises:

  • GRPCError – If an invalid part ID is passed.

  • ValueError – If a list of Timestamp objects is provided and its length does not match the length of the list of tabular data.

async streaming_data_capture_upload(data: bytes, part_id: str, file_ext: str, component_type: Optional[str] = None, component_name: Optional[str] = None, method_name: Optional[str] = None, method_parameters: Optional[Mapping[str, Any]] = None, data_request_times: Optional[Tuple[datetime.datetime, datetime.datetime]] = None, tags: Optional[List[str]] = None) → str[source]

Uploads the metadata and contents of streaming binary data.

Parameters:

  • data (bytes) – the data to be uploaded.

  • part_id (str) – Part ID of the resource associated with the file.

  • file_ext (str) – file extension type for the data. required for determining MIME type.

  • component_type (Optional[str]) – Optional type of the component associated with the file (e.g., “movement_sensor”).

  • component_name (Optional[str]) – Optional name of the component associated with the file.

  • method_name (Optional[str]) – Optional name of the method associated with the file.

  • method_parameters (Optional[str]) – Optional dictionary of the method parameters. No longer in active use.

  • data_request_times (Optional[Tuple[datetime.datetime, datetime.datetime]]) – Optional tuple containing `datetime`s objects denoting the times this data was requested[0] by the robot and received[1] from the appropriate sensor.

  • tags (Optional[List[str]]) – Optional list of tags to allow for tag-based filtering when retrieving data.

Raises:

GRPCError – If an invalid part ID is passed.

Returns:

the file_id of the uploaded data.

Return type:

str

async file_upload(part_id: str, data: bytes, component_type: Optional[str] = None, component_name: Optional[str] = None, method_name: Optional[str] = None, file_name: Optional[str] = None, method_parameters: Optional[Mapping[str, Any]] = None, file_extension: Optional[str] = None, tags: Optional[List[str]] = None) → str[source]

Upload arbitrary file data.

Upload file data that may be stored on a robot along with the relevant metadata to app.viam.com. File data can be found under the “Files” subtab of the Data tab on app.viam.com.

Parameters:

  • part_id (str) – Part ID of the resource associated with the file.

  • data (bytes) – Bytes representing file data to upload.

  • component_type (Optional[str]) – Optional type of the component associated with the file (e.g., “movement_sensor”).

  • component_name (Optional[str]) – Optional name of the component associated with the file.

  • method_name (Optional[str]) – Optional name of the method associated with the file.

  • file_name (Optional[str]) – Optional name of the file. The empty string “” will be assigned as the file name if one isn’t provided.

  • method_parameters (Optional[str]) – Optional dictionary of the method parameters. No longer in active use.

  • file_extension (Optional[str]) – Optional file extension. The empty string “” will be assigned as the file extension if one isn’t provided. Files with a .jpeg, .jpg, or .png extension will be saved to the images tab.

  • tags (Optional[List[str]]) – Optional list of tags to allow for tag-based filtering when retrieving data.

Raises:

GRPCError – If an invalid part ID is passed.

Returns:

ID of the new file.

Return type:

str

async file_upload_from_path(filepath: str, part_id: str, component_type: Optional[str] = None, component_name: Optional[str] = None, method_name: Optional[str] = None, method_parameters: Optional[Mapping[str, Any]] = None, tags: Optional[List[str]] = None) → str[source]

Upload arbitrary file data.

Upload file data that may be stored on a robot along with the relevant metadata to app.viam.com. File data can be found under the “Files” subtab of the Data tab on app.viam.com.

Parameters:

  • filepath (str) – Absolute filepath of file to be uploaded.

  • part_id (str) – Part ID of the component associated with the file.

  • component_type (Optional[str]) – Optional type of the component associated with the file (e.g., “movement_sensor”).

  • component_name (Optional[str]) – Optional name of the component associated with the file.

  • method_name (Optional[str]) – Optional name of the method associated with the file.

  • method_parameters (Optional[str]) – Optional dictionary of the method parameters. No longer in active use.

  • tags (Optional[List[str]]) – Optional list of tags to allow for tag-based filtering when retrieving data.

Raises:

  • GRPCError – If an invalid part ID is passed.

  • FileNotFoundError – If the provided filepath is not found.

Returns:

ID of the new file.

Return type:

str

static create_filter(component_name: Optional[str] = None, component_type: Optional[str] = None, method: Optional[str] = None, robot_name: Optional[str] = None, robot_id: Optional[str] = None, part_name: Optional[str] = None, part_id: Optional[str] = None, location_ids: Optional[List[str]] = None, organization_ids: Optional[List[str]] = None, mime_type: Optional[List[str]] = None, start_time: Optional[datetime.datetime] = None, end_time: Optional[datetime.datetime] = None, tags: Optional[List[str]] = None, bbox_labels: Optional[List[str]] = None) → viam.proto.app.data.Filter[source]