> For the complete documentation index, see [llms.txt](https://v2.dataos.info/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://v2.dataos.info/references/interfaces/apis/data-product-apis/querying-data-products/rest.md).

# REST

Reference for expressing semantic analytics through structured JSON requests.

Use Semantic REST when an application needs to construct governed analytical queries as JSON. It is the default choice for dashboards, backend services, and generated queries because the request describes intent (measures, dimensions, filters, and time grain) without exposing warehouse SQL.

**Endpoint:** `POST /api/v1/query/semantic/rest`

## Submit a query

```bash
curl --request POST "$BASE_URL/query/semantic/rest" \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "query": {
      "measures": ["orders.total_revenue"],
      "dimensions": ["orders.store_region"],
      "timeDimensions": [
        {
          "dimension": "orders.order_date",
          "granularity": "month",
          "dateRange": ["2026-01-01", "2026-06-30"]
        }
      ],
      "filters": [
        {
          "member": "orders.status",
          "operator": "equals",
          "values": ["delivered"]
        }
      ],
      "order": [["orders.order_date", "asc"]],
      "limit": 1000,
      "timezone": "Asia/Kolkata"
    }
  }'
```

The top-level `query` object is required. A query must include at least one non-empty `measures`, `dimensions`, or `timeDimensions` field. Member names use `<model>.<member>`; dimensions can also use a three-part join path exposed by the semantic schema.

## Query fields

| Property         | Type            | Description                                                                                          |
| ---------------- | --------------- | ---------------------------------------------------------------------------------------------------- |
| `measures`       | array           | Measures to aggregate, in `table.field` form.                                                        |
| `dimensions`     | array           | Dimensions to group by, in `table.field` form.                                                       |
| `filters`        | array           | Filter objects and logical operators. See [Filters](#filters).                                       |
| `timeDimensions` | array           | Time dimension with an optional date range and granularity. See [Time dimensions](#time-dimensions). |
| `segments`       | array           | Named filters defined in the data model.                                                             |
| `limit`          | number          | Row limit for the result set. Default `10000`; max `50000`.                                          |
| `offset`         | number          | Number of leading rows to skip. Defaults to `0`.                                                     |
| `order`          | object or array | Sort specification. See [Ordering](#ordering).                                                       |
| `timezone`       | string          | IANA time zone applied to time dimensions, for example `America/Los_Angeles`. Defaults to `UTC`.     |

## Filters

Each filter object takes three keys:

| Key        | Description                                                                                                                       |
| ---------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `member`   | The dimension or measure to filter on, for example `orders.total_units`.                                                          |
| `operator` | The comparison to apply. Available operators depend on whether the member is a measure or a dimension, and on the dimension type. |
| `values`   | Array of values. Values are always strings. Dates go in as strings in `YYYY-MM-DD` format.                                        |

### Dimension filters vs measure filters

Filters behave differently depending on what they target. A filter on a dimension restricts the raw rows before aggregation, equivalent to `WHERE`. A filter on a measure restricts the results after the measure has been calculated, equivalent to `HAVING`.

### Operators

| Operator         | Description                                                                     | Types                      | Example                                                                                                 |
| ---------------- | ------------------------------------------------------------------------------- | -------------------------- | ------------------------------------------------------------------------------------------------------- |
| `equals`         | Exact match. Supports multiple values.                                          | `string`, `number`, `time` | `{"member": "customers.country", "operator": "equals", "values": ["US", "UK", "India"]}`                |
| `notEquals`      | Inverse of `equals`. Supports multiple values.                                  | `string`, `number`, `time` | `{"member": "customers.country", "operator": "notEquals", "values": ["France"]}`                        |
| `contains`       | Case-insensitive `LIKE` with wildcards on both sides. Supports multiple values. | `string`                   | `{"member": "products.brand", "operator": "contains", "values": ["nike", "adidas"]}`                    |
| `notContains`    | Inverse of `contains`. Supports multiple values.                                | `string`                   | `{"member": "products.brand", "operator": "notContains", "values": ["nike", "adidas"]}`                 |
| `startsWith`     | Case-insensitive `LIKE` with a trailing wildcard. Supports multiple values.     | `string`                   | `{"member": "products.brand", "operator": "startsWith", "values": ["lev"]}`                             |
| `notStartsWith`  | Inverse of `startsWith`.                                                        | `string`                   | `{"member": "products.brand", "operator": "notStartsWith", "values": ["lev"]}`                          |
| `endsWith`       | Case-insensitive `LIKE` with a leading wildcard. Supports multiple values.      | `string`                   | `{"member": "products.product_name", "operator": "endsWith", "values": ["jeans"]}`                      |
| `notEndsWith`    | Inverse of `endsWith`.                                                          | `string`                   | `{"member": "products.product_name", "operator": "notEndsWith", "values": ["jeans"]}`                   |
| `gt`             | Greater than.                                                                   | `number`                   | `{"member": "orders.total_units", "operator": "gt", "values": ["100"]}`                                 |
| `gte`            | Greater than or equal to.                                                       | `number`                   | `{"member": "orders.total_units", "operator": "gte", "values": ["100"]}`                                |
| `lt`             | Less than.                                                                      | `number`                   | `{"member": "orders.total_units", "operator": "lt", "values": ["100"]}`                                 |
| `lte`            | Less than or equal to.                                                          | `number`                   | `{"member": "orders.total_units", "operator": "lte", "values": ["100"]}`                                |
| `set`            | Member is not `NULL`. Omit `values`.                                            | `number`, `string`, `time` | `{"member": "customers.phone_number", "operator": "set"}`                                               |
| `notSet`         | Member is `NULL`. Omit `values`.                                                | `number`, `string`, `time` | `{"member": "customers.phone_number", "operator": "notSet"}`                                            |
| `inDateRange`    | Restricts a time dimension to a date range.                                     | `time`                     | `{"member": "orders.order_date", "operator": "inDateRange", "values": ["2025-01-01", "2025-12-31"]}`    |
| `notInDateRange` | Inverse of `inDateRange`.                                                       | `time`                     | `{"member": "orders.order_date", "operator": "notInDateRange", "values": ["2025-01-01", "2025-12-31"]}` |
| `beforeDate`     | Everything before a date. Pass a single value.                                  | `time`                     | `{"member": "orders.order_date", "operator": "beforeDate", "values": ["2025-01-01"]}`                   |
| `afterDate`      | Everything after a date. Pass a single value.                                   | `time`                     | `{"member": "orders.order_date", "operator": "afterDate", "values": ["2025-01-01"]}`                    |

### Logical operators

A filter entry can be a logical operator instead of a comparison. A logical operator carries exactly one key:

* `or`: an array of one or more filters or nested logical operators
* `and`: an array of one or more filters or nested logical operators

```json
{
  "or": [
    {
      "member": "products.brand",
      "operator": "contains",
      "values": ["Nike", "Adidas"]
    },
    {
      "member": "products.category",
      "operator": "equals",
      "values": ["Jeans"]
    },
    {
      "and": [
        {
          "member": "products.brand",
          "operator": "equals",
          "values": ["Levi's"]
        }
      ]
    }
  ]
}
```

> **Dimensions and measures cannot share a logical operator.** The following is rejected because `products.brand` and `products.category` are dimensions while `orders.total_revenue` is a measure, and all three sit under the same `or`.

```json
{
  "or": [
    {
      "member": "products.brand",
      "operator": "contains",
      "values": ["Nike", "Adidas"]
    },
    {
      "member": "products.category",
      "operator": "equals",
      "values": ["Jeans"]
    },
    {
      "and": [
        {
          "member": "orders.total_revenue",
          "operator": "gt",
          "values": ["100"]
        }
      ]
    }
  ]
}
```

Split the measure condition into a separate top-level filter entry instead.

## Time dimensions

`timeDimensions` is a shorthand for filtering and bucketing a time column in one place. Each entry takes a `dimension`, an optional `dateRange`, and an optional `granularity`.

| Key           | Description                                                                                                                                 |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `dimension`   | The time dimension to filter and group on.                                                                                                  |
| `dateRange`   | A fixed range as `["YYYY-MM-DD", "YYYY-MM-DD"]`, or a relative expression.                                                                  |
| `granularity` | Bucket size for grouping. One of `second`, `minute`, `hour`, `day`, `week`, `month`, `quarter`, `year`. Omit it to filter without grouping. |

### Date range presets

Accepted as `dateRange` strings in `timeDimensions[]`. Evaluated in the query timezone.

| Category          | Presets                                                                                                                                           |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| Single day        | `today`, `yesterday`, `tomorrow`                                                                                                                  |
| Rolling window    | `last 7 days`, `last 14 days`, `last 30 days`, `last 60 days`, `last 90 days`, `last 180 days`, `last 365 days`, `last 6 months`, `last 3 months` |
| Calendar: past    | `last week`, `last month`, `last quarter`, `last year`                                                                                            |
| Calendar: current | `this week`, `this month`, `this quarter`, `this year`                                                                                            |
| Calendar: future  | `next week`, `next month`, `next quarter`, `next year`                                                                                            |
| Extended          | `from 7 days ago to now`, `from now to 2 weeks from now`, `last 360 days`                                                                         |

```json
{
  "query": {
    "measures": ["orders.total_units"],
    "timeDimensions": [
      {
        "dimension": "orders.order_date",
        "dateRange": "last week",
        "granularity": "day"
      }
    ]
  }
}
```

For anything the shorthand does not cover, such as excluding a range, use the `time` operators in `filters`.

## Ordering

The default form is an object whose keys are measures or dimensions and whose values are `asc` or `desc`. Sort precedence follows key order.

```json
{
  "order": {
    "products.product_name": "asc",
    "orders.total_units": "desc"
  }
}
```

Because key order in an object is not guaranteed by every client library, an array of tuples is also supported and is the safer choice when precedence matters:

```json
{
  "order": [
    ["orders.order_date", "asc"],
    ["orders.total_units", "asc"]
  ]
}
```

### Default order

When `order` is omitted, results are sorted by the first rule that applies:

1. The first time dimension with a granularity, ascending.
2. Otherwise the first measure, descending.
3. Otherwise the first dimension, ascending.

## Pagination

`limit` and `offset` page through a result set. There is no total row count in the response, so keep requesting pages until a page returns fewer rows than `limit`.

```json
{
  "query": {
    "measures": ["orders.total_units"],
    "dimensions": ["products.product_name"],
    "order": [["products.product_name", "asc"]],
    "limit": 1000,
    "offset": 2000
  }
}
```

Always set a deterministic `order` when paginating. Without one, rows can shift between pages and you will get duplicates and gaps.

For result sets beyond a few thousand rows, see the [pagination recipe](https://v2.dataos.info/consume/recipes/retrieve-large-result-sets-with-pagination) in Consume.

## Transpile without executing

Append `?transpile_only=true` to inspect the generated warehouse SQL. The endpoint returns `200`, compiled SQL, and parameters. It creates no statement.

Normal execution returns `202 Accepted`. Continue with the [query lifecycle](https://v2.dataos.info/references/interfaces/apis/data-product-apis/querying-data-products/advanced/query-lifecycle.md).

## Next steps

* Choose [Semantic SQL](https://v2.dataos.info/references/interfaces/apis/data-product-apis/querying-data-products/semantic-sql.md) when consumers need to author governed SQL.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://v2.dataos.info/references/interfaces/apis/data-product-apis/querying-data-products/rest.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
