--- schema_version: "1" id: 3db4638de6509686c87e9e21702105828b5ec20cd07e1ceb004d441ea2de1a2e title: Semantic Query API Overview collection: developer version: current locale: en-us portal_url: https://docs.salesforce.com/developer/current/en-us/data-cloud/semantic-layer/guides/query-api-in-depth-overview.md canonical_url: https://developer.salesforce.com/docs/data/semantic-layer/guide/query-api-in-depth-overview.html source_site: developer.salesforce.com content_type: documentation content_hash: 22549fc737e62f46512cdaf4e13a5950503b58f53203256567a78dec8a5b43ed products: - Tableau Semantics Layer APIs - Data 360 Developer Documentation --- # Semantic Query API Overview ## Overview 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. ## Metadata in the model 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](https://developer.salesforce.com/docs/data/semantic-layer/guide/connect-api-in-depth-entities.md#semantic-model-semanticmodel) and [Semantic Data Object](https://developer.salesforce.com/docs/data/semantic-layer/guide/connect-api-in-depth-entities.md#semantic-data-object-semanticdataobject) 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](#set-the-semantic-context). ## Query usage ### Provide a model by API name 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`. ```json { "structuredSemanticQuery": { "fields": [ { "expression": { "table_field": { "name": "Account Name", "table_name": "AccountSemanticLayer__dll" } } }, { "expression": { "table_field": { "name": "Annual Revenue", "table_name": "AccountSemanticLayer__dll" } } } ], "options": { "detailed_rows": true } }, "semanticModelApiName": "test_model" } ``` Field names accept both camelCase and snake_case spellings; the same request in snake_case uses `structured_semantic_query` and `semantic_model_api_name`. ### Provide a model inline 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`. ```json { "structuredSemanticQuery": { "fields": [ { "expression": { "table_field": { "name": "Name", "table_name": "SemanticAccount_SDO" } } }, { "expression": { "table_field": { "name": "AnnualRevenueAmount", "table_name": "SemanticAccount_SDO" } } } ], "options": { "limit_options": { "limit": 10 } } }, "semanticModel": { "apiName": "TestSDM", "label": "TestSDM", "semanticDataObjects": [ { "apiName": "SemanticAccount_SDO", "label": "SemanticAccount", "dataObjectName": "SemanticAccount_SDO__dll", "dataObjectType": "Dlo", "semanticDimensions": [ { "apiName": "Name", "label": "Name", "dataType": "Text", "dataObjectFieldName": "Name__c" } // ... ], "semanticMeasurements": [ { "apiName": "AnnualRevenueAmount", "label": "AnnualRevenueAmount", "dataType": "Number", "dataObjectFieldName": "AnnualRevenueAmount__c" } ] } ] } } ``` ### Send a query through the Query Connect API 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`: ```json { "structured_semantic_query": { "fields": [ // ... ], "options": { "detailed_rows": true } }, "semanticModelApiName": "SalesSDM" } ``` 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: ``` POST https://{dne_cdpInstanceUrl}/services/data/vXX.0/ssot/query-sql?dataspace=default&workloadName=semantic-query ``` ```json { "sql": "SELECT * FROM semantic_query('{\"structured_semantic_query\":{\"fields\":[],\"options\":{\"detailed_rows\":true}},\"semanticModelApiName\":\"SalesSDM\"}')" } ``` 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 the semantic context 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. ```json { "structuredSemanticQuery": { "semantic_context": { "timezone": { "id": "America/Los_Angeles" }, "locale": { "code": "en_US" } }, "fields": [ { "expression": { "table_field": { "name": "Name", "table_name": "SemanticAccount_SDO" } } } // ... ] }, "semanticModelApiName": "test_model" } ``` To convert monetary values, set `currency.id` to an ISO currency code. The requested currency takes precedence over the model and org defaults. ```json { "structured_semantic_query": { "semantic_context": { "currency": { "id": "EUR" } }, "fields": [ // ... ] }, "semantic_model": { // ... } } ``` For the full behavior of currency, fiscal, time zone, and locale handling, see [Currency & Fiscal Handling](https://developer.salesforce.com/docs/data/semantic-layer/guide/query-api-in-depth-currency-fiscal.md). ## Reference | 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](https://developer.salesforce.com/docs/data/semantic-layer/guide/query-api-in-depth-fields.md). ## Limitations - Supply exactly one model identifier per request. An inline `semanticModel` cannot be combined with `semanticModelId`, and `semanticModelId` cannot be combined with `semanticModelApiName`. - Every field referenced by the query — in `fields`, filters, sorting, or grouping — must resolve within the supplied model. Fields outside the model's scope are not queryable. ## Related - [Dimensions, Measurements & Semantic Data Objects](https://developer.salesforce.com/docs/data/semantic-layer/guide/query-api-in-depth-fields.md) — the fields you select and how they resolve. - [Filtering](https://developer.salesforce.com/docs/data/semantic-layer/guide/query-api-in-depth-filtering.md) — narrow the result set. - [Grouping](https://developer.salesforce.com/docs/data/semantic-layer/guide/query-api-in-depth-grouping.md) · [Aggregation & Totals](https://developer.salesforce.com/docs/data/semantic-layer/guide/query-api-in-depth-aggregation.md) · [Sorting & Limiting](https://developer.salesforce.com/docs/data/semantic-layer/guide/query-api-in-depth-sorting-limiting.md) — shape results. - [Currency & Fiscal Handling](https://developer.salesforce.com/docs/data/semantic-layer/guide/query-api-in-depth-currency-fiscal.md) — full semantic-context behavior. - [Request Reference](https://developer.salesforce.com/docs/data/semantic-layer/guide/query-api-in-depth-fields.md) — complete request schema. - [Semantic Model](https://developer.salesforce.com/docs/data/semantic-layer/guide/connect-api-in-depth-entities.md#semantic-model-semanticmodel) · [Semantic Data Object](https://developer.salesforce.com/docs/data/semantic-layer/guide/connect-api-in-depth-entities.md#semantic-data-object-semanticdataobject) — Authoring API for defining the model you query. - [Query Data using the Query Connect API](https://developer.salesforce.com/docs/data/connectapi/guides/query-use-case.md) — submit a SQL query through `/ssot/query-sql`, poll for status, and page through results.