Edit

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.

Prerequisites

A running machine connected to the Viam app. Click to see instructions.

Add a new machine in the Viam app. Then follow the to install viam-server or viam-micro-server on the device 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.

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

2. Install requirements

To query data with the Python SDK, you will the bson package or the pymongo package. To install bson, run the following command:

pip install bson

Query data with the Python SDK

1. Get an API key

To access your machines using the Python SDK, you must use an API key. You can get an organization API key from the organization’s Settings accessible in the top right of the navigation bar in the Viam app.

2. Use the API key with the data_client

Use the API key and TabularDataByFilter(), TabularDataBySQL(), TabularDataByMQL(), andDeleteTabularData() to query data by creating and running the following Python script:

Note

Make sure to replace the value in line 30 with your correct sensor name, line 35 with your organization ID which you can get by running viam organizations list, and line 37 with your location ID which you can get by running viam locations list.

import asyncio
import bson

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(
      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

    # TODO: replace "my-sensor" with your correct sensor name
    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(
      # TODO: Replace  <ORGANIZATION-ID> with your organization ID
      organization_id='<ORGANIZATION-ID>',
      mql_binary=[
        # TODO: Replace  <LOCATION-ID> with your location ID
        bson.dumps({'$match': {'location_id': '<LOCATION-ID>'}}),
        bson.dumps({
          "$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"}
          }
        })
      ])
    print(data)

    viam_client.close()

if __name__ == '__main__':
    asyncio.run(main())

Adjust the Python script to query your data further with the data_client API.

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.

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!