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.

The data client API supports the following methods:

Methods to upload data like images or sensor readings directly to the Viam app:

Method NameDescription
BinaryDataCaptureUploadUpload binary data collected on your machine through a specific component and the relevant metadata to the Viam app.
TabularDataCaptureUploadUpload tabular data collected on your machine through a specific component to the Viam app.
FileUploadUpload arbitrary files stored on your machine to the Viam app by file name.
FileUploadFromPathUpload files stored on your machine to the Viam app by filepath.
StreamingDataCaptureUploadUpload 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 NameDescription
GetLatestTabularDataGets the most recent tabular data captured from the specified data source, as long as it was synced within the last year.
ExportTabularDataObtain unified tabular data and metadata from the specified data source.
TabularDataByFilterRetrieve optionally filtered tabular data from the Viam app.
TabularDataBySQLObtain unified tabular data and metadata, queried with SQL. Make sure your API key has permissions at the organization level in order to use this.
TabularDataByMQLObtain unified tabular data and metadata, queried with MQL.
BinaryDataByFilterRetrieve optionally filtered binary data from the Viam app.
BinaryDataByIDsRetrieve binary data from the Viam app by BinaryID.
DeleteTabularDataDelete tabular data older than a specified number of days.
DeleteBinaryDataByFilterFilter and delete binary data.
DeleteBinaryDataByIDsFilter and delete binary data by ids.
AddTagsToBinaryDataByIDsAdd tags to binary data by ids.
AddTagsToBinaryDataByFilterAdd tags to binary data by filter.
RemoveTagsFromBinaryDataByIDsRemove tags from binary by ids.
RemoveTagsFromBinaryDataByFilterRemove tags from binary data by filter.
TagsByFilterGet a list of tags using a filter.
AddBoundingBoxToImageByIDAdd a bounding box to an image specified by its BinaryID.
RemoveBoundingBoxFromImageByIDRemoves a bounding box from an image specified by its BinaryID.
BoundingBoxLabelsByFilterGet a list of bounding box labels using a Filter.
GetDatabaseConnectionGet a connection to access a MongoDB Atlas Data federation instance.
ConfigureDatabaseUserConfigure a database user for the Viam organization’s MongoDB Atlas Data Federation instance.
AddBinaryDataToDatasetByIDsAdd the BinaryData to the provided dataset.
RemoveBinaryDataFromDatasetByIDsRemove the BinaryData from the provided dataset.

Methods to work with datasets:

Method NameDescription
CreateDatasetCreate a new dataset.
DeleteDatasetDelete a dataset.
RenameDatasetRename a dataset specified by the dataset ID.
ListDatasetsByOrganizationIDGet the datasets in an organization.
ListDatasetsByIDsGet 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.

Parameters:

Returns:

Example:

_viam = await Viam.withApiKey(
     dotenv.env['API_KEY_ID'] ?? '',
     dotenv.env['API_KEY'] ?? ''
 );
 final dataClient = _viam.dataClient;

 try {
   final imageBytes = getPNGasBytes(); // Replace with your image bytes getter

   (DateTime, DateTime) dataRequestTimes = (
     DateTime(2025, 1, 15, 10, 30), // Start time
     DateTime(2025, 1, 15, 14, 45)  // End time
   );

   final fileId = await dataClient.binaryDataCaptureUpload(
     imageBytes,
     "<YOUR-PART-ID>",
     ".png",
     componentType: "rdk:component:camera",
     componentName: "camera-1",
     methodName: "ReadImage",
     dataRequestTimes: dataRequestTimes);

   print('Successfully uploaded binary data with fileId: $fileId');
 } catch (e) {
   print('Error uploading binary data: $e');
 }

For more information, see the Flutter 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. Must include the key “readings” for sensors.
  • 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:

from datetime import datetime

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:movement_sensor',
    component_name='my_movement_sensor',
    method_name='Readings',
    tags=["sensor_data"],
    data_request_times=[(time_requested, time_received)],
    tabular_data=[{
        'readings': {
            'linear_velocity': {'x': 0.5, 'y': 0.0, 'z': 0.0},
            'angular_velocity': {'x': 0.0, 'y': 0.0, 'z': 0.1}
        }
    }]
)

For more information, see the Python SDK Docs.

Parameters:

Returns:

Example:

_viam = await Viam.withApiKey(
     dotenv.env['API_KEY_ID'] ?? '',
     dotenv.env['API_KEY'] ?? ''
 );

 try {
   // Define tabular data
   final List<Map<String, dynamic>> tabularData;
   tabularData = [{
     'readings': {
       "altitude_m": 50.2,
       "coordinate": {
         "latitude": 40.5,
         "longitude": -72.98
      }
     }
   }];

  // Define date request times
  final List<(DateTime, DateTime)> timeSpan = [(DateTime(2025, 1, 23, 11), DateTime(2025, 1, 23, 11, 0, 3))];

  // Upload captured tabular data
  final fileId = await dataClient.tabularDataCaptureUpload(
    tabularData,
    "<YOUR-PART-ID>",
    componentType: "rdk:component:movement_sensor",
    componentName: "movement_sensor-1",
    methodName: "Position",
    dataRequestTimes: timeSpan,
    tags: ["tag_1", "tag_2"]
  );
   print('Successfully uploaded captured tabular data: $fileId');
 } catch (e) {
   print('Error uploading captured tabular data: $e');
 }

For more information, see the Flutter SDK Docs.

FileUpload

Upload arbitrary files stored on your machine to the Viam app by file name. If uploaded with a file extension of .jpeg/.jpg/.png, uploaded files can be found in the Images subtab of the app’s Data tab. If .pcd, the uploaded files can be found in the Point clouds subtab. All other types of uploaded files can be found under the Files subtab of the app’s Data tab.

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.

Parameters:

Returns:

Example:

import 'package:file_picker/file_picker.dart';
import 'package:cross_file/cross_file.dart';

_viam = await Viam.withApiKey(
     dotenv.env['API_KEY_ID'] ?? '',
     dotenv.env['API_KEY'] ?? ''
);
final dataClient = _viam.dataClient;

// File picker function
Future<XFile?> pickTextFile() async {
  FilePickerResult? result = await FilePicker.platform.pickFiles(
    type: FileType.custom,
    allowedExtensions: ['txt', 'md', 'json', 'csv'],  // Add any other text file extensions you want to support
  );
 if (result != null) {
   return XFile(result.files.single.path!);
 }
   return null;
 }

// Upload text file function. Call this in onPressed in a button in your application.
Future<void> uploadTextFile() async {
  final file = await pickTextFile();
  if (file == null) return;

  try {
    // Get file name
    final fileName = file.name;

    // Upload the file
    final result = await _viam.dataClient.uploadFile(
      file.path,
      fileName: fileName,
      "<YOUR-PART-ID>",
      tags: ["text_file", "document"]
    );
    print('Upload success: $result');
  } catch (e) {
    print('Upload error: $e');
  }
 }

For more information, see the Flutter 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.

Parameters:

Returns:

Example:

import 'package:file_picker/file_picker.dart';
import 'dart:typed_data';

Future<Uint8List> pickVideoAsBytes() async {
  try {
    // Open file picker
    FilePickerResult? result = await FilePicker.platform.pickFiles(
      type: FileType.video,
      allowMultiple: false,
    );

    if (result == null || result.files.isEmpty) {
      throw Exception('No file selected');
    }

    // For mobile, we get the file path and read it
    final String? filePath = result.files.first.path;
    if (filePath == null) {
      throw Exception('Invalid file path');
    }

    // Read the file as bytes
    final File file = File(filePath);
    final Uint8List bytes = await file.readAsBytes();

    if (bytes.isEmpty) {
      throw Exception('File is empty');
    }

    print('Successfully read file: ${bytes.length} bytes');

    return bytes;
  } catch (e, stackTrace) {
    print('Error picking video: $e');
    print('Stack trace: $stackTrace');
    rethrow;
  }
}

void _uploadData() async {
  _viam = await Viam.withApiKey(
       dotenv.env['API_KEY_ID'] ?? '',
       dotenv.env['API_KEY'] ?? ''
   );
   final dataClient = _viam.dataClient;

   try {
     Uint8List video = await pickVideoAsBytes();

     (DateTime, DateTime) dataRequestTimes = (
       DateTime(2025, 1, 15, 10, 30), // Start time
       DateTime(2025, 1, 15, 14, 45)  // End time
     );

     final fileId = await dataClient.streamingDataCaptureUpload(
       video,
       "<YOUR-PART-ID>",
       ".mp4", // Replace with your desired file format
       componentType: "rdk:component:camera",
       componentName: "camera-1",
       dataRequestTimes: dataRequestTimes);

     print('Successfully uploaded streaming binary data with fileId: $fileId');
   } catch (e) {
     print('Error uploading streaming binary data: $e');
   }
}

For more information, see the Flutter SDK Docs.

GetLatestTabularData

Gets the most recent tabular data captured from the specified data source, as long as it was synced within the last year.

Parameters:

  • part_id (str) (required): The ID of the part that owns the data.
  • resource_name (str) (required): The name of the requested resource that captured the data. Ex: “my-sensor”.
  • resource_api (str) (required): The API of the requested resource that captured the data. Ex: “rdk:component:sensor”.
  • method_name (str) (required): The data capture method name. Ex: “Readings”.

Returns:

  • (Tuple[datetime.datetime, datetime.datetime, Dict[str, viam.utils.ValueTypes]] | None): A return value of None means that data hasn’t been synced yet for the data source or the most recently captured data was over a year ago, otherwise the returned tuple contains the following: datetime: The time captured, datetime: The time synced, Dict[str, ValueTypes]: The latest tabular data captured from the specified data source.

Example:

tabular_data = await data_client.get_latest_tabular_data(
    part_id="77ae3145-7b91-123a-a234-e567cdca8910",
    resource_name="camera-1",
    resource_api="rdk:component:camera",
    method_name="GetImage"
)

if tabular_data:
    time_captured, time_synced, payload = tabular_data
    print(f"Time Captured: {time_captured}")
    print(f"Time Synced: {time_synced}")
    print(f"Payload: {payload}")
else:
    print(f"No data returned: {tabular_data}")

For more information, see the Python SDK Docs.

Parameters:

  • partId (string) (required): The ID of the part that owns the data.
  • resourceName (string) (required): The name of the requested resource that captured the data. Ex: “my-sensor”.
  • resourceSubtype (string) (required): The subtype of the requested resource that captured the data. Ex: “rdk:component:sensor”.
  • methodName (string) (required): The data capture method name. Ex: “Readings”.

Returns:

  • (Promise<null | [Date, Date, Record<string, JsonValue>]>): A tuple containing [timeCaptured, timeSynced, payload] or null if no data has been synced for the specified resource OR the most recently captured data was over a year ago.

For more information, see the TypeScript SDK Docs.

Parameters:

Returns:

Example:

_viam = await Viam.withApiKey(
     dotenv.env['API_KEY_ID'] ?? '',
     dotenv.env['API_KEY'] ?? ''
 );
 final dataClient = _viam.dataClient;

 try {
   // Get latest tabular data
   final response = await dataClient.getLatestTabularData(
     "<YOUR-PART-ID>",
     "movement_sensor-1",
     "rdk:component:movement_sensor",
     "Position"
   );
   print('Successfully retrieved latest tabular data: $response');
 } catch (e) {
   print('Error retrieving latest tabular data: $e');
 }

For more information, see the Flutter SDK Docs.

ExportTabularData

Obtain unified tabular data and metadata from the specified data source.

Parameters:

  • part_id (str) (required): The ID of the part that owns the data.
  • resource_name (str) (required): The name of the requested resource that captured the data.
  • resource_api (str) (required): The API of the requested resource that captured the data.
  • method_name (str) (required): The data capture method name.
  • start_time (datetime.datetime) (optional): Optional start time for requesting a specific range of data.
  • end_time (datetime.datetime) (optional): Optional end time for requesting a specific range of data.

Returns:

Example:

tabular_data = await data_client.export_tabular_data(
    part_id="<PART-ID>",
    resource_name="<RESOURCE-NAME>",
    resource_api="<RESOURCE-API>",
    method_name="<METHOD-NAME>",
    start_time="<START_TIME>"
    end_time="<END_TIME>"
)

print(f"My data: {tabular_data}")

For more information, see the Python SDK Docs.

Parameters:

  • partId (string) (required): The ID of the part that owns the data.
  • resourceName (string) (required): The name of the requested resource that captured the data.
  • resourceSubtype (string) (required): The subtype of the requested resource that captured the data.
  • methodName (string) (required): The data capture method name.
  • startTime (Date) (optional): Optional start time (Date object) for requesting a specific range of data.
  • endTime (Date) (optional): Optional end time (Date object) for requesting a specific range of data.

Returns:

  • (Promise<TabularDataPoint[]>): An array of unified tabular data and metadata.

For more information, see the TypeScript SDK Docs.

Parameters:

Returns:

Example:

 _viam = await Viam.withApiKey(
     dotenv.env['API_KEY_ID'] ?? '',
     dotenv.env['API_KEY'] ?? ''
 );
 final dataClient = _viam.dataClient;

 try {
  // Define date request times
  final startTime = DateTime(2025, 1, 23, 11);
  final endTime = DateTime(2025, 1, 23, 11, 0, 3);

  final tabularData = await dataClient.exportTabularData(
    "<YOUR-PART-ID>",
    "movement_sensor-1",
    "rdk:component:movement_sensor",
    "Position",
    startTime,
    endTime
  );

  for (var dataPoint in tabularData) {
    print(dataPoint.partId);
    print(dataPoint.resourceName);
    print(dataPoint.methodName);
    print(dataPoint.payload);
  }

  print('Successfully exported tabular data');
 } catch (e) {
  print('Error exporting tabular data: $e');
 }

For more information, see the Flutter 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 to TabularDataByFilter 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.

Parameters:

  • filter (Filter) (optional): Optional pb.Filter specifying tabular data to retrieve. No filter implies all tabular data.
  • limit (number) (optional): The maximum number of entries to include in a page. Defaults to 50 if unspecfied.
  • sortOrder (Order) (optional): The desired sort order of the data.
  • last (string) (optional): Optional string indicating the ID of the last-returned data. If provided, the server will return the next data entries after the last ID.
  • countOnly (boolean) (optional): Whether to return only the total count of entries.
  • includeInternalData (boolean) (optional): Whether to retun internal data. Internal data is used for Viam-specific data ingestion, like cloud SLAM. Defaults to false.

Returns:

  • (Promise<{ count: bigint; data: TabularData[]; last: string }>): An array of data objects, the count (number of entries), and the last-returned page ID.

For more information, see the TypeScript SDK Docs.

Parameters:

  • filter Filter? (optional)
  • limit int? (optional)
  • sortOrder Order? (optional)
  • last String? (optional)
  • countOnly dynamic (optional)

Returns:

Example:

_viam = await Viam.withApiKey(
    dotenv.env['API_KEY_ID'] ?? '',
    dotenv.env['API_KEY'] ?? ''
);
final dataClient = _viam.dataClient;

try {
 // Create a filter to target specific tabular data
 final filter = Filter(
  componentName: "arm-1",
 );

 final response = await dataClient.tabularDataByFilter(
   filter: filter,
   limit: 10
 );
 print('Number of items: ${response.count.toInt()}');
 print('Total size: ${response.totalSizeBytes.toInt()}');
 for (var metadata in response.metadata) {
   print(metadata);
 }
 for (var data in response.data) {
   print(data);
 }

 print('Successfully retrieved tabular data by filter');
} catch (e) {
 print('Error retrieving tabular data by filter: $e');
}

For more information, see the Flutter SDK Docs.

TabularDataBySQL

Obtain unified tabular data and metadata, queried with SQL. Make sure your API key has permissions at the organization level in order to use this.

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.

Parameters:

  • organizationId (string) (required): The ID of the organization that owns the data.
  • query (string) (required): The SQL query to run.

Returns:

  • (Promise<(Object | any[])[]>): An array of data objects.

For more information, see the TypeScript SDK Docs.

Parameters:

Returns:

Example:

// List<Map<String, dynamic>>? _responseData;

 _viam = await Viam.withApiKey(
     dotenv.env['API_KEY_ID'] ?? '',
     dotenv.env['API_KEY'] ?? ''
 );
 final dataClient = _viam.dataClient;

 // Example SQL query
 final sqlQuery = "SELECT * FROM readings LIMIT 5";

 _responseData = await dataClient.tabularDataBySql(
   "<YOUR-ORG-ID>",
   sqlQuery
 );

For more information, see the Flutter 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.
  • query (List[bytes] | List[Dict[str, Any]]) (required): The MQL query to run, as a list of MongoDB aggregation pipeline stages. Note: Each stage can be provided as either a dictionary or raw BSON bytes, but support for bytes will be removed in the future, so using a dictionary is preferred.
  • use_recent_data (bool) (optional): Whether to query blob storage or your recent data store. Defaults to False.

Returns:

  • (List[Dict[str, viam.utils.ValueTypes | datetime.datetime]]): An array of decoded BSON data objects.

Example:

import bson

tabular_data = await data_client.tabular_data_by_mql(organization_id="<YOUR-ORG-ID>", query=[
    { '$match': { 'location_id': '<YOUR-LOCATION-ID>' } },
    { "$limit": 5 }
])

print(f"Tabular Data: {tabular_data}")

For more information, see the Python SDK Docs.

Parameters:

  • organizationId (string) (required): The ID of the organization that owns the data.
  • query (Uint8Array) (required): The MQL query to run as a list of BSON documents.
  • useRecentData (boolean) (optional): Whether to query blob storage or your recent data store. Defaults to false.

Returns:

  • (Promise<(Object | any[])[]>): An array of data objects.

For more information, see the TypeScript SDK Docs.

Parameters:

  • organizationId String (required)
  • query dynamic (required)
  • useRecentData bool (optional)

Returns:

Example:

// import 'package:bson/bson.dart';

// List<Map<String, dynamic>>? _responseData;

 _viam = await Viam.withApiKey(
     dotenv.env['API_KEY_ID'] ?? '',
     dotenv.env['API_KEY'] ?? ''
 );
 final dataClient = _viam.dataClient;

 final query = BsonCodec.serialize({
  "\$match": {
     "location_id": "<YOUR-LOCATION-ID>",
  }
 });

 final sort = BsonCodec.serialize({
   "\$sort": {"time_requested": -1}
   sqlQuery
 });

 final limit = BsonCodec.serialize({"\$limit": 1});

 final pipeline = [query.byteList, sort.byteList, limit.byteList];
 _responseData = await dataClient.tabularDataByMql(
  "<YOUR-ORG-ID>",
  pipeline
 );

For more information, see the Flutter 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 to BinaryDataByFilter 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.

Parameters:

  • filter (Filter) (optional): Optional pb.Filter specifying binary data to retrieve. No filter implies all binary data.
  • limit (number) (optional): The maximum number of entries to include in a page. Defaults to 50 if unspecfied.
  • sortOrder (Order) (optional): The desired sort order of the data.
  • last (string) (optional): Optional string indicating the ID of the last-returned data. If provided, the server will return the next data entries after the last ID.
  • includeBinary (boolean) (optional): Whether to include binary file data with each retrieved file.
  • countOnly (boolean) (optional): Whether to return only the total count of entries.
  • includeInternalData (boolean) (optional): Whether to retun internal data. Internal data is used for Viam-specific data ingestion, like cloud SLAM. Defaults to false.

Returns:

  • (Promise<{ count: bigint; data: BinaryData[]; last: string }>): An array of data objects, the count (number of entries), and the last-returned page ID.

For more information, see the TypeScript SDK Docs.

Parameters:

  • filter Filter? (optional)
  • limit int? (optional)
  • sortOrder Order? (optional)
  • last String? (optional)
  • countOnly bool (optional)
  • includeBinary bool (optional)

Returns:

Example:

_viam = await Viam.withApiKey(
    dotenv.env['API_KEY_ID'] ?? '',
    dotenv.env['API_KEY'] ?? ''
);
final dataClient = _viam.dataClient;

try {
 // Create a filter to target specific binary data
 final filter = Filter(
  componentName: "camera-1",
 );

 final response = await dataClient.binaryDataByFilter(filter: filter, limit: 1);

 print('Number of items: ${response.count.toInt()}');
 print('Total size: ${response.totalSizeBytes.toInt()} bytes');
 for (var dataPoint in response.data) {
   print(dataPoint.binary);
   print(dataPoint.metadata);
 }

 print('Successfully retrieved binary data by filter');
} catch (e) {
 print('Error retrieving binary data by filter: $e');
}

For more information, see the Flutter 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:

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.

Parameters:

  • ids (BinaryID) (required): The IDs of the requested binary data.

Returns:

  • (Promise<BinaryData[]>): An array of data objects.

For more information, see the TypeScript SDK Docs.

Parameters:

Returns:

Example:

 _viam = await Viam.withApiKey(
     dotenv.env['API_KEY_ID'] ?? '',
     dotenv.env['API_KEY'] ?? ''
 );
 final dataClient = _viam.dataClient;

 try {
  final binaryIDs = [
   BinaryID(fileId: '<YOUR-FILE-ID>', organizationId: '<YOUR-ORG-ID>', locationId: '<YOUR-LOCATION-ID>'),
   BinaryID(fileId: '<YOUR-FILE-ID>', organizationId: '<YOUR-ORG-ID>', locationId: '<YOUR-LOCATION-ID>')
  ];

  final response = await dataClient.binaryDataByIds(
    binaryIDs,
    includeBinary: true
  );

  for (var dataPoint in response.data) {
    print(dataPoint.binary);
    print(dataPoint.metadata);
  }

  print('Successfully retrieved binary data by IDs');
 } catch (e) {
  print('Error retrieving binary data by IDs: $e');
 }

For more information, see the Flutter 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.

Parameters:

  • organizationId (string) (required): The ID of organization to delete data from.
  • deleteOlderThanDays (number) (required): Delete data that was captured more than this many days ago. For example if deleteOlderThanDays is 10, this deletes any data that was captured more than 10 days ago. If it is 0, all existing data is deleted.

Returns:

  • (Promise): The number of items deleted.

For more information, see the TypeScript SDK Docs.

Parameters:

  • organizationId String (required)
  • olderThanDays int (required)

Returns:

Example:

_viam = await Viam.withApiKey(
    dotenv.env['API_KEY_ID'] ?? '',
    dotenv.env['API_KEY'] ?? ''
);
final dataClient = _viam.dataClient;

try {
  dataClient.deleteTabularData("<YOUR-ORG-ID>", 5);

 print('Successfully deleted tabular data');
} catch (e) {
 print('Error deleting tabular data: $e');
}

For more information, see the Flutter 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.

Parameters:

  • filter (Filter) (optional): Optional pb.Filter specifying binary data to delete. No filter implies all binary data.
  • includeInternalData (boolean) (optional): Whether or not to delete internal data. Default is true.

Returns:

  • (Promise): The number of items deleted.

For more information, see the TypeScript SDK Docs.

Parameters:

  • filter Filter? (required)
  • includeInternalData bool (optional)

Returns:

Example:

 _viam = await Viam.withApiKey(
     dotenv.env['API_KEY_ID'] ?? '',
     dotenv.env['API_KEY'] ?? ''
 );
 final dataClient = _viam.dataClient;

 try {
  // Create a filter to target specific binary data. Must include at least one org ID.
  final filter = Filter(
   componentName: "camera-1",
   organizationIds: ["<YOUR-ORG-ID>"]
  );

  final deletedCount = await dataClient.deleteBinaryDataByFilter(filter);

  print('Successfully deleted binary data by filter: count $deletedCount');
 } catch (e) {
  print('Error deleting binary data by filter: $e');
 }

For more information, see the Flutter SDK Docs.

DeleteBinaryDataByIDs

Filter and delete binary data by ids.

Parameters:

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.

Parameters:

  • ids (BinaryID) (required): The IDs of the data to be deleted. Must be non-empty.

Returns:

  • (Promise): The number of items deleted.

For more information, see the TypeScript SDK Docs.

Parameters:

Returns:

Example:

 _viam = await Viam.withApiKey(
     dotenv.env['API_KEY_ID'] ?? '',
     dotenv.env['API_KEY'] ?? ''
 );
 final dataClient = _viam.dataClient;

 try {
  final binaryIDs = [
   BinaryID(fileId: '<YOUR-FILE-ID>', organizationId: '<YOUR-ORG-ID>', locationId: '<YOUR-LOCATION-ID>'),
   BinaryID(fileId: '<YOUR-FILE-ID>', organizationId: '<YOUR-ORG-ID>', locationId: '<YOUR-LOCATION-ID>')
  ];

  // Call the function to delete binary data
  await dataClient.deleteBinaryDataByIds(binaryIDs);

  print('Successfully deleted binary data');
 } catch (e) {
  print('Error deleting binary data: $e');
 }

For more information, see the Flutter 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.

Parameters:

  • tags (string) (required): The list of tags to add to specified binary data. Must be non-empty.
  • ids (BinaryID) (required): The IDs of the data to be tagged. Must be non-empty.

Returns:

  • (Promise)

For more information, see the TypeScript SDK Docs.

Parameters:

Returns:

Example:

 _viam = await Viam.withApiKey(
     dotenv.env['API_KEY_ID'] ?? '',
     dotenv.env['API_KEY'] ?? ''
 );
 final dataClient = _viam.dataClient;

 try {
  // List of tags to add
  final List<String> tags = ['tag_1', 'tag_2'];

  final binaryIDs = [
   BinaryID(fileId: '<YOUR-FILE-ID>', organizationId: '<YOUR-ORG-ID>', locationId: '<YOUR-LOCATION-ID>'),
   BinaryID(fileId: '<YOUR-FILE-ID>', organizationId: '<YOUR-ORG-ID>', locationId: '<YOUR-LOCATION-ID>')
  ];

  // Call the function with both tags and IDs
  await dataClient.addTagsToBinaryDataByIds(tags, binaryIDs);

  print('Successfully added tags to binary IDs');
 } catch (e) {
  print('Error adding tags: $e');
 }

For more information, see the Flutter 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.

Parameters:

  • tags (string) (required): The tags to add to the data.
  • filter (Filter) (optional): Optional pb.Filter specifying binary data to add tags to. No filter implies all binary data.

Returns:

  • (Promise)

For more information, see the TypeScript SDK Docs.

Parameters:

Returns:

Example:

 _viam = await Viam.withApiKey(
     dotenv.env['API_KEY_ID'] ?? '',
     dotenv.env['API_KEY'] ?? ''
 );
 final dataClient = _viam.dataClient;

 try {
  // List of tags to add
  final List<String> tags = ['tag_1', 'tag_2'];

  // Create a filter to target specific binary data
  final filter = Filter(
   componentName: "camera-1",
  );

  await dataClient.addTagsToBinaryDataByFilter(tags, filter);

  print('Successfully added tags to binary data by filter');
 } catch (e) {
  print('Error adding tags to binary data by filter: $e');
 }

For more information, see the Flutter 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.

Parameters:

  • tags (string) (required): List of tags to remove from specified binary data. Must be non-empty.
  • ids (BinaryID) (required): The IDs of the data to be edited. Must be non-empty.

Returns:

  • (Promise): The number of items deleted.

For more information, see the TypeScript SDK Docs.

Parameters:

Returns:

Example:

 _viam = await Viam.withApiKey(
     dotenv.env['API_KEY_ID'] ?? '',
     dotenv.env['API_KEY'] ?? ''
 );
 final dataClient = _viam.dataClient;

 try {
  // List of tags to remove
  final List<String> tags = ['tag_1', 'tag_2'];

  final binaryIDs = [
   BinaryID(fileId: '<YOUR-FILE-ID>', organizationId: '<YOUR-ORG-ID>', locationId: '<YOUR-LOCATION-ID>'),
   BinaryID(fileId: '<YOUR-FILE-ID>', organizationId: '<YOUR-ORG-ID>', locationId: '<YOUR-LOCATION-ID>')
  ];

  // Call the function with both tags and IDs
  await dataClient.removeTagsFromBinaryDataByIds(tags, binaryIDs);

  print('Successfully removed tags from binary IDs');
 } catch (e) {
  print('Error removing tags: $e');
 }

For more information, see the Flutter 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.

Parameters:

  • tags (string) (required): List of tags to remove from specified binary data. Must be non-empty.
  • filter (Filter) (optional): Optional pb.Filter specifying binary data to add tags to. No filter implies all binary data.

Returns:

  • (Promise): The number of items deleted.

For more information, see the TypeScript SDK Docs.

Parameters:

Returns:

Example:

_viam = await Viam.withApiKey(
    dotenv.env['API_KEY_ID'] ?? '',
    dotenv.env['API_KEY'] ?? ''
);
final dataClient = _viam.dataClient;

try {
 // List of tags to remove
 final List<String> tags = ['tag_1', 'tag_2'];

 // Create a filter to target specific binary data
 final filter = Filter(
  componentName: "camera-1",
 );

 await dataClient.removeTagsFromBinaryDataByFilter(tags, filter);

 print('Successfully removed tags from binary data by filter');
} catch (e) {
 print('Error removing tags from binary data by filter: $e');
}

For more information, see the Flutter 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.

Parameters:

  • filter (Filter) (optional): Optional pb.Filter specifying what data to get tags from. No filter implies all data.

Returns:

  • (Promise<string[]>): The list of tags.

For more information, see the TypeScript SDK Docs.

Parameters:

Returns:

Example:

_viam = await Viam.withApiKey(
     dotenv.env['API_KEY_ID'] ?? '',
     dotenv.env['API_KEY'] ?? ''
);
final dataClient = _viam.dataClient;

try {
 // Create a filter to target specific binary data
 final filter = Filter(
   componentName: "camera-1",
 );

 // Call the function to get tags by filter
 final tags = await dataClient.tagsByFilter(filter);

 print('Successfully got tags: $tags');
} catch (e) {
 print('Error getting tags: $e');
}

For more information, see the Flutter 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.

Parameters:

  • id (BinaryID) (required)
  • label (string) (required): A label for the bounding box.
  • xMinNormalized (number) (required): The min X value of the bounding box normalized from 0 to 1.
  • yMinNormalized (number) (required): The min Y value of the bounding box normalized from 0 to 1.
  • xMaxNormalized (number) (required): The max X value of the bounding box normalized from 0 to 1.
  • yMaxNormalized (number) (required): The max Y value of the bounding box normalized from 0 to 1.

Returns:

  • (Promise): The bounding box ID.

For more information, see the TypeScript SDK Docs.

Parameters:

Returns:

Example:

_viam = await Viam.withApiKey(
     dotenv.env['API_KEY_ID'] ?? '',
     dotenv.env['API_KEY'] ?? ''
 );
 final dataClient = _viam.dataClient;

// Example binary ID to add a bounding box to
final binaryId = BinaryID(fileId: '<YOUR-FILE-ID>', organizationId: '<YOUR-ORG-ID>', locationId: '<YOUR-LOCATION-ID>');

try {
  await dataClient.addBoundingBoxToImageById(
    "label",
    binaryId,
    0,
   .1,
   .2,
   .3
  );
  print('Successfully added bounding box');
} catch (e) {
  print('Error adding bounding box: $e');
}

For more information, see the Flutter 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.

Parameters:

  • binId (BinaryID) (required): The ID of the image to remove the bounding box from.
  • bboxId (string) (required): The ID of the bounding box to remove.

Returns:

  • (Promise)

For more information, see the TypeScript SDK Docs.

Parameters:

Returns:

Example:

_viam = await Viam.withApiKey(
     dotenv.env['API_KEY_ID'] ?? '',
     dotenv.env['API_KEY'] ?? ''
 );
 final dataClient = _viam.dataClient;

// Example binary ID to remove a bounding box from
final binaryId = BinaryID(fileId: '<YOUR-FILE-ID>', organizationId: '<YOUR-ORG-ID>', locationId: '<YOUR-LOCATION-ID>');

// Example bbox ID (label)
final bboxId = "label";
try {
  await dataClient.removeBoundingBoxFromImageById(
    bboxId,
    binaryId,
  );

  print('Successfully removed bounding box');
} catch (e) {
  print('Error removing bounding box: $e');
}

For more information, see the Flutter 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.

Parameters:

  • filter (Filter) (optional): Optional pb.Filter specifying what data to get tags from. No filter implies all labels.

Returns:

  • (Promise<string[]>): The list of bounding box labels.

For more information, see the TypeScript SDK Docs.

Parameters:

Returns:

Example:

_viam = await Viam.withApiKey(
     dotenv.env['API_KEY_ID'] ?? '',
     dotenv.env['API_KEY'] ?? ''
);
final dataClient = _viam.dataClient;

try {
 // Create a filter to target specific binary data
 final filter = Filter(
   componentName: "camera-1",
 );

 // Call the function to get bounding box labels by filter
 final labels = await dataClient.boundingBoxLabelsByFilter(filter);

 print('Successfully got bounding box labels: $labels');
} catch (e) {
 print('Error getting bounding box labels: $e');
}

For more information, see the Flutter 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.

Parameters:

  • organizationId (string) (required): Organization to retrieve connection for.

Returns:

  • (Promise): Hostname of the federated database.

For more information, see the TypeScript SDK Docs.

Parameters:

  • organizationId String (required)

Returns:

Example:

_viam = await Viam.withApiKey(
     dotenv.env['API_KEY_ID'] ?? '',
     dotenv.env['API_KEY'] ?? ''
);
final dataClient = _viam.dataClient;

try {
 final String organizationId = "<YOUR-ORG-ID>";
 // Get the database connection
 final connection = await dataClient.getDatabaseConnection(organizationId);

 final hostname = connection.hostname;
 final mongodbUri = connection.mongodbUri;

 print('Successfully got database connection: with hostname $hostname and mongodbUri $mongodbUri');
} catch (e) {
 print('Error getting database connection: $e');
}

For more information, see the Flutter 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.

Parameters:

  • organizationId (string) (required): The ID of the organization.
  • password (string) (required): The password of the user.

Returns:

  • (Promise)

For more information, see the TypeScript SDK Docs.

Parameters:

Returns:

Example:

_viam = await Viam.withApiKey(
     dotenv.env['API_KEY_ID'] ?? '',
     dotenv.env['API_KEY'] ?? ''
);
final dataClient = _viam.dataClient;

try {
 await dataClient.configureDatabaseUser(
   "<YOUR-ORG-ID>",
   "PasswordLikeThis1234",
 );

 print('Successfully configured database user for this organization');
} catch (e) {
 print('Error configuring database user: $e');
}

For more information, see the Flutter 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 data page, click on an image and copy its File ID from the details tab. To retrieve the dataset ID, navigate to your dataset’s page in the Viam app, and use the left-hand menu to copy the 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.

Parameters:

  • ids (BinaryID) (required): The IDs of binary data to add to dataset.
  • datasetId (string) (required): The ID of the dataset to be added to.

Returns:

  • (Promise)

For more information, see the TypeScript SDK Docs.

Parameters:

Returns:

Example:

_viam = await Viam.withApiKey(
     dotenv.env['API_KEY_ID'] ?? '',
     dotenv.env['API_KEY'] ?? ''
 );
 final dataClient = _viam.dataClient;

// Example binary IDs to add to the dataset
 final binaryIds = [
   BinaryID(fileId: '<YOUR-FILE-ID>', organizationId: '<YOUR-ORG-ID>', locationId: '<YOUR-LOCATION-ID>'),
   BinaryID(fileId: '<YOUR-FILE-ID>', organizationId: '<YOUR-ORG-ID>', locationId: '<YOUR-LOCATION-ID>')
 ];

 // Dataset ID where the binary data will be added
 const datasetId = '<YOUR-DATASET-ID>';

 try {
   // Add the binary data to the dataset
   await dataClient.addBinaryDataToDatasetByIds(
     binaryIds,
     datasetId
 );
   print('Successfully added binary data to dataset');
 } catch (e) {
   print('Error adding binary data to dataset: $e');
 }

For more information, see the Flutter 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 data page, click on an image and copy its File ID from the details tab. To retrieve the dataset ID, navigate to your dataset’s page in the Viam app, and use the left-hand menu to copy the 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.

Parameters:

  • ids (BinaryID) (required): The IDs of the binary data to remove from dataset.
  • datasetId (string) (required): The ID of the dataset to be removed from.

Returns:

  • (Promise)

For more information, see the TypeScript SDK Docs.

Parameters:

Returns:

Example:

_viam = await Viam.withApiKey(
     dotenv.env['API_KEY_ID'] ?? '',
     dotenv.env['API_KEY'] ?? ''
 );
 final dataClient = _viam.dataClient;

// Example binary IDs to remove from the dataset
 final binaryIds = [
   BinaryID(fileId: '<YOUR-FILE-ID>', organizationId: '<YOUR-ORG-ID>', locationId: '<YOUR-LOCATION-ID>'),
   BinaryID(fileId: '<YOUR-FILE-ID>', organizationId: '<YOUR-ORG-ID>', locationId: '<YOUR-LOCATION-ID>')
 ];

 // Dataset ID where the binary data will be removed
 const datasetId = '<YOUR-DATASET-ID>';

 try {
   // Remove the binary data from the dataset
   await dataClient.removeBinaryDataFromDatasetByIds(
     binaryIds,
     datasetId
 );
   print('Successfully removed binary data from dataset');
 } catch (e) {
   print('Error removing binary data from dataset: $e');
 }

For more information, see the Flutter 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.

Parameters:

Returns:

Example:

_viam = await Viam.withApiKey(
     dotenv.env['API_KEY_ID'] ?? '',
     dotenv.env['API_KEY'] ?? ''
 );
 final dataClient = _viam.dataClient;

 // Org ID to create dataset in
 const orgId = '<YOUR-ORG-ID>';

 try {
   // Create the dataset
   final datasetId = await dataClient.createDataset(orgId, "example-dataset");
   print('Successfully created dataset');
 } catch (e) {
   print('Error creating dataset: $e');
 }

For more information, see the Flutter 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.

Parameters:

Returns:

Example:

_viam = await Viam.withApiKey(
     dotenv.env['API_KEY_ID'] ?? '',
     dotenv.env['API_KEY'] ?? ''
 );
 final dataClient = _viam.dataClient;

 // Dataset ID to delete
 const datasetId = '<YOUR-DATASET-ID>';

 try {
   // Delete the dataset
   await dataClient.deleteDataset(datasetId);
   print('Successfully deleted dataset');
 } catch (e) {
   print('Error deleting dataset: $e');
 }

For more information, see the Flutter 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.

Parameters:

Returns:

Example:

_viam = await Viam.withApiKey(
     dotenv.env['API_KEY_ID'] ?? '',
     dotenv.env['API_KEY'] ?? ''
 );
 final dataClient = _viam.dataClient;

 // Dataset ID to rename
 const datasetId = '<YOUR-DATASET-ID>';

 try {
   // Rename the dataset
   await dataClient.renameDataset(datasetId, "new-name");
   print('Successfully renamed dataset');
 } catch (e) {
   print('Error renaming dataset: $e');
 }

For more information, see the Flutter 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:

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.

Parameters:

Returns:

Example:

_viam = await Viam.withApiKey(
     dotenv.env['API_KEY_ID'] ?? '',
     dotenv.env['API_KEY'] ?? ''
 );
 final dataClient = _viam.dataClient;

 // Org ID to list datasets from
 const orgId = '<YOUR-ORG-ID>';

 try {
   // List datasets from org
   final datasets = await dataClient.listDatasetsByOrganizationID(orgId);
   print('Successfully retrieved list of datasets: $datasets');
 } catch (e) {
   print('Error retrieving list of datasets: $e');
 }

For more information, see the Flutter 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:

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.

Parameters:

Returns:

Example:

_viam = await Viam.withApiKey(
     dotenv.env['API_KEY_ID'] ?? '',
     dotenv.env['API_KEY'] ?? ''
 );
 final dataClient = _viam.dataClient;

 const datasetIds = ["<YOUR-DATASET-ID>", "<YOUR-DATASET-ID-2>"];

 try {
   // List datasets by ids
   final datasets = await dataClient.listDatasetsByIDs(datasetIds);
   print('Successfully listed datasets by ids: $datasets');
 } catch (e) {
   print('Error retrieving datasets by ids: $e');
 }

For more information, see the Flutter 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:

Part ID displayed in the Viam app.

Previous

Service APIs

Next

ML Training Client