Upload and Retrieve Data with Viam's Data Client API
The data client API allows you to upload and retrieve data to and from the Viam Cloud.
Support Notice
Data client API methods are only available in the Python SDK.
The data client API supports the following methods:
Methods to upload data like images or sensor readings directly to the Viam app:
Method Name | Description |
---|---|
BinaryDataCaptureUpload | Upload binary data collected on your machine through a specific component and the relevant metadata to the Viam app. |
TabularDataCaptureUpload | Upload tabular data collected on your machine through a specific component to the Viam app. |
FileUpload | Upload arbitrary files stored on your machine to the Viam app by file name. |
FileUploadFromPath | Upload files stored on your machine to the Viam app by filepath. |
StreamingDataCaptureUpload | Upload the contents of streaming binary data and the relevant metadata to the Viam app. |
Methods to download, filter, tag, or perform other tasks on data like images or sensor readings:
Method Name | Description |
---|---|
TabularDataByFilter | Retrieve optionally filtered tabular data from the Viam app. |
TabularDataBySQL | Obtain unified tabular data and metadata, queried with SQL. |
TabularDataByMQL | Obtain unified tabular data and metadata, queried with MQL. |
BinaryDataByFilter | Retrieve optionally filtered binary data from the Viam app. |
BinaryDataByIDs | Retrieve binary data from the Viam app by BinaryID . |
DeleteTabularData | Delete tabular data older than a specified number of days. |
DeleteBinaryDataByFilter | Filter and delete binary data. |
DeleteBinaryDataByIDs | Filter and delete binary data by ids. |
AddTagsToBinaryDataByIDs | Add tags to binary data by ids. |
AddTagsToBinaryDataByFilter | Add tags to binary data by filter. |
RemoveTagsFromBinaryDataByIDs | Remove tags from binary by ids. |
RemoveTagsFromBinaryDataByFilter | Remove tags from binary data by filter. |
TagsByFilter | Get a list of tags using a filter. |
AddBoundingBoxToImageByID | Add a bounding box to an image specified by its BinaryID. |
RemoveBoundingBoxFromImageByID | Removes a bounding box from an image specified by its BinaryID. |
BoundingBoxLabelsByFilter | Get a list of bounding box labels using a Filter. |
GetDatabaseConnection | Get a connection to access a MongoDB Atlas Data federation instance. |
ConfigureDatabaseUser | Configure a database user for the Viam organization’s MongoDB Atlas Data Federation instance. |
AddBinaryDataToDatasetByIDs | Add the BinaryData to the provided dataset. |
RemoveBinaryDataFromDatasetByIDs | Remove the BinaryData from the provided dataset. |
Methods to work with datasets:
Method Name | Description |
---|---|
CreateDataset | Create a new dataset. |
DeleteDataset | Delete a dataset. |
RenameDataset | Rename a dataset specified by the dataset ID. |
ListDatasetsByOrganizationID | Get the datasets in an organization. |
ListDatasetsByIDs | Get a list of datasets using their IDs. |
Establish a connection
To use the Viam data client API, you first need to instantiate a ViamClient
and then instantiate a DataClient
.
You will also need an API key and API key ID to authenticate your session. To get an API key (and corresponding ID), you have two options:
The following example instantiates a ViamClient
, authenticating with an API key, and then instantiates a DataClient
:
import asyncio
from viam.rpc.dial import DialOptions, Credentials
from viam.app.viam_client import ViamClient
async def connect() -> ViamClient:
dial_options = DialOptions(
credentials=Credentials(
type="api-key",
# Replace "<API-KEY>" (including brackets) with your machine's API key
payload='<API-KEY>',
),
# Replace "<API-KEY-ID>" (including brackets) with your machine's
# API key ID
auth_entity='<API-KEY-ID>'
)
return await ViamClient.create_from_dial_options(dial_options)
async def main():
# Make a ViamClient
viam_client = await connect()
# Instantiate a DataClient to run data client API methods on
data_client = viam_client.data_client
viam_client.close()
if __name__ == '__main__':
asyncio.run(main())
Once you have instantiated a DataClient
, you can run API methods against the DataClient
object (named data_client
in the examples).
API
BinaryDataCaptureUpload
Upload binary data collected on your machine through a specific component and the relevant metadata to the Viam app. Uploaded binary data can be found under the Images, Point clouds, or Files subtab of the app’s Data tab, depending on the type of data that you upload.
Parameters:
binary_data
(bytes) (required): The data to be uploaded, represented in bytes.part_id
(str) (required): Part ID of the component used to capture the data.component_type
(str) (required): Type of the component used to capture the data (for example, “movement_sensor”).component_name
(str) (required): Name of the component used to capture the data.method_name
(str) (required): Name of the method used to capture the data.file_extension
(str) (required): The file extension of binary data including the period, for example .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
(Mapping[str, Any]) (optional): Optional dictionary of method parameters. No longer in active use.tags
(List[str]) (optional): Optional list of tags to allow for tag-based data filtering when retrieving data.data_request_times
(Tuple[datetime.datetime, datetime.datetime]) (optional): Optional tuple containing datetime objects denoting the times this data was requested[0] by the robot and received[1] from the appropriate sensor.
Returns:
- (str): The file_id of the uploaded data.
Raises:
- (GRPCError): If an invalid part ID is passed.
Example:
time_requested = datetime(2023, 6, 5, 11)
time_received = datetime(2023, 6, 5, 11, 0, 3)
file_id = await data_client.binary_data_capture_upload(
part_id="INSERT YOUR PART ID",
component_type='camera',
component_name='my_camera',
method_name='GetImages',
method_parameters=None,
tags=["tag_1", "tag_2"],
data_request_times=[time_requested, time_received],
file_extension=".jpg",
binary_data=b"Encoded image bytes"
)
For more information, see the Python SDK Docs.
TabularDataCaptureUpload
Upload tabular data collected on your machine through a specific component to the Viam app. Uploaded tabular data can be found under the Sensors subtab of the app’s Data tab.
Parameters:
tabular_data
(List[Mapping[str, Any]]) (required): List of the data to be uploaded, represented tabularly as a collection of dictionaries.part_id
(str) (required): Part ID of the component used to capture the data.component_type
(str) (required): Type of the component used to capture the data (for example, “rdk:component:movement_sensor”).component_name
(str) (required): Name of the component used to capture the data.method_name
(str) (required): Name of the method used to capture the data.data_request_times
(List[Tuple[datetime.datetime, datetime.datetime]]) (required): 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.method_parameters
(Mapping[str, Any]) (optional): Optional dictionary of method parameters. No longer in active use.tags
(List[str]) (optional): Optional list of tags to allow for tag-based data filtering when retrieving data.
Returns:
- (str): The file_id of the uploaded data.
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.
Example:
time_requested = datetime(2023, 6, 5, 11)
time_received = datetime(2023, 6, 5, 11, 0, 3)
file_id = await data_client.tabular_data_capture_upload(
part_id="INSERT YOUR PART ID",
component_type='rdk:component:motor',
component_name='left_motor',
method_name='IsPowered',
tags=["tag_1", "tag_2"],
data_request_times=[(time_requested, time_received)],
tabular_data=[{'PowerPCT': 0, 'IsPowered': False}]
)
For more information, see the Python SDK Docs.
FileUpload
Upload arbitrary files stored on your machine to the Viam app by file name.
If uploaded with a file extension of
Parameters:
part_id
(str) (required): Part ID of the resource associated with the file.data
(bytes) (required): Bytes representing file data to upload.component_type
(str) (optional): Optional type of the component associated with the file (for example, “movement_sensor”).component_name
(str) (optional): Optional name of the component associated with the file.method_name
(str) (optional): Optional name of the method associated with the file.file_name
(str) (optional): Optional name of the file. The empty string “” will be assigned as the file name if one isn’t provided.method_parameters
(Mapping[str, Any]) (optional): Optional dictionary of the method parameters. No longer in active use.file_extension
(str) (optional): 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
(List[str]) (optional): Optional list of tags to allow for tag-based filtering when retrieving data.
Returns:
- (str): ID of the new file.
Raises:
- (GRPCError): If an invalid part ID is passed.
Example:
file_id = await data_client.file_upload(
data=b"Encoded image bytes",
part_id="INSERT YOUR PART ID",
tags=["tag_1", "tag_2"],
file_name="your-file",
file_extension=".txt"
)
For more information, see the Python SDK Docs.
FileUploadFromPath
Upload files stored on your machine to the Viam app by filepath. Uploaded files can be found under the Files subtab of the app’s Data tab.
Parameters:
filepath
(str) (required): Absolute filepath of file to be uploaded.part_id
(str) (required): Part ID of the component associated with the file.component_type
(str) (optional): Optional type of the component associated with the file (for example, “movement_sensor”).component_name
(str) (optional): Optional name of the component associated with the file.method_name
(str) (optional): Optional name of the method associated with the file.method_parameters
(Mapping[str, Any]) (optional): Optional dictionary of the method parameters. No longer in active use.tags
(List[str]) (optional): Optional list of tags to allow for tag-based filtering when retrieving data.
Returns:
- (str): ID of the new file.
Raises:
- (GRPCError): If an invalid part ID is passed.
- (FileNotFoundError): If the provided filepath is not found.
Example:
file_id = await data_client.file_upload_from_path(
part_id="INSERT YOUR PART ID",
tags=["tag_1", "tag_2"],
filepath="/Users/<your-username>/<your-directory>/<your-file.txt>"
)
For more information, see the Python SDK Docs.
StreamingDataCaptureUpload
Upload the contents of streaming binary data and the relevant metadata to the Viam app. Uploaded streaming data can be found under the Data tab.
Parameters:
data
(bytes) (required): the data to be uploaded.part_id
(str) (required): Part ID of the resource associated with the file.file_ext
(str) (required): file extension type for the data. required for determining MIME type.component_type
(str) (optional): Optional type of the component associated with the file (for example, “movement_sensor”).component_name
(str) (optional): Optional name of the component associated with the file.method_name
(str) (optional): Optional name of the method associated with the file.method_parameters
(Mapping[str, Any]) (optional): Optional dictionary of the method parameters. No longer in active use.data_request_times
(Tuple[datetime.datetime, datetime.datetime]) (optional): Optional tuple containing datetime objects denoting the times this data was requested[0] by the robot and received[1] from the appropriate sensor.tags
(List[str]) (optional): Optional list of tags to allow for tag-based filtering when retrieving data.
Returns:
- (str): The file_id of the uploaded data.
Raises:
- (GRPCError): If an invalid part ID is passed.
Example:
time_requested = datetime(2023, 6, 5, 11)
time_received = datetime(2023, 6, 5, 11, 0, 3)
file_id = await data_client.streaming_data_capture_upload(
data="byte-data-to-upload",
part_id="INSERT YOUR PART ID",
file_ext="png",
component_type='motor',
component_name='left_motor',
method_name='IsPowered',
data_request_times=[time_requested, time_received],
tags=["tag_1", "tag_2"]
)
For more information, see the Python SDK Docs.
TabularDataByFilter
Retrieve optionally filtered tabular data from the Viam app. You can also find your tabular data under the Sensors subtab of the app’s Data tab.
Parameters:
filter
(viam.proto.app.data.Filter) (optional): Optional Filter specifying tabular data to retrieve. No Filter implies all tabular data.limit
(int) (optional): The maximum number of entries to include in a page. Defaults to 50 if unspecified.sort_order
(viam.proto.app.data.Order.ValueType) (optional): The desired sort order of the data.last
(str) (optional): Optional string indicating the object identifier of the last-returned data. This object identifier is returned by calls toTabularDataByFilter
as the last value. If provided, the server will return the next data entries after the last object identifier.count_only
(bool) (required): Whether to return only the total count of entries.include_internal_data
(bool) (required): Whether to return the internal data. Internal data is used for Viam-specific data ingestion, like cloud SLAM. Defaults to False.dest
(str) (optional): Optional filepath for writing retrieved data.
Returns:
- (Tuple[List[TabularData], int, str]): A tuple containing the following: List[TabularData]: The tabular data, int: The count (number of entries), str: The last-returned page ID.
Example:
from viam.utils import create_filter
my_data = []
my_filter = create_filter(component_name="motor-1")
last = None
while True:
tabular_data, count, last = await data_client.tabular_data_by_filter(my_filter, last=last)
if not tabular_data:
break
my_data.extend(tabular_data)
print(f"My data: {my_data}")
For more information, see the Python SDK Docs.
TabularDataBySQL
Obtain unified tabular data and metadata, queried with SQL.
Parameters:
organization_id
(str) (required): The ID of the organization that owns the data. You can obtain your organization ID from the Viam app’s organization settings page.sql_query
(str) (required): The SQL query to run.
Returns:
- (List[Dict[str, viam.utils.ValueTypes | datetime.datetime]]): An array of decoded BSON data objects.
Example:
data = await data_client.tabular_data_by_sql(
organization_id="<YOUR-ORG-ID>",
sql_query="SELECT * FROM readings LIMIT 5"
)
For more information, see the Python SDK Docs.
TabularDataByMQL
Obtain unified tabular data and metadata, queried with MQL.
Parameters:
organization_id
(str) (required): The ID of the organization that owns the data. You can obtain your organization ID from the Viam app’s organization settings page.mql_binary
(List[bytes]) (required): The MQL query to run as a list of BSON queries. You can encode your bson queries using a library like pymongo.
Returns:
- (List[Dict[str, viam.utils.ValueTypes | datetime.datetime]]): An array of decoded BSON data objects.
Example:
import bson
# using pymongo package (pip install pymongo)
tabular_data = await data_client.tabular_data_by_mql(organization_id="<YOUR-ORG-ID>", mql_binary=[
bson.encode({ '$match': { 'location_id': '<YOUR-LOCATION-ID>' } }),
bson.encode({ "$limit": 5 })
])
print(f"Tabular Data: {tabular_data}")
For more information, see the Python SDK Docs.
BinaryDataByFilter
Retrieve optionally filtered binary data from the Viam app. You can also find your binary data under the Images, Point clouds, or Files subtab of the app’s Data tab, depending on the type of data that you have uploaded.
Parameters:
filter
(viam.proto.app.data.Filter) (optional): Optional Filter specifying tabular data to retrieve. No Filter implies all binary data.limit
(int) (optional): The maximum number of entries to include in a page. Defaults to 50 if unspecified.sort_order
(viam.proto.app.data.Order.ValueType) (optional): The desired sort order of the data.last
(str) (optional): Optional string indicating the object identifier of the last-returned data. This object identifier is returned by calls toBinaryDataByFilter
as the last value. If provided, the server will return the next data entries after the last object identifier.include_binary_data
(bool) (required): Boolean specifying whether to actually include the binary file data with each retrieved file. Defaults to true (that is, both the files’ data and metadata are returned).count_only
(bool) (required): Whether to return only the total count of entries.include_internal_data
(bool) (required): Whether to return the internal data. Internal data is used for Viam-specific data ingestion, like cloud SLAM. Defaults to False.dest
(str) (optional): Optional filepath for writing retrieved data.
Returns:
- (Tuple[List[viam.proto.app.data.BinaryData], int, str]): A tuple containing the following: List[viam.proto.app.data.BinaryData]: The binary data, int: The count (number of entries), str: The last-returned page ID.
Example:
from viam.utils import create_filter
from viam.proto.app.data import Filter, TagsFilter, TagsFilterType
# Get data captured from camera components
my_data = []
last = None
my_filter = create_filter(component_name="camera-1")
while True:
data, count, last = await data_client.binary_data_by_filter(
my_filter, limit=1, last=last)
if not data:
break
my_data.extend(data)
print(f"My data: {my_data}")
# Get untagged data from a dataset
my_untagged_data = []
last = None
tags_filter = TagsFilter(type=TagsFilterType.TAGS_FILTER_TYPE_UNTAGGED)
my_filter = Filter(
dataset_id="66db6fe7d93d1ade24cd1dc3",
tags_filter=tags_filter
)
while True:
data, count, last = await data_client.binary_data_by_filter(
my_filter, last=last, include_binary_data=False)
if not data:
break
my_untagged_data.extend(data)
For more information, see the Python SDK Docs.
BinaryDataByIDs
Retrieve binary data from the Viam app by BinaryID
.
You can also find your binary data under the Images, Point clouds, or Files subtab of the app’s Data tab, depending on the type of data that you have uploaded.
Parameters:
binary_ids
(List[viam.proto.app.data.BinaryID]) (required): BinaryID objects specifying the desired data. Must be non-empty.dest
(str) (optional): Optional filepath for writing retrieved data.
Returns:
- (List[viam.proto.app.data.BinaryData]): The binary data.
Raises:
- (GRPCError): If no BinaryID objects are provided.
Example:
from viam.proto.app.data import BinaryID
binary_metadata, count, last = await data_client.binary_data_by_filter(
include_binary_data=False
)
my_ids = []
for obj in binary_metadata:
my_ids.append(
BinaryID(
file_id=obj.metadata.id,
organization_id=obj.metadata.capture_metadata.organization_id,
location_id=obj.metadata.capture_metadata.location_id
)
)
binary_data = await data_client.binary_data_by_ids(my_ids)
For more information, see the Python SDK Docs.
DeleteTabularData
Delete tabular data older than a specified number of days.
Parameters:
organization_id
(str) (required): ID of organization to delete data from. You can obtain your organization ID from the Viam app’s organization settings page.delete_older_than_days
(int) (required): 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.
Returns:
- (int): The number of items deleted.
Example:
tabular_data = await data_client.delete_tabular_data(
organization_id="<YOUR-ORG-ID>",
delete_older_than_days=150
)
For more information, see the Python SDK Docs.
DeleteBinaryDataByFilter
Filter and delete binary data.
Parameters:
filter
(viam.proto.app.data.Filter) (optional): Optional Filter specifying binary data to delete. Passing an empty Filter will lead to all data being deleted. Exercise caution when using this option. You must specify an organization ID with “organization_ids” when using this option.
Returns:
- (int): The number of items deleted.
Example:
from viam.utils import create_filter
my_filter = create_filter(component_name="left_motor", organization_ids=["<YOUR-ORG-ID>"])
res = await data_client.delete_binary_data_by_filter(my_filter)
For more information, see the Python SDK Docs.
DeleteBinaryDataByIDs
Filter and delete binary data by ids.
Parameters:
binary_ids
(List[viam.proto.app.data.BinaryID]) (required): BinaryID objects specifying the data to be deleted. Must be non-empty.
Returns:
- (int): The number of items deleted.
Raises:
- (GRPCError): If no BinaryID objects are provided.
Example:
from viam.proto.app.data import BinaryID
from viam.utils import create_filter
my_filter = create_filter(component_name="camera-1", organization_ids=["<YOUR-ORG-ID>"])
binary_metadata, count, last = await data_client.binary_data_by_filter(
filter=my_filter,
limit=20,
include_binary_data=False
)
my_ids = []
for obj in binary_metadata:
my_ids.append(
BinaryID(
file_id=obj.metadata.id,
organization_id=obj.metadata.capture_metadata.organization_id,
location_id=obj.metadata.capture_metadata.location_id
)
)
binary_data = await data_client.delete_binary_data_by_ids(my_ids)
For more information, see the Python SDK Docs.
AddTagsToBinaryDataByIDs
Add tags to binary data by ids.
Parameters:
tags
(List[str]) (required): List of tags to add to specified binary data. Must be non-empty.binary_ids
(List[viam.proto.app.data.BinaryID]) (required): List of BinaryID objects specifying binary data to tag. Must be non-empty.
Returns:
- None.
Raises:
- (GRPCError): If no BinaryID objects or tags are provided.
Example:
from viam.proto.app.data import BinaryID
from viam.utils import create_filter
tags = ["tag1", "tag2"]
my_filter = create_filter(component_name="camera-1", organization_ids=["<YOUR-ORG-ID>"])
binary_metadata, count, last = await data_client.binary_data_by_filter(
filter=my_filter,
limit=20,
include_binary_data=False
)
my_ids = []
for obj in binary_metadata:
my_ids.append(
BinaryID(
file_id=obj.metadata.id,
organization_id=obj.metadata.capture_metadata.organization_id,
location_id=obj.metadata.capture_metadata.location_id
)
)
binary_data = await data_client.add_tags_to_binary_data_by_ids(tags, my_ids)
For more information, see the Python SDK Docs.
AddTagsToBinaryDataByFilter
Add tags to binary data by filter.
Parameters:
tags
(List[str]) (required): List of tags to add to specified binary data. Must be non-empty.filter
(viam.proto.app.data.Filter) (optional): Filter specifying binary data to tag. If no Filter is provided, all data will be tagged.
Returns:
- None.
Raises:
- (GRPCError): If no tags are provided.
Example:
from viam.utils import create_filter
my_filter = create_filter(component_name="my_camera")
tags = ["tag1", "tag2"]
await data_client.add_tags_to_binary_data_by_filter(tags, my_filter)
For more information, see the Python SDK Docs.
RemoveTagsFromBinaryDataByIDs
Remove tags from binary by ids.
Parameters:
tags
(List[str]) (required): List of tags to remove from specified binary data. Must be non-empty.binary_ids
(List[viam.proto.app.data.BinaryID]) (required): List of BinaryID objects specifying binary data to untag. Must be non-empty.
Returns:
- (int): The number of tags removed.
Raises:
- (GRPCError): If no binary_ids or tags are provided.
Example:
from viam.proto.app.data import BinaryID
from viam.utils import create_filter
tags = ["tag1", "tag2"]
my_filter = create_filter(component_name="camera-1")
binary_metadata, count, last = await data_client.binary_data_by_filter(
filter=my_filter,
limit=50,
include_binary_data=False
)
my_ids = []
for obj in binary_metadata:
my_ids.append(
BinaryID(
file_id=obj.metadata.id,
organization_id=obj.metadata.capture_metadata.organization_id,
location_id=obj.metadata.capture_metadata.location_id
)
)
binary_data = await data_client.remove_tags_from_binary_data_by_ids(
tags, my_ids)
For more information, see the Python SDK Docs.
RemoveTagsFromBinaryDataByFilter
Remove tags from binary data by filter.
Parameters:
tags
(List[str]) (required): List of tags to remove from specified binary data.filter
(viam.proto.app.data.Filter) (optional): Filter specifying binary data to untag. If no Filter is provided, all data will be untagged.
Returns:
- (int): The number of tags removed.
Raises:
- (GRPCError): If no tags are provided.
Example:
from viam.utils import create_filter
my_filter = create_filter(component_name="my_camera")
tags = ["tag1", "tag2"]
res = await data_client.remove_tags_from_binary_data_by_filter(tags, my_filter)
For more information, see the Python SDK Docs.
TagsByFilter
Get a list of tags using a filter.
Parameters:
filter
(viam.proto.app.data.Filter) (optional): Filter specifying data to retrieve from. If no Filter is provided, all data tags will return.
Returns:
- (List[str]): The list of tags.
Example:
from viam.utils import create_filter
my_filter = create_filter(component_name="my_camera")
tags = await data_client.tags_by_filter(my_filter)
For more information, see the Python SDK Docs.
AddBoundingBoxToImageByID
Add a bounding box to an image specified by its BinaryID.
Parameters:
binary_id
(viam.proto.app.data.BinaryID) (required): The ID of the image to add the bounding box to.label
(str) (required): A label for the bounding box.x_min_normalized
(float) (required): Min X value of the bounding box normalized from 0 to 1.y_min_normalized
(float) (required): Min Y value of the bounding box normalized from 0 to 1.x_max_normalized
(float) (required): Max X value of the bounding box normalized from 0 to 1.y_max_normalized
(float) (required): Max Y value of the bounding box normalized from 0 to 1.
Returns:
- (str): The bounding box ID.
Raises:
- (GRPCError): If the X or Y values are outside of the [0, 1] range.
Example:
from viam.proto.app.data import BinaryID
MY_BINARY_ID = BinaryID(
file_id="<YOUR-FILE-ID>",
organization_id="<YOUR-ORG-ID>",
location_id="<YOUR-LOCATION-ID>"
)
bbox_id = await data_client.add_bounding_box_to_image_by_id(
binary_id=MY_BINARY_ID,
label="label",
x_min_normalized=0,
y_min_normalized=.1,
x_max_normalized=.2,
y_max_normalized=.3
)
print(bbox_id)
For more information, see the Python SDK Docs.
RemoveBoundingBoxFromImageByID
Removes a bounding box from an image specified by its BinaryID.
Parameters:
bbox_id
(str) (required): The ID of the bounding box to remove.binary_id
(viam.proto.app.data.BinaryID) (required): Binary ID of the image to remove the bounding box from.
Returns:
- None.
Example:
from viam.proto.app.data import BinaryID
MY_BINARY_ID = BinaryID(
file_id=your-file_id,
organization_id=your-org-id,
location_id=your-location-id
)
await data_client.remove_bounding_box_from_image_by_id(
binary_id=MY_BINARY_ID,
bbox_id="your-bounding-box-id-to-delete"
)
For more information, see the Python SDK Docs.
BoundingBoxLabelsByFilter
Get a list of bounding box labels using a Filter.
Parameters:
filter
(viam.proto.app.data.Filter) (optional): Filter specifying data to retrieve from. If no Filter is provided, all labels will return.
Returns:
- (List[str]): The list of bounding box labels.
Example:
from viam.utils import create_filter
my_filter = create_filter(component_name="my_camera")
bounding_box_labels = await data_client.bounding_box_labels_by_filter(
my_filter)
print(bounding_box_labels)
For more information, see the Python SDK Docs.
GetDatabaseConnection
Get a connection to access a MongoDB Atlas Data federation instance.
Parameters:
organization_id
(str) (required): Organization to retrieve the connection for. You can obtain your organization ID from the Viam app’s organization settings page.
Returns:
- (str): The hostname of the federated database.
Example:
hostname = await data_client.get_database_connection(organization_id="<YOUR-ORG-ID>")
For more information, see the Python SDK Docs.
ConfigureDatabaseUser
Configure a database user for the Viam organization’s MongoDB Atlas Data Federation instance. It can also be used to reset the password of the existing database user.
Parameters:
organization_id
(str) (required): The ID of the organization. You can obtain your organization ID from the Viam app’s organization settings page.password
(str) (required): The password of the user.
Returns:
- None.
Example:
await data_client.configure_database_user(
organization_id="<YOUR-ORG-ID>",
password="Your_Password@1234"
)
For more information, see the Python SDK Docs.
AddBinaryDataToDatasetByIDs
Add the BinaryData
to the provided dataset.
This BinaryData will be tagged with the VIAM_DATASET_{id} label.
Parameters:
binary_ids
(List[viam.proto.app.data.BinaryID]) (required): The IDs of binary data to add to dataset. To retrieve these IDs, navigate to your dataset’s page in the Viam app, click … in the left-hand menu, and click Copy dataset ID.dataset_id
(str) (required): The ID of the dataset to be added to.
Returns:
- None.
Example:
from viam.proto.app.data import BinaryID
binary_metadata, count, last = await data_client.binary_data_by_filter(
include_binary_data=False
)
my_binary_ids = []
for obj in binary_metadata:
my_binary_ids.append(
BinaryID(
file_id=obj.metadata.id,
organization_id=obj.metadata.capture_metadata.organization_id,
location_id=obj.metadata.capture_metadata.location_id
)
)
await data_client.add_binary_data_to_dataset_by_ids(
binary_ids=my_binary_ids,
dataset_id="abcd-1234xyz-8765z-123abc"
)
For more information, see the Python SDK Docs.
RemoveBinaryDataFromDatasetByIDs
Remove the BinaryData from the provided dataset. This BinaryData will lose the VIAM_DATASET_{id} tag.
Parameters:
binary_ids
(List[viam.proto.app.data.BinaryID]) (required): The IDs of binary data to remove from dataset. To retrieve these IDs, navigate to your dataset’s page in the Viam app, click … in the left-hand menu, and click Copy dataset ID.dataset_id
(str) (required): The ID of the dataset to be removed from.
Returns:
- None.
Example:
from viam.proto.app.data import BinaryID
binary_metadata, count, last = await data_client.binary_data_by_filter(
include_binary_data=False
)
my_binary_ids = []
for obj in binary_metadata:
my_binary_ids.append(
BinaryID(
file_id=obj.metadata.id,
organization_id=obj.metadata.capture_metadata.organization_id,
location_id=obj.metadata.capture_metadata.location_id
)
)
await data_client.remove_binary_data_from_dataset_by_ids(
binary_ids=my_binary_ids,
dataset_id="abcd-1234xyz-8765z-123abc"
)
For more information, see the Python SDK Docs.
CreateDataset
Create a new dataset.
Parameters:
name
(str) (required): The name of the dataset being created.organization_id
(str) (required): The ID of the organization where the dataset is being created. You can obtain your organization ID from the Viam app’s organization settings page.
Returns:
- (str): The dataset ID of the created dataset.
Example:
dataset_id = await data_client.create_dataset(
name="<DATASET-NAME>",
organization_id="<YOUR-ORG-ID>"
)
print(dataset_id)
For more information, see the Python SDK Docs.
DeleteDataset
Delete a dataset.
Parameters:
id
(str) (required): The ID of the dataset. You can retrieve this by navigating to the DATASETS sub-tab of the DATA tab, clicking on the dataset, clicking the … menu and selecting Copy dataset ID.
Returns:
- None.
Example:
await data_client.delete_dataset(
id="<YOUR-DATASET-ID>"
)
For more information, see the Python SDK Docs.
RenameDataset
Rename a dataset specified by the dataset ID.
Parameters:
id
(str) (required): The ID of the dataset. You can retrieve this by navigating to the DATASETS sub-tab of the DATA tab, clicking on the dataset, clicking the … menu and selecting Copy dataset ID.name
(str) (required): The new name of the dataset.
Returns:
- None.
Example:
await data_client.rename_dataset(
id="<YOUR-DATASET-ID>",
name="MyDataset"
)
For more information, see the Python SDK Docs.
ListDatasetsByOrganizationID
Get the datasets in an organization.
Parameters:
organization_id
(str) (required): The ID of the organization. You can obtain your organization ID from the Viam app’s organization settings page.
Returns:
- (Sequence[viam.proto.app.dataset.Dataset]): The list of datasets in the organization.
Example:
datasets = await data_client.list_datasets_by_organization_id(
organization_id="<YOUR-ORG-ID>"
)
print(datasets)
For more information, see the Python SDK Docs.
ListDatasetsByIDs
Get a list of datasets using their IDs.
Parameters:
ids
(List[str]) (required): The IDs of the datasets being called for. To retrieve these IDs, navigate to your dataset’s page in the Viam app, click … in the left-hand menu, and click Copy dataset ID.
Returns:
- (Sequence[viam.proto.app.dataset.Dataset]): The list of datasets.
Example:
datasets = await data_client.list_dataset_by_ids(
ids=["<YOUR-DATASET-ID-1>, <YOUR-DATASET-ID-2>"]
)
print(datasets)
For more information, see the Python SDK Docs.
Find part ID
To copy the ID of your machine part, select the part status dropdown to the right of your machine’s location and name on the top of its page and click the copy icon next to Part ID.
For example:
Have questions, or want to meet other people working on robots? Join our Community Discord.
If you notice any issues with the documentation, feel free to file an issue or edit this file.
Was this page helpful?
Glad to hear it! If you have any other feedback please let us know:
We're sorry about that. To help us improve, please tell us what we can do better:
Thank you!