Parameters are named, single-value variables defined in a Semantic Model that a query can supply or override at request time. A parameter stands in for a constant inside a calculated-field formula or a filter condition, so the same model can serve many queries that differ only by the value a consumer selects — a threshold, a date, a category, a currency amount.
Use a parameter when you want a calculation or filter to be driven by a value chosen per query rather than hard-coded in the model. Each parameter carries a data type and a default value in the model. At query time you either accept the default or pass an ad-hoc value in the request; the value you pass overrides the model default for that query only. A parameter always resolves to exactly one value — it is a constant, not an expression, and it cannot reference another parameter or a calculated field.
The single most important thing to know: you do not select a parameter as a field. You reference it — by the name Parameters.<apiName> — inside a calculated-field expression or a filter, and you set its value through the parameters array on the query. The resolved value is substituted wherever the parameter is referenced.
Parameters are defined at authoring time as SemanticParameter definitions in the Semantic Model, each with a dataType, a value-selection type (All, List, or Range), and a defaultValue. List-type parameters carry a set of allowed value/displayName entries; Range-type parameters carry min, max, and step-size bounds. Parameters appear in the model’s semanticParameters array. For how parameters are defined, see Semantic Parameter, Semantic Parameter List, and Semantic Parameter Range in the Authoring API.
Supply ad-hoc parameter values with the parameters array on structuredSemanticQuery. Each entry is an object with a name (the parameter’s API name) and a value. A value supplied here overrides the parameter’s model defaultValue for this query; if you omit a parameter from the array, it resolves to its model default.
1{
2 "structured_semantic_query": {
3 "fields": [
4 {
5 "expression": {
6 "semantic_field": {
7 "name": "formula_measurement_example"
8 }
9 }
10 }
11 // ...
12 ],
13 "filter": {
14 "binary_predicate": {
15 "left_expression": {
16 "semantic_field": {
17 "name": "Parameters.param1"
18 }
19 },
20 "binary_operator": "BINARY_OPERATOR_EQUALS",
21 "right_expression": {
22 "string_expression": "Web"
23 }
24 }
25 },
26 "parameters": [
27 {
28 "name": "param1",
29 "value": "adhoc"
30 }
31 ]
32 },
33 "semantic_model": {
34 "apiName": "Sales",
35 "semanticParameters": [
36 {
37 "apiName": "param1",
38 "label": "param1",
39 "dataType": "Text",
40 "defaultValue": "Web"
41 }
42 // ...
43 ]
44 }
45}Performance: Parameter values are inlined as constants in the generated query, so they support constant folding, partition pruning, and predicate pushdown just like literal values, with no per-row overhead.
Reference a parameter inside a calculated-field formula by the name Parameters.<apiName>. When the calc is evaluated, the reference is replaced with the parameter’s resolved value. In Salesforce-syntax formulas the reference is written Parameters.<apiName>; in bracketed (Tableau) syntax it is written [Parameters].[<apiName>].
1{
2 "structured_semantic_query": {
3 "fields": [
4 {
5 "expression": {
6 "semantic_field": {
7 "name": "formula_measurement_example"
8 }
9 }
10 }
11 // ...
12 ]
13 },
14 "semantic_model": {
15 "apiName": "Sales",
16 "semanticParameters": [
17 {
18 "apiName": "param1",
19 "label": "param1",
20 "dataType": "Text",
21 "defaultValue": "Web"
22 }
23 ],
24 "semanticCalculatedMeasurements": [
25 {
26 "apiName": "formula_measurement_example",
27 "dataType": "Number",
28 "decimalPlace": 3,
29 "expression": "10 * Parameters.param1",
30 "syntax": "Salesforce"
31 }
32 ]
33 }
34}Use a parameter as a filter operand by referencing it as a semantic_field whose name is Parameters.<apiName>. The reference resolves to the parameter’s value, so the same filter shape can compare a field against a value the consumer sets per query.
1{
2 "structured_semantic_query": {
3 "fields": [
4 // ...
5 ],
6 "filter": {
7 "binary_predicate": {
8 "left_expression": {
9 "semantic_field": {
10 "name": "Parameters.param1"
11 }
12 },
13 "binary_operator": "BINARY_OPERATOR_EQUALS",
14 "right_expression": {
15 "string_expression": "Web"
16 }
17 }
18 }
19 },
20 "semantic_model": {
21 "apiName": "Sales",
22 "semanticParameters": [
23 {
24 "apiName": "param1",
25 "label": "param1",
26 "dataType": "Text",
27 "defaultValue": "Web"
28 }
29 ]
30 // ...
31 }
32}A parameter can be referenced inside a summary-level calculated measurement — a calc whose expression aggregates. Reference the parameter with the bracketed [Parameters].[<apiName>] form alongside the aggregation, and pass its value through the parameters array (or rely on the model default). The parameter contributes its resolved value to the aggregated result.
1{
2 "structured_semantic_query": {
3 "fields": [
4 {
5 "alias": "name",
6 "expression": {
7 "table_field": {
8 "name": "sdm__AccountTypeId__c",
9 "table_name": "SemanticAccount__dlm"
10 }
11 },
12 "grouping": "ROW_GROUPING"
13 },
14 {
15 "expression": {
16 "calculated_field": {
17 "name": "summary-calc-in-select",
18 "expression": "SUM([SemanticAccount__dlm].[sdm__AccountTypeId__c]) + [Parameters].[test12]",
19 "calculated_measure_expression": {
20 "measure_output_type": "SEMANTIC_MEASUREMENT_TYPE_NUMBER",
21 "decimal_places_options": {
22 "decimal_places": 2
23 }
24 }
25 }
26 }
27 }
28 ],
29 "options": {
30 "detailed_rows": true,
31 "grand_total": true
32 }
33 },
34 "semantic_model": {
35 "apiName": "Sales",
36 "semanticParameters": [
37 {
38 "apiName": "test12",
39 "label": "test1",
40 "dataType": "Number",
41 "defaultValue": "0"
42 }
43 ]
44 // ...
45 }
46}A parameter’s dataType fixes the kind of value it accepts. Supported values are Text, Number, Date, DateTime, Percentage, Url, Email, PhoneNumber, and Boolean. The value you pass in the parameters array — and the model defaultValue — must be convertible to this type.
The value-selection type controls how a value is chosen. A List-type parameter defines allowedValues, each with a value (the underlying constant) and a displayName (the label shown to consumers). Display names are unique within a list; when selecting a List value at query time, the selection matches on the displayName.
1{
2 "semantic_model": {
3 "apiName": "Sales",
4 "semanticParameters": [
5 {
6 "apiName": "test12",
7 "label": "test1",
8 "dataType": "Number",
9 "defaultValue": "0",
10 "type": "List",
11 "allowedValues": [
12 {
13 "displayName": "0",
14 "value": "0"
15 },
16 {
17 "displayName": "1",
18 "value": "1"
19 }
20 ]
21 }
22 ]
23 // ...
24 }
25}Fields this section introduces on structuredSemanticQuery. For the full request schema, see Request Reference.
| Field (wire name) | Type | Required | Description |
|---|---|---|---|
parameters | QueryParameter[] | N | Ad-hoc parameter values for this query. Each entry overrides the model defaultValue for the named parameter. |
parameters[].name | String | Y* | API name of the model parameter to set. |
parameters[].value | String | Y* | Value to use for this parameter; must be convertible to the parameter’s dataType. |
A parameter is referenced (not listed in parameters) by using Parameters.<apiName> as a semantic_field name in a filter, or Parameters.<apiName> / [Parameters].[<apiName>] inside a calculated-field expression.
parameters must be convertible to the parameter’s dataType; for a List-type parameter, a query-time selection matches on the entry’s displayName.parameters entry whose name does not match a model-defined parameter is ignored — it is filtered out and has no effect on the query.
j