Semantic Metric Query Entities

The following are the top-level entities that compose the Semantic Metric Query API:

Field Label	Type	Description
StructuredMetricQuery	StructuredMetricQuery	Required. Representation of a semantic metric 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.
source	String	ID of the source of the query used for usage lake reporting.
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.

StructuredMetricQuery Fields

The following are the fields within the StructuredMetricQuery object:

Field Label	Type	Description
model_api_name	String	Required. The API name of the semantic model to use for this query.
submetric_definition	SubmetricDefinition	The metric definition that specifies which metric to query.
time_grain	SemanticMetricTimeGrainTypeEnum	The time grain for the metric query (Day, Week, Month, Quarter, Year).
additional_dimensions	repeated SemanticFieldReference	Array of additional dimensions to add to the metric results.
time_range	SemanticFilter	Time range filter for the metric query.
sort_orders	repeated SortOrder	Array of sort orders that define how query results are sorted.
limit_options	LimitOptions	Limits the number of results returned.
semantic_context	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.

The following are the fields within the SubmetricDefinition object:

Field Label	Type	Description
metric_api_name	String	Required. The API name of the metric to query.
filters	repeated SemanticFilter	Optional. Array of filters to apply to the metric query.

The following are the fields within the StatusCondition object:

Field Label	Type	Description
status_name	String	Required. The name of the status condition.
value	String	Required. The value to compare against.
operator	SemanticFilterOperatorTypeEnum	Required. The operator for the comparison (equals, greater than, etc.).
is_primary	Boolean	Optional. Whether this is the primary status condition. Default: false.

The following are the fields within the SemanticFieldReference object:

Field Label	Type	Description
tableFieldReference	SemanticTableFieldReference	Optional. Reference to a table field that will be used as an additional dimension.
calculatedFieldApiName	String	Optional. The API name of a calculated field. Alternative to tableFieldReference.

The following are the fields within the SortOrder object:

Field Label	Type	Description
simple_sort_order	SimpleSortOrder	Optional. Simple sort order for basic sorting operations.
aggregative_sort_order	AggregativeSortOrder	Optional. Aggregative sort order for sorting grouped results.

The following are the fields within the LimitOptions object:

Field Label	Type	Description
limit	int32	Required. The maximum number of results to return.

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.