> 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/concepts/foundations/activation/apis/getting-started/querying-data-products/measure-and-dimension-behavior.md).

# Measure and dimension behavior

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.

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.

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.

### Measure types

**`simple`** — Plain count, sum, avg, min, max. Safe to group by any dimension and sum across any time range. Examples: `users.total_users`, `usage_events.total_events`.

**`flow`** — Amount accumulated during a time window. January plus February equals Jan–Feb. Meaningless without a bounded window. Examples: `subscriptions.churn_count`, `usage_events.api_usage_count`. Always set `timeDimensions` with a `dateRange` in [REST](/concepts/foundations/activation/apis/getting-started/querying-data-products/rest.md).

**`stock`** — Level at a point in time. Sum across entities (plan types, regions) is fine. Sum across time is not — each snapshot row counts again. Examples: `subscriptions.total_arr`, `usage_events.daily_active_users`. Pin time to a single point or narrow boundary. Metadata exposes `time_dimension`, `period_treatment` (`last`, `avg`, `first`), and `period_grain` on the behavior object.

**`ratio`** — Numerator ÷ denominator at the query grain. Do not average a pre-computed ratio column; the API recomputes from parts. Example: `subscriptions.churn_rate`. Check `behavior.numerator` and `behavior.denominator`.

**`derived`** — Built from other measures (growth rates, shifted comparisons). Check `behavior.measure_refs` for dependencies.

### Dimension types

**`categorical`** — Safe in `dimensions[]`. Examples: `users.plan_type`, `users.signup_channel`.

**`identifier`** — Filter and join only, not for grouping. Most are `public: false` and cannot appear in queries at all.

**`bucketing`** — Numeric range bands (MRR tiers). Group like categorical.

**`ordinal`** — Ordered categories (tier levels, NPS bands). Group like categorical; alphabetic sort 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 completed_orders 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://v2.dataos.info/concepts/foundations/activation/apis/getting-started/querying-data-products/measure-and-dimension-behavior.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.