# Dimensions, Measurements, and Semantic Data Objects ## Overview Every semantic query selects **fields** from **Semantic Data Objects**. A Semantic Data Object (SDO) is the queryable unit of a Semantic Model: it wraps one underlying Data 360 table and exposes that table's columns as semantic fields. Each field plays one of two roles: - **Dimensions** are the descriptive, non-aggregated attributes you group and filter by — names, dates, categories, identifiers. - **Measurements** are the numeric values you aggregate — revenue, counts, amounts. A measurement carries a default aggregation method that applies when you don't specify one. An SDO wraps one of three underlying object types, given by the model field `dataObjectType`: - `Dmo` — a Data Model Object. - `Dlo` — a Data Lake Object. - `Cio` — a Calculated Insight Object. All three resolve to a queryable table, and you reference their fields the same way regardless of type. You select fields by adding entries to the `fields` array of `structuredSemanticQuery`. Each entry is a `QueryField` that wraps an `expression` (the field or calculation to return) plus optional per-field settings such as `alias`, `rowGrouping`, and `semanticAggregationMethod`. ## Metadata in the model Semantic Data Objects and their dimension/measurement fields are defined in the Semantic Data Model, not per query. An SDO declares its `apiName`, its underlying `dataObjectName`, its `dataObjectType` (`Dmo` | `Dlo` | `Cio`), and its `semanticDimensions` and `semanticMeasurements`. Each field carries its `apiName`, `dataType`, and — for measurements — an `aggregationType`. A query references these definitions by name; it never redefines them. For the authoring shape of these entities, see [Semantic Data Object](/docs/data/semantic-layer/guide/connect-api-in-depth-entities.md#semantic-data-object-semanticdataobject) and [Semantic Data Object Field](/docs/data/semantic-layer/guide/connect-api-in-depth-entities.md#semantic-data-object-field-semanticdataobjectfield) in the Authoring API. ## Query usage ### Selecting fields Add each field you want returned as an entry in the `fields` array. The only required part of a `QueryField` is its `expression`. This example selects three dimension fields from a single data object with no grouping or aggregation. ```json { "structured_semantic_query": { "fields": [ { "expression": { "table_field": { "name": "Account Name", "table_name": "AccountSemanticLayer__dll" } } }, { "expression": { "table_field": { "name": "Annual Revenue", "table_name": "AccountSemanticLayer__dll" } } }, { "expression": { "table_field": { "name": "Is Active", "table_name": "AccountSemanticLayer__dll" } } } ], "options": { "detailed_rows": true } }, "semanticModelApiName": "test_model" } ``` Beyond `expression`, a `QueryField` can carry: - `alias` — a name for the field in the query and response (see [Aliases](#aliases)). - `rowGrouping` and `grouping` — mark the field as a grouping axis (see [Grouping](/docs/data/semantic-layer/guide/query-api-in-depth-grouping.md)). - `semanticAggregationMethod` — the aggregation to apply to a measurement (see [Aggregation & Totals](/docs/data/semantic-layer/guide/query-api-in-depth-aggregation.md)). - `showMissingValues` — data densification settings (see [Predict and Forecast](/docs/data/semantic-layer/guide/query-api-in-depth-predict-forecast.md)). ### Field references: `table_field` vs. `semantic_field` An `expression` names the field to return. Two reference forms exist: - **`table_field`** points at a physical column and requires both `name` (the field's `apiName`) and `table_name` (the SDO's `apiName`). Use it for plain dimensions and measurements. - **`semantic_field`** points at a virtual field by `name` only. Use it for calculated dimensions, calculated measurements, and other model-defined fields whose value is computed rather than stored in a single column. This example returns two grouped `table_field` dimensions alongside a `semantic_field` that references a model-defined calculated measurement. ```json { "structured_semantic_query": { "fields": [ { "expression": { "table_field": { "name": "semantic__AccountSource__c", "table_name": "SemanticAccount__dlm" } }, "row_grouping": true }, { "expression": { "table_field": { "name": "semantic__Id__c", "table_name": "SemanticAccount__dlm" } }, "row_grouping": true }, { "expression": { "semantic_field": { "name": "summary_level_example" } }, "semantic_aggregation_method": "SEMANTIC_AGGREGATION_METHOD_AUTO" }, { "expression": { "table_field": { "name": "semantic__Number__c", "table_name": "SemanticAccount__dlm" } }, "semantic_aggregation_method": "SEMANTIC_AGGREGATION_METHOD_SUM" } ], "options": { "detailed_rows": true, "grand_total": true } }, "semantic_model": { "apiName": "Sales", "semanticDataObjects": [ { "apiName": "SemanticAccount__dlm", "dataObjectName": "ssot__Account__dlm", "dataObjectType": "Dmo", "semanticDimensions": [ // ... ], "semanticMeasurements": [ // ... ] } ], "semanticCalculatedMeasurements": [ { "apiName": "summary_level_example", "dataType": "Number", "expression": "sum(SemanticAccount__dlm.semantic__Number__c) + 100", "syntax": "Salesforce", "aggregationType": "UserAgg" } // ... ] } } ``` ### Data types Each dimension and measurement declares a `dataType` in the model that governs how the field is interpreted and formatted. Observed wire values include `Text`, `Number`, `Date`, `DateTime`, `Boolean`, `Currency`, `Percentage`, `Duration`, `Url`, `Email`, and `PhoneNumber`. You don't set `dataType` in the query — you reference the field, and its model-defined type applies. This model fragment shows dimension and measurement fields carrying their types. ```json { "semantic_model": { "apiName": "Sales", "semanticDataObjects": [ { "apiName": "SemanticAccount__dlm", "dataObjectName": "ssot__Account__dlm", "dataObjectType": "Dmo", "semanticDimensions": [ { "apiName": "semantic__Name__c", "dataType": "Text", "dataObjectFieldName": "ssot__Name__c" } // ... ], "semanticMeasurements": [ { "apiName": "semantic__Number__c", "dataType": "Percentage", "dataObjectFieldName": "ssot__Number__c" } ] } // ... ] } } ``` Converting or overriding a field's type is an authoring-time concern defined on the field, not a query knob — see [Semantic Data Object Field](/docs/data/semantic-layer/guide/connect-api-in-depth-entities.md#semantic-data-object-field-semanticdataobjectfield). ### Aliases Set `alias` on a `QueryField` to name the field in the query and its response. Once aliased, a field can be referenced by that alias elsewhere in the query — for example, `sort_by_field_alias` in a sort order. This example aliases a field `"Simple Calc"` and then sorts by that alias. ```json { "structured_semantic_query": { "fields": [ { "expression": { "calculated_field": { "name": "simple_calc", "expression": "123", "calculated_measure_expression": { "measure_output_type": "SEMANTIC_MEASUREMENT_TYPE_NUMBER" } } }, "semantic_aggregation_method": "SEMANTIC_AGGREGATION_METHOD_SUM", "alias": "Simple Calc" } // ... ], "options": { "detailed_rows": true, "sort_orders": [ { "simple_sort_order": { "sort_by_field_alias": "Simple Calc", "sorting_order": "DESC" } } ] } }, "semanticModelApiName": "test_model" } ``` ### Logical views A **logical view** is a queryable object whose fields come from more than one underlying data object, composed inside the model rather than stored in a single physical table. You query it exactly like a plain data object: reference its columns with `table_field`, using the logical view's `apiName` as `table_name`. Each output column is named `_` — the member object's API name and the field's API name joined by an underscore — which keeps two same-named fields from different members distinct. Logical views come in three types — standard (join), union, and custom SQL — each covered on its own page, with examples. See [Logical Views](/docs/data/semantic-layer/guide/query-api-in-depth-logical-views.md). ## Reference Only the fields introduced in this section are listed. For the full request schema, see [Request Reference](/docs/data/semantic-layer/guide/query-api-in-depth-fields.md). | Field (wire name) | Type | Required | Description | | ----------------------------- | ------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `fields` | QueryField[] | Y | The dimensions, measurements, and calculations to return. | | `expression` | Expression | Y | The field or calculation a `QueryField` returns (e.g., `table_field`, `semantic_field`). | | `table_field` | TableField | N | Physical column reference; requires `name` and `table_name`. | | `semantic_field` | SemanticField | N | Virtual/model-defined field reference; requires `name`. | | `alias` | String | N | Names the field in the query and response; referenced by sort/filter aliases. | | `semantic_aggregation_method` | SemanticAggregationMethod | N | Aggregation applied to the field (see Aggregation & Totals). | | `row_grouping` | bool | N | Marks the field as a grouping axis (see Grouping). | | `dataType` | String (enum) | — | Model-defined field type (`Text`, `Number`, `Date`, `DateTime`, `Boolean`, `Currency`, …). | | `dataObjectType` | String (enum) | — | Underlying object type of an SDO: `Dmo`, `Dlo`, or `Cio`. | | `semanticLogicalViews` | SemanticLogicalView[] | N | Logical views on the model; each bundles member data objects and their relationships and exposes their columns as one queryable object. Defined at authoring time — see Related. | ## Limitations - **A `table_field` reference requires both `name` and `table_name`.** A physical column cannot be resolved by name alone; the owning data object's `apiName` must be supplied in `table_name`. - **Field metadata is model-defined, not query-defined.** A query cannot introduce a data object, change a field's `dataType`, or set a measurement's default aggregation — it can only reference fields that already exist in the model. - **A logical view exposes its columns under composite names, referenced by the view's own `apiName`.** Use `_` as the column `name` and the logical view's `apiName` as `table_name` — this is the form the view exposes, distinct from the member object's original field `apiName`. ## Related - [Semantic Data Object](/docs/data/semantic-layer/guide/connect-api-in-depth-entities.md#semantic-data-object-semanticdataobject) — Authoring API for defining data objects and their `dataObjectType`. - [Semantic Data Object Field](/docs/data/semantic-layer/guide/connect-api-in-depth-entities.md#semantic-data-object-field-semanticdataobjectfield) — Authoring API for defining dimension/measurement fields, data types, and type conversion. - [Semantic Logical View](/docs/data/semantic-layer/guide/connect-api-in-depth-entities.md#semantic-logical-view-semanticlogicalview) — Authoring API for defining logical views and their member objects. - [Logical Views](/docs/data/semantic-layer/guide/query-api-in-depth-logical-views.md) — Standard, union, and custom SQL logical views. - [Relationships & Joins](/docs/data/semantic-layer/guide/query-api-in-depth-relationships.md) — Connecting a logical view to another data object. - [Calculated Fields](/docs/data/semantic-layer/guide/query-api-in-depth-calculated-fields.md) — Reference model calculated dimensions/measurements via `semantic_field`, or inline a `calculated_field`. - [Grouping](/docs/data/semantic-layer/guide/query-api-in-depth-grouping.md) — Use `rowGrouping` and `grouping` to group by a field. - [Aggregation & Totals](/docs/data/semantic-layer/guide/query-api-in-depth-aggregation.md) — Set `semanticAggregationMethod` to aggregate a measurement. - [Filtering](/docs/data/semantic-layer/guide/query-api-in-depth-filtering.md) — Filter on dimensions, measurements, and calculated fields. - [Request Reference](/docs/data/semantic-layer/guide/query-api-in-depth-fields.md) — Complete field schema.