Query sensor data with 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

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:

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