Entity reference

On this page

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. In the Aurelia Utilities sample they are 1,129 and 245: most buckets hold a single record and are not a duplicate signal at all.

indexDuplicateCounts reports 84 tax-identifier groups, 76 email groups, 85 name-and-postcode groups, and 0 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`	Last reported execution time for that source

Each destination entry reports its resource and optional transformation. 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`: deliver the current full set; `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.

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.

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.