> 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/advanced/measure-and-dimension-behavior.md).

# Measure and dimension behavior

Clarify the semantic rules that shape calculations, grouping, filtering, and relationships.

Behavior tells you how a measure or dimension should be interpreted in analysis. Read it before you choose a member, group results, or compare values across time.

{% hint style="info" %}
Each column in metadata carries a `behavior` field. It tells you what the value *means* in analysis, separate from `ltype` (string, number, time) and `details.agg_type` (count, sum, avg). Read `behavior.type` before you pick a measure or interpret a result.
{% endhint %}

{% hint style="warning" %}
If you sum net revenue across thirty daily snapshots without deduplicating orders, you inflate totals. No error is thrown. The query succeeds. `behavior.type: stock` is what warns you this can happen.
{% endhint %}

### Measure types

| Type      | Meaning                                                                        | Use it safely                                                                                                                                                                                                            |
| --------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `simple`  | Plain count, sum, avg, min, or max.                                            | Group by any dimension and sum across any time range. Examples: `orders.total_units`, `products.sku_count`.                                                                                                              |
| `flow`    | Amount accumulated during a time window. January plus February equals Jan–Feb. | Always set `timeDimensions` with a `dateRange` in [REST](https://v2.dataos.info/references/interfaces/apis/data-product-apis/querying-data-products/rest.md). Examples: `orders.total_revenue`, `orders.returned_units`. |
| `stock`   | Level at a point in time.                                                      | Sum across entities such as brands or store regions. Do not sum across time. Pin time to a single point or narrow boundary. Check `time_dimension`, `period_treatment` (`last`, `avg`, `first`), and `period_grain`.     |
| `ratio`   | Numerator divided by denominator at the query grain.                           | Do not average a pre-computed ratio. The API recomputes it from parts. Check `behavior.numerator` and `behavior.denominator`. Example: `orders.return_rate`.                                                             |
| `derived` | Built from other measures, such as growth rates or shifted comparisons.        | Check `behavior.measure_refs` for dependencies.                                                                                                                                                                          |

### Dimension types

| Type          | Meaning                                                         | Use it safely                                                                           |
| ------------- | --------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| `categorical` | A standard analysis category.                                   | Safe in `dimensions[]`. Examples: `orders.store_region`, `products.brand`.              |
| `identifier`  | A key for filtering and joining.                                | Do not group by it. Most identifiers are `public: false` and cannot appear in queries.  |
| `bucketing`   | A numeric range band, such as a price tier.                     | Group it like a categorical dimension.                                                  |
| `ordinal`     | An ordered category, such as a size band or satisfaction score. | Group it like a categorical dimension. Alphabetic sorting may not match semantic order. |

### Reading behavior from metadata

```python
behavior = col.get("behavior", {})
behavior_type = behavior.get("type")
# measures: simple | flow | stock | ratio | derived
# dimensions: categorical | identifier | bucketing | ordinal
```

### Author warnings

Columns and models can carry `ai_context.caveats[]`: short notes from the model author. Read them before using a measure.

```json
{
  "ai_context": {
    "caveats": [
      "Net revenue is per order day; use the orders_delivered segment before comparing totals."
    ]
  }
}
```


---

# 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/advanced/measure-and-dimension-behavior.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.
