--- schema_version: "1" id: 7627dd9c962bd598d997fda680f223d8d157605b38931edb47859ffcc0f7c140 title: Parameters 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-parameters.md canonical_url: https://developer.salesforce.com/docs/data/semantic-layer/guide/query-api-in-depth-parameters.html source_site: developer.salesforce.com content_type: documentation content_hash: 6063aaea6fcc8c576fb0b7b69473cafbf18e815e6e791063e0804f724a3a8b60 products: - Tableau Semantics Layer APIs - Data 360 Developer Documentation --- # Parameters ## Overview 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.` — 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. ## Metadata in the model 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](https://developer.salesforce.com/docs/data/semantic-layer/guide/connect-api-in-depth-entities.md#semantic-parameter-semanticparameter), [Semantic Parameter List](https://developer.salesforce.com/docs/data/semantic-layer/guide/connect-api-in-depth-entities.md#semantic-parameter-list-semanticparameterlist), and [Semantic Parameter Range](https://developer.salesforce.com/docs/data/semantic-layer/guide/connect-api-in-depth-entities.md#semantic-parameter-range-semanticparameterrange) in the Authoring API. ## Query usage ### Passing parameter values 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. ```json { "structured_semantic_query": { "fields": [ { "expression": { "semantic_field": { "name": "formula_measurement_example" } } } // ... ], "filter": { "binary_predicate": { "left_expression": { "semantic_field": { "name": "Parameters.param1" } }, "binary_operator": "BINARY_OPERATOR_EQUALS", "right_expression": { "string_expression": "Web" } } }, "parameters": [ { "name": "param1", "value": "adhoc" } ] }, "semantic_model": { "apiName": "Sales", "semanticParameters": [ { "apiName": "param1", "label": "param1", "dataType": "Text", "defaultValue": "Web" } // ... ] } } ``` > **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. ### Parameters in expressions Reference a parameter inside a calculated-field formula by the name `Parameters.`. When the calc is evaluated, the reference is replaced with the parameter's resolved value. In Salesforce-syntax formulas the reference is written `Parameters.`; in bracketed (Tableau) syntax it is written `[Parameters].[]`. ```json { "structured_semantic_query": { "fields": [ { "expression": { "semantic_field": { "name": "formula_measurement_example" } } } // ... ] }, "semantic_model": { "apiName": "Sales", "semanticParameters": [ { "apiName": "param1", "label": "param1", "dataType": "Text", "defaultValue": "Web" } ], "semanticCalculatedMeasurements": [ { "apiName": "formula_measurement_example", "dataType": "Number", "decimalPlace": 3, "expression": "10 * Parameters.param1", "syntax": "Salesforce" } ] } } ``` ### Parameters in filters Use a parameter as a filter operand by referencing it as a `semantic_field` whose `name` is `Parameters.`. 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. ```json { "structured_semantic_query": { "fields": [ // ... ], "filter": { "binary_predicate": { "left_expression": { "semantic_field": { "name": "Parameters.param1" } }, "binary_operator": "BINARY_OPERATOR_EQUALS", "right_expression": { "string_expression": "Web" } } } }, "semantic_model": { "apiName": "Sales", "semanticParameters": [ { "apiName": "param1", "label": "param1", "dataType": "Text", "defaultValue": "Web" } ] // ... } } ``` ### Parameter with summary level A parameter can be referenced inside a summary-level calculated measurement — a calc whose expression aggregates. Reference the parameter with the bracketed `[Parameters].[]` 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. ```json { "structured_semantic_query": { "fields": [ { "alias": "name", "expression": { "table_field": { "name": "sdm__AccountTypeId__c", "table_name": "SemanticAccount__dlm" } }, "grouping": "ROW_GROUPING" }, { "expression": { "calculated_field": { "name": "summary-calc-in-select", "expression": "SUM([SemanticAccount__dlm].[sdm__AccountTypeId__c]) + [Parameters].[test12]", "calculated_measure_expression": { "measure_output_type": "SEMANTIC_MEASUREMENT_TYPE_NUMBER", "decimal_places_options": { "decimal_places": 2 } } } } } ], "options": { "detailed_rows": true, "grand_total": true } }, "semantic_model": { "apiName": "Sales", "semanticParameters": [ { "apiName": "test12", "label": "test1", "dataType": "Number", "defaultValue": "0" } ] // ... } } ``` ### Parameter data types 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`. ```json { "semantic_model": { "apiName": "Sales", "semanticParameters": [ { "apiName": "test12", "label": "test1", "dataType": "Number", "defaultValue": "0", "type": "List", "allowedValues": [ { "displayName": "0", "value": "0" }, { "displayName": "1", "value": "1" } ] } ] // ... } } ``` ## Reference Fields this section introduces on `structuredSemanticQuery`. For the full request schema, see [Request Reference](https://developer.salesforce.com/docs/data/semantic-layer/guide/query-api-in-depth-fields.md). | 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.` as a `semantic_field` name in a filter, or `Parameters.` / `[Parameters].[]` inside a calculated-field expression. ## Limitations - A parameter resolves to a single constant value. It cannot reference a calculated field or another parameter. - A value passed in `parameters` must be convertible to the parameter's `dataType`; for a `List`-type parameter, a query-time selection matches on the entry's `displayName`. - A `parameters` entry whose `name` does not match a model-defined parameter is ignored — it is filtered out and has no effect on the query. ## Related - [Semantic Parameter](https://developer.salesforce.com/docs/data/semantic-layer/guide/connect-api-in-depth-entities.md#semantic-parameter-semanticparameter) · [Semantic Parameter List](https://developer.salesforce.com/docs/data/semantic-layer/guide/connect-api-in-depth-entities.md#semantic-parameter-list-semanticparameterlist) · [Semantic Parameter Range](https://developer.salesforce.com/docs/data/semantic-layer/guide/connect-api-in-depth-entities.md#semantic-parameter-range-semanticparameterrange) — Authoring API for defining parameters. - [Calculated Fields](https://developer.salesforce.com/docs/data/semantic-layer/guide/query-api-in-depth-calculated-fields.md) — Reference parameters inside calculated-field expressions. - [Filtering](https://developer.salesforce.com/docs/data/semantic-layer/guide/query-api-in-depth-filtering.md) — Use a parameter as a filter operand. - [Request Reference](https://developer.salesforce.com/docs/data/semantic-layer/guide/query-api-in-depth-fields.md) — Complete request schema.