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

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

    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(
      organization_id=organization_id,
      mql_query=[
        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"}
          }
        })
      ])

    viam_client.close()

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