Skip to main content

Semantic Model

The semantic model entity represents a logical data model that groups datasets and defines the dimensional context (fields, dimensions, relationships) used by metrics. It serves as the bridge between raw datasets and the business metrics calculated over them.

Identity

Semantic models are identified by three fields:

  • platform — the DataPlatform URN that owns this semantic model (e.g. urn:li:dataPlatform:dbt, urn:li:dataPlatform:snowflake). Searchable as a URN field with autocomplete and a "Platform" filter pill.
  • path — the namespace path that scopes this semantic model within its platform, preventing name collisions when two teams define models with the same id on the same platform.
  • id — the model name within that platform and path (e.g. orders_model, customer_360).

An example URN: urn:li:semanticModel:(urn:li:dataPlatform:dbt,analytics,orders_model).

Important Capabilities

Semantic Model Info

Core metadata is stored in the semanticModelInfo aspect:

  • name — human-readable display name; used for full-text search and autocomplete.
  • description — free-text description of what the model represents.
  • created -- AuditStamp (time + actor) capturing when the semantic model was created and by whom. Search-indexed as createdAt (DATETIME).
  • lastModified -- AuditStamp capturing the most recent modification. Search-indexed as lastModifiedAt (DATETIME).
  • nativeDefinition — optional verbatim source definition (e.g. the Snowflake CREATE SEMANTIC VIEW DDL, the dbt semantic_model YAML, or the Databricks CREATE METRIC VIEW DDL). Preserved as-is for round-tripping and debugging; not parsed by DataHub.
  • datasets — array of dataset URNs: the logical datasets that this semantic model exposes. Each is a full dataset entity carrying the Semantic Model Dataset subtype. See Logical Datasets as Dataset Entities below.
  • relationships — optional array of SemanticModelRelationship records describing join paths between the logical datasets in this model (from-alias, to-alias, join columns, optional name, optional cardinality reusing ERModelRelationshipCardinality, and optional per-relationship AI context). The from/to aliases refer to each logical dataset's semanticModelProperties.alias.

AI Context

Optional AI/LLM hints for the semantic model itself are stored in the first-class aiContext aspect (synonyms, natural-language instructions, few-shot examples, and custom instructions). Per-relationship AI context on SemanticModelRelationship remains inlined.

Logical Datasets as Dataset Entities

Each logical dataset exposed by a semantic model is its own dataset entity — with its own URN, its own schemaMetadata, and its own governance surface. Independent identity is what makes independent search, governance, and lineage possible without reimplementing them.

  • URN pattern: use the source platform (already registered — e.g. dbt, snowflake, databricks, cube, atscale) and encode <sm_path>.<sm_id>.<view_name> in the dataset name so logical datasets stay unique across semantic models. Example: urn:li:dataset:(urn:li:dataPlatform:dbt,analytics.orders_model.orders_ds,PROD).
  • subTypes — carries Semantic Model Dataset (DatasetSubTypes.SEMANTIC_MODEL_DATASET in the Python ingestion SDK), a dedicated subtype distinct from Semantic View (DatasetSubTypes.SEMANTIC_VIEW). The latter remains reserved for a platform's native semantic-view object (e.g. a Snowflake CREATE SEMANTIC VIEW) ingested as its own top-level dataset.
  • semanticModelProperties aspect — the semantic-model-specific facet on top of the standard Dataset aspects:
    • alias — the logical alias used to reference this dataset within its owning semantic model's SemanticModelRelationship join paths.
    • semanticModel — back-reference to the owning semanticModel entity (IsPartOf relationship), enabling "which semantic model does this view belong to" search facets.
  • viewProperties aspect (standard, already registered on dataset) — holds the native SQL (viewLogic) when the logical dataset is backed by a view or inline query, exactly as it does for any other view-backed dataset.
  • schemaMetadata aspect (standard) — the field projection: which columns this logical dataset exposes, with their structural types. Field-level semantic metadata (expression, aggregation, dimension/measure/filter classification) is layered on top via semanticFieldAnnotation — see Fields and Dimensions below.
  • upstreamLineage aspect (standard) — physical lineage back to the table(s) or query this logical dataset derives from; see Lineage below.

Fields and Dimensions

Column identity, structural typing, and governance (tags, glossary terms, description) all live on the standard schemaField entity — the same entity every other Dataset's columns use, which already has column-level lineage, search indexing, and an audit trail. Semantic-specific metadata is layered on top via the semanticFieldAnnotation aspect, attached to the schemaField entity for that column:

  • type — required SemanticFieldType enum identifying the kind of field: DIMENSION (grouping / filtering attribute), MEASURE (aggregatable numeric value), FILTER (named boolean predicate), or OTHER (forward-compat escape hatch for source constructs that do not map cleanly to the three named kinds).
  • expression — the underlying SQL expression(s) in one or more dialects.
  • aggregationFunction — optional aggregation function name (e.g. SUM, COUNT_DISTINCT, AVG) applied when type == MEASURE.
  • dimension — optional Dimension record; populated only when type == DIMENSION. Currently exposes isTime: boolean to flag time dimensions used for date-range filtering.

Field-level AI/LLM hints live on the schemaField entity's first-class aiContext aspect.

Inline Query Sources

Some semantic-layer platforms allow a logical dataset to source from an inline SQL query rather than a persistent table (e.g. Databricks metric views with source: <SELECT ...>). Since the logical dataset is a standard dataset entity, this uses the same machinery any other view-backed dataset with unresolvable-to-a-single-table SQL uses: the raw SQL lives in viewProperties.viewLogic, and upstreamLineage.upstreams carries one Upstream entry per physical table the SQL references (extracted via SQL parsing), each optionally annotated with the causal query entity via Upstream.query. No semantic-model-specific modeling is required for this case.

Lineage

The canonical lineage chain for a semantic-model-backed metric is:

Metric → SemanticModel → Logical Dataset (Semantic Model Dataset) → Physical Dataset

Metric → semantic model — metrics that declare metricInfo.semanticModel pointing at this entity appear as downstream nodes via the ModeledBy lineage edge. Do not also populate metricUpstreams for these metrics; that aspect is reserved for metrics without a semantic model.

Semantic model → logical dataset — the Contains relationship, derived from semanticModelInfo.datasets, is a lineage edge (isLineage: true). Each logical dataset is an upstream of the semantic model.

Logical dataset → physical source — standard upstreamLineage aspect on the logical dataset (the same aspect every dataset already uses), populated with one Upstream entry per physical source table or query.

Column-level lineage — standard upstreamLineage.fineGrainedLineages on the logical dataset, using schemaField URNs on both sides — no semantic-model-specific column lineage infrastructure.

Governance

The semantic model entity reuses these standard governance aspects: ownership, domains, globalTags, glossaryTerms, institutionalMemory, structuredProperties, status, deprecation, dataPlatformInstance, subTypes, documentation, browsePathsV2, applications, aiContext.

Its logical dataset entities (and their schemaFields) inherit the full standard Dataset/SchemaField governance surface automatically — tags, glossary terms, ownership, descriptions, structured properties — with no semantic-model-specific reimplementation.

Relationships with Other Entities

RelationshipDirectionTarget entityAspect / edge nameLineage?
ContainsoutbounddatasetsemanticModelInfoyes
IsPartOfinbounddatasetsemanticModelPropertiesno
ModeledByinboundmetricmetricInfoyes

The Contains edges are derived from the datasets URN array in semanticModelInfo and are lineage edges; each target logical dataset also carries the reverse IsPartOf edge via its own semanticModelProperties aspect. Each logical dataset's own upstreamLineage aspect provides the physical lineage graph traversal path (table-level and column-level) from there onward.

Notable Exceptions

SemanticModelRelationship vs common Relationship

The join-path record is named SemanticModelRelationship (rather than Relationship) to avoid a name collision with DataHub's com.linkedin.common.Relationship model.

Extensibility via structuredProperties

Entity-level extensibility uses the structuredProperties aspect, which is already registered for the semanticModel entity (and the dataset/schemaField entities that back its logical datasets and fields). Structured properties support typed values, governance controls, search facets, and PATCH semantics — they are the recommended mechanism for any platform-specific metadata that does not warrant a first-class PDL field.

Technical Reference Guide

The sections above provide an overview of how to use this entity. The following sections provide detailed technical information about how metadata is stored and represented in DataHub.

Aspects are the individual pieces of metadata that can be attached to an entity. Each aspect contains specific information (like ownership, tags, or properties) and is stored as a separate record, allowing for flexible and incremental metadata updates.

Relationships show how this entity connects to other entities in the metadata graph. These connections are derived from the fields within each aspect and form the foundation of DataHub's knowledge graph.

Reading the Field Tables

Each aspect's field table includes an Annotations column that provides additional metadata about how fields are used:

  • ⚠️ Deprecated: This field is deprecated and may be removed in a future version. Check the description for the recommended alternative
  • Searchable: This field is indexed and can be searched in DataHub's search interface
  • Searchable (fieldname): When the field name in parentheses is shown, it indicates the field is indexed under a different name in the search index. For example, dashboardTool is indexed as tool
  • → RelationshipName: This field creates a relationship to another entity. The arrow indicates this field contains a reference (URN) to another entity, and the name indicates the type of relationship (e.g., → Contains, → OwnedBy)

Fields with complex types (like Edge, AuditStamp) link to their definitions in the Common Types section below.

Aspects

semanticModelInfo

Core information about a SemanticModel entity.

FieldTypeRequiredDescriptionAnnotations
externalUrlstringURL where the reference existSearchable
namestringDisplay name of the semantic model.Searchable
descriptionstringHuman-readable description of the semantic model.Searchable
createdAuditStampAudit stamp capturing when this semantic model was created and by whom (as reported by the source...Searchable
lastModifiedAuditStampAudit stamp capturing when this semantic model was last modified and by whom. Equals created wh...Searchable
nativeDefinitionstringThe raw, native definition of this semantic model as authored on the source platform (e.g. the Sn...
datasetsstring[]The logical datasets that this semantic model exposes. Each is a dataset entity in its own righ...Searchable, → Contains
relationshipsSemanticModelRelationship[]Join relationships between the datasets of this semantic model.

upstreamLineage

Upstream lineage of a dataset

FieldTypeRequiredDescriptionAnnotations
upstreamsUpstream[]List of upstream dataset lineage information
fineGrainedLineagesFineGrainedLineage[]List of fine-grained lineage information, including field-level lineage→ DownstreamOf

ownership

Ownership information of an entity.

FieldTypeRequiredDescriptionAnnotations
ownersOwner[]List of owners of the entity.
ownerTypesmapOwnership type to Owners map, populated via mutation hook.Searchable
lastModifiedAuditStampAudit stamp containing who last modified the record and when. A value of 0 in the time field indi...

domains

Links from an Asset to its Domains

FieldTypeRequiredDescriptionAnnotations
domainsstring[]The Domains attached to an AssetSearchable, → AssociatedWith
domainAssociationsDomainAssociation[]Additional per-domain association metadata such as attribution and propagation source. A superset...

globalTags

Tag aspect used for applying tags to an entity

FieldTypeRequiredDescriptionAnnotations
tagsTagAssociation[]Tags associated with a given entitySearchable, → TaggedWith

glossaryTerms

Related business terms information

FieldTypeRequiredDescriptionAnnotations
termsGlossaryTermAssociation[]The related business terms
auditStampAuditStampAudit stamp containing who reported the related business term

institutionalMemory

Institutional memory of an entity. This is a way to link to relevant documentation and provide description of the documentation. Institutional or tribal knowledge is very important for users to leverage the entity.

FieldTypeRequiredDescriptionAnnotations
elementsInstitutionalMemoryMetadata[]List of records that represent institutional memory of an entity. Each record consists of a link,...

structuredProperties

Properties about an entity governed by StructuredPropertyDefinition

FieldTypeRequiredDescriptionAnnotations
propertiesStructuredPropertyValueAssignment[]Custom property bag.

status

The lifecycle status metadata of an entity, e.g. dataset, metric, feature, etc. This aspect is used to represent soft deletes conventionally.

FieldTypeRequiredDescriptionAnnotations
removedbooleanWhether the entity has been removed (soft-deleted). Kept for backward compatibility. When lifecyc...Searchable
lifecycleStagestringThe lifecycle stage of the entity, referencing a lifecycleStageType entity. When null, the entity...Searchable
lifecycleLastUpdatedAuditStampAttribution for the lifecycle stage transition ��� who moved the entity into its current stage an...

deprecation

Deprecation status of an entity

FieldTypeRequiredDescriptionAnnotations
deprecatedbooleanWhether the entity is deprecated.Searchable
decommissionTimelongThe time user plan to decommission this entity.
notestringAdditional information about the entity deprecation plan, such as the wiki, doc, RB.
actorstringThe user URN which will be credited for modifying this deprecation content.
replacementstring

dataPlatformInstance

The specific instance of the data platform that this entity belongs to

FieldTypeRequiredDescriptionAnnotations
platformstringData PlatformSearchable
instancestringInstance of the data platform (e.g. db instance)Searchable (platformInstance)

subTypes

Sub Types. Use this aspect to specialize a generic Entity e.g. Making a Dataset also be a View or also be a LookerExplore

FieldTypeRequiredDescriptionAnnotations
typeNamesstring[]The names of the specific types.Searchable

documentation

Aspect used for storing all applicable documentations on assets. This aspect supports multiple documentations from different sources. There is an implicit assumption that there is only one documentation per source. For example, if there are two documentations from the same source, the latest one will overwrite the previous one. If there are two documentations from different sources, both will be stored. Future evolution considerations: The first entity that uses this aspect is Schema Field. We will expand this aspect to other entities eventually. The values of the documentation are not currently searchable. This will be changed once this aspect develops opinion on which documentation entry is the authoritative one. Ensuring that there is only one documentation per source is a business rule that is not enforced by the aspect yet. This will currently be enforced by the application that uses this aspect. We will eventually enforce this rule in the aspect using AspectMutators.

FieldTypeRequiredDescriptionAnnotations
documentationsDocumentationAssociation[]Documentations associated with this asset. We could be receiving docs from different sources

browsePathsV2

Shared aspect containing a Browse Path to be indexed for an entity.

FieldTypeRequiredDescriptionAnnotations
pathBrowsePathEntry[]A valid browse path for the entity. This field is provided by DataHub by default. This aspect is ...Searchable

applications

Links from an Asset to its Applications

FieldTypeRequiredDescriptionAnnotations
applicationsstring[]The Applications attached to an AssetSearchable, → AssociatedWith

aiContext

AI-specific context attached to a metric, semantic model, or schema field to improve disambiguation, retrieval, and generation quality (OSI ai_context shape).

FieldTypeRequiredDescriptionAnnotations
synonymsstring[]Alternative names or abbreviations by which this entity is known.
instructionsstringHuman-readable guidance for AI models on how to interpret this entity.
examplesstring[]Example values or usage patterns to ground AI reasoning.
customInstructionsstringAdditional free-form instructions for AI model customisation.

Common Types

These types are used across multiple aspects in this entity.

AuditStamp

Data captured on a resource/association/sub-resource level giving insight into when that resource/association/sub-resource moved into a particular lifecycle stage, and who acted to move it into that specific lifecycle stage.

Fields:

  • time (long): When did the resource/association/sub-resource move into the specific lifecyc...
  • actor (string): The entity (e.g. a member URN) which will be credited for moving the resource...
  • impersonator (string?): The entity (e.g. a service URN) which performs the change on behalf of the Ac...
  • message (string?): Additional context around how DataHub was informed of the particular change. ...

Relationships

Outgoing

These are the relationships stored in this entity's aspects

  • Contains

    • Dataset via semanticModelInfo.datasets
  • DownstreamOf

    • Dataset via upstreamLineage.upstreams.dataset
    • Dataset via upstreamLineage.fineGrainedLineages
    • SchemaField via upstreamLineage.fineGrainedLineages
  • OwnedBy

    • Corpuser via ownership.owners.owner
    • CorpGroup via ownership.owners.owner
  • ownershipType

    • OwnershipType via ownership.owners.typeUrn
  • AssociatedWith

    • Domain via domains.domains
    • Application via applications.applications
  • TaggedWith

    • Tag via globalTags.tags
  • TermedWith

    • GlossaryTerm via glossaryTerms.terms.urn

Incoming

These are the relationships stored in other entity's aspects

  • IsPartOf

    • Dataset via semanticModelProperties.semanticModel

Global Metadata Model

Global Graph

💡 Contributing to this documentation

This page is auto-generated from the underlying source code. To make changes, please edit the relevant source files in the metadata-models directory.

Tip: For quick typo fixes or documentation updates, you can click the ✏️ Edit icon directly in the GitHub UI to open a Pull Request. For larger changes and PR naming conventions, please refer to our Contributing Guide.