Field Autocomplete

Autocomplete extracted field names from the field registry with GET /v1/search/autocomplete: relevance-ranked suggestions with counts and sample values.

The Talonic API lets you search and filter documents by their extracted field values: field autocomplete resolves field names, document filtering applies composable conditions, and global omnisearch queries every entity type at once. The field autocomplete endpoint is the entry point: it performs type-ahead search over the field registry, the deduplicated catalog of every field Talonic has extracted from your documents.

Results are ranked by a combination of name relevance and occurrence count, so frequently seen fields surface first. Use this to power field picker dropdowns and search-as-you-type UIs, or to resolve a field ID before calling the field values or filter endpoints: the fieldId each suggestion carries is exactly what POST /v1/documents/filter conditions and GET /v1/search/field-values expect.

Each suggestion carries two counts that answer different questions. documentCount is the number of documents an is_not_empty filter on this field matches today — it is counted from the same materialized store the filter executes against, so the picker never promises more than the filter delivers. occurrenceCount (and its raw registry twin registryOccurrenceCount) is the discovery-time count of how often the field concept was seen during extraction; it can exceed documentCount when values have not been materialized yet.

Suggestions are visibility-filtered: the endpoint evaluates Sources-IAM as the API key's minting user, so counts and sample values only reflect documents that key is admitted to see. An empty or omitted q returns the top fields by occurrence rather than an error, which makes the endpoint safe to call for an initial "browse all fields" state before the user types anything.

Build filters against documentCount, not occurrenceCount: a field with a large occurrenceCount but documentCount 0 has no materialized values yet, so a filter on it matches nothing until materialization catches up.

GET/v1/search/autocomplete

Query parameters

qstringSearch text to match against field names. Empty returns top fields by occurrence.

source_idstringScope results to fields seen in a specific source.

limitintegerMaximum number of results to return (up to 100). Default: 20

Request

curl "https://api.talonic.com/v1/search/autocomplete?q=supplier" \
  -H "Authorization: Bearer $TALONIC_API_KEY"

Response

Response fields

dataarrayArray of matching field objects ranked by relevance.

data[].fieldIdstringField registry UUID — the id filter conditions and field-values lookups expect.

data[].canonicalNamestringCanonical field name (lowercase, underscore-separated).

data[].displayNamestring | nullHuman-readable display name, when one was derived.

data[].dataTypestringField data type (string, number, date, boolean).

data[].tierintegerRegistry maturity tier: 1 = Canonical, 2 = Established, 3 = Provisional.

data[].documentCountintegerDocuments an is_not_empty filter on this field matches today, counted from the materialized value store.

data[].occurrenceCountintegerDiscovery-time occurrence count from the field registry. Can exceed documentCount before materialization.

data[].registryOccurrenceCountintegerThe raw registry occurrence counter backing occurrenceCount.

data[].matchSourcestringHow the field matched the query: `canonical`, `display`, or `variant`.

data[].sampleValuesstring[]Up to 3 representative values from the field.

Response

{
  "data": [
    {
      "fieldId": "6f1e9a2b-4c3d-4e5f-8a7b-9c0d1e2f3a4b",
      "canonicalName": "supplier_name",
      "displayName": "Supplier Name",
      "dataType": "string",
      "tier": 1,
      "documentCount": 1794,
      "occurrenceCount": 1842,
      "registryOccurrenceCount": 1842,
      "matchSource": "canonical",
      "sampleValues": ["Acme Corp", "Globex Inc", "Initech"]
    }
  ]
}

Errors

Error responses

401unauthorizedMissing or invalid API key.

429rate_limitedToo many requests. Retry after the period indicated in the Retry-After header.

Frequently asked questions

How does the ranking work?+

Results are ranked by a combined score of name match relevance (canonical name, display name, and variant matches) and occurrence count. Fields that appear in more documents rank higher for equivalent relevance.

What does the tier field represent?+

Tier is the registry maturity of the field concept: 1 = Canonical (proven, consistently extracted across documents), 2 = Established, 3 = Provisional. Use tier to decide which fields to display prominently.

Why do documentCount and occurrenceCount differ?+

occurrenceCount is how often the field was seen at discovery time; documentCount is how many documents a filter on the field actually matches right now, counted from the materialized value store the filter executes against. They converge once materialization is current.

Can I search by variant names?+

Yes. The autocomplete matches against canonical names, display names, and variant names seen across your documents. The `matchSource` field (`canonical`, `display`, or `variant`) indicates how the match was made.

Field Autocomplete

Response

Errors

Frequently asked questions

Related