Aggregate text results

Summarize stored document values across matching full-text results or the whole field.

POST /v1/tenants/{tenant}/fts/{table}/_aggs

Summarize values from matching documentsStore facet values first; indexing words alone is not enough.

Choose the document setUse a text search or the whole field.
Aggregate stored valuesGroup or summarize the requested facets.
Read counts and summariesCompare doc_count with the named aggregation results.

Before you start

Use your database bearer token.

Connection setup

Store facet values with Store original text before aggregating them. The example uses category facets.

Path parameters

Field	Type	Required
`tenant`	`string`	Required
`table`	`string`	Required

Headers

Field	Type	Required	Description
`x-oc-db-user`	`string`	Optional	Acting database user (role, grant and row-policy checks). Send with x-oc-db-key.
`x-oc-db-key`	`string`	Optional	API key of the x-oc-db-user user.

Request body

application/json

Limits and accepted values

field names the full-text field whose per-document values (written via the doc endpoint) are aggregated.
aggs must be non-empty (400 otherwise).
filter_expr is accepted only to be refused: any non-null value, top-level or inside search, answers 501.

Field	Type	Required	Description
`aggs`	`object`	Optional	Map of aggregation name -> aggregation node. A node is {"<kind>": {...}, "aggs": {<children>}}. Bucket kinds: terms, range, histogram, date_histogram, filter, filters, missing, global. Metric kinds: count, min, max, sum, avg, stats, extended_stats, cardinality, percentiles, percentile_ranks, top_hits. Pipeline kinds: bucket_sort, cumulative_sum, derivative, serial_diff, moving_fn, bucket_script, bucket_selector, avg_bucket, sum_bucket, min_bucket, max_bucket, stats_bucket. Fields are named with "field".
`field`	`string`	Required	—
`search`	`object`	Optional	A _search request body selecting the documents to aggregate (doc_values_field is refused here). Absent means match_all over field.

Fields in search

Field	Type	Required	Description
`default_field`	`string`	Optional	—
`exact_total`	`boolean`	Optional	—
`min_score`	`number`	Optional	—
`params`	`object`	Optional	BM25 tunables; both optional.

Fields in params

Field	Type	Required
`b`	`number`	Optional
`k1`	`number`	Optional

Field	Type	Required	Description
`query`	`any JSON`	Required	—
`search_after`	`object`	Optional	values holds one JSON scalar per sort key (any scalar type; null means missing) and must match the sort length. doc_id is the tiebreak of the last hit seen.

Fields in search_after

Field	Type	Required
`doc_id`	`string`	Optional
`values`	`any JSON[]`	Required

Fields in values

Field	Type	Required
`values`	`any JSON`	Optional

Field	Type	Required
`sort`	`object[]`	Optional

Fields in sort

Field	Type	Required
`ascending`	`boolean`	Required
`field`	`string`	Required
`missing`	`any JSON`	Optional
`mode`	`string`	Optional
`role`	`string`	Required
`truncate`	`boolean`	Optional

Field	Type	Required
`table`	`string`	Optional
`top_k`	`integer`	Optional
`total_ceiling`	`integer`	Optional
`unindexed_fields_are_empty`	`boolean`	Optional
`universe_field`	`string`	Optional

Read the result

Read doc_count alongside the named results in aggs. Bucket counts group stored facet values, so you must store those values before aggregating them; indexing words alone is not enough.

Response statuses

HTTP status reference

Status	What to do
200	OK
400	Correct the request before retrying.
401	Check the credential and Authorization header.
402	Check feature access or available credits.
403	Check tenant access, roles and permissions.
404	Check the resource ID and API route.
408	Reduce query work or adjust the timeout.
413	Split or reduce the request body.
415	Send the required Content-Type.
422	Correct the values or unsupported combination.
429	Honor Retry-After when present; back off.
499	The client cancelled the request.
500	Check the outcome before retrying a write.
501	Check deployment support for this operation.
503	Honor Retry-After when present; check write outcomes.

Request example

curl --include --request POST "${OC_BASE_URL}/v1/tenants/${OC_TENANT}/fts/demo_docs/_aggs" \
  --header "Authorization: Bearer ${OC_TOKEN}" \
  --header "Content-Type: application/json" \
  --data-binary '{
  "field": "body",
  "aggs": {
    "categories": {
      "terms": {
        "field": "category"
      }
    }
  }
}'

Response example

Examples use synthetic values to show the response format.

Response status

{
  "doc_count": 1,
  "aggs": {
    "categories": {
      "kind": "buckets",
      "buckets": [
        {
          "key": "outdoor",
          "doc_count": 1,
          "aggs": {}
        }
      ]
    }
  }
}

Download the OpenAPI specification for the complete response schemas.

Before you startCopy Anchor Link

Path parametersCopy Anchor Link

HeadersCopy Anchor Link

Request bodyCopy Anchor Link