On this page

Golden searches within one entity, and offers two ways in:

OperationFor
POST /api/golden/{entity}/searchA structured query: a record fragment whose fields belong to the entity dataset
POST /api/golden/{entity}/search/textA 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.

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:

FieldDefaultPurpose
transformationNoneApply a named transformation to the submitted record before searching
entityfalseInclude entity information in the response
filterNoneA 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
tableTypeBothTABLE searches only current records; HISTORY only historical ones. See History and merged records
pageSize10From 1 to 1000. A larger value is a 400, not a silent truncation
optionsDefaultsOptional; see below

Search options

OptionDefaultEffect
identitytrueSearch by _id when the submitted record carries one. false with only _id is a 400
combineANYHow several filled fields combine: ANY or ALL
fieldModesPer mappingPer-column probe mode: MAPPING, EXACT, or SIMILAR
radiusMeters0Radius for a geographic search. Zero or negative falls back to geoPrecision
geoPrecisionDefaultGeographic area precision, L1–L10, used when radiusMeters is not positive
maximumResults-1Result cap, applied once after combining; -1 means no count limit
maximumDuration5 secondsSearch processing time limit; at least 50 milliseconds
provenancetrueFree-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

RequestAnswer
An _idThe _id alone. When it misses, count: 0 and a message; the other members are not searched
An _id beside other membersThe _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 search400 naming them
A blank member (null, empty, whitespace, or a list of only such values) beside a usable oneSearched without it; messages names it as blank
Only blank members, or blank and unsearchable ones400 naming them and saying which were blank
A column the entity’s pipeline empties, such as an invalid email a cleaner clearsNamed in messages; as the only criterion, the 400 above
The pipeline or the requested transformation fails on the search recordThe record is searched as sent; messages says which step failed
Field criteria on an entity of type NONE400: the entity has no indexing, so only a lookup by _id is available
A geographic value that is not a point400 naming it
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:

  1. Identifier. When the whole query, trimmed, is a record’s _id, that record is the answer and the search ends, unless options.identity is false. A merged _id answers with its live survivor.
  2. Provenance. When the whole query, trimmed, is a source record reference (_source._src_id) and provenance is true, that record is added alongside the term matches. A record both steps found keeps its better hit, which is SOURCE.
  3. 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:

SourceReferenceFull nameTax IDEmail
CRMCRM-0001Ana García Muñoz12345678Zana.garcia@example.com
CRMCRM-DUP-0001Ana Garcaí Muñoz12345678ZAna.Garcia@example.com
BILLINGBILL-0001Ana 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.

SituationAnswer
An _id the caller may see that the filter excludescount: 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 excludesmessages 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 seeNo hit
An archived row outside the caller’s data scope, even when its survivor is visibleAnswered exactly as an unknown id

The filter applies to the record returned, so a forwarded hit is filtered as the survivor.

Read the response

FieldMeaning
searchStructured search only: the record criteria Golden used, after the pipeline and any requested transformation
resultRecords on the current page
countTotal matching record count
truncatedThe answer was cut. The result is part of the answer
messagesWhat Golden did not search, ignored or could not use, and why a cut happened
pageCurrent pagination information
entityOptional 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:

CutRemedy
The maximumDuration deadlineRaise 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 recordsNarrow 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:

FieldMeaning
indexIndexer mapping that found the result
matchMatched text, normalized
typeThe kind of match; see below
rankRelative match-strength signal within the type
exactTrue only when the term equals the whole of the record’s own key for that mapping
originHow the record was reached, which is not the same question as what matched it
sourceIdWith 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 typeType rankFound by
ID100The record’s _id
SOURCE95A source record reference
EXACT90The mapping’s key, matched whole
PREFIX80The start of the mapping’s key
SUFFIX70The end of the mapping’s key
INFIX60Part of the mapping’s key, including free-text search’s approximate step
SIMILAR55Word similarity: free-text search’s approximate step, or fieldModes: SIMILAR. rank is the similarity, from 0 to 1
FUZZY50A FUZZY mapping’s typo-tolerant matching
GEOGRAPHIC40Distance 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

ValueMeaning
DIRECTThe record’s own key for that mapping is what matched
CLUSTERThe 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_FORWARDThe 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
HISTORYThe 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/capabilities settles both;
  • messages does 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;
  • combine is the combination you meant;
  • a filter is 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.

Golden 3.4.0 · Published 2026-10-29