# Shared Dimensions

## Overview

A shared dimension is a Semantic Data Object that multiple fact tables connect through, so a single query can analyze several facts along a common axis — a shared Product, Date, or Account key — without defining duplicate relationships between each fact and the dimension.

There is no shared-dimension request construct. You mark the object as shared in the model, and at query time you simply select fields from the shared object and from the fact objects; the engine combines results across the facts on the shared columns.

Use a shared dimension for cross-fact analysis: reporting two or more fact tables side by side, grouped or filtered along the dimension they have in common.

> **Performance:** Include a shared dimension column in the query. When the queried fact trees share no dimension, they are combined with a cross join (Cartesian product); the shared dimension supplies the join key that avoids it.

## Metadata in the model

A shared dimension is a Semantic Data Object marked with `tableType: Shared` in the Semantic Data Model. That marking lets multiple fact tables connect through the same dimension table. For definitions, see [Semantic Data Object](/docs/data/semantic-layer/guide/connect-api-in-depth-entities.md#semantic-data-object-semanticdataobject) in the Authoring API, including the `tableType` (Standard / Shared) property.

At query time the shared object behaves like any other queryable object: you select its fields through `table_field` (by physical column and table name) or `semantic_field` (by API name).

## Query usage

### Query across facts through a shared dimension

Select fields from the shared object and from the fact objects; results are combined across the facts on the shared columns. A field from the shared object (for example, a Product or Date key) supplies the join key and a common grouping axis across the facts.

```json
{
  "semantic_model": {
    "apiName": "Sales",
    "label": "Sales",
    "semanticDataObjects": [
      {
        "apiName": "SemanticAccount__dlm",
        "label": "semantic account",
        "dataObjectName": "ssot__Account__dlm",
        "dataObjectType": "Dmo",
        "tableType": "Shared",
        "semanticDimensions": [
          {
            "apiName": "semantic__Id__c",
            "label": "ssot Id c",
            "dataType": "Text",
            "dataObjectFieldName": "ssot__Id__c"
          }
          // ...
        ],
        "semanticMeasurements": [
          // ...
        ]
      }
    ]
    // ...
  }
}
```

> **Performance:** Each fact tree is aggregated to the shared-dimension grain and then combined pairwise, so cost grows with the number of fact trees combined in a single query.

### Filter scope across shared dimensions

Filter behavior across shared dimensions is directional: a filter on a fact-specific field affects only the fact tree that contains it, while a filter on a shared-dimension field affects every fact tree connected to that shared table.

> **Performance:** Accurate cardinality within each fact tree still applies and avoids row multiplication before the trees are combined.

## Reference

| Field (wire name)        | Type          | Required | Description                                                                                                                                                        |
| ------------------------ | ------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `tableType` (`"Shared"`) | String (enum) | N        | On a Semantic Data Object in the model. Marks the object as a shared dimension that multiple fact tables connect through. Defined at authoring time — see Related. |

For the full request schema, see [Request Reference](/docs/data/semantic-layer/guide/query-api-in-depth-fields.md).

## Limitations

- **Shared dimensions have no query-time request construct.** The dimension is marked `tableType: Shared` in the model and referenced by field; you cannot pass a shared-dimension directive in a query.
- **Shared-dimension filter scope is directional.** A filter on a fact-specific field affects only the fact tree containing that field; a filter on a shared-dimension field affects all connected fact trees.
- **Detail rows and aggregate (HAVING) filters do not apply across the shared-dimension path.** When a query spans fact trees connected through a shared dimension, per-tree detail rows and HAVING/advanced-dimension filters are not honored.

## Related

- [Relationships & Joins](/docs/data/semantic-layer/guide/query-api-in-depth-relationships.md) — join-path and cross-join behavior that governs how shared-dimension fact trees are combined.
- [Filtering](/docs/data/semantic-layer/guide/query-api-in-depth-filtering.md) — filter operators and how filter scope interacts with shared dimensions.
- [Semantic Data Object](/docs/data/semantic-layer/guide/connect-api-in-depth-entities.md#semantic-data-object-semanticdataobject) — Authoring API for data objects, including the `tableType` (Standard / Shared) property.
- [Request Reference](/docs/data/semantic-layer/guide/query-api-in-depth-fields.md) — Complete request schema.