Class DataClient

Constructors

constructor

new DataClient(transport: Transport): DataClient
Parameters
- transport: Transport
Returns DataClient

Methods

addBinaryDataToDatasetByIds

addBinaryDataToDatasetByIds(
ids: string[] | BinaryID[],
datasetId: string,
): Promise<void>
Add BinaryData to the provided dataset.
Parameters
- ids: string[] | BinaryID[]
  The IDs of binary data to add to dataset
- datasetId: string
  The ID of the dataset to be added to
Returns Promise<void>
Example
```
await dataClient.addBinaryDataToDatasetByIds(
  [
    'ccb74b53-1235-4328-a4b9-91dff1915a50/x5vur1fmps/YAEzj5I1kTwtYsDdf4a7ctaJpGgKRHmnM9bJNVyblk52UpqmrnMVTITaBKZctKEh',
  ],
  '12ab3de4f56a7bcd89ef0ab1'
);
```

addBoundingBoxToImageById

addBoundingBoxToImageById(
    binaryId: string | BinaryID,
    label: string,
    xMinNormalized: number,
    yMinNormalized: number,
    xMaxNormalized: number,
    yMaxNormalized: number,
): Promise<string>
Add bounding box to an image.
Parameters
- binaryId: string | BinaryID
  The ID of the image to add the bounding box to
- label: string
  A label for the bounding box
- xMinNormalized: number
  The min X value of the bounding box normalized from 0 to 1
- yMinNormalized: number
  The min Y value of the bounding box normalized from 0 to 1
- xMaxNormalized: number
  The max X value of the bounding box normalized from 0 to 1
- yMaxNormalized: number
  The max Y value of the bounding box normalized from 0 to 1
Returns Promise<string>
The bounding box ID
Example
```
const bboxId = await dataClient.addBoundingBoxToImageById(
  'ccb74b53-1235-4328-a4b9-91dff1915a50/x5vur1fmps/YAEzj5I1kTwtYsDdf4a7ctaJpGgKRHmnM9bJNVyblk52UpqmrnMVTITaBKZctKEh',
  'label1',
  0.3,
  0.3,
  0.6,
  0.6
);
```

addTagsToBinaryDataByFilter

addTagsToBinaryDataByFilter(tags: string[], filter?: Filter): Promise<void>
Add tags to binary data, specified by filter.
Parameters
- tags: string[]
  The tags to add to the data
- Optionalfilter: Filter
  Optional pb.Filter specifying binary data to add tags to. No filter implies all binary data.
Returns Promise<void>
Example
```
const data = await dataClient.addTagsToBinaryDataByFilter(
  ['tag1', 'tag2'],
  [
    {
      componentName: 'camera-1',
    } as Filter,
  ]
);
```

addTagsToBinaryDataByIds

addTagsToBinaryDataByIds(
tags: string[],
ids: string[] | BinaryID[],
): Promise<void>
Add tags to binary data, specified by ID.
Parameters
- tags: string[]
  The list of tags to add to specified binary data. Must be non-empty.
- ids: string[] | BinaryID[]
  The IDs of the data to be tagged. Must be non-empty.
Returns Promise<void>
Example
```
const data = await dataClient.addTagsToBinaryDataByIds(
  ['tag1', 'tag2'],
  [
    'ccb74b53-1235-4328-a4b9-91dff1915a50/x5vur1fmps/YAEzj5I1kTwtYsDdf4a7ctaJpGgKRHmnM9bJNVyblk52UpqmrnMVTITaBKZctKEh',
  ]
);
```

binaryDataByFilter

binaryDataByFilter(
    filter?: Filter,
    limit?: number,
    sortOrder?: Order,
    last?: string,
    includeBinary?: boolean,
    countOnly?: boolean,
    includeInternalData?: boolean,
): Promise<{ count: bigint; data: BinaryData[]; last: string }>
Filter and get a page of binary data. The returned metadata might be empty if the metadata index of the data is out of the bounds of the returned metadata list. The data will be paginated into pages of limit items, and the pagination ID will be included in the returned tuple.
Parameters
- Optionalfilter: Filter
  Optional pb.Filter specifying binary data to retrieve. No filter implies all binary data.
- Optionallimit: number
  The maximum number of entries to include in a page. Defaults to 50 if unspecfied
- OptionalsortOrder: Order
  The desired sort order of the data
- last: string = ''
  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 = true
  Whether to include binary file data with each retrieved file
- countOnly: boolean = false
  Whether to return only the total count of entries
- includeInternalData: boolean = false
  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.
Example
```
const data = await dataClient.binaryDataByFilter(
  {
    componentName: 'camera-1',
    componentType: 'rdk:component:camera',
  } as Filter,
  1
);
```

binaryDataByIds

binaryDataByIds(ids: string[] | BinaryID[]): Promise<BinaryData[]>
Get binary data using the binary data ID.
Parameters
- ids: string[] | BinaryID[]
  The IDs of the requested binary data
Returns Promise<BinaryData[]>
An array of data objects
Example
```
const data = await dataClient.binaryDataByIds([
  'ccb74b53-1235-4328-a4b9-91dff1915a50/x5vur1fmps/YAEzj5I1kTwtYsDdf4a7ctaJpGgKRHmnM9bJNVyblk52UpqmrnMVTITaBKZctKEh',
]);
```

binaryDataCaptureUpload

binaryDataCaptureUpload(
    binaryData: Uint8Array,
    partId: string,
    componentType: string,
    componentName: string,
    methodName: string,
    fileExtension: string,
    dataRequestTimes: [Date, Date],
    tags?: string[],
): Promise<string>
Uploads the content and metadata for binary data.

Upload binary data collected on a robot through a specific component (e.g., a motor) along with the relevant metadata to app.viam.com. binary data can be found under the "Sensors" subtab of the Data tab on app.viam.com.
Parameters
- binaryData: Uint8Array
  The data to be uploaded, represented in bytes
- partId: string
  The part ID of the component used to capture the data
- componentType: string
  The type of the component used to capture the data (e.g., "movementSensor")
- componentName: string
  The name of the component used to capture the data
- methodName: string
  The name of the method used to capture the data.
- fileExtension: string
  The file extension of binary data including the period, e.g. .jpg, .png, .pcd. The backend will route the binary to its corresponding mime type based on this extension. Files with a .jpeg, .jpg, or .png extension will be saved to the images tab.
- dataRequestTimes: [Date, Date]
  Tuple containing Date objects denoting the times this data was requested[0] by the robot and received[1] from the appropriate sensor.
- Optionaltags: string[]
  The list of tags to allow for tag-based filtering when retrieving data
Returns Promise<string>
The binary data ID of the uploaded data
Example
```
const binaryDataId = await dataClient.binaryDataCaptureUpload(
  binaryData,
  '123abc45-1234-5678-90ab-cdef12345678',
  'rdk:component:camera',
  'my-camera',
  'ReadImage',
  '.jpg',
  [new Date('2025-03-19'), new Date('2025-03-19')]
);
```

boundingBoxLabelsByFilter

boundingBoxLabelsByFilter(filter?: Filter): Promise<string[]>
Get a list of bounding box labels using a Filter.
Parameters
- Optionalfilter: Filter
  Optional pb.Filter specifying what data to get tags from. No filter implies all labels.
Returns Promise<string[]>
The list of bounding box labels
Example
```
const data = await dataClient.boundingBoxLabelsByFilter({
  componentName: 'camera-1',
} as Filter);
```

configureDatabaseUser

configureDatabaseUser(organizationId: string, password: string): Promise<void>
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
- organizationId: string
  The ID of the organization
- password: string
  The password of the user
Returns Promise<void>
Example
```
await dataClient.configureDatabaseUser(
  '123abc45-1234-5678-90ab-cdef12345678',
  'Password01!'
);
```

createDataset

createDataset(name: string, organizationId: string): Promise<string>
Create a new dataset.
Parameters
- name: string
  The name of the new dataset
- organizationId: string
  The ID of the organization the dataset is being created in
Returns Promise<string>
The ID of the dataset
Example
```
const datasetId = await dataClient.createDataset(
  'my-new-dataset',
  '123abc45-1234-5678-90ab-cdef12345678'
);
```

createFilter

createFilter(options: FilterOptions): Filter
Parameters
- options: FilterOptions
Returns Filter

deleteBinaryDataByFilter

deleteBinaryDataByFilter(
filter?: Filter,
includeInternalData?: boolean,
): Promise<bigint>
Filter and delete binary data.
Parameters
- Optionalfilter: Filter
  Optional pb.Filter specifying binary data to delete. No filter implies all binary data.
- includeInternalData: boolean = true
  Whether or not to delete internal data. Default is true
Returns Promise<bigint>
The number of items deleted
Example
```
const data = await dataClient.deleteBinaryDataByFilter({
  componentName: 'camera-1',
  componentType: 'rdk:component:camera',
  organizationIds: ['123abc45-1234-5678-90ab-cdef12345678'],
  startTime: new Date('2025-03-19'),
  endTime: new Date('2025-03-20'),
} as Filter);
```

deleteBinaryDataByIds

deleteBinaryDataByIds(ids: string[] | BinaryID[]): Promise<bigint>
Delete binary data, specified by ID.
Parameters
- ids: string[] | BinaryID[]
  The IDs of the data to be deleted. Must be non-empty.
Returns Promise<bigint>
The number of items deleted
Example
```
const data = await dataClient.deleteBinaryDataByIds([
  'ccb74b53-1235-4328-a4b9-91dff1915a50/x5vur1fmps/YAEzj5I1kTwtYsDdf4a7ctaJpGgKRHmnM9bJNVyblk52UpqmrnMVTITaBKZctKEh',
]);
```

deleteDataset

deleteDataset(id: string): Promise<void>
Delete a dataset.
Parameters
- id: string
  The ID of the dataset.
Returns Promise<void>
Example
```
await dataClient.deleteDataset('12ab3de4f56a7bcd89ef0ab1');
```

deleteTabularData

deleteTabularData(
organizationId: string,
deleteOlderThanDays: number,
): Promise<bigint>
Delete tabular data older than a specified number of days.
Parameters
- organizationId: string
  The ID of organization to delete data from
- deleteOlderThanDays: number
  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<bigint>
The number of items deleted
Example
```
const data = await dataClient.deleteTabularData(
  '123abc45-1234-5678-90ab-cdef12345678',
  10
);
```

exportTabularData

exportTabularData(
    partId: string,
    resourceName: string,
    resourceSubtype: string,
    methodName: string,
    startTime?: Date,
    endTime?: Date,
): Promise<TabularDataPoint[]>
Obtain unified tabular data and metadata from the specified data source.
Parameters
- partId: string
  The ID of the part that owns the data
- resourceName: string
  The name of the requested resource that captured the data
- resourceSubtype: string
  The subtype of the requested resource that captured the data
- methodName: string
  The data capture method name
- OptionalstartTime: Date
  Optional start time (Date object) for requesting a specific range of data
- OptionalendTime: Date
  Optional end time (Date object) for requesting a specific range of data
Returns Promise<TabularDataPoint[]>
An array of unified tabular data and metadata.
Example
```
const data = await dataClient.exportTabularData(
  '123abc45-1234-5678-90ab-cdef12345678',
  'my-sensor',
  'rdk:component:sensor',
  'Readings',
  new Date('2025-03-25'),
  new Date('2024-03-27')
);
```

getDatabaseConnection

getDatabaseConnection(organizationId: string): Promise<string>
Get a connection to access a MongoDB Atlas Data federation instance.
Parameters
- organizationId: string
  Organization to retrieve connection for
Returns Promise<string>
Hostname of the federated database
Example
```
const hostname = await dataClient.getDatabaseConnection(
  '123abc45-1234-5678-90ab-cdef12345678'
);
```

getLatestTabularData

getLatestTabularData(
    partId: string,
    resourceName: string,
    resourceSubtype: string,
    methodName: string,
): Promise<null | [Date, Date, Record<string, JsonValue>]>
Gets the most recent tabular data captured from the specified data source, as long as it was synced within the last year.
Parameters
- partId: string
  The ID of the part that owns the data
- resourceName: string
  The name of the requested resource that captured the data. Ex: "my-sensor"
- resourceSubtype: string
  The subtype of the requested resource that captured the data. Ex: "rdk:component:sensor"
- methodName: string
  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
Example
```
const data = await dataClient.getLatestTabularData(
  '123abc45-1234-5678-90ab-cdef12345678',
  'my-sensor',
  'rdk:component:sensor',
  'Readings'
);
```

listDatasetsByIds

listDatasetsByIds(ids: string[]): Promise<Dataset[]>
List all of the datasets specified by the given dataset IDs.
Parameters
- ids: string[]
  The list of IDs of the datasets
Returns Promise<Dataset[]>
The list of datasets
Example
```
const datasets = await dataClient.listDatasetsByIds([
  '12ab3de4f56a7bcd89ef0ab1',
]);
```

listDatasetsByOrganizationID

listDatasetsByOrganizationID(organizationId: string): Promise<Dataset[]>
List all of the datasets for an organization.
Parameters
- organizationId: string
  The ID of the organization
Returns Promise<Dataset[]>
The list of datasets in the organization
Example
```
const datasets = await dataClient.listDatasetsByOrganizationID(
  '123abc45-1234-5678-90ab-cdef12345678'
);
```

removeBinaryDataFromDatasetByIds

removeBinaryDataFromDatasetByIds(
ids: string[] | BinaryID[],
datasetId: string,
): Promise<void>
Remove BinaryData from the provided dataset.
Parameters
- ids: string[] | BinaryID[]
  The IDs of the binary data to remove from dataset
- datasetId: string
  The ID of the dataset to be removed from
Returns Promise<void>
Example
```
await dataClient.removeBinaryDataFromDatasetByIds(
  [
    'ccb74b53-1235-4328-a4b9-91dff1915a50/x5vur1fmps/YAEzj5I1kTwtYsDdf4a7ctaJpGgKRHmnM9bJNVyblk52UpqmrnMVTITaBKZctKEh',
  ],
  '12ab3de4f56a7bcd89ef0ab1'
);
```

removeBoundingBoxFromImageById

removeBoundingBoxFromImageById(
binId: string | BinaryID,
bboxId: string,
): Promise<void>
Remove a bounding box from an image.
Parameters
- binId: string | BinaryID
  The ID of the image to remove the bounding box from
- bboxId: string
  The ID of the bounding box to remove
Returns Promise<void>
Example
```
await dataClient.removeBoundingBoxFromImageById(
  'ccb74b53-1235-4328-a4b9-91dff1915a50/x5vur1fmps/YAEzj5I1kTwtYsDdf4a7ctaJpGgKRHmnM9bJNVyblk52UpqmrnMVTITaBKZctKEh',
  '5Z9ryhkW7ULaXROjJO6ghPYulNllnH20QImda1iZFroZpQbjahK6igQ1WbYigXED'
);
```

removeTagsFromBinaryDataByFilter

removeTagsFromBinaryDataByFilter(
tags: string[],
filter?: Filter,
): Promise<bigint>
Remove tags from binary data, specified by filter.
Parameters
- tags: string[]
  List of tags to remove from specified binary data. Must be non-empty.
- Optionalfilter: Filter
  Optional pb.Filter specifying binary data to add tags to. No filter implies all binary data.
Returns Promise<bigint>
The number of items deleted
Example
```
const data = await dataClient.removeTagsFromBinaryDataByFilter(
  ['tag1', 'tag2'],
  {
    componentName: 'camera-1',
    componentType: 'rdk:component:camera',
    organizationIds: ['123abc45-1234-5678-90ab-cdef12345678'],
    startTime: new Date('2025-03-19'),
    endTime: new Date('2025-03-20'),
  } as Filter
);
```

removeTagsFromBinaryDataByIds

removeTagsFromBinaryDataByIds(
tags: string[],
ids: string[] | BinaryID[],
): Promise<bigint>
Remove tags from binary data, specified by ID.
Parameters
- tags: string[]
  List of tags to remove from specified binary data. Must be non-empty.
- ids: string[] | BinaryID[]
  The IDs of the data to be edited. Must be non-empty.
Returns Promise<bigint>
The number of items deleted
Example
```
const data = await dataClient.removeTagsFromBinaryDataByIds(
  ['tag1', 'tag2'],
  [
    'ccb74b53-1235-4328-a4b9-91dff1915a50/x5vur1fmps/YAEzj5I1kTwtYsDdf4a7ctaJpGgKRHmnM9bJNVyblk52UpqmrnMVTITaBKZctKEh',
  ]
);
```

renameDataset

renameDataset(id: string, name: string): Promise<void>
Rename a dataset.
Parameters
- id: string
  The ID of the dataset
- name: string
  The new name of the dataset
Returns Promise<void>
Example
```
await dataClient.renameDataset(
  '12ab3de4f56a7bcd89ef0ab1',
  'my-new-dataset'
);
```

tabularDataByFilter

tabularDataByFilter(
    filter?: Filter,
    limit?: number,
    sortOrder?: Order,
    last?: string,
    countOnly?: boolean,
    includeInternalData?: boolean,
): Promise<{ count: bigint; data: TabularData[]; last: string }>
Filter and get a page of tabular data. The returned metadata might be empty if the metadata index of the data is out of the bounds of the returned metadata list. The data will be paginated into pages of limit items, and the pagination ID will be included in the returned tuple.
Parameters
- Optionalfilter: Filter
  Optional pb.Filter specifying tabular data to retrieve. No filter implies all tabular data.
- Optionallimit: number
  The maximum number of entries to include in a page. Defaults to 50 if unspecfied
- OptionalsortOrder: Order
  The desired sort order of the data
- last: string = ''
  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 = false
  Whether to return only the total count of entries
- includeInternalData: boolean = false
  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.
Example
```
const data = await dataClient.tabularDataByFilter(
  {
    componentName: 'sensor-1',
    componentType: 'rdk:component:sensor',
  } as Filter,
  5
);
```

tabularDataByMQL

tabularDataByMQL(
    organizationId: string,
    query: Uint8Array[] | Record<string, JsonValue | Date>[],
    useRecentData?: boolean,
): Promise<(Object | any[])[]>
Obtain unified tabular data and metadata, queried with MQL.
Parameters
- organizationId: string
  The ID of the organization that owns the data
- query: Uint8Array[] | Record<string, JsonValue | Date>[]
  The MQL query to run as a list of BSON documents
- OptionaluseRecentData: boolean
  Whether to query blob storage or your recent data store. Defaults to false
Returns Promise<(Object | any[])[]>
An array of data objects
Example
```
type JsonValue =
  | string
  | number
  | boolean
  | null
  | JsonValue[]
  | { [key: string]: JsonValue };
const mqlQuery: Record<string, JsonValue>[] = [
  {
    $match: {
      component_name: 'sensor-1',
    },
  },
  {
    $limit: 5,
  },
];

const data = await dataClient.tabularDataByMQL(
  '123abc45-1234-5678-90ab-cdef12345678',
  mqlQuery
);
```

tabularDataBySQL

tabularDataBySQL(
organizationId: string,
query: string,
): Promise<(Object | any[])[]>
Obtain unified tabular data and metadata, queried with SQL.
Parameters
- organizationId: string
  The ID of the organization that owns the data
- query: string
  The SQL query to run
Returns Promise<(Object | any[])[]>
An array of data objects
Example
```
const data = await dataClient.tabularDataBySQL(
  '123abc45-1234-5678-90ab-cdef12345678',
  'SELECT * FROM readings LIMIT 5'
);
```

tabularDataCaptureUpload

tabularDataCaptureUpload(
    tabularData: Record<string, JsonValue>[],
    partId: string,
    componentType: string,
    componentName: string,
    methodName: string,
    dataRequestTimes: [Date, Date][],
    tags?: string[],
): Promise<string>
Uploads the content and metadata for tabular data.

Upload tabular data collected on a robot through a specific component (e.g., a motor) along with the relevant metadata to app.viam.com. Tabular data can be found under the "Sensors" subtab of the Data tab on app.viam.com.
Parameters
- tabularData: Record<string, JsonValue>[]
  The list of data to be uploaded, represented tabularly as an array.
- partId: string
  The part ID of the component used to capture the data
- componentType: string
  The type of the component used to capture the data (e.g., "movementSensor")
- componentName: string
  The name of the component used to capture the data
- methodName: string
  The name of the method used to capture the data.
- dataRequestTimes: [Date, Date][]
  Array of Date tuples, each containing two Date 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.
- Optionaltags: string[]
  The list of tags to allow for tag-based filtering when retrieving data
Returns Promise<string>
The file ID of the uploaded data
Example
```
const fileId = await dataClient.tabularDataCaptureUpload(
  [
    {
      timestamp: '2025-03-26T10:00:00Z',
      value: 10,
    },
  ],
  '123abc45-1234-5678-90ab-cdef12345678',
  'rdk:component:sensor',
  'my-sensor',
  'Readings',
  [
    [
      new Date('2025-03-26T10:00:00Z'),
      new Date('2025-03-26T10:00:00Z'),
    ],
  ]
);
```

tagsByFilter

tagsByFilter(filter?: Filter): Promise<string[]>
Get a list of tags using a filter.
Parameters
- Optionalfilter: Filter
  Optional pb.Filter specifying what data to get tags from. No filter implies all data.
Returns Promise<string[]>
The list of tags
Example
```
const data = await dataClient.tagsByFilter({
  componentName: 'camera-1',
} as Filter);
```

Class DataClient

Index

Constructors

Methods

Constructors

constructor

Parameters

Returns DataClient

Methods

addBinaryDataToDatasetByIds

Parameters

Returns Promise<void>

Example

addBoundingBoxToImageById

Parameters

Returns Promise<string>

Example

addTagsToBinaryDataByFilter

Parameters

Returns Promise<void>

Example

addTagsToBinaryDataByIds

Parameters

Returns Promise<void>

Example

binaryDataByFilter

Parameters

Returns Promise<{ count: bigint; data: BinaryData[]; last: string }>

Example

binaryDataByIds

Parameters

Returns Promise<BinaryData[]>

Example

binaryDataCaptureUpload

Parameters

Returns Promise<string>

Example

boundingBoxLabelsByFilter

Parameters

Returns Promise<string[]>

Example

configureDatabaseUser

Parameters

Returns Promise<void>

Example

createDataset

Parameters

Returns Promise<string>

Example

createFilter

Parameters

Returns Filter

deleteBinaryDataByFilter

Parameters

Returns Promise<bigint>

Example

deleteBinaryDataByIds

Parameters

Returns Promise<bigint>

Example

deleteDataset

Parameters

Returns Promise<void>

Example

deleteTabularData

Parameters

Returns Promise<bigint>

Example

exportTabularData

Parameters

Returns Promise<TabularDataPoint[]>

Example

getDatabaseConnection

Parameters

Returns Promise<string>

Example

getLatestTabularData

Parameters

Returns Promise<null | [Date, Date, Record<string, JsonValue>]>

Example