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:
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.
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 and Semantic Data Object Field in the Authoring API.
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.
1{
2 "structured_semantic_query": {
3 "fields": [
4 {
5 "expression": {
6 "table_field": {
7 "name": "Account Name",
8 "table_name": "AccountSemanticLayer__dll"
9 }
10 }
11 },
12 {
13 "expression": {
14 "table_field": {
15 "name": "Annual Revenue",
16 "table_name": "AccountSemanticLayer__dll"
17 }
18 }
19 },
20 {
21 "expression": {
22 "table_field": {
23 "name": "Is Active",
24 "table_name": "AccountSemanticLayer__dll"
25 }
26 }
27 }
28 ],
29 "options": {
30 "detailed_rows": true
31 }
32 },
33 "semanticModelApiName": "test_model"
34}Beyond expression, a QueryField can carry:
alias — a name for the field in the query and response (see Aliases).rowGrouping and grouping — mark the field as a grouping axis (see Grouping).semanticAggregationMethod — the aggregation to apply to a measurement (see Aggregation & Totals).showMissingValues — data densification settings (see Predict and Forecast).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.
1{
2 "structured_semantic_query": {
3 "fields": [
4 {
5 "expression": {
6 "table_field": {
7 "name": "semantic__AccountSource__c",
8 "table_name": "SemanticAccount__dlm"
9 }
10 },
11 "row_grouping": true
12 },
13 {
14 "expression": {
15 "table_field": {
16 "name": "semantic__Id__c",
17 "table_name": "SemanticAccount__dlm"
18 }
19 },
20 "row_grouping": true
21 },
22 {
23 "expression": {
24 "semantic_field": {
25 "name": "summary_level_example"
26 }
27 },
28 "semantic_aggregation_method": "SEMANTIC_AGGREGATION_METHOD_AUTO"
29 },
30 {
31 "expression": {
32 "table_field": {
33 "name": "semantic__Number__c",
34 "table_name": "SemanticAccount__dlm"
35 }
36 },
37 "semantic_aggregation_method": "SEMANTIC_AGGREGATION_METHOD_SUM"
38 }
39 ],
40 "options": {
41 "detailed_rows": true,
42 "grand_total": true
43 }
44 },
45 "semantic_model": {
46 "apiName": "Sales",
47 "semanticDataObjects": [
48 {
49 "apiName": "SemanticAccount__dlm",
50 "dataObjectName": "ssot__Account__dlm",
51 "dataObjectType": "Dmo",
52 "semanticDimensions": [
53 // ...
54 ],
55 "semanticMeasurements": [
56 // ...
57 ]
58 }
59 ],
60 "semanticCalculatedMeasurements": [
61 {
62 "apiName": "summary_level_example",
63 "dataType": "Number",
64 "expression": "sum(SemanticAccount__dlm.semantic__Number__c) + 100",
65 "syntax": "Salesforce",
66 "aggregationType": "UserAgg"
67 }
68 // ...
69 ]
70 }
71}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.
1{
2 "semantic_model": {
3 "apiName": "Sales",
4 "semanticDataObjects": [
5 {
6 "apiName": "SemanticAccount__dlm",
7 "dataObjectName": "ssot__Account__dlm",
8 "dataObjectType": "Dmo",
9 "semanticDimensions": [
10 {
11 "apiName": "semantic__Name__c",
12 "dataType": "Text",
13 "dataObjectFieldName": "ssot__Name__c"
14 }
15 // ...
16 ],
17 "semanticMeasurements": [
18 {
19 "apiName": "semantic__Number__c",
20 "dataType": "Percentage",
21 "dataObjectFieldName": "ssot__Number__c"
22 }
23 ]
24 }
25 // ...
26 ]
27 }
28}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.
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.
1{
2 "structured_semantic_query": {
3 "fields": [
4 {
5 "expression": {
6 "calculated_field": {
7 "name": "simple_calc",
8 "expression": "123",
9 "calculated_measure_expression": {
10 "measure_output_type": "SEMANTIC_MEASUREMENT_TYPE_NUMBER"
11 }
12 }
13 },
14 "semantic_aggregation_method": "SEMANTIC_AGGREGATION_METHOD_SUM",
15 "alias": "Simple Calc"
16 }
17 // ...
18 ],
19 "options": {
20 "detailed_rows": true,
21 "sort_orders": [
22 {
23 "simple_sort_order": {
24 "sort_by_field_alias": "Simple Calc",
25 "sorting_order": "DESC"
26 }
27 }
28 ]
29 }
30 },
31 "semanticModelApiName": "test_model"
32}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 <SourceObjectApiName>_<fieldApiName> — 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.
Only the fields introduced in this section are listed. For the full request schema, see Request Reference.
| 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. |
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.dataType, or set a measurement’s default aggregation — it can only reference fields that already exist in the model.apiName. Use <SourceObjectApiName>_<fieldApiName> 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.dataObjectType.semantic_field, or inline a calculated_field.rowGrouping and grouping to group by a field.semanticAggregationMethod to aggregate a measurement.
j