Query sensor data with the Python SDK

You can use the data management service to capture sensor data from any machine and sync that data to the cloud. Then, you can use the Python SDK to retrieve and query that data. For example, you can configure data capture for several sensors on one machine, or for several sensors across multiple machines, to report the ambient operating temperature. You can then write a script to run queries against that data to search for outliers or edge cases, to analyze how the ambient temperature affects your machines’ operation or to take action if the machines are overheating.


A running machine connected to the Viam app. Click to see instructions.
Add a new machine in the Viam app. Then follow the setup instructions to install viam-server on the computer you’re using for your project and connect to the Viam app. Wait until your machine has successfully connected.
Captured sensor data. Click to see instructions.
Follow the guide to capture sensor data.
The Viam CLI to set up data query. Click to see instructions.

You must have the Viam CLI installed to configure querying with third-party tools.

To download the Viam CLI on a macOS computer, run the following commands:

brew tap viamrobotics/brews
brew install viam

To download the Viam CLI on a Linux computer with the aarch64 architecture, run the following commands:

sudo curl -o /usr/local/bin/viam https://storage.googleapis.com/packages.viam.com/apps/viam-cli/viam-cli-stable-linux-arm64
sudo chmod a+rx /usr/local/bin/viam

To download the Viam CLI on a Linux computer with the amd64 (Intel x86_64) architecture, run the following commands:

sudo curl -o /usr/local/bin/viam https://storage.googleapis.com/packages.viam.com/apps/viam-cli/viam-cli-stable-linux-amd64
sudo chmod a+rx /usr/local/bin/viam

You can also install the Viam CLI using brew on Linux amd64 (Intel x86_64):

brew tap viamrobotics/brews
brew install viam

If you have Go installed, you can build the Viam CLI directly from source using the go install command:

go install go.viam.com/rdk/cli/viam@latest

To confirm viam is installed and ready to use, issue the viam command from your terminal. If you see help instructions, everything is correctly installed. If you do not see help instructions, add your local go/bin/* directory to your PATH variable. If you use bash as your shell, you can use the following command:

echo 'export PATH="$HOME/go/bin:$PATH"' >> ~/.bashrc

For more information see install the Viam CLI.

Set up the Python SDK

1. Install the Python SDK

For macOS (both Intel x86_64 and Apple Silicon) or Linux (x86, aarch64, armv6l), run the following commands:

python3 -m venv .venv
source .venv/bin/activate
pip install viam-sdk

Query data with the Python SDK

1. Create an API key

To access your machines using the Python SDK, you must use an API key:

viam organizations api-key create --org-id <org-id> --name my-api-key

2. Use the API key with the data_client

Use the API key and TabularDataByFilter(), TabularDataBySQL(), TabularDataByMQL(), andDeleteTabularData() to query data:

import asyncio

from viam.rpc.dial import DialOptions, Credentials
from viam.app.viam_client import ViamClient
from viam.proto.app.data import Filter

async def connect() -> ViamClient:
    dial_options = DialOptions(
        # Replace "<API-KEY>" (including brackets) with your machine's API key
      # Replace "<API-KEY-ID>" (including brackets) with your machine's
      # 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

    my_filter = Filter(component_name="my-sensor")
    data, count, id = await data_client.tabular_data_by_filter(
        filter=my_filter, limit=5)
    # This query requests all stored data grouped by hour and calculates the
    # average, minimum, and maximum of the memory usage
    data = await data_client.tabular_data_by_mql(
        bson.dumps({'$match': {'location_id': '<location-id>'}}),
          "$group": {
            "_id": {
              "year": {"$year": "$time_requested"},
              "dayOfYear": {"$dayOfYear": "$time_requested"},
              "hour": {"$hour": "$time_requested"}
            "count": {"$sum": 1},
            "max_mem": {"$max": "$data.readings.mem.used_percent"},
            "min_mem": {"$min": "$data.readings.mem.used_percent"},
            "average_mem": {"$avg": "$data.readings.mem.used_percent"}


if __name__ == '__main__':

Adjust the Python script to uery your data further.

Next steps

On top of querying sensor data with the Python SDK, you can also query or visualize it with third-party tools.

To see sensor data in action, check out this tutorial:

Have questions, or want to meet other people working on robots? Join our Community Discord.

If you notice any issues with the documentation, feel free to file an issue or edit this file.