# Manage data with the CLI Export captured data to your local machine, organize it with tags, delete old data, and configure database access for direct queries. ##### Prerequisites You need the Viam CLI installed and authenticated. See [Viam CLI overview](https://docs.viam.com/cli/overview/) for installation and authentication instructions. ## Find your IDs Many data commands require an organization ID, location ID, or part ID. To look up these values: ```sh viam organizations list ``` ```sh viam locations list ``` ```sh viam machines list --organization= --location= ``` ```sh viam machines part list --machine= ``` ## Export data ### Export images and binary files Export all binary data from an organization: ```sh viam data export binary filter \ --destination=./my-data \ --org-ids= ``` The CLI downloads files into the destination directory and prints progress as it goes. Narrow the export with filters: ```sh viam data export binary filter \ --destination=./my-data \ --org-ids= \ --mime-types=image/jpeg,image/png \ --machine-id= \ --start=2026-01-01T00:00:00Z \ --end=2026-02-01T00:00:00Z ``` Available filters: | Filter | Flag | Example | | --- | --- | --- | | By machine | `--machine-id` or `--machine-name` | `--machine-id=abc123` | | By part | `--part-id` or `--part-name` | `--part-id=def456` | | By location | `--location-ids` | `--location-ids=loc1,loc2` | | By time range | `--start`, `--end` | `--start=2026-01-01T00:00:00Z` | | By component | `--component-name`, `--component-type` | `--component-name=my-camera` | | By MIME type | `--mime-types` | `--mime-types=image/jpeg,image/png` | | By tag | `--tags` | `--tags=defective,reviewed` | | By bounding box label | `--bbox-labels` | `--bbox-labels=screw,bolt` | Export specific files by their binary data IDs: ```sh viam data export binary ids \ --destination=./my-data \ --binary-data-ids=aaa,bbb,ccc ``` ### Export sensor and tabular data Tabular exports require a part ID and resource identifier: ```sh viam data export tabular \ --destination=./sensor-data \ --part-id= \ --resource-name=my-sensor \ --resource-subtype=rdk:component:sensor \ --method=Readings ``` Output is written to a `data.ndjson` file (one JSON object per line). You can also filter by time range with `--start` and `--end`. ## Tag data Tags help you organize data for filtering, dataset creation, and search. ### Add tags by ID Add tags to specific files by their binary data IDs: ```sh viam data tag ids add \ --tags=reviewed,approved \ --binary-data-ids=aaa,bbb ``` Remove tags from specific files: ```sh viam data tag ids remove \ --tags=reviewed \ --binary-data-ids=aaa,bbb ``` ### Add tags by filter #### Note The filter-based tag commands (`tag filter add` and `tag filter remove`) use deprecated underlying APIs. They still work but may be removed in a future release. Prefer the ID-based commands above when possible. Add tags to all data matching a filter: ```sh viam data tag filter add \ --tags=reviewed,approved \ --org-ids= \ --location-ids= \ --mime-types=image/jpeg ``` Remove tags by filter: ```sh viam data tag filter remove \ --tags=reviewed \ --org-ids= ``` ## Delete data ### Delete binary data Delete binary data matching a filter. Both `--start` and `--end` are required: ```sh viam data delete binary \ --org-ids= \ --mime-types=image/jpeg \ --start=2026-01-01T00:00:00Z \ --end=2026-02-01T00:00:00Z ``` ### Delete tabular data Delete tabular data older than a specified number of days. Pass `0` to delete all tabular data for your organization. ```sh viam data delete tabular --org-id= --delete-older-than-days=90 ``` If the organization has a [hot data store](https://docs.viam.com/data/hot-data-store/), matching data is deleted from that store as well. #### Caution Passing `--delete-older-than-days=0` deletes **all** tabular data in the organization. This command has no component or location filter. ## Query data Run SQL or MQL queries against your organization’s tabular data, or query binary data metadata by filter, directly from the CLI. ### Query tabular data with SQL ```sh viam data query tabular sql --org-id= \ --sql="SELECT component_name, data FROM readings WHERE time_received >= CAST('2025-01-01T00:00:00Z' AS TIMESTAMP) LIMIT 10" ``` Results are printed to stdout as NDJSON (one JSON object per line). Use `--destination` to write results to a file instead: ```sh viam data query tabular sql --org-id= \ --sql="SELECT * FROM readings WHERE time_received >= CAST('2025-01-01T00:00:00Z' AS TIMESTAMP) LIMIT 100" \ --destination=./query-results ``` SQL queries run against your `standard` tabular data. To query the [hot data store](https://docs.viam.com/data/hot-data-store/) or pipeline results, use MQL with `--data-source-type`, shown below. ### Query tabular data with MQL ```sh viam data query tabular mql --org-id= \ --mql='[{"$match":{"component_name":"my-sensor"}},{"$limit":10}]' ``` For complex queries, put the MQL in a JSON file and use `--mql-path`: ```sh viam data query tabular mql --org-id= --mql-path=./my-query.json ``` ### Query the hot data store or pipeline results Use `--data-source-type` to query data from different sources: ```sh # query the hot data store viam data query tabular mql --org-id= --data-source-type=hot-storage \ --mql='[{"$limit":5}] # query pipeline results by ID viam data query tabular mql --org-id= --data-source-type=pipeline-sink \ --pipeline-id= --mql='[{"$limit":5}] # query pipeline results by name viam data query tabular mql --org-id= --data-source-type=pipeline-sink \ --pipeline-name=my-pipeline --mql='[{"$limit":5}] ``` ### Query binary data metadata Query binary data metadata matching a filter. Returns metadata only, not binary content. ```sh # query binary data metadata for a specific component viam data query binary filter --org-ids= --component-name=front-camera --mime-types=image/jpeg --limit=10 # save results to a file viam data query binary filter --org-ids= --component-name=front-camera --destination=./query-results ``` See [Query data in the app](https://docs.viam.com/data/query-data/) for SQL and MQL syntax reference. ## Configure database access To query synced data directly with MongoDB-compatible tools like `mongosh` or Grafana, set up a database user: ```sh viam data database configure --org-id= --password= ``` #### Caution If you already have database credentials configured, changing the password breaks existing connections from dashboards and integrations that use the old password. Get the connection hostname: ```sh viam data database hostname --org-id= ``` Use the returned hostname with your MongoDB client. See [Visualize data](https://docs.viam.com/data/visualize-data/) for Grafana setup instructions. ## Manage data indexes Create custom indexes to speed up queries on large datasets. The `--collection-type` flag specifies the target: `hot-storage` for hot data store collections, or `pipeline-sink` for data pipeline output collections (requires `--pipeline-name`). The `--index-path` flag takes a JSON file defining the index using [MongoDB index specification format](https://www.mongodb.com/docs/manual/reference/command/createIndexes/): ```json { "key": { "meta.captured_at": 1, "tags": 1 }, "name": "captured-at-tags" } ``` ```sh viam data index create \ --collection-type=hot-storage \ --index-path=./my-index.json ``` List existing indexes: ```sh viam data index list --collection-type=hot-storage ``` Delete an index: ```sh viam data index delete --collection-type=hot-storage --index-name=my-index ```