Salesforce Docs Portal

SemanticQueryRequest Fields

The following are the top-level fields that compose the SemanticQueryRequest:

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.

StructuredSemanticQuery Fields

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.

QueryField Fields

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.

QueryOptions Fields

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.

SimpleSortOrder Fields

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.

AggregativeSortOrder Fields

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.

SemanticContext Fields

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.

SemanticModel Fields

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.

Expression Types

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.