On this page
Entity reference
Look up Trazadera Golden entity types, states, public statistics, control flags, and synchronization request options.
An entity connects a table with optional search, duplicate-resolution, resource, and scheduling configuration.
Entity types
| Type | Capability |
|---|---|
NONE | Managed records without search or duplicate resolution |
SEARCH | Managed records and record search |
DUPLICATES | Search and duplicate candidates for stewardship |
AUTO_DUPLICATES | Duplicate resolution with configured automatic stewardship |
Entity states
| State | Meaning | Response |
|---|---|---|
EMPTY | No completed data-processing cycle | Run a controlled synchronization when configuration is ready |
WORKING | Entity work is active | Follow its task |
READY | Available for configured operations | Verify the intended search or review result |
INCONSISTENT | Configuration and processed state need reconciliation | Validate dependencies and synchronize with the appropriate masks |
ERROR | Validation or processing failed | Inspect 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:
| Field | Purpose |
|---|---|
enabled | Whether the entity can serve configured operations |
locked | Whether entity-changing work is blocked |
automatic | Whether configured automatic synchronization is active |
status | Current lifecycle state |
searches, duplicates, stewarding | Capabilities derived from entity type |
stewardCronType, stewardCron | Automatic-steward scheduling settings when configured |
view | The data view a record of this entity is presented with |
validation | Validation findings and their count, or nulls when the entity is valid |
dependency | What 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.
| Field | Meaning |
|---|---|
recordCount | Records in the entity’s table |
bucketCount | Buckets the indexer produced, duplicated or not |
duplicateBucketCount | Buckets holding a possible duplicate |
indexDuplicateCounts | Duplicate groups per indexer mapping |
indexLabels | Each 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
| Field | Meaning |
|---|---|
scopeColumn | The column that partitions this entity for row-level access, or null |
scopeIndexState | NONE, BUILDING, VALID, or FAILED |
aggregateScope | The scope the entity’s aggregates are computed over |
See Restrict access with data scopes.
Sources and destinations
Each source entry reports:
| Field | Purpose |
|---|---|
resource | Source resource identifier |
transformation | Optional transformation applied to its records |
cronType, cron | Source-specific schedule preset and expression |
incremental | Whether the source uses incremental loading |
lastExecution | Stored 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:
| Field | Purpose |
|---|---|
id | Entity identifier |
loadMask | Select source-load work |
loadFrom, loadTo | Optional ISO 8601 load-time bounds |
indexClassificationMask | Select indexing and classification work |
sinkMask | Select destination work |
Choose values per phase; a shared schema enum does not make each value valid in every field:
| Field | Accepted values and behavior |
|---|---|
loadMask | FULL: read the full source; INCREMENTAL: use the incremental loading window; CUSTOM: use supplied time bounds; NONE: skip loading |
indexClassificationMask | FULL: rebuild indexing and classification for a duplicate-capable entity; CHANGES: reconcile changed configuration; DIRTY: classify pending groups without reindexing; NONE: skip this phase |
sinkMask | FULL: 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.