On this page
Search records through the API
Search a Golden entity with record-shaped criteria or free text, discover what an entity can be searched by, and interpret hits, notices, history and truncated results.
Golden searches within one entity, and offers two ways in:
| Operation | For |
|---|---|
POST /api/golden/{entity}/search | A structured query: a record fragment whose fields belong to the entity dataset |
POST /api/golden/{entity}/search/text | A free-text query: one line, the way a search bar works |
Each answers one question and says, in messages, what it did not search.
Record search allows VIEWER, STEWARD, and ADMIN, within their data
grants.
Examples use the Aurelia Utilities sample,
whose entity is sample-customer-entity.
Discover searchable fields
Do this before hard-coding field names. The answer is generated from the entity’s indexer, and it is the same answer the web application uses to build its search bar.
curl --fail-with-body --silent --show-error \
--header "Authorization: Bearer ${GOLDEN_TOKEN}" \
"${GOLDEN_URL}/api/golden/sample-customer-entity/search/capabilities"
{
"entity": "sample-customer-entity",
"searchable": true,
"provenanceSearchable": true,
"freeTextIndexed": true,
"fields": [
{ "mapping": "by-tax-id", "columns": ["taxId"], "matching": "EXACT", "combined": false, "freeText": true },
{ "mapping": "by-email", "columns": ["email"], "matching": "EXACT", "combined": false, "freeText": true },
{ "mapping": "by-phone", "columns": ["phone"], "matching": "EXACT", "combined": false, "freeText": true },
{ "mapping": "by-name-postcode", "columns": ["fullName", "postcode"], "matching": "FUZZY", "combined": true, "freeText": true }
]
}
combined: true means the mapping’s columns form one key together — searching
fullName alone does not use by-name-postcode. provenanceSearchable is
true on every entity: a source record reference needs no indexing. On an
entity of type NONE, searchable is false: structured search accepts only a
lookup by _id, and free-text search runs only its identifier and provenance
steps.
Structured search
curl --fail-with-body --silent --show-error \
--request POST \
--header "Authorization: Bearer ${GOLDEN_TOKEN}" \
--header "Content-Type: application/json" \
--data '{
"record": { "taxId": "12345678Z" },
"pageNumber": 0,
"pageSize": 10
}' \
"${GOLDEN_URL}/api/golden/sample-customer-entity/search"
record is required and cannot be empty: a request with an empty record, or
with only a filter, is a 400 “Invalid null or empty search record”.
Search behavior follows the entity’s
indexer, including which fields bring
candidates together and how text is normalized. The entity’s pipeline, and
the request’s transformation when one is named, run on the submitted record
first, so a value is searched in the canonical form records are stored in.
The request can also carry:
| Field | Default | Purpose |
|---|---|---|
transformation | None | Apply a named transformation to the submitted record before searching |
entity | false | Include entity information in the response |
filter | None | A metadata filter, the same one the record page sends, applied to the records reached. It narrows what record found; it is not a criterion on its own |
tableType | Both | TABLE searches only current records; HISTORY only historical ones. See History and merged records |
pageSize | 10 | From 1 to 1000. A larger value is a 400, not a silent truncation |
options | Defaults | Optional; see below |
Search options
| Option | Default | Effect |
|---|---|---|
identity | true | Search by _id when the submitted record carries one. false with only _id is a 400 |
combine | ANY | How several filled fields combine: ANY or ALL |
fieldModes | Per mapping | Per-column probe mode: MAPPING, EXACT, or SIMILAR |
radiusMeters | 0 | Radius for a geographic search. Zero or negative falls back to geoPrecision |
geoPrecision | Default | Geographic area precision, L1–L10, used when radiusMeters is not positive |
maximumResults | -1 | Result cap, applied once after combining; -1 means no count limit |
maximumDuration | 5 seconds | Search processing time limit; at least 50 milliseconds |
provenance | true | Free-text search only: also look up a term as a source record reference |
exact, fuzzy, geo, geoSteps and fuzzyMaximumTypos are deprecated and
ignored. They are accepted with any value and change nothing; remove them from
requests.
To find the record that holds an exact source pair, read the table’s records
with filterSource and filterSourceId; see
Find the record that holds a source pair.
In a structured search, the same members in filter only narrow the records
the search record reached. Free-text search finds a source record reference
through its query, in its provenance step, not through filter.
combine defaults to ANY in the API. The advanced web form sends ALL.
With ANY, adding another field can broaden the results; with ALL, every
filled field must match by the record’s own value. Set this option
explicitly.
fieldModes is the API form of the advanced form’s per-field Exact /
Similar switch. A column absent from the map is probed with its mapping’s
own matching type. SIMILAR on a column a geographic mapping indexes is a
400: a geographic column is searched by distance.
The five-second default duration means a broad search is time-bounded. Choose a duration appropriate to the workflow rather than assuming every search is exhaustive.
What a structured search uses
| Request | Answer |
|---|---|
An _id | The _id alone. When it misses, count: 0 and a message; the other members are not searched |
An _id beside other members | The _id alone; messages names the members not searched |
Some members nothing can search (an unmapped column, _source, half of a combined mapping) | Searched without them; messages names them |
| Only members nothing can search | 400 naming them |
A blank member (null, empty, whitespace, or a list of only such values) beside a usable one | Searched without it; messages names it as blank |
| Only blank members, or blank and unsearchable ones | 400 naming them and saying which were blank |
| A column the entity’s pipeline empties, such as an invalid email a cleaner clears | Named in messages; as the only criterion, the 400 above |
| The pipeline or the requested transformation fails on the search record | The record is searched as sent; messages says which step failed |
Field criteria on an entity of type NONE | 400: the entity has no indexing, so only a lookup by _id is available |
| A geographic value that is not a point | 400 naming it |
Free-text search
curl --fail-with-body --silent --show-error \
--request POST \
--header "Authorization: Bearer ${GOLDEN_TOKEN}" \
--header "Content-Type: application/json" \
--data '{"query":"Ana Garcia Munoz","pageNumber":0,"pageSize":10}' \
"${GOLDEN_URL}/api/golden/sample-customer-entity/search/text"
The field is query, not text. Sending text answers “Invalid null
or empty search query”, and so does a query of only blank phrases.
Whitespace separates terms and double quotes hold a phrase together. Golden runs three steps:
- Identifier. When the whole query, trimmed, is a record’s
_id, that record is the answer and the search ends, unlessoptions.identityisfalse. A merged_idanswers with its live survivor. - Provenance. When the whole query, trimmed, is a source record reference
(
_source._src_id) andprovenanceis true, that record is added alongside the term matches. A record both steps found keeps its better hit, which isSOURCE. - Terms. Each term is probed against every searchable field. A term is asked exactly first, over current and historical records together, and approximately only when neither has an exact answer: inside each mapping’s key, and by word similarity.
The term step needs indexing; on an entity without it, only the identifier and
provenance steps run. Under several terms, a record must match every term
by its own value or through a record merged into it; a record reached only
through its group does not count. When no record matches every term, Golden returns the records
that match any, ranks a record that matches more terms higher, and says in
messages that no record matched every term.
A term that every searchable field reduces to nothing, such as & or -
under the default key options, is dropped and named in messages; if no term
is left, the request is a 400. combine, fieldModes, radiusMeters and
geoPrecision belong to structured search: free-text search ignores them and
names any set to a non-default value.
similarity sets the word-similarity threshold; unset, zero or negative means
0.7. It must be below 1.0; a value at or above it is a 400, because word
similarity can reach 1.0 only on a whole-key match.
The query above returns these three records from the sample:
| Source | Reference | Full name | Tax ID | |
|---|---|---|---|---|
| CRM | CRM-0001 | Ana García Muñoz | 12345678Z | ana.garcia@example.com |
| CRM | CRM-DUP-0001 | Ana Garcaí Muñoz | 12345678Z | Ana.Garcia@example.com |
| BILLING | BILL-0001 | Ana Garcia Munoz | (empty) | ana.garcia@ |
A structured search on taxId returns only two: the billing record has no tax
identifier. Free-text search can find this record through its name even
though that identifier is absent.
History and merged records
Without tableType, a search covers current and historical records, so a
deleted record can legitimately come back. Every row returned from history
carries _metadata._history: true; that is how a client tells it from a
current one. tableType: TABLE asks for current records only. tableType is a
request option, never a response member.
A search that reaches a record a merge absorbed — by its _id, a value or a
source reference — returns the live survivor at the end of the merge chain,
however many merges it went through, with _search.origin: MERGED_FORWARD and
_search.sourceId naming the absorbed record. This holds under
tableType: TABLE too: history is consulted only to reach a survivor, and an
archived row is not returned. A chain that ends in a deletion or an undone
merge returns the archived row that matched, as HISTORY, and nothing under
TABLE.
| Situation | Answer |
|---|---|
An _id the caller may see that the filter excludes | count: 0 and a message saying the record exists but does not match the filter. On free-text search it ends the search |
A merged _id whose survivor the filter excludes | messages says the _id was merged into a record that does not match the filter |
An unknown _id, or one the caller may not see | “No record has the _id”, identically for both |
| A merged record whose survivor the caller may not see | No hit |
| An archived row outside the caller’s data scope, even when its survivor is visible | Answered exactly as an unknown id |
The filter applies to the record returned, so a forwarded hit is filtered as the survivor.
Read the response
| Field | Meaning |
|---|---|
search | Structured search only: the record criteria Golden used, after the pipeline and any requested transformation |
result | Records on the current page |
count | Total matching record count |
truncated | The answer was cut. The result is part of the answer |
messages | What Golden did not search, ignored or could not use, and why a cut happened |
page | Current pagination information |
entity | Optional entity information when requested |
An identifier hit is one record: a later page is empty with count: 1.
Truncated results
When the deadline or a probe ceiling cuts the answer, truncated: true comes
with a sentence in messages saying which:
| Cut | Remedy |
|---|---|
The maximumDuration deadline | Raise maximumDuration or narrow the search |
| A probe ceiling: a safety cap on how many records each probe reads, or the source-reference step’s limit of 100 records | Narrow the search; more time would not help |
Both sentences can appear. The safety cap is the larger of 5000 and ten times
maximumResults. Your own maximumResults also sets truncated and caps the
result, with no sentence.
Read the search evidence
Each result carries one _search object describing the record’s best hit
and how the record was reached:
| Field | Meaning |
|---|---|
index | Indexer mapping that found the result |
match | Matched text, normalized |
type | The kind of match; see below |
rank | Relative match-strength signal within the type |
exact | True only when the term equals the whole of the record’s own key for that mapping |
origin | How the record was reached, which is not the same question as what matched it |
sourceId | With MERGED_FORWARD, the absorbed record the hit came through |
A record reached by several hits shows one: the best by type, then rank,
then origin, then a fixed order. Results with the same type and rank are
listed by origin — DIRECT, MERGED_FORWARD, CLUSTER, HISTORY — and then
by _id.
Hit types
_search.type says what found the result. Hit types are their own list,
separate from the matching types
an indexer mapping is configured with. From strongest to weakest:
| Hit type | Type rank | Found by |
|---|---|---|
ID | 100 | The record’s _id |
SOURCE | 95 | A source record reference |
EXACT | 90 | The mapping’s key, matched whole |
PREFIX | 80 | The start of the mapping’s key |
SUFFIX | 70 | The end of the mapping’s key |
INFIX | 60 | Part of the mapping’s key, including free-text search’s approximate step |
SIMILAR | 55 | Word similarity: free-text search’s approximate step, or fieldModes: SIMILAR. rank is the similarity, from 0 to 1 |
FUZZY | 50 | A FUZZY mapping’s typo-tolerant matching |
GEOGRAPHIC | 40 | Distance from a point |
The type rank orders hits before their rank. SIMILAR and SOURCE exist
only as hit types: no indexer mapping can be configured with either. A stored
annotation with no type, or with one Golden no longer knows, reads as NONE;
NONE is never the type of a hit. A client that switches on
_search.type must accept SIMILAR. A SIMILAR hit of similarity 1.0 is not
exact unless the term equals the key, and a GEOGRAPHIC hit never is.
Free-text search’s approximate step looks for the term inside the key of every
mapping, whatever the mapping’s matching type. A mapping configured as EXACT
can therefore return an INFIX hit with exact: false; the mapping’s type has
not changed.
A geographic hit’s rank is 1 − distance / radius: 1 at the point and 0 at
the edge. Geographic results are listed nearest first, so maximumResults
keeps the nearest. The radius is radiusMeters when positive, otherwise the
size of the geoPrecision area.
Search result origin
| Value | Meaning |
|---|---|
DIRECT | The record’s own key for that mapping is what matched |
CLUSTER | The record came in through its group: a bucket of a key it does not own. Its own value may be nothing like the search term |
MERGED_FORWARD | The record is current and was reached through a record merged into it. The matching value belonged to the absorbed record, which sourceId names, and the evidence describes that record |
HISTORY | The record is no longer in the table |
exact and origin describe the record’s own key, derived again at search
time. A CLUSTER record is never credited with the term: combine: ALL and
free-text search’s every-term rule require the record’s own value. A CLUSTER
record found in history keeps origin: CLUSTER, and _metadata._history
says it is archived.
Use the evidence to understand the lookup; do not reproduce ranking behavior
from rank, and do not use it for identity decisions. That is what the
classifier and the duplicate review are for. See the
record metadata reference.
If search returns nothing
Check that:
- the entity identifier and field names are correct —
search/capabilitiessettles both; messagesdoes not name a member as unsearchable, blank or emptied by the pipeline;- the entity is enabled and its synchronization has completed;
- the relevant indexer mapping participates in search;
combineis the combination you meant;- a
filteris not excluding the record — the message says so for an_id; - normalization and matching options suit the submitted value; and
- the caller is using the intended environment and credential.
An empty result means this search found no matching record under these
options. If the question is whether a raw row exists, inspect the entity’s
table separately with Query table data.