Skip to main content

ID Dispensers

ID dispensers generate a unique, stable identifier for each row in a data product. You configure rules that build IDs from extracted field values with an optional prefix, fallback chains for when the primary field is empty, and resolution maps that normalize variant values before ID generation. Unlike random UUIDs, dispenser-generated IDs are derived from your actual data, making them human-readable and usable as primary keys in downstream databases.

ID rule configuration

ParameterTypeDescription
Source fieldfieldThe primary field to derive the ID from. When empty, generates a prefix-less sequential ID.
Fallback chainfield[]Ordered list of alternative fields tried when the source field is empty on a row.
Resolution mapmapKey-value lookup that normalizes field values before ID generation (e.g., "ACME Corp" → "ACME").

How generation works

ID rules are persisted before generating IDs. Navigate to a data product detail page and use Apply ID Rules to generate or Regenerate IDs to refresh. The generation process evaluates each row against the configured rules: it reads the source field value, applies the resolution map if one exists, prepends the prefix, and writes the resulting ID. If the source field is empty, the dispenser walks the fallback chain in order until it finds a non-empty value. If all fields in the chain are empty, a prefix-less sequential ID is assigned so no row is left without an identifier.

  1. Open the data product detail page and locate the ID rules panel.
  2. Choose a high-cardinality source field (invoice number, contract reference).
  3. Add 1-2 fallback fields (e.g., document name, then upload date) so every row gets a value.
  4. Optionally define a resolution map to collapse variant spellings before ID generation.
  5. Click Apply ID Rules to generate, or Regenerate IDs later to refresh.
Example ID rule set (configured on the data product detail page)
{
  "source_field": "invoice_number",
  "prefix": "INV",
  "fallback_chain": ["document_name", "upload_date"],
  "resolution_map": {
    "ACME Corp": "ACME",
    "ACME Corporation": "ACME",
    "Acme": "ACME"
  }
}
// A row with invoice_number "2026-042" receives the ID "INV-2026-042".
// A row with no invoice_number falls back to its document name.

Choosing source fields and resolution maps

Choose source fields with high uniqueness: contract numbers, invoice IDs, and purchase order references work well because they are unique per document, while generic fields like "status" produce collisions. Resolution maps normalize field values before they become part of the ID: for example, collapsing "ACME Corp", "ACME Corporation", and "Acme" into a single canonical value "ACME" prevents duplicate IDs for rows that refer to the same real-world entity under different names.

The deterministic nature of generation means the same rules and the same data always produce the same IDs, regardless of when or how many times you regenerate. This is critical for maintaining referential integrity with downstream systems that store these IDs as foreign keys. Regeneration is also non-destructive: only the ID column is updated, and all other data product values remain unchanged.

ID generation is deterministic — running Regenerate IDs with the same rules and data always produces the same output. This makes ID dispensers safe to re-run without breaking downstream references.

Frequently asked questions

How do ID dispensers handle missing field values?+
When the source field is empty, the dispenser tries each field in the fallback chain in order. If all are empty, it generates a prefix-less sequential ID.
What is a resolution map?+
A resolution map is a key-value lookup that normalizes field values before ID generation. For example, it can collapse "ACME Corp" and "ACME Corporation" into "ACME" to prevent duplicate IDs for the same entity.
Can I regenerate IDs without losing data?+
Yes. Regenerating IDs only updates the ID column — all other data product values remain unchanged. The operation is deterministic, so the same rules and data always produce the same IDs.
What makes a good source field for ID generation?+
Choose fields with high cardinality — values that are unique or nearly unique per document. Invoice numbers, contract references, and purchase order IDs work well. Avoid generic fields like status or document type, which produce collisions. Configure a fallback chain with 1-2 alternative fields so the dispenser always has a value to work with.
Where do I configure ID dispenser rules?+
On the data product detail page. Set the source field, optional prefix, fallback chain, and resolution map there, then click Apply ID Rules to generate identifiers or Regenerate IDs to refresh them after the underlying data changes.

Related

Dataset Templates
Assemblies
Sharing & Export