Currency and fiscal context shape how a semantic query interprets monetary amounts and date grains, and how it formats results. Currency handling converts currency-typed measures from each record’s source currency into a single target currency so that totals, calculated fields, and grouped results all report amounts in one consistent currency. Fiscal handling lets you group and filter dates by fiscal grains (fiscal year, quarter, month, week) rather than the calendar grains.
You set this context per query through the semanticContext object on the structuredSemanticQuery. semanticContext carries currency, timezone, and locale. The single most important thing to know about currency is precedence: a currency supplied in semanticContext overrides the model’s default currency, which in turn overrides the org default. When no target currency resolves from any of these, currency-typed values are returned in their original record currency without conversion.
Currency conversion depends on a source-currency column that the model marks on each currency-bearing data object. That column, and the model’s default currency, are defined in the Semantic Data Model; the target currency for a specific query is the only piece you set at query time.
Two pieces of currency handling are defined in the model. First, each data object that holds currency amounts declares exactly one field whose semanticDataType is RecordCurrency — this is the column that stores the ISO currency code for each record and is the anchor for conversion. Second, the model can carry a default target currency in a nested currency object (currency.id = ISO code). Fiscal grouping and fiscal relative-date filters rely on date-typed fields defined on the model’s data objects; there is no separate fiscal metadata to set per query.
For how these are defined, see Semantic Data Object Field for the RecordCurrency field and Semantic Model for the model default currency.
The time zone and locale in semanticContext are pure query-time knobs — no model metadata backs them.
Set semanticContext.currency.id to an ISO currency code to convert every currency-typed field in the query into that currency. This value takes precedence over the model default and the org default. The query below selects a field from a logical view and requests results in euros; the response carries the resolved currency back in the enriched context.
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 "semantic_context": {
16 "currency": {
17 "id": "EUR"
18 }
19 }
20 },
21 "semantic_model": {
22 "apiName": "Sales",
23 "label": "Sales",
24 "semanticLogicalViews": [
25 {
26 "apiName": "logicalTable",
27 "semanticDataObjects": [
28 {
29 "apiName": "SemanticAccount__dlm",
30 "dataObjectName": "ssot__Account__dlm",
31 "dataObjectType": "Dmo",
32 "semanticDimensions": [
33 {
34 "apiName": "SemanticAccount__dlm_semantic__Id__c",
35 "dataType": "Currency",
36 "dataObjectFieldName": "ssot__Id__c"
37 },
38 {
39 "apiName": "SemanticAccount__dlm_semantic__account_source__c",
40 "dataType": "Text",
41 "semanticDataType": "RecordCurrency",
42 "dataObjectFieldName": "ssot__AccountSource__c"
43 }
44 // ...
45 ]
46 }
47 // ...
48 ]
49 // ...
50 }
51 ]
52 }
53}Performance: Currency conversion runs only when a currency field is part of the query, and each converted measure is wrapped in a per-row conversion. Omit currency fields you don’t need to avoid the overhead.
Currency conversion also applies to currency-typed calculated measures. When no per-query currency is set, the model’s default currency (the nested currency object on the model) is the target. In the query below the model default is EUR, and the calculated measure currency_calc — a Currency-typed expression over a currency measure — is converted to euros.
1{
2 "structured_semantic_query": {
3 "fields": [
4 {
5 "expression": {
6 "semantic_field": {
7 "name": "currency_calc"
8 }
9 },
10 "row_grouping": true
11 }
12 ]
13 },
14 "semantic_model": {
15 "currency": {
16 "id": "EUR"
17 },
18 "apiName": "Sales",
19 "label": "Sales",
20 "semanticDataObjects": [
21 {
22 "apiName": "SemanticAccount__dlm",
23 "dataObjectName": "ssot__Account__dlm",
24 "dataObjectType": "Dmo",
25 "semanticDimensions": [
26 {
27 "apiName": "test1",
28 "dataType": "Text",
29 "dataObjectFieldName": "ssot__Name__c",
30 "semanticDataType": "RecordCurrency"
31 }
32 // ...
33 ],
34 "semanticMeasurements": [
35 {
36 "apiName": "Cost",
37 "dataType": "Currency",
38 "dataObjectFieldName": "ssot__Number__c"
39 }
40 ]
41 }
42 ],
43 "semanticCalculatedMeasurements": [
44 {
45 "apiName": "currency_calc",
46 "label": "currency_calc",
47 "dataType": "Currency",
48 "expression": "10 * [SemanticAccount__dlm].[Cost]"
49 }
50 ]
51 }
52}To group by a fiscal grain, reference a fiscal date function over a date field in a calculated expression and mark the field with row_grouping. The FISCAL_YEAR and FISCAL_QUARTER functions return the fiscal year and quarter of a date. This query groups by a computed fiscal quarter/year label and sets the time zone and locale in semantic_context.
1{
2 "structured_semantic_query": {
3 "fields": [
4 {
5 "expression": {
6 "calculated_field": {
7 "name": "fiscal_quarter_on_the_fly_calculation",
8 "expression": "CONCAT('FY', TEXT(FISCAL_QUARTER(AccountSemanticLayer__dll.LastModifiedDate__c)), '-Q', TEXT(FISCAL_YEAR(AccountSemanticLayer__dll.LastModifiedDate__c)))"
9 }
10 },
11 "row_grouping": true
12 }
13 ],
14 "semantic_context": {
15 "timezone": {
16 "id": "Africa/Accra"
17 },
18 "locale": {
19 "code": "be_BY"
20 }
21 }
22 },
23 "semanticModelApiName": "test_model"
24}Relative date filters accept fiscal date parts as well as calendar parts. Use relativeDateRange inside a BINARY_OPERATOR_BETWEEN predicate and set datePart to a fiscal grain — Fiscal_Week, Fiscal_Month, Fiscal_Quarter, or Fiscal_Year. Combine it with startOffset, endOffset, and either useCurrentDateAsEndDate or an explicit anchorDate to define the window.
1{
2 "structuredSemanticQuery": {
3 "filter": {
4 "binaryPredicate": {
5 "leftExpression": {
6 "tableField": {
7 "name": "CreatedDate",
8 "tableName": "SemanticAccount_SDO"
9 }
10 },
11 "binaryOperator": "BINARY_OPERATOR_BETWEEN",
12 "rightExpression": {
13 "relativeDateRange": {
14 "datePart": "Day",
15 "useCurrentDateAsEndDate": true,
16 "startOffset": -30,
17 "endOffset": 1,
18 "anchorDate": "2024-12-23T00:00:00.000"
19 }
20 }
21 }
22 },
23 "fields": [
24 // ...
25 ]
26 },
27 "semanticModelId": "2SMxx0000004CAeGAM"
28}The supported datePart values are Minute, Hour, Day, Week, Month, Quarter, Year, Fiscal_Week, Fiscal_Month, Fiscal_Quarter, Fiscal_Year, and Localized_Week. Substitute one of the Fiscal_* values in the example above to filter on a fiscal window.
Set semanticContext.timezone.id to shift datetime values and datetime-derived grains into a specific time zone, and semanticContext.locale.code to drive display formats for dates, numbers, and names. Both are set alongside currency in the same semanticContext object.
1{
2 "structuredSemanticQuery": {
3 "fields": [
4 // ...
5 ],
6 "semanticContext": {
7 "timezone": {"id": "America/Los_Angeles"},
8 "locale": {"code": "en_US"}
9 }
10 // ...
11 }
12}| Field (wire name) | Type | Required | Description |
|---|---|---|---|
semanticContext.currency | Currency | N | Target currency for the query. currency.id is an ISO currency code. Highest-precedence source for currency conversion. |
semanticContext.timezone | Timezone | N | Time zone applied to datetime values and datetime-derived grains. timezone.id is a time-zone identifier. |
semanticContext.locale | Locale | N | Locale driving display formats for dates, numbers, and names. locale.code is a locale code. |
currency (on semanticModel) | Currency | N | Model default target currency (currency.id = ISO code). Used when semanticContext.currency is absent. |
relativeDateRange.datePart | String (enum) | N | Date grain for a relative date filter; includes Fiscal_Week, Fiscal_Month, Fiscal_Quarter, Fiscal_Year. |
For the full request schema, see Request Reference.
semanticContext.currency → model default currency → org default. If none resolves, currency-typed values are returned in their original record currency with no conversion.semanticDataType: RecordCurrency; otherwise the query fails.datePart values.RecordCurrency field.semanticContext.
j