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.