Skip to main content

Run a Domain

Run entity resolution for the vendors, customers or materials domain: read every source read-only, resolve golden records, and replace the stored records.

POST /v1/master-records/{domain}/run reads every configured source of the domain read-only, resolves the rows into golden records, and replaces the domain's stored records in one transaction. The call is synchronous and returns 201 with the run id and its statistics. Accept and split decisions are applied. A run replaces the domain whole: the workspace holds only the latest run of a domain, and there are no partial runs.

A source that returns more rows than the configured cap fails the run instead of resolving a partial master. The cap is 200000 rows per source by default. The resolution links only rows of different sources, so two rows of one source never merge. Run the domain again after the source data changes; the stored records do not follow the source systems by themselves.

POST/v1/master-records/{domain}/run

Path parameters

domain*stringvendors, customers or materials. An unknown domain is a 404.

Response fields

run_iduuidThe run.
stats.source_rowsintegerRows read from all sources.
stats.recordsintegerGolden records, single-source ones included.
stats.multi_sourceintegerRecords with two or more members.
stats.auto_merged / to_reviewintegerMerged without review, and awaiting review.
stats.conflicts / bad_conflictsintegerRecords with a field conflict, and with a conflict on a field where disagreement is a control failure.
stats.per_sourceobjectRows by source label.
stats.pairs_compared / resolve_msintegerCandidate pairs scored and the resolution time in milliseconds.

cURL: Run the vendors domain

curl -X POST "https://api.talonic.com/v1/master-records/vendors/run" \
  -H "Authorization: Bearer $TALONIC_API_KEY"

Response: 201 Run and statistics

{
  "run_id": "5b1d7f93-2c4e-4a68-8e0f-3d9a1c6b7e25",
  "stats": {
    "source_rows": 2444,
    "records": 2108,
    "multi_source": 301,
    "auto_merged": 262,
    "to_review": 39,
    "conflicts": 44,
    "bad_conflicts": 7,
    "per_source": { "ERP-A": 1380, "ERP-B": 1064 },
    "pairs_compared": 9120,
    "resolve_ms": 84
  }
}

Run Errors

A run that cannot proceed stores nothing. 400 means a source query is not read-only, lacks the required columns, or returns more rows than the cap. 404 means the domain is unknown. 422 means no sources are configured for the domain. Failures of the connection itself, such as an unreachable host, are reported as errors of the run and are not part of this documented contract.

A run reads every source and resolves in memory inside the request. Reading the sources dominates the time. For very large masters, expect a long request and set a generous client timeout.

Frequently asked questions

Does a run keep my accept and split decisions?+
Yes. Decisions are keyed by the record's members, and a run applies them: an accepted record gets status accepted, and a split record becomes single records with status split. A record whose members changed gets a new key, so the old decision does not apply to it.
Why did my run fail with 400?+
A source query is not read-only, lacks the required columns (id and name), or returned more rows than the configured per-source cap. A run never resolves a partial master, so it fails instead.
Does a run touch the source systems?+
It only reads them. Every query is a read-only SELECT and the connection's host is checked first. The only thing written is the platform's own table of golden records for the domain.

Related

Master Records Overview
Master Records Configuration
Golden Records
Record Decisions