On this page

An entity connects a table with optional search, duplicate-resolution, resource, and scheduling configuration.

Entity types

TypeCapability
NONEManaged records without search or duplicate resolution
SEARCHManaged records and record search
DUPLICATESSearch and duplicate candidates for stewardship
AUTO_DUPLICATESDuplicate resolution with configured automatic stewardship

Entity states

StateMeaningResponse
EMPTYNo completed data-processing cycleRun a controlled synchronization when configuration is ready
WORKINGEntity work is activeFollow its task
READYAvailable for configured operationsVerify the intended search or review result
INCONSISTENTConfiguration and processed state need reconciliationValidate dependencies and synchronize with the appropriate masks
ERRORValidation or processing failedInspect the related task and correct the cause

Configuration and control fields

Entity responses include identifiers for the table, dataset, and applicable pipeline, indexer, classifier, merger, steward, source, and sink resources. They also expose:

FieldPurpose
enabledWhether the entity can serve configured operations
lockedWhether entity-changing work is blocked
automaticWhether configured automatic synchronization is active
statusCurrent lifecycle state
searches, duplicates, stewardingCapabilities derived from entity type
stewardCronType, stewardCronAutomatic-steward scheduling settings when configured
viewThe data view a record of this entity is presented with
validationValidation findings and their count, or nulls when the entity is valid
dependencyWhat the entity uses and what uses it, with counts

Use the explicit state endpoints to change enabled, locked, or automatic flags; see Golden API endpoints.

Reported figures

An entity response carries its own current counts. They are read-only.

FieldMeaning
recordCountRecords in the entity’s table
bucketCountBuckets the indexer produced, duplicated or not
duplicateBucketCountBuckets holding a possible duplicate
indexDuplicateCountsDuplicate groups per indexer mapping
indexLabelsEach mapping’s description, for display

bucketCount and duplicateBucketCount answer different questions. Many buckets contain a single record and are not duplicate signals. Read the entity response for the current counts; the sample’s 350 customer duplicate groups are logical clusters and need not equal either bucket count.

indexDuplicateCounts reports 84 tax-identifier groups, 76 email groups, 106 name-and-postcode groups, and 84 exact-phone groups in the initial sample.

Data-scope fields

FieldMeaning
scopeColumnThe column that partitions this entity for row-level access, or null
scopeIndexStateNONE, BUILDING, VALID, or FAILED
aggregateScopeThe scope the entity’s aggregates are computed over

See Restrict access with data scopes.

Sources and destinations

Each source entry reports:

FieldPurpose
resourceSource resource identifier
transformationOptional transformation applied to its records
cronType, cronSource-specific schedule preset and expression
incrementalWhether the source uses incremental loading
lastExecutionStored incremental watermark for that source

Each destination entry reports its resource, optional transformation, and audit, which includes the record’s audit history in the delivered payload (default true). Use source-level scheduling fields to answer when an entity reads that source; task scheduling is a separate product surface.

Read these statistics from GET /api/entities/{entity}. Counts describe volume; they do not establish that a classification or decision is correct.

Synchronization

PUT /api/entities/synchronize accepts:

FieldPurpose
idEntity identifier
loadMaskSelect source-load work
loadFrom, loadToOptional ISO 8601 load-time bounds
indexClassificationMaskSelect indexing and classification work
sinkMaskSelect destination work

Choose values per phase; a shared schema enum does not make each value valid in every field:

FieldAccepted values and behavior
loadMaskFULL: read the full source; INCREMENTAL: use the incremental loading window; CUSTOM: use supplied time bounds; NONE: skip loading
indexClassificationMaskFULL: rebuild indexing and classification for a duplicate-capable entity; CHANGES: reconcile changed configuration; DIRTY: classify pending groups without reindexing; NONE: skip this phase
sinkMaskFULL: rebuild every destination’s mirror — a clear event, then every live record; NONE: skip delivery

CUSTOM loading requires at least loadFrom or loadTo. CHANGES can be a no-op when the configuration is already applied; DIRTY specifically requests pending classification. For a SEARCH entity, use CHANGES to build or update search without duplicate classification.

loadOperation is UPSERT by default. DELETE removes the records identified by the source documents; it is ignored when loading is NONE. A full load is not an instruction to delete every target record absent from the source.

A load applies the entity’s pipeline and the upsert’s identity rules to each row, and reports skipped and refused rows by category. An INCREMENTAL source reads from its stored watermark minus an overlap (60 seconds by default), up to the whole second in which the run starts. Its first run after the upgrade reads all rows. A row lost to a transient failure holds the watermark back; a row refused for a data reason advances it, with a message identifying where a custom reread can begin. Its source rows are full snapshots: a JDBC NULL empties the stored value. See Entity synchronization for each case. A sinkMask: FULL delivery is described in Full re-delivery rebuilds the mirror.

All three masks and id are required. Synchronization requires ADMIN. The response contains run when work was queued; an already up-to-date entity may return no run. Follow run.id to a terminal state and then verify the entity and records. See the complete search tutorial.

Disabled entities and indexing failures

Disabling an entity turns off its source and steward schedules and requests cancellation of runs already in progress. Jobs that start while it is disabled skip its work. Record writes, group decisions, load deletes and table clears are refused with 423; asynchronous indexing waits until the entity is enabled. Enabling an automatic entity re-arms its schedules.

GET /api/golden/{entity}/records/{recordId}/index-status reports PENDING before FAILED, and a failed entry includes the latest error. An ADMIN can read GET /api/entities/{entity}/index-failures?page&size, retry one with POST /api/entities/{entity}/index-failures/{recordId}/retry, or retry all with POST /api/entities/{entity}/index-failures/retry. The entity read also reports failedIndexCount to an ADMIN. A retry on a disabled entity answers 423. Failed entries are removed after a later successful index, record deletion, or entity clear or deletion.

Clear an entity’s groups

PUT /api/entities/{entity}/clear removes the entity’s candidate groups, current and historical, with their classification. It touches no record, no history and no queued delivery, and it publishes nothing to the entity’s destinations. It requires ADMIN, and a disabled entity answers 423.

It is not a table clear. PUT /api/tables/clear/{name} also empties the records and tells each destination to empty its mirror (see Clear events), and it physically deletes the table’s history and audit events, which cannot be undone; see Clear or delete.

Exchange entity definitions

Administrators can export selected entities with POST /api/entities/export, export all with GET /api/entities/export/all, and import a previously returned exchange with POST /api/entities/import. Promote dependencies before the entity and validate environment-specific resources before enabling work. See Manage resources.

Golden 3.4.0 · Published 2026-10-29