> 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/cross-model-queries.md).

# Cross-model queries

Combine related business entities in a single governed analytical request.

Cross-model queries let you combine measures and dimensions from related models. They only work when the semantic graph gives the transpiler a valid and safe join path.

Mixing measures and dimensions from different models requires a join path in the transpiler. Three rules decide what works.

### Rule 1: Directionality

A join is only traversable from the model that declares it. Joins live in `model.joins[]`.

In a clothing retail catalog:

* `customers.joins` → `orders` (one\_to\_many), `store_visits` (one\_to\_many)
* `orders.joins` is empty

Valid: `orders.store_region` as a dimension while measuring `customers.total_customers` (customers declares the join).

Invalid: `customers.country` as a dimension while measuring `orders.total_units` (orders declares no path to customers).

Check `joins[]` on the model that owns your measure. Only declared targets are reachable.

### Rule 2: Fan-out

Crossing a `one_to_many` edge from the measure's model and grouping by a dimension on the many side inflates the measure. A customer with three orders appears three times when you group by `orders.store_region`, so `customers.total_customers` counts each customer three times.

Safe patterns:

* Filter across the join without grouping by the many-side dimension (filter `orders.status = delivered` while counting customers).
* Put the measure on the many-side model (`orders.total_revenue` by `orders.store_region`).

When in doubt, measure from the model that owns what you are counting. Use joins to filter, not to group.

### Rule 3: Ambiguous paths and joinHints

When multiple paths connect two models, the transpiler picks the shortest by hop count, which may not match business intent.

```
A → B → C → X
A → D → E → X   ← correct business path
A → F → X       ← shortest, picked by default
```

Set an explicit path in [REST](https://v2.dataos.info/references/interfaces/apis/data-product-apis/querying-data-products/rest.md):

```json
{
  "joinHints": [["A", "D", "E", "X"]]
}
```

Or encode the path in a member name:

```json
{
  "dimensions": ["customers.orders.products.category"]
}
```

`joinHints` is a REST request field and is not exposed by [GraphQL](https://v2.dataos.info/references/interfaces/apis/data-product-apis/querying-data-products/graphql.md). In Semantic SQL, model order and `CROSS JOIN` shape communicate the requested models; there is no separate request-body `joinHints` field.

### Safe patterns

```json
{
  "measures": ["customers.total_customers"],
  "dimensions": ["customers.country"]
}
```

```json
{
  "measures": ["customers.active_customers"],
  "filters": [
    {
      "member": "orders.status",
      "operator": "equals",
      "values": ["delivered"]
    }
  ]
}
```

```json
{
  "measures": ["orders.total_revenue"],
  "dimensions": ["orders.store_region"]
}
```

Semantic SQL equivalent for the filter-across-join case:

```sql
SELECT customers.country, MEASURE(customers.active_customers)
FROM customers
CROSS JOIN orders
WHERE orders.status = 'delivered'
GROUP BY 1;
```

### Patterns to avoid

```json
{
  "measures": ["orders.total_units"],
  "dimensions": ["customers.country"]
}
```

Transpiler error: no join path.

```json
{
  "measures": ["customers.total_customers"],
  "dimensions": ["orders.store_region"]
}
```

No error. Silent count inflation.


---

# 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/cross-model-queries.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.
