SemanticQueryRequest Fields
The following are the top-level fields that compose the SemanticQueryRequest:
| Field Label | Type | Description |
|---|---|---|
| structuredSemanticQuery | StructuredSemanticQuery | Required. Representation of a semantic query. |
| dataspace | String | ID of the data space in which the query is executed. The default data space is used if no data space is selected. |
| groupId | String | ID of a group of queries. The query is sent as a part of this group if this field is defined. |
| queryParameter | String | Query parameter name and value for parameterized queries. |
| semanticModelId | String | The unique identifier of an existing semantic model to use for this query. When provided, the system will retrieve the model from the authoring service. Cannot be used together with semanticModel field. |
| semanticModel | SemanticModel | The complete semantic model definition to use for this query. This allows you to provide the model inline without requiring it to be pre-saved. Cannot be used together with semanticModelId field. |
The following are the fields within the StructuredSemanticQuery object:
| Field Label | Type | Description |
|---|---|---|
| fields | repeated QueryField | Required field that define the dimensions and measurements in the query and the query grouping. |
| filter | Predicate | Rules that define which records to exclude from the query, including dimensions, measurements, and calculated fields. Valid values are dates, text, num-type, logic (AND, OR, NOT), and relative date. |
| options | QueryOptions | Defines object limits, sort order, and row limits. |
| semanticContext | SemanticContext | Central class configuration that manages a variety of settings that determine how the query is executed and how results are shown. Settings include time zone, fiscal year, and locale. |
| aggregateFilter | Predicate | Filter that is applied to an aggregate measurement. Valid values are Sum, AVG, Min, Max, Median, Count Distinct, Stddev, Stddevp, Var, and Varp. |
The following are the fields within the QueryField object:
| Field Label | Type | Description |
|---|---|---|
| expression | Expression | Required. Represents an expression within the query. A field can be any column, array, function, or constant within the query. |
| semanticAggregationMethod | SemanticAggregationMethod | Defines the aggregation method for a specific field. Valid values are None, Auto, Count, Sum, AVG, Min, Max, Median, Unique Count, Stddev, Stddevp, Var, Varp, First, Last, Unique, and User_agg. |
| alias | string | Defines the alias of a field within a query. |
| rowGrouping | bool | Defines whether results are grouped by a specific field (True) or not (False). |
| grouping | Grouping | Required if the rowGrouping field is set to "True". Defines the columns used to group and manage large datasets and obtain aggregated total results for each column. Valid values are Dimensions, Measurements, Dates, Field, and Fiscal Dates. |
| showMissingValues | ShowMissingValues | Defines data densification settings for a query field. Controls whether missing values are shown in results. |
The following are the fields within the QueryOptions object:
| Field Label | Type | Description |
|---|---|---|
| sort_orders | repeated SortOrder | Defines how query results are sorted. Valid values are Simple Sort Order and Aggregative Sort Order. |
| limit_options | LimitOptions | Defines the maximum number of rows to return from the query results. |
| offset_options | OffsetOptions | Defines the offset of query results from a specific row by integer. |
| detailed_rows | bool | Defines whether to return detailed row information in the query results. |
| subtotals | bool | Defines whether subtotals are calculated based on the formula logic (True) or not (False). If True, subtotal measurements are calculated according to the aggregation method selected for grouping dimensions. The result of the calculation is added as a row to the Semantic Query results set. Valid values are Sum, AVG, Min, Max, Median. Default is Sum. |
| grand_total | bool | Defines whether grand totals are calculated based on the formula logic (True) or not (False). Grand totals reflect all total values in the entire dataset in a Semantic Query and are aggregated based on user selection. Valid values are Sum, AVG, Min, Max, Median. Default is Sum. |
| row_counts | bool | Defines whether to include row count information in the query results. |
| join_path_plan | JoinPathPlan | Defines the join path strategy for query execution. Valid values are JOIN_ALL_TABLES and JOIN_MINIMAL_TABLES. |
| smart_aggregations | bool | Defines whether to use smart aggregation logic for query optimization. |
| apply_model_sorting | bool | Defines whether to apply model-defined sorting to query results. |
| disallow_cross_join | bool | Defines whether to disallow cross joins in the query execution. |
The following are the fields within the SimpleSortOrder object:
| Field Label | Type | Description |
|---|---|---|
| sort_by | SortField sort_by_field / string sort_by_field_alias | Required. Defines how the query results are sorted. Valid values are sort_by_field and sort_by_field_alias, where "field" and "alias" are the name of the field or alias that you want to sort by. |
| sorting_order | SortingOrder | Defines whether the query results are sorted in ascending or descending order. Valid values are Asc and Desc. |
| null_values_position | NullValuesPosition | Defines whether query result rows with null values appear at the top or the bottom of the response. Valid values are Nulls_first and Nulls_last. |
The following are the fields within the AggregativeSortOrder object:
| Field Label | Type | Description |
|---|---|---|
| sort_group | Expression grouped_expression / string grouped_field_alias | Required. Defines the sort group for the aggregative sort order. Valid values are grouped_expression and grouped_field_alias. |
| sort_by | SortField sort_by_field / string sort_by_field_alias / bool sort_by_row_count | Required. Defines how aggregated query results are sorted. Valid values are sort_by_field, sort_by_field_alias, and sort_by_row_count. The field or alias used must be defined. |
| sorting_order | SortingOrder | Defines whether the query results are sorted in ascending or descending order. Valid values are Asc and Desc. |
| null_values_position | NullValuesPosition | Defines whether query result rows with null values appear at the top or the bottom of the response. Valid values are Nulls_first and Nulls_last. |
The following are the fields within the SemanticContext object:
| Field Label | Type | Description |
|---|---|---|
| timezone | Timezone | Represents a specific timezone. Valid values and codes can be found in the Supported Time Zones documentation. |
| locale | Locale | Represents a locale. Locales determine the display formats for date and time, users' names, addresses, and commas and periods in numbers. Valid values can be found in the Salesforce Supported Locales documentation. |
| currency | Currency | Represents a currency for financial calculations and display formatting. |
The following are the fields within the SemanticModel object:
| Field Label | Type | Description |
|---|---|---|
| apiName | string | The API name of the semantic model. |
| label | string | The display label of the semantic model. |
| unrelatedDataObjectsQueryBehavior | SemanticQueryUnrelatedDataObjectsTypeEnum | Defines how to handle querying unrelated data objects. Valid values are Exception and Union. |
| semanticDataObjects | repeated SemanticDataObject | List of semantic data objects in the model. |
| semanticRelationships | repeated SemanticRelationship | List of semantic relationships in the model. |
| semanticCalculatedDimensions | repeated SemanticCalculatedDimension | List of calculated dimensions in the model. |
| semanticCalculatedMeasurements | repeated SemanticCalculatedMeasurement | List of calculated measurements in the model. |
| dataspace | string | The dataspace associated with the semantic model. |
| semanticParameters | repeated SemanticParameter | List of parameters in the semantic model. |
| semanticLogicalViews | repeated SemanticLogicalView | List of logical views in the semantic model. |
| semanticMetrics | repeated SemanticMetric | List of metrics in the semantic model. |
| semanticGroupings | repeated SemanticGrouping | List of groupings in the semantic model. |
| currency | Currency | The currency associated with the semantic model. |
| externalConnections | repeated ExternalConnection | List of external connections in the semantic model. |
| id | string | The unique identifier of the semantic model. |
| hasUnmapped | bool | Indicates whether the semantic model has unmapped fields. |
| businessPreferences | string | Business preferences for the semantic model. |
| agentEnabled | bool | Indicates whether the agent is enabled for this semantic model. |
The following are the possible expression types within the Expression field:
| Field Label | Type | Description |
|---|---|---|
| bool_expression | bool | Boolean expression value (true/false). |
| int_expression | int32 | 32-bit integer expression value. |
| long_expression | int64 | 64-bit integer expression value. |
| float_expression | float | Single-precision floating-point expression value. |
| double_expression | double | Double-precision floating-point expression value. |
| string_expression | string | String expression value. |
| bytes_expression | bytes | Binary data expression value. |
| table_field | TableField | Reference to a physical table column. |
| semantic_field | SemanticField | Reference to a virtual/semantic column. |
| calculated_field | CalculatedField | Reference to a calculated field expression. |
| array_expression | ArrayExpression | Array of expressions. |
| date_expression | DateExpression | Date expression without time component. |
| range_values | RangeValues | Range of values with upper and lower boundaries. |
| null_value | NullValue | Null value expression. |
| datetime_expression | string | DateTime expression as string. |
| relative_date_range | RelativeDateRange | Relative date range expression. |
| forecast_field | ForecastField | Forecast field expression for predictive analytics. |
| relationship_formula | string | Relationship formula expression. |