Top-Level Entities
The following are the top-level entities that compose the Tableau Semantics Authoring API and their API names (in parenthesis):
- Semantic Model (SemanticModel) - Represents a group of Semantic Definitions consumed by an application or used to solve a particular use case.
- Semantic Data Object (SemanticDataObject) - Represents a reference to an existing DMO or CIO that is part of a specific Semantic Model.
- Semantic Relationship (SemanticRelationship) - Represents the join type and the joined fields between two Semantic Data Objects.
- Semantic Calculated Dimension (SemanticCalDimension) - Represents a non-aggregatable field or dimension that you can create on top of your existing data.
- Semantic Calculated Measurement (SemanticCalMeasurement) - Represents a numerical custom calculation that you can create on top of your existing data.
- Semantic Data Object Field (SemanticDataObjectField) - Represents the fields that are included in a Semantic Data Object, which is added to a specific Semantic Model.
- Semantic Metric Definition (SemanticMetricDefinition) - Represents a semantic metric, which is a business KPI that can be tracked over time in the semantic layer.
- Semantic Override Element (SemanticOverrideElement) - Represents an audit table that tracks changes in specific semantic entity fields.
- Semantic Parameter (SemanticParameter) - Represents a parameter that can be used in filters and/or calculated expressions in the semantic layer.
- Semantic Parameter List (SemanticParameterList) - Represents a pre-defined list of parameter values when the parameter type is "List".
- Semantic Parameter Range (SemanticParameterRange) - Represents a pre-defined list of parameter properties when the parameter type is "Range".
- Semantic Logical View (SemanticLogicalView) - Represents a join view that is composed of multiple table representations of semantic data objects, such as data model objects (DMOs), calculated insights (CIs), and semantic model objects (SMOs).
The following sections provide a description of the entity and a table of its attributes and fields, including the entity name, field name, API name, entity type, whether the field is required, possible values, and a description.
Use the SemanticModel entity to define the Semantic Model being used. Define the required fields including the object ID, developer name, the display name of the Semantic Model and the dataspace in which the model is located. You can also define non-required fields including the description, category, and app.
| Entity | Field Label | Developer Name | Type | Required? | Values | Description |
|---|---|---|---|---|---|---|
| SemanticModel | ID | ID | ID | Y | Required. Object ID that references the Semantic Model. | |
| SemanticModel | Developer Name | DeveloperName | String | Y | Required. API name of the Semantic Model. | |
| SemanticModel | Display Name | DisplayName | String | Y | Required. Display name of the Semantic Model. | |
| SemanticModel | Description | Description | String | N | Description of the Semantic Model. | |
| SemanticModel | Dataspace Definition | DataspaceDefinition | ID | Y | Required. Dataspace in which the Semantic Model is located. | |
| SemanticModel | Category | Category | StaticEnum | N | Marketing,Commerce, Sales, Service, Other | Product category of the Semantic Model. Valid values are Marketing, Commerce, Sales, Service, and Other. |
| SemanticModel | App | App | String | N | App to which the Semantic Model belongs. | |
| SemanticModel | Unrelated Data Objects Query Behavior | UnrelatedDataObjectsQueryBehavior | StaticEnum | N | Exception, Union | Default behavior of the model when querying data objects without a predefined relationship at the model level. Valid values are Exception and Union. |
Use the SemanticDataObject entity to reference to an existing DMO or CIO that is part of a specific Semantic Model. Define the required fields of the ID of the SemanticDataObject entity and the ID of each Semantic Data Object that is being references together with the object's developer name, data object type, and whether all of the object's fields should be included in the Semantic Model.
| Entity | Field Label | Developer Name | Type | Required? | Values | Description |
|---|---|---|---|---|---|---|
| SemanticDataObject | ID | ID | ID | Y | Required. Object ID that references a Semantic Data Object. | |
| SemanticDataObject | Semantic Definition | SemanticDefinition | ID | Y | Required. Foreign key ID that references the Semantic Definition referenced by the Semantic Data Object. | |
| SemanticDataObject | Data Object Developer Name | DataObjectDeveloperName | String | Y | Required. API name of the Semantic Data Object. | |
| SemanticDataObject | Data Object Type | DataObjectType | StaticEnum | Y | Required. Semantic Data Object type. Values include DLO, DMO, and CIO. | |
| SemanticDataObject | Should Include All Fields | ShouldIncludeAllFields | Boolean | Y | Required. Indicates whether to import all fields from the Data Object into the Semantic Data Object in the Semantic Model (true) or not (false). |
Use the SemanticRelationship entity to define the join type and the joined fields between two Semantic Data Objects within a Semantic Definition. Define the required fields of the ID of the SemanticRelationship entity and the ID of the Semantic Definition that the relationship extends. Also define the required fields of the developer names of the left and right joins, the join type, and the join criteria.
| Entity | Field Label | Developer Name | Type | Required? | Values | Description |
|---|---|---|---|---|---|---|
| SemanticRelationship | ID | ID | ID | Y | Required. Object ID that references the Semantic Relationship. | |
| SemanticRelationship | Semantic Definition | SemanticDefinition | ID | Y | Required. Object ID that references the Semantic Definition that this entity extends. | |
| SemanticRelationship | Left Semantic Definition Developer Name | LeftSemanticDefinitionDeveloperName | String | Y | Required. API name of the left table field Semantic Definition. | |
| SemanticRelationship | Right Semantic Definition Developer Name | RightSemanticDefinitionDeveloperName | String | Y | Required. API name of the right table field Semantic Definition. | |
| SemanticRelationship | Join Type | JoinType | StaticEnum | Y | Auto, Left,Right,Inner,Full | Required. Type of join performed between the defined Data Cloud Objects. Valid values are AUTO, LEFT, RIGHT, FULL, and INNER. |
| SemanticRelationship | Criteria | Criteria | String | Y | Required. JSON representation of the join conditions between two Data Cloud Objects. |
Use the SemanticCalcDimension entity to define the attributes of a non-aggregatable field or dimension that you can create on top of your existing data. Use this entity for every Calculated Dimension you want to add to your Semantic Model. Define the required fields of the Semantic Calculated Dimension ID and the ID of the Semantic Definition that will use the Semantic Calculated Dimension, the data type, and the expression formula to create the dimension. You can also define non-required fields such as geo role, sort order, display category, and whether the dimension is visible in the consumption layer.
| Entity | Field Label | Developer Name | Type | Required? | Values | Description |
|---|---|---|---|---|---|---|
| SemanticCalculatedDimension | ID | ID | ID | Y | Required. Type of data stored in the Semantic Calculated Dimension. Valid values are Text,Date,DateTime,Image,Boolean,Geo, and Number. | |
| SemanticCalculatedDimension | Semantic Definition | SemanticDefinition | ID | Y | Required. Foreign key ID that references the Semantic Definition. | |
| SemanticCalculatedDimension | Data Type | DataType | StaticEnum | Y | Text,Date,DateTime,Image,Boolean,Geo, | |
| Number | Required. Object ID that references the Semantic Definition. | |||||
| SemanticCalculatedDimension | Geo Role | GeoRole | StaticEnum | N | Airport,Area Code (US),CBSA/MSA (US), City,Congressional,District (US),Country/Region,Country,NUTS Europe,Latitude,Longitude,State/Province,Zip Code/Postcode | Geographic role of the Semantic Calculated Dimension. Valid values are Airport,Area Code (US),CBSA/MSA (US), City,Congressional, District (US),Country/Region,Country,NUTS Europe,Latitude,Longitude,State/Province,and Zip Code/Postcode. |
| SemanticCalculatedDimension | Sort Order | SortOrder | StaticEnum | N | Ascending,Descending, None | Sort order of the Semantic Calculated Dimension. Valid values are Ascending,Descending, and None. |
| SemanticCalculatedDimension | Expression | Expression | String | Y | Required. A formula that creates a new Semantic Calculated Dimension based on a calculation that uses raw data fields and calculated fields. | |
| SemanticCalculatedDimension | Display Category | DisplayCategory | StaticEnum | N | Discrete,Continuous | Controls how data is represented in visualizations of the relationships between Semantic Calculated Dimensions and other Data Cloud Objects. Valid values are Discrete and Continuous. |
| SemanticCalculatedDimension | Is Visible | IsVisible | Boolean | N | Indicates whether the Semantic Calculated Dimension is visible in the consumption layer (true) or not (false). True is the default. |
Use the SemanticCalcMeasurement entity to define the attributes of a numerical custom calculation that you can create on top of your existing data. Use this entity for every Calculated Measurement you want to add to your Semantic Model. Define the required fields of the Semantic Calculated Measurement ID and the ID of the Semantic Definition that will use the Semantic Calculated Measurement, the data type, aggregation type, decimal place, and the expression formula to create the dimension. You can also define the non-required fields of filter logic.
| Entity | Field Label | Developer Name | Type | Required? | Values | Description |
|---|---|---|---|---|---|---|
| SemanticCalcMeasurement | ID | ID | ID | Y | Required. Object ID that references the Semantic Calculated Measurement. | |
| SemanticCalcMeasurement | Semantic Definition | SemanticDefinition | ID | Y | Required. Foreign key ID that references the Semantic Definition. | |
| SemanticCalcMeasurement | Data Type | DataType | StaticEnum | Y | Currency,Number, Duration,Percentage | Required. Type of data stored in specific fields in a Semantic Calculated Measurement. Valid values are Currency,Number, Duration,and Percentage |
| SemanticCalcMeasurement | Aggregation Type | AggregationType | StaticEnum | Y | Sum,Average,Min,Max,Median,Count Distinct,Count,Stddev,Stddevp,Var,Varp,Last,First,UserAgg, None | Required. Function that computes numerical calculations on data, allowing the query to return summarized information about the expression results. Valid values are Sum,Average,Min,Max,Median,Count Distinct,Count,Stddev,Stddevp,Var,Varp,Last,First, UserAgg, and None. |
| SemanticCalcMeasurement | Decimal Place | DecimalPlace | Number | Y | Required. Number of decimal places to display in the Semantic Calculated Measurement. | |
| SemanticCalcMeasurement | Expression | Expression | String | Y | Required. Formula that generates a new Semantic Calculated Measurement based on a calculation that uses raw data fields and calculated fields. | |
| SemanticCalcMeasurement | Filter Logic | FilterLogic | String | N | Logical expression that defines how and when the filter conditions will be applied. Valid values are AND, OP, NOT, and parenthesis (). |
Use the SemanticDataObjectField entity to define the attributes of each field that is included in a Semantic Data Object, which is added to a specific Semantic Model. The field options vary on whether the object is a Semantic Calculated Dimension or Semantic Calculated Measurement. Define the required fields including the ID of the Semantic Data Object Field, the ID of Semantic Definition in which the field is used, the data field developer name, the data role of the field (dimension or measurement), the display name, and the data type. You can also define non-required fields, depending on whether you are working with a dimension or measurement. These include the aggregation type, decimal place, geo role, sort order, display category, directionality, and whether the field is visible in the consumption layer.
| Entity | Field Label | Developer Name | Type | Required? | Values | Description |
|---|---|---|---|---|---|---|
| SemanticDataObjectField | ID | ID | ID | Y | Required. Object ID that references the Semantic Data Object Field. | |
| SemanticDataObjectField | Semantic Definition Id | SemanticDefinition | ID | Y | Required. Foreign key ID that references the Semantic Definition. | |
| SemanticDataObjectField | DataFieldDeveloperName | DataFieldDeveloperName | String | Y | Required. API name of the Semantic Data Object Field. | |
| SemanticDataObjectField | DataRole | DataRole | StaticEnum | Y | Dimension,Measurement | Required. Data role type of a Semantic Data Object Field. Valid values are Dimension and Measurement. |
| SemanticDataObjectField | Display Name | DisplayName | String | Y | Required. Display name of the Semantic Data Object Field. | |
| SemanticDataObjectField | Data Type | DataType | StaticEnum | Y | Text,Date,DateTime,Image,Boolean,Geo,Currency,Number, Duration,Percentage | Required. Data type stored in a specific Semantic Data Object Field. Valid values are Text,Date,DateTime,Image,Boolean,Geo,Currency,Number, Duration,and Percentage. |
| SemanticDataObjectField | Aggregation Type | AggregationType | StaticEnum | N | Sum,Average,Min,Max,Median,Count Distinct,Count,Stddev,Stddevp,Var,Varp,Last,First, | |
| UserAgg, None | Function that computes numerical calculations on data, allowing the query to return summarized information about the expression results. Valid values are Sum,Average,Min,Max,Median,Count Distinct,Count,Stddev,Stddevp,Var,Varp,Last,First, UserAgg, and None. | |||||
| SemanticDataObjectField | Decimal Place | DecimalPlace | Number | N | Number of decimal places to display. | |
| SemanticDataObjectField | Geo Role | GeoRole | StaticEnum | N | Airport,Area Code (US),CBSA/MSA (US), City,Congressional,District (US),Country/Region,Country,NUTS Europe,Latitude,Longitude,State/Province,Zip Code/Postcode | Geographic role of the Semantic Calculated Dimension. Valid values are Airport,Area Code (US),CBSA/MSA (US), City,Congressional,District (US),Country/Region,Country,NUTS Europe,Latitude,Longitude,State/Province,and Zip Code/Postcode. |
| SemanticDataObjectField | Sort Order | SortOrder | StaticEnum | N | Ascending,Descending, None | Sort order of the Semantic Calculated Measurement. Valid values are Ascending,Descending, and None. |
| SemanticDataObjectField | Display Category | DisplayCategory | StaticEnum | N | Discrete,Continuous | Controls how data is represented in visualizations of the relationships between Data Cloud Objects. Valid values are Discrete and Continuous. |
| SemanticDataObjectField | Direcionailty | Directionailty | StaticEnum | N | Up, Down | Indicates the directionality of the Semantic Calculated Measurement by establishing whether an upward or a downward trend is seen as positive (Up) or negative (Down). |
| SemanticDataObjectField | Is Visible | IsVisible | Boolean | N | Indicates whether the Semantic Data Object Field is visible in the consumption layer (true) or not (false). True is the default. |
Use the SemanticMetricDefinition entity to define a Semantic Metric Definition and associated properties, including the ID of the Metric Definition, the ID of the Semantic Definition used in the Metric Definition, and a variety of time measure and filtering settings.
| Entity | Field Label | Developer Name | Type | Required? | Description |
|---|---|---|---|---|---|
| SemanticMetricDefinition | ID | ID | ID | Y | Required. ID of the SemanticMetricDefinition entity. |
| SemanticMetricDefinition | Semantic Definition | SemanticDefinition | ENTITYID | Y | Required. ID of the SemanticDefinition entity used in the SemanticMetricDefinition entity. |
| SemanticMetricDefinition | Time Dimension Api Name | TimeDimensionApiName | TEXT | Y | Required. ID of the SemanticDataObjectField or SemanticCalculatedDimension that is used for time selection in the SemanticMetricDefinition. |
| SemanticMetricDefinition | Measurement Api Name | MeasurementApiName | TEXT | Y | Required. ID of the SemanticDataObjectField or SemanticCalculatedDimension that is used to evaluate the values of the SemanticMetricDefinition. |
| *SemanticMetricDefinition | Allowed Time Grain Types | AllowedTimeGrains | TEXT | Y | Required. List of available time grain types that can be used to query the data in the SemanticMetricDefinition. |
| SemanticMetricDefinition | Adjustables Filters Api Names | AdjustableFiltersApiNames | STRINGPLUSCLOB | N | List of dimensions related to the SemanticMetricDefinition. These dimensions can be used by queries to provide different views of the metric data. |
| SemanticMetricDefinition | Insigths Settings | InsightsSettings | STRINGPLUSCLOB | N | Set of configurations that specify which insight types and dimensions to use when generating insights based on the SemanticMetricDefinition. |
| SemanticMetricDefinition | Filters | Filters | TEXT | Y | Required. Textual represenation of the filters applied to the SemanticMetricDefinition. |
| SemanticMetricDefinition | FilterLogic | FilterLogic | STRINGPLUSCLOB | Y | Required. Textual representation of the filter logic applied to the SemanticMetricDefinition. |
Use the SemanticOverrideElement entity to override any existing Semantic entity.
| Entity | Field Label | Developer Name | Type | Required? | Description |
|---|---|---|---|---|---|
| SemanticOverrideElement | ID | ID | ID | Y | Required. ID of the SemanticOverrideElement entity. |
| SemanticOverrideElement | Object Type | ObjectType | StaticEnum | Y | Required. Entity type referenced by the SemanticOverrideElement. Valid values are SemanticDataObject and SemanticDataObjectField. |
| SemanticOverrideElement | Referenced Object | ReferencedObject | ID | Y | Required.The ID of the entity that has been changed due to the Semantic Override Element entity. |
| SemanticOverrideElement | OverrideElementName | OverrideElementName | StaticEnum | Y | Required. Element or attribute that was changed due to the SemanticOverrideElement entity. |
Use the Semantic Parameter entity to define a Semantic Parameter and related properties, such as the Semantic Definition that is used by the Parameter, the data type, the parameter type, and parameter value.
| Entity | Field | Developer Name | Type | Required? | Description |
|---|---|---|---|---|---|
| SemanticParameter | ID | ID | ID | Y | Required. ID of the SemanticParameter entity. |
| SemanticParameter | Semantic Definition | SemanticDefinition | Lookup(SemanticDefinition) | Y | Required. ID of the SemanticDefinition entity used in the SemanticParameter entity. |
| SemanticParameter | Data Type | DataType | StaticEnum | Y | Required. SemanticParameter data type. Valid values are Text, Date, DateTime, Number, Percentage, Boolean, Url, and Phone number. |
| SemanticParameter | Type | Type | StaticEnum | Y | Required. SemanticParameter type. Valid values are All, List, and Range. |
| SemanticParameter | Default Value | DefaultValue | String | Y | Required. Default value of the SemanticParameter. |
Use the SemanticParameterList entity to define a Semantic Parameter List and related properties, such as the ID of the list entity, the ID of the parameter that is referenced by the list, and the value of the parameter.
| Entity | Field Label | Developer Name | Data Type | Required? | Description |
|---|---|---|---|---|---|
| SemanticParameterList | ID | ID | ID | Y | Required. ID of the SemanticParameterList entity. |
| SemanticParameterList | Semantic Parameter | SemanticParameter | Lookup(SemanticParameter) | Y | Required. ID of the SemanticParameter that is referenced in the SemanticParameterList entity. |
| SemanticParameterList | Value | Value | String | Y | Required. Value of the SemanticParameter in the SemanticParameterList entity. |
Use the SemanticParameterRange entity to define a Semantic Parameter Range and related properties, such as the ID of the range entity, the ID of the parameter that is referenced by the range, the minimum and maximum values of the range, and a time scale for the range.
| Entity | Field Label | Developer Name | Type | Required? | Description |
|---|---|---|---|---|---|
| SemanticParameterRange | ID | ID | ID | Y | Required. ID of the SemanticDataParameter entity. |
| SemanticParameterRange | Semantic Parameter | SemanticParameter | Lookup(SemanticParameter) | Y | Required. ID of the SemanticParameter that is referenced in the SemanticParameterRange entity. |
| SemanticParameterRange | Min Value | MinValue | String | N | Minimum value of the SemanticParameterRange. |
| SemanticParameterRange | Max Value | MaxValue | String | N | Maximum value of the SemanticParameterRange. |
| SemanticParameterRange | Step Size | StepSize | String | N | Value that determines the time scale of the SemanticParameterRange by step size. A step size can be any time period, such as 30 days or 1 year. |
Use the SemanticLogicalView entity to define a Semantic Logical View and related properties, including the ID of the logical view, the ID of the Semantic Definition used in the logical view, and filter representations to use with the logical view.
| Entity | Field Label | Developer Name | Type | Required? | Description |
|---|---|---|---|---|---|
| SemanticLogicalView | ID | ID | ID | Y | Required. ID of the SemanticLogicalView entity. |
| SemanticLogicalView | Semantic Definition | SemanticDefinition | Lookup(SemanticDefinition) | Y | Required. ID of the SemanticDefinition entity used in the SemanticLogicalView entity. |
| SemanticLogicalView | Filters | Filters | Text | Y | Required. Textual representation of the filters applied to the SemanticLogicalView. |
| SemanticLogicalView | FilterLogic | FilterLogic | Text | Y | Required. Textual representation of the filter logic applied to the SemanticLogicalView. |
Use the SemanticModelLock entity to lock a Semantic Model. Properties include the ID of the lock entity, the ID of the Semantic Mode that is being locked, the ID of the user who owns the lock, and the time when the lock was imposed and will be released.
| Entity | Field Label | Developer Name | Type | Required? | Description |
|---|---|---|---|---|---|
| SemanticModelLock | ID | ID | ID | Y | Required. ID of the SemanticModelLock entity. |
| SemanticModelLock | Semantic Model Id | SemanticModelId | ID | Y | Required. ID of the semantic model that is locked by the SemanticModelLock entity. |
| SemanticModelLock | Lock Id | LockId | TEXT | Y | Required. Identifier of the user that owns the lock imposed on a semantic model by the SemanticModelLock entity. |
| SemanticModelLock | End Time | EndTime | Date | Y | Required. Time when the lock imposed on a semantic model by the SemanticModelLock entity is automatically released. |