A logical view is a queryable object whose fields come from more than one underlying data object, composed inside the Semantic Model rather than stored in a single physical table. Defined as a SemanticLogicalView, it bundles its member data objects and how they combine, then exposes their columns as one flat set of fields. You query a logical view exactly like a plain data object: reference its columns with table_field, using the logical view’s apiName as table_name.
There are four types of logical view, distinguished by how the view composes its members:
UNION ALL), aligning their columns through mapped fields.Whichever type a view is, you never express the composition at query time — no join clauses, no UNION, no raw SQL travel in the request. The composition lives in the model, and a query only names the view’s columns. The single most important thing to know: a logical view is addressed by its own apiName, and its columns carry composite names (<SourceObjectApiName>_<fieldApiName>) that keep same-named fields from different members distinct.
A logical view is defined in the Semantic Data Model as a SemanticLogicalView under the model’s semanticLogicalViews. Its type is set by semanticViewTypeEnum: a standard view (the default) carries member data objects and their join relationships; a union view carries a semanticUnions block; a custom SQL view sets semanticViewTypeEnum: "CustomSQL" and carries the SQL in customSQLV2; an organizational hierarchy sets semanticViewTypeEnum: "Hierarchy" and derives a transitive parent-child table. A query references a view’s fields by name; it never redefines the view. For the authoring shape, see Semantic Logical View and Semantic CustomSql Logical View in the Authoring API.
At query time every logical view behaves like any other queryable object: select its columns through table_field (by physical column and table name) or reference model-defined calculated fields over it through semantic_field.
A standard logical view joins its member data objects internally and exposes their columns as one flat set of fields. Each output column is named <SourceObjectApiName>_<fieldApiName> — the member object’s API name and the field’s API name joined by an underscore — which is how two same-named fields from different member objects stay distinct.
Query it exactly like a plain data object: reference a column with table_field, using the logical view’s apiName as table_name. Model-defined calculated fields can read the view’s columns through the same <logicalView>.<column> path, and you select those calcs through semantic_field as usual.
The example below queries a logical view named logicalTable that joins an Account and a Contact data object: it selects two of the view’s columns and a calculated measurement whose expression reads one of them.
1{
2 "structured_semantic_query": {
3 "fields": [
4 {
5 "expression": {
6 "tableField": {
7 "name": "SemanticAccount__dlm_semantic__Id__c",
8 "tableName": "logicalTable"
9 }
10 },
11 "alias": "name",
12 "rowGrouping": true
13 },
14 {
15 "expression": {
16 "tableField": {
17 "name": "SemanticContact__dlm_semantic__FirstName__c",
18 "tableName": "logicalTable"
19 }
20 },
21 "alias": "first_name",
22 "rowGrouping": true
23 },
24 {
25 "expression": {
26 "semanticField": {
27 "name": "formula_summary_measurement_example"
28 }
29 },
30 "semanticAggregationMethod": "SEMANTIC_AGGREGATION_METHOD_SUM",
31 "alias": "formula_summary_measurement_example"
32 }
33 ]
34 },
35 "semantic_model": {
36 "apiName": "Sales",
37 "semanticCalculatedMeasurements": [
38 {
39 "apiName": "formula_summary_measurement_example",
40 "dataType": "Number",
41 "expression": "10 * (logicalTable.SemanticAccount__dlm_semantic__Number__c)",
42 "syntax": "Salesforce"
43 }
44 ],
45 "semanticLogicalViews": [
46 {
47 "apiName": "logicalTable",
48 "label": "logical table",
49 "semanticDataObjects": [
50 {
51 "apiName": "SemanticAccount__dlm",
52 "dataObjectName": "ssot__Account__dlm",
53 "dataObjectType": "Dmo",
54 "semanticDimensions": [
55 {
56 "apiName": "SemanticAccount__dlm_semantic__Id__c",
57 "dataType": "Text",
58 "dataObjectFieldName": "ssot__Id__c"
59 }
60 // ...
61 ],
62 "semanticMeasurements": [
63 {
64 "apiName": "SemanticAccount__dlm_semantic__Number__c",
65 "dataType": "Number",
66 "dataObjectFieldName": "ssot__Number__c"
67 }
68 ]
69 },
70 {
71 "apiName": "SemanticContact__dlm",
72 "dataObjectName": "ssot__Contact__dlm",
73 "dataObjectType": "Dmo",
74 "semanticDimensions": [
75 {
76 "apiName": "SemanticContact__dlm_semantic__FirstName__c",
77 "dataType": "Text",
78 "dataObjectFieldName": "ssot__FirstName__c"
79 }
80 // ...
81 ]
82 }
83 ],
84 "semanticRelationships": [
85 {
86 "apiName": "relationship",
87 "leftSemanticDefinitionApiName": "SemanticAccount__dlm",
88 "rightSemanticDefinitionApiName": "SemanticContact__dlm",
89 "joinType": "Left",
90 "criteria": [
91 {
92 "leftSemanticFieldApiName": "SemanticAccount__dlm_Semantic_KQ_Id__c",
93 "rightSemanticFieldApiName": "SemanticContact__dlm_Semantic_KQ_Id__c"
94 }
95 ]
96 }
97 ]
98 }
99 ]
100 // ...
101 }
102}Joins inside a logical view are defined by the view itself, with explicit join types, not through the model’s top-level semanticRelationships. To connect a whole logical view to another data object, use a top-level relationship — see Relationships & Joins.
A union logical view appends the rows of several member data objects that share a schema — a vertical combination (UNION ALL), unlike a standard view’s horizontal join. The members live under a semanticUnions block, and their columns are aligned by semanticMappedFields: each mapped field declares a unified column and the member field it draws from in each source object. At query time you select the unified column from the outer view; the engine emits the UNION ALL and returns one row per source record, with a column that a given source object does not map returning NULL.
The example below queries an outerLogicalView whose semanticUnions block unions three member objects. It selects two unified columns, unifiedName and unifiedDate.
1{
2 "structured_semantic_query": {
3 "fields": [
4 {
5 "expression": {
6 "tableField": {
7 "name": "unifiedName",
8 "tableName": "outerLogicalView"
9 }
10 }
11 },
12 {
13 "expression": {
14 "tableField": {
15 "name": "unifiedDate",
16 "tableName": "outerLogicalView"
17 }
18 }
19 }
20 ],
21 "options": {
22 "detailed_rows": true
23 }
24 },
25 "semantic_model": {
26 "apiName": "Sales",
27 "semanticLogicalViews": [
28 {
29 "apiName": "outerLogicalView",
30 "label": "Outer Logical View",
31 "semanticDataObjects": [],
32 "semanticUnions": [
33 {
34 "apiName": "innerLogicalView",
35 "label": "inner logical view",
36 "semanticDataObjects": [
37 {
38 "apiName": "SemanticAccount__dlm",
39 "dataObjectName": "ssot__Account__dlm",
40 "dataObjectType": "Dmo",
41 "semanticDimensions": [
42 // ...
43 ]
44 },
45 {
46 "apiName": "SemanticContact__dlm",
47 "dataObjectName": "ssot__Contact__dlm",
48 "dataObjectType": "Dmo",
49 "semanticDimensions": [
50 // ...
51 ]
52 },
53 {
54 "apiName": "SemanticOrder__dlm",
55 "dataObjectName": "ssot__Account__dlm",
56 "dataObjectType": "Dmo",
57 "semanticDimensions": [
58 // ...
59 ]
60 }
61 ],
62 "semanticMappedFields": [
63 {
64 "apiName": "unifiedName",
65 "label": "Unified Product",
66 "fields": [
67 {
68 "tableApiName": "SemanticAccount__dlm",
69 "fieldApiName": "SemanticAccount__dlm_semantic__Name__c"
70 },
71 {
72 "tableApiName": "SemanticContact__dlm",
73 "fieldApiName": "SemanticContact__dlm_semantic__FirstName__c"
74 },
75 {
76 "tableApiName": "SemanticOrder__dlm",
77 "fieldApiName": "SemanticOrder__dlm_semantic__Name__c"
78 }
79 ],
80 "semanticDimension": {
81 "label": "Unified Name",
82 "dataType": "Text"
83 }
84 },
85 {
86 "apiName": "unifiedDate",
87 "label": "Unified Date",
88 "fields": [
89 {
90 "tableApiName": "SemanticAccount__dlm",
91 "fieldApiName": "SemanticAccount__dlm_date__c"
92 },
93 {
94 "tableApiName": "SemanticOrder__dlm",
95 "fieldApiName": "SemanticOrder__dlm__date__c"
96 }
97 ],
98 "semanticDimension": {
99 "label": "Unified Date",
100 "dataType": "Date"
101 }
102 }
103 ]
104 }
105 ]
106 }
107 ],
108 "semanticDataObjects": []
109 }
110}Note that unifiedDate maps only SemanticAccount__dlm and SemanticOrder__dlm — it omits SemanticContact__dlm, so rows contributed by the Contact object return NULL for that column.
A custom SQL logical view is a SemanticLogicalView with semanticViewTypeEnum: "CustomSQL" whose fields are the output columns of a SQL statement defined in the model. The SQL statement lives in the customSQLV2 attribute, and the objects it reads from are declared in referenceIntegritySemanticDataObjects. The output columns of that SQL become the view’s queryable fields.
There is no query-time SQL construct: you never send raw SQL in a request. The SQL lives in the model, and a query references the resulting view’s columns by name exactly as it would any other data object. Reference the logical view’s output fields with table_field, using the logical view’s apiName as the table_name.
1{
2 "structured_semantic_query": {
3 "fields": [
4 {
5 "expression": {
6 "table_field": {
7 "name": "ssot__Id__c",
8 "table_name": "OrderCostBook"
9 }
10 },
11 "alias": "AccountId"
12 },
13 {
14 "expression": {
15 "table_field": {
16 "name": "ssot__Name__c",
17 "table_name": "OrderCostBook"
18 }
19 },
20 "alias": "AccountName"
21 }
22 ],
23 "options": {
24 "limit_options": {
25 "limit": 100
26 },
27 "detailed_rows": true
28 }
29 },
30 "semantic_model": {
31 "apiName": "Sales",
32 "label": "Sales",
33 "semanticLogicalViews": [
34 {
35 "apiName": "OrderCostBook",
36 "label": "Order Cost Book",
37 "semanticViewTypeEnum": "CustomSQL",
38 "customSQLV2": "SELECT \"ssot__Id__c\", \"ssot__Name__c\" FROM \"IAccount\" ",
39 "referenceIntegritySemanticDataObjects": [
40 // ...
41 ],
42 "semanticDataObjects": [
43 // ...
44 ]
45 }
46 ]
47 // ...
48 }
49}Performance: A custom SQL logical view is treated as an opaque subquery. Outer filters and limits are not pushed into it, so the inner statement materializes in full before they apply.
Performance: Selecting fewer columns does not reduce work inside the custom SQL — every column, join, and aggregation in the statement is computed regardless of what the outer query selects.
Performance: For an expensive custom SQL view, consider precomputing it upstream to cut query-time cost.
An organizational hierarchy — such as a role, manager, or territory hierarchy — is a SemanticLogicalView with semanticViewTypeEnum: "Hierarchy" that derives a transitive parent-child table from an underlying parent-key relationship. It lets a query aggregate values that roll up through parent-child relationships and exposes generated fields such as level and path.
Most of the hierarchy is transparent at query time: you reference the hierarchical view’s fields by name, and the engine performs the recursive walk. The one construct you set directly in a query is the HierarchyScope filter operator, which limits a result to the subtree rooted at a specific node.
Performance: On-the-fly hierarchy resolution uses a recursive traversal whose cost grows with hierarchy depth and node count; consider a persisted hierarchy for large trees.
Reference the hierarchical logical view’s fields — such as the generated level and path fields — by table_field, using the view’s apiName as the table_name. Set row_grouping: true on the fields you want to group by.
1{
2 "structured_semantic_query": {
3 "fields": [
4 {
5 "expression": {
6 "table_field": {
7 "name": "level",
8 "table_name": "UserManagementHierarchy"
9 }
10 },
11 "semantic_aggregation_method": "SEMANTIC_AGGREGATION_METHOD_NONE",
12 "semantic_dimension_type": "SEMANTIC_DIMENSION_TYPE_NUMBER",
13 "alias": "level",
14 "row_grouping": true
15 },
16 {
17 "expression": {
18 "table_field": {
19 "name": "path",
20 "table_name": "UserManagementHierarchy"
21 }
22 },
23 "semantic_aggregation_method": "SEMANTIC_AGGREGATION_METHOD_NONE",
24 "semantic_dimension_type": "SEMANTIC_DIMENSION_TYPE_TEXT",
25 "alias": "path",
26 "row_grouping": true
27 }
28 ],
29 "options": {}
30 },
31 "semantic_model": {
32 "apiName": "Sales",
33 "label": "Sales",
34 "semanticLogicalViews": [
35 {
36 "apiName": "UserManagementHierarchy",
37 "label": "User Management Hierarchy",
38 "semanticViewTypeEnum": "Hierarchy",
39 "semanticUnions": [
40 // ...
41 ]
42 }
43 ]
44 // ...
45 }
46}Performance: A persisted (materialized) hierarchy is read from a precomputed table instead of being resolved with a recursive traversal at query time, which substantially reduces query cost.
Use the HierarchyScope operator to limit a hierarchy result to the subtree rooted at a specific node. In a flatten_filter (or a model filter), set "operator": "HierarchyScope" with the root node identifier as value, referencing the hierarchy’s parent-key field.
1{
2 "structured_semantic_query": {
3 "fields": [
4 // ...
5 ],
6 "flatten_filter": {
7 "filterLogic": "1",
8 "filters": [
9 {
10 "fieldName": "[UserRoleObject].[ParentRoleId]",
11 "operator": "HierarchyScope",
12 "value": "ROLE_VP_SALES"
13 }
14 ]
15 },
16 "options": {}
17 }
18 // ...
19}The same scope can be expressed as a structured predicate with the BINARY_OPERATOR_HIERARCHY_SCOPE operator, using a table_field left expression and a string_expression right operand for the root node.
1{
2 "structured_semantic_query": {
3 "filter": {
4 "binary_predicate": {
5 "left_expression": {
6 "table_field": {
7 "name": "ParentRoleId",
8 "table_name": "UserRoleObject"
9 }
10 },
11 "binary_operator": "BINARY_OPERATOR_HIERARCHY_SCOPE",
12 "right_expression": {
13 "string_expression": "ROLE_VP_SALES"
14 }
15 }
16 },
17 "options": {}
18 }
19 // ...
20}Performance: Scope a hierarchy query to a subtree with
HierarchyScopeto prune the traversal to the nodes under a chosen root.
Only the fields introduced on this page are listed. For the full request schema, see Request Reference.
| Field (wire name) | Type | Required | Description |
|---|---|---|---|
semanticLogicalViews | SemanticLogicalView[] | N | Logical views on the model. Each bundles member data objects and how they combine (join, union, or custom SQL) and exposes their columns as one queryable object. Defined at authoring time — see Related. |
table_field | TableField | N | References a column of a logical view by name + table_name, where table_name is the logical view’s apiName. |
semanticViewTypeEnum | String (enum) | N | The composition type of a logical view. CustomSQL marks a custom SQL view; Hierarchy marks an organizational hierarchy; a standard (join) view is the default. |
semanticUnions | SemanticUnion[] | N | On a union logical view, the block that appends member data objects vertically (UNION ALL). |
semanticMappedFields | SemanticMappedField[] | N | Within a semanticUnions block, aligns member columns into a unified column; each declares the source field per member object. |
customSQLV2 | String | N | On a custom SQL view, the SQL statement whose output columns become the view’s fields. Requires semanticViewTypeEnum: "CustomSQL". |
referenceIntegritySemanticDataObjects | SemanticDataObject[] | N | On a custom SQL view, the data objects the SQL statement reads from. All tables and fields referenced in the SQL should be listed. |
operator ("HierarchyScope") | String (PascalCase) | N | In flatten_filter/model-filter form, limits an organizational-hierarchy result to the subtree rooted at value. |
binary_operator (BINARY_OPERATOR_HIERARCHY_SCOPE) | String (enum) | N | Structured-predicate form of the hierarchy-scope operator; the root node is supplied as the right string_expression. |
For the relationship fields that define joins inside a standard logical view, see Relationships & Joins and the authoring entity in Related.
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 a member object’s original field apiName.NULL. When a union member does not map a given unified column, rows contributed by that member return NULL for it.HierarchyScope value is a single root node. It scopes an organizational-hierarchy result to that node’s subtree; pair it with an IsNull condition on the parent-key field to also include entry-level rows.flatten_filter, and structured predicates used by the HierarchyScope operator.level and path fields.semantic_field.
j