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 ModelDataset records, each linking a logical dataset name to a source URN. The source is normally a dataset URN, but may be a query URN when the semantic model uses an inline SQL query with no backing table.
  • relationships — optional array of SemanticModelRelationship records describing join paths between the logical datasets in this model (from-table, to-table, join columns, optional name, optional cardinality reusing ERModelRelationshipCardinality, and AI context).
  • aiContext — optional hints for AI/LLM consumers: synonyms, natural-language instructions, few-shot examples, and custom instructions.

Inline Query Sources​

Some semantic-layer platforms allow a metric view or model to source from an inline SQL query rather than a persistent table (e.g. Databricks metric views with source: <SELECT ...>). DataHub represents these using the query entity:

  1. Emit the query entity. The ingestion source constructs a query URN whose id is a content-hash of the normalized SQL
  2. Point ModelDataset.source at the query URN. No other change is needed on the SemanticModel side; the SourcedBy edge is emitted the same way for both target kinds.

Fields and Dimensions​

Each ModelDataset entry can carry a list of SemanticField records that describe the columns exposed by the semantic model:

  • schemaField — required inline SchemaField that gives this field its identity and governance surface. The fieldPath inside it becomes the field-path component of the urn:li:schemaField:(<semanticModelUrn>,<fieldPath>) URN used for column-level lineage edges.
  • 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.
  • dimension — optional Dimension record; populated only when type == DIMENSION. Currently exposes isTime: boolean to flag time dimensions used for date-range filtering.
  • aiContext — AI hints specific to this field.

Lineage​

Semantic models support both table-level and column-level lineage via the upstreamLineage aspect, the same aspect used by datasets.

Table-level upstream lineage — populate upstreamLineage.upstreams with one Upstream entry per source table or query.

Column-level lineage — populate upstreamLineage.fineGrainedLineages with FineGrainedLineage records.

Metrics as downstream nodes — metrics that declare metricInfo.semanticModel pointing at this entity automatically appear as downstream nodes in the lineage explorer.

Governance​

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

Relationships with Other Entities​

RelationshipDirectionTarget entityAspect / edge name
SourcedByoutbounddataset, querysemanticModelInfo
UpstreamOfoutbounddataset, queryupstreamLineage
ModeledByinboundmetricmetricInfo

The SourcedBy edges are derived from the datasets[].source URN fields in semanticModelInfo. The upstreamLineage aspect provides the full lineage graph traversal path (table-level and column-level), so both upstream sources and downstream metrics appear in the lineage explorer.

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. 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.

Ingestion sources that need to store per-field vendor blobs should hoist the data into entity-level structuredProperties keyed by field name.

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
namestring✓Display 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...
aiContextAiContextAI-specific context for improved disambiguation and retrieval.
datasetsModelDataset[]✓The logical datasets that this semantic model exposes.
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
lastModifiedAuditStamp✓Audit 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
auditStampAuditStamp✓Audit 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
removedboolean✓Whether 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
deprecatedboolean✓Whether the entity is deprecated.Searchable
decommissionTimelongThe time user plan to decommission this entity.
notestring✓Additional information about the entity deprecation plan, such as the wiki, doc, RB.
actorstring✓The 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
platformstring✓Data 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

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

  • SourcedBy

    • Dataset via semanticModelInfo.datasets.source
    • Query via semanticModelInfo.datasets.source

  • SchemaFieldTaggedWith

    • Tag via semanticModelInfo.datasets.fields.schemaField.globalTags

  • TaggedWith

    • Tag via semanticModelInfo.datasets.fields.schemaField.globalTags.tags
    • Tag via globalTags.tags

  • SchemaFieldWithGlossaryTerm

    • GlossaryTerm via semanticModelInfo.datasets.fields.schemaField.glossaryTerms

  • TermedWith

    • GlossaryTerm via semanticModelInfo.datasets.fields.schemaField.glossaryTerms.terms.urn
    • GlossaryTerm via glossaryTerms.terms.urn

  • 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

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.