Edit

Data management service API

The data management service API allows you to sync data stored on the machine it is deployed on to the cloud.

The data management service supports the following methods:

Method Name	Description	`viam-micro-server` Support
`Sync`	Sync data stored on the machine to the cloud.
`UploadImageToDataset`	Upload an image directly to specified datasets.
`Reconfigure`	Reconfigure this resource.
`DoCommand`	Execute model-specific commands that are not otherwise defined by the service API.
`Close`	Safely shut down the resource and prevent further use.

The data client API supports a separate set of methods that allow you to upload and export data to and from Viam. For information about that API, see Data Client API.

Establish a connection

To get started using Viam’s SDKs to connect to and control your machine, go to your machine’s page, navigate to the CONNECT tab’s Code sample page, select your preferred programming language, and copy the sample code.

To show your machine’s API key in the sample code, toggle Include API key.

Caution: Keep your API key safe

We strongly recommend that you add your API key as an environment variable. Anyone with your API key can access your machine, and the computer running your machine.

When executed, this sample code creates a connection to your machine as a client.

The following examples assume that you have a machine configured with an data_manager service.

import (
  "go.viam.com/rdk/services/datamanager"
)

API

Sync

Important

This method is not yet available in the Viam Python SDK.

Sync data stored on the machine to the cloud.

Go
TypeScript

Parameters:

ctx (Context): A Context carries a deadline, a cancellation signal, and other values across API boundaries.
extra (map[string]interface{}): Extra options to pass to the underlying RPC call.

Returns:

(error): An error, if one occurred.

Example:

// Sync data stored on the machine to the cloud.
err := data.Sync(context.Background(), nil)

For more information, see the Go SDK Docs.

Parameters:

extra (None) (optional): Extra arguments to pass to the sync request.
callOptions (CallOptions) (optional): Call options for the sync request.

Returns:

(Promise)

Example:

const dataManager = new VIAM.DataManagerClient(
  machine,
  'my_data_manager'
);
await dataManager.sync();

For more information, see the TypeScript SDK Docs.

UploadImageToDataset

Upload an image directly to specified datasets for machine learning workflows.

Parameters:

image (bytes): The image data as bytes.
dataset_ids (List[str]): List of dataset IDs to upload the image to.
tags (List[str]): List of tags to apply to the uploaded image.
extra (Mapping[str, Any]) (optional): Extra options to pass to the underlying RPC call.
timeout (float) (optional): An option to set how long to wait (in seconds) before calling a time-out and closing the underlying RPC call.

Returns:

None

Example:

from viam.services.data_manager import DataManagerClient

# Get the data manager service
data_manager = DataManagerClient.from_robot(robot, "builtin")

# Read image file
with open("path/to/image.jpg", "rb") as f:
    image_data = f.read()

# Upload to datasets with tags
await data_manager.upload_image_to_dataset(
    image=image_data,
    dataset_ids=["dataset_1", "dataset_2"],
    tags=["training", "outdoor", "robot_vision"]
)

Parameters:

ctx (Context): A Context carries a deadline, a cancellation signal, and other values across API boundaries.
image ([]byte): The image data as bytes.
datasetIDs ([]string): List of dataset IDs to upload the image to.
tags ([]string): List of tags to apply to the uploaded image.
extra (map[string]interface{}): Extra options to pass to the underlying RPC call.

Returns:

(error): An error, if one occurred.

Example:

// Get the data manager service
dataManager, err := datamanager.FromRobot(machine, "builtin")

// Read image file
imageData, err := os.ReadFile("path/to/image.jpg")
if err != nil {
    return err
}

// Upload to datasets with tags
err = dataManager.UploadImageToDataset(
    context.Background(),
    imageData,
    []string{"dataset_1", "dataset_2"},
    []string{"training", "outdoor", "robot_vision"},
    nil,
)

For more information, see the Go SDK Docs.

Parameters:

image (Uint8Array): The image data as bytes.
datasetIds (string[]): List of dataset IDs to upload the image to.
tags (string[]): List of tags to apply to the uploaded image.
extra (Struct) (optional): Extra options to pass to the underlying RPC call.
callOptions (CallOptions) (optional): Call options for the request.

Returns:

(Promise)

Example:

const dataManager = new VIAM.DataManagerClient(
  machine,
  'builtin'
);

// Read image file (example using File API in browser)
const fileInput = document.getElementById('imageFile') as HTMLInputElement;
const file = fileInput.files[0];
const imageData = new Uint8Array(await file.arrayBuffer());

// Upload to datasets with tags
await dataManager.uploadImageToDataset(
  imageData,
  ['dataset_1', 'dataset_2'],
  ['training', 'outdoor', 'robot_vision']
);

For more information, see the TypeScript SDK Docs.

Reconfigure

Reconfigure this resource. Reconfigure must reconfigure the resource atomically and in place.

Parameters:

ctx (Context): A Context carries a deadline, a cancellation signal, and other values across API boundaries.
deps (Dependencies): The resource dependencies.
conf (Config): The resource configuration.

Returns:

(error): An error, if one occurred.

For more information, see the Go SDK Docs.

DoCommand

Execute model-specific commands that are not otherwise defined by the service API. Most models do not implement DoCommand. Any available model-specific commands should be covered in the model’s documentation. If you are implementing your own data manager service and want to add features that have no corresponding built-in API method, you can implement them with DoCommand.

Go
TypeScript

Parameters:

ctx (Context): A Context carries a deadline, a cancellation signal, and other values across API boundaries.
cmd (map[string]interface{}): The command to execute.

Returns:

(map[string]interface{}): The command response.
(error): An error, if one occurred.

Example:

myDataManagerSvc, err := datamanager.FromRobot(machine, "my_data_manager_svc")

command := map[string]interface{}{"cmd": "test", "data1": 500}
result, err := myDataManagerSvc.DoCommand(context.Background(), command)

For more information, see the Go SDK Docs.

Parameters:

command (Struct) (required): The command to do.
callOptions (CallOptions) (optional): Call options for the command.

Returns:

(Promise<JsonValue>)

Example:

const dataManager = new VIAM.DataManagerClient(
  machine,
  'my_data_manager'
);
await dataManager.doCommand(new Struct({ cmd: 'test', data1: 500 }));

For more information, see the TypeScript SDK Docs.

Close

Safely shut down the resource and prevent further use.

Parameters:

ctx (Context): A Context carries a deadline, a cancellation signal, and other values across API boundaries.

Returns:

(error): An error, if one occurred.

Example:

data, err := datamanager.FromRobot(machine, "my_data_manager")

err := data.Close(context.Background())

For more information, see the Go SDK Docs.

Was this page helpful?

Glad to hear it! If you have any other feedback please let us know:

We're sorry about that. To help us improve, please tell us what we can do better:

Thank you!