Semantic IDs - Entity Enricher Documentation

Semantic IDs

Enrich the same kind of entity again and again and you keep re-discovering the same real-world things — the same company, the same drug side-effect, the same person — described with slightly different words each time. A semantic ID is a stable, organization-scoped identifier Entity Enricher assigns to an object from its key fields, so those near-duplicates collapse to one identity you can group, deduplicate, and join on.

The problem: same thing, different words

An object’s identity is built from its key fields — and there can be one or several. Two examples:

One key

A side-effect keyed by `name`

It shows up as Headache, Céphalée, and Cephalalgia across runs and languages. One key field, three spellings, one real concept.

Two keys

A company keyed by `name` + `country`

Acme Inc. · United States and Acme Incorporated · United States are the same company — while Acme Inc. · Germany is a different one. The second key disambiguates; that’s why an object can carry more than one.

Plain string matching fails on all of these; a human knows which are the same. Semantic IDs encode that judgement automatically.

What a semantic ID is

•A single string property on an object (named id by default), holding an opaque, stable identifier.
•Stable & organization-scoped — the same real-world thing resolves to the same ID across enrichments, batches, and time, within your organization only.
•Assigned automatically, never by the LLM — it’s computed in a post-enrichment pass, so the model can’t hallucinate it. It’s a pass-through field (input values flow through untouched): always a string, never a key, never preserve, never multilingual, at most one per object.
•Allowed on any object — the whole entity (root), a 1-1 nested object (e.g. a manufacturer), or each item in an array (e.g. each side_effect).

How it works

After the model returns its result, Entity Enricher resolves each semantic ID in six steps — cheapest first. The four steps before the embedding are pure text comparison, so an identity settled there costs nothing at all:

Compose the identity text

Join the key fields that identify the object itself into a single string, in your primary language. A nested object that is an entity in its own right is left out: its key names it, not the thing referring to it, and every sibling referring to the same entity would carry that same value — two missions sharing a launch site would read almost identically and risk collapsing into one. Nested objects that merely group fields still contribute; so does a related entity’s key if you add it yourself. Items inside arrays are never pulled in: each array item owns its own identity. The schema editor’s identity participants list shows exactly which values compose the text and lets you reorder or change them — schemas that pick the same participants in the same order mint identical IDs. The text is normalized (lowercased, parentheticals dropped, whitespace collapsed) to shrink trivial differences. If every one of those key fields comes back empty, there is nothing to identify the object by and no ID can be assigned — so the object is removed rather than kept as an anonymous one nothing can be grouped, joined or deduplicated on: a nested object becomes null in its parent, and an item inside a list is dropped from the list. The enriched entity itself is never removed; it simply has no ID.

Look for an exact match

If that exact normalized text has been seen before in your organization, its existing ID is reused immediately — no model call, no cost.

Match on a code, if there is one

When one of the identity keys is a code — a pattern-constrained field, or one whose examples look like identifiers — it is composed first and compared on its own. An exact code match settles the identity immediately, whatever the surrounding wording, so LC-39A unifies every way the rest of the text was written. Just as importantly it works the other way round: a different code vetoes a merge the embedding step would otherwise have accepted, because two things with different identifiers are two things however alike they read.

Match on the same words in any order

Before spending an embedding, the words themselves are compared as a set: if one text’s words are contained in the other’s, they are the same identity written at different lengths — “Boeing” and “The Boeing Company”. This catches exactly the verbosity differences that embeddings measure as far apart, and it costs nothing: like the exact-text step, a hit here means no embedding call and no charge.

Embed & compare

Otherwise the text is embedded and compared, by meaning, against existing concepts of the same concept type (the entity type name by default — overridable in the editor so differently-named schemas share one concept space) using vector similarity — so “Acme Inc.” and“Acme Incorporated” land next to each other.

Reuse or mint

If the closest match scores above the similarity threshold (default 0.92, tunable per property), that concept’s ID is reused. Otherwise a brand-new ID is minted and stored for next time. One exception overrides a high score: when the two texts are the same words counted differently — “second stage” and“third stage” — they are treated as different things, because counting is exactly what tells them apart. The same number written two ways (2 andII) still matches.

Threshold trade-off: a higher threshold is stricter (fewer accidental merges); a lower one is looser (more aggressive deduplication). Tune it per property when the default 0.92 over- or under-merges.

Input IDs vs. generated IDs

Whether an ID is generated depends on whether one is already present in the input for that object. This is what lets you round-trip: enrich once to obtain IDs, then pass a known ID back on later runs to attach new facts to the same identity — cheaper and unambiguous.

ID already in the input → kept (lookup)

If the object you send already carries a semantic ID, it’s treated as a lookup: the ID is kept verbatim, the record is linked to that existing concept, and there is no embedding — no cost, no match-or-mint. You’re telling the platform “this object is already identified in our database.”

No ID in the input → generated

If the object has no semantic ID, the platform generates one with the steps above. That ID becomes the object’s stable identifier in your organization’s database from then on.

A present-but-unrecognizable value (not a real concept ID) is ignored, and an ID is generated instead.

How to enable it

Pick an embedding model (once per organization)

An owner picks an embedding-capable model under Settings → Organization → Defaults as the organization’s default embedding model (a plan-gated setting; see Models & Pricing for which models can embed). Stored vectors aren’t comparable across models, so once concepts exist the setting itself can only be cleared — switching runs as a migration from the Semantic IDs page, which re-embeds every concept and keeps their IDs. Without a model, semantic IDs are simply skipped.

Add semantic IDs to the schema

Two ways, both in the Workflow Editor:

Automatically at generation — tick “Generate semantic IDs for types”; every object with a key (its own, or one on a 1-1 nested object) gets one, including the root entity.
Manually — use the “+ Add semantic ID” control on any object or the entity footer.

Resolution costs a small amount of embedding usage per enrichment (metered like any model call). The exact-match cache makes repeats free, and input-provided IDs cost nothing.

Where the IDs show up & what to do with them

Resolved IDs appear in the enrichment output JSON (the id field on each object), in the record detail’s semantic concepts, and all together on the Semantic IDs page, where the vocabulary they form is browsed and curated. Use them to:

•Deduplicate rows across batches and over time.
•Build a stable join key for your data warehouse or CRM.
•Reconcile the same entity seen on different days or in different languages.

Complements multi-model fusion

Fusion reconciles disagreements across models within a single run; semantic IDs reconcile the same entity across runs and time. The two work together.

Core Concepts

Search & merge keys, which semantic IDs build on

Multilingual Enrichment

Collapse cross-language spellings to one identity

Multi-Model Fusion

Reconcile across models within one run

Workflow Editor

Add semantic IDs to any object

The Semantic IDs page

Browse, curate and deduplicate the resulting vocabulary