The Semantic Query API lets you query your data in Data 360 through a Semantic Data Model rather than against physical tables. You send a logical request that names fields, filters, groupings, and options against a model; the Semantic Layer resolves that request into SQL over the underlying Data 360 objects, runs it in the context of your tenant, and returns result rows.
A request has two parts: the query — what to retrieve, expressed in structuredSemanticQuery — and the model — the Semantic Data Model the query runs against, supplied either by reference (its API name) or inline in the request body. You compose the query from the building blocks documented in the rest of this section (fields, relationships, parameters, calculated fields, filters, grouping, aggregation, sorting), and you shape execution with a per-query semantic context (time zone, locale, currency).
The single most important thing to know: every field you select or filter on must resolve within the model you supply. Only objects and fields that are part of that model’s scope are queryable. Choose a model-provisioning style (by reference or inline) and an API surface (the Semantic Query gateway endpoint, or the Query Connect API through the semantic_query() table function), then build the query on top.
The model you query is a Semantic Data Model, defined through the Tableau Semantics Authoring experience or the Authoring API as a SemanticModel entity. The model holds the data objects, fields, relationships, calculated fields, and parameters that a query can reference; a query never creates model metadata, it only references it (or supplies an equivalent model inline for a single request). For how a model and its objects are defined, see Semantic Model and Semantic Data Object in the Authoring API.
The semantic context (time zone, locale, currency) is not model metadata — you set it per query. See Set the semantic context.
Reference a saved, published model by its API name with semanticModelApiName, supplied alongside the structuredSemanticQuery in the request body. The Semantic Layer resolves the model from your tenant’s metadata; you don’t ship the model definition with the request. This is the recommended way to name a model — prefer it over semanticModelId.
1{
2 "structuredSemanticQuery": {
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 "options": {
22 "detailed_rows": true
23 }
24 },
25 "semanticModelApiName": "test_model"
26}Field names accept both camelCase and snake_case spellings; the same request in snake_case uses structured_semantic_query and semantic_model_api_name.
Embed the full model in the request under semanticModel when you want to query a model that isn’t saved, or a variant of one, without a separate authoring step. The model definition travels with the query in the same request body, next to structuredSemanticQuery.
1{
2 "structuredSemanticQuery": {
3 "fields": [
4 {
5 "expression": {
6 "table_field": {
7 "name": "Name",
8 "table_name": "SemanticAccount_SDO"
9 }
10 }
11 },
12 {
13 "expression": {
14 "table_field": {
15 "name": "AnnualRevenueAmount",
16 "table_name": "SemanticAccount_SDO"
17 }
18 }
19 }
20 ],
21 "options": {
22 "limit_options": {
23 "limit": 10
24 }
25 }
26 },
27 "semanticModel": {
28 "apiName": "TestSDM",
29 "label": "TestSDM",
30 "semanticDataObjects": [
31 {
32 "apiName": "SemanticAccount_SDO",
33 "label": "SemanticAccount",
34 "dataObjectName": "SemanticAccount_SDO__dll",
35 "dataObjectType": "Dlo",
36 "semanticDimensions": [
37 {
38 "apiName": "Name",
39 "label": "Name",
40 "dataType": "Text",
41 "dataObjectFieldName": "Name__c"
42 }
43 // ...
44 ],
45 "semanticMeasurements": [
46 {
47 "apiName": "AnnualRevenueAmount",
48 "label": "AnnualRevenueAmount",
49 "dataType": "Number",
50 "dataObjectFieldName": "AnnualRevenueAmount__c"
51 }
52 ]
53 }
54 ]
55 }
56}You can also run a semantic query through the Query Connect API by wrapping the structured query in the semantic_query() table function inside a SQL statement and submitting that statement in the sql field of POST /services/data/vXX.0/ssot/query-sql. The single string argument to semantic_query() is the same structured-query-plus-model JSON used elsewhere; select from it as a table. The dataspace and workloadName query parameters identify the data space to run in and a label that helps Salesforce Customer Support trace the request.
The semantic_query() argument is this JSON payload — the same shape as the other requests, referencing a saved model by semanticModelApiName:
1{
2 "structured_semantic_query": {
3 "fields": [
4 // ...
5 ],
6 "options": {
7 "detailed_rows": true
8 }
9 },
10 "semanticModelApiName": "SalesSDM"
11}Pass that payload as the single string argument to semantic_query() in the sql field. The argument is a JSON string, so it is minified onto one line (and its inner quotes escaped) inside the SQL statement:
1POST https://{dne_cdpInstanceUrl}/services/data/vXX.0/ssot/query-sql?dataspace=default&workloadName=semantic-query1{
2 "sql": "SELECT * FROM semantic_query('{\"structured_semantic_query\":{\"fields\":[],\"options\":{\"detailed_rows\":true}},\"semanticModelApiName\":\"SalesSDM\"}')"
3}The response returns column metadata and the first chunk of rows, along with a queryId you can use to poll for status and page through remaining results. For the full request and response shape, pagination, and parameterized queries, see the Query Connect API guide in Related.
Set a per-query semantic_context to control how the query executes and how results are shaped. The context carries timezone (an IANA zone id), locale (a code that drives date, number, and name formatting), and currency (an ISO currency id used for currency conversion). Set only the fields you need.
1{
2 "structuredSemanticQuery": {
3 "semantic_context": {
4 "timezone": {
5 "id": "America/Los_Angeles"
6 },
7 "locale": {
8 "code": "en_US"
9 }
10 },
11 "fields": [
12 {
13 "expression": {
14 "table_field": {
15 "name": "Name",
16 "table_name": "SemanticAccount_SDO"
17 }
18 }
19 }
20 // ...
21 ]
22 },
23 "semanticModelApiName": "test_model"
24}To convert monetary values, set currency.id to an ISO currency code. The requested currency takes precedence over the model and org defaults.
1{
2 "structured_semantic_query": {
3 "semantic_context": {
4 "currency": {
5 "id": "EUR"
6 }
7 },
8 "fields": [
9 // ...
10 ]
11 },
12 "semantic_model": {
13 // ...
14 }
15}For the full behavior of currency, fiscal, time zone, and locale handling, see Currency & Fiscal Handling.
| Field (wire name) | Type | Required | Description |
|---|---|---|---|
structuredSemanticQuery | StructuredSemanticQuery | Y | The logical query: fields, filter, options, semanticContext, aggregateFilter. |
semanticModelApiName | String | N* | Reference a saved model by its API name; the model is resolved from tenant metadata. Preferred way to reference a saved model. |
semanticModelId | String | N* | Deprecated — reference a saved model by record ID. Use semanticModelApiName instead. Cannot be combined with semanticModel. |
semanticModel | SemanticModel | N* | The full model definition, supplied inline in the request. Cannot be combined with semanticModelId. |
N* — supply exactly one model identifier per request. In Query Connect API requests, the query and its model identifier are passed as the single string argument to the semantic_query() table function.
For the full request schema, see Request Reference.
semanticModel cannot be combined with semanticModelId, and semanticModelId cannot be combined with semanticModelApiName.fields, filters, sorting, or grouping — must resolve within the supplied model. Fields outside the model’s scope are not queryable./ssot/query-sql, poll for status, and page through results.
j