> ## Documentation Index
> Fetch the complete documentation index at: https://docs.upstackdata.com/llms.txt
> Use this file to discover all available pages before exploring further.

# upstack query

> Run a measures-and-dimensions query from the command line. Wraps POST /api/query.

Run a measures-and-dimensions query against your event stream. Wraps `POST /api/query` — see the [API reference](/api-reference/overview).

## Usage

```bash theme={null}
upstack query \
  --measures orders.gross_revenue,tracked.purchases \
  --dimensions utm_source \
  --date-start 2026-04-01 \
  --date-end 2026-04-30
```

## Required flags

| Flag                                                  | Description                                                                       |
| ----------------------------------------------------- | --------------------------------------------------------------------------------- |
| `--measures <m1,m2,...>`                              | Comma-separated canonical measure ids (see [`upstack measures`](/cli/measures)).  |
| `--granularity <g>`                                   | `none`, `second`, `minute`, `hour`, `day`, `week`, `month`, `quarter`, or `year`. |
| `--date-start <YYYY-MM-DD>` `--date-end <YYYY-MM-DD>` | Date range.                                                                       |

## Optional flags

| Flag                                                        | Description                                                                                        | Default |
| ----------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | ------- |
| `--dimensions <d1,d2,...>`                                  | Comma-separated dimension ids. Max 5.                                                              |         |
| `--filter <json>`                                           | Canonical [Filter](/cli/filters) as JSON. See the [Filters](#filters) section below for the shape. |         |
| `--compare-start <YYYY-MM-DD>` `--compare-end <YYYY-MM-DD>` | Optional comparison period. Must not overlap the primary date range.                               |         |
| `--timezone <tz>`                                           | IANA timezone (e.g. `America/New_York`).                                                           | `UTC`   |

## Shared flags

All query commands ([`query`](/cli/query), [`query-attribution`](/cli/query-attribution), [`query-cohort`](/cli/query-cohort)) support these:

| Flag                 | Description                                                             | Default |
| -------------------- | ----------------------------------------------------------------------- | ------- |
| `-i, --interactive`  | Build the query step-by-step with prompts.                              |         |
| `--output <format>`  | `json`, `table`, or `csv`.                                              | `json`  |
| `--file <path>`      | Write output to a file instead of stdout.                               |         |
| `--from-file <path>` | Load query parameters from a JSON file. CLI flags override file values. |         |

## Examples

```bash theme={null}
# Gross revenue by day, last 30 days
upstack query --measures orders.gross_revenue --granularity day \
  --date-start 2026-04-01 --date-end 2026-04-30

# CSV output, broken down by UTM source
upstack query --measures orders.gross_revenue,tracked.purchases \
  --dimensions utm_source --granularity day \
  --date-start 2026-04-01 --date-end 2026-04-30 \
  --output csv --file ./april-by-source.csv

# Scope to web/POS orders for new customers via canonical filter
upstack query --measures orders.gross_revenue --granularity day \
  --date-start 2026-04-01 --date-end 2026-04-30 \
  --filter '{"and":[{"field":"orders.source_name","op":"in","value":["web","pos"]},{"field":"orders.customer_type","op":"equals","value":"new_customer"}]}'

# Interactive
upstack query -i
```

## Filters

`--filter` takes a canonical Filter JSON object. The shape is a recursive
`{ and | or | not }` group tree with leaves of the form
`{ field, op, value }`:

```json theme={null}
{
  "and": [
    { "field": "orders.source_name", "op": "in", "value": ["web", "pos"] },
    { "field": "orders.customer_type", "op": "equals", "value": "new_customer" }
  ]
}
```

Field ids are namespaced (`orders.*`, `channel.*`, `attribution.*`, `emq.*`)
and each one is only valid in certain contexts. Run
[`upstack filters --detail`](/cli/filters) to list every field with its
operators and applicable contexts before constructing a filter.

## Save a query for reuse

```bash theme={null}
upstack saved create morning-report --command query --from-file ./params.json
upstack saved run morning-report
```

See [`upstack saved`](/cli/saved-queries) for the full reference.