Perform reverse search on a percolate table

Performs a percolate search. This method must be used only on percolate tables. Expects two parameters: the table name and an object with array of documents to be tested. An example of the documents object: ``` { "query" { "percolate": { "document": { "content":"sample content" } } } }

Responds with an object with matched stored queries:  ```
  {
    'timed_out':false,
    'hits': {
      'total':2,
      'max_score':1,
      'hits': [
        {
          'table':'idx_pq_1',
          '_type':'doc',
          '_id':'2',
          '_score':'1',
          '_source': {
            'query': {
              'match':{'title':'some'}
            }
          }
        },
        {
          'table':'idx_pq_1',
          '_type':'doc',
          '_id':'5',
          '_score':'1',
          '_source': {
            'query': {
              'ql':'some | none'
            }
          }
        }
      ]
    }
  }

post/pq/{table}/search

Path parameters

tablestring required

Name of the percolate table

Request body

Example request

{
  "query": {
    "percolate": {
      "document": {
        "title": "some text to match"
      }
    }
  }
}

Response

items found

tookinteger

Time taken to execute the search

timed_outboolean

Indicates whether the search operation timed out

{"stackTrail":"components:schemas:searchResponse:properties:aggregations","oasType":"schema","type":"unknown","description":"Aggregated search results grouped by the specified criteria. Each named aggregation typically contains a `buckets` array (or keyed map) of bucket objects with `key`, `doc_count`, and optional `status`.\n","example":{"sizes":{"buckets":[{"key":"small","doc_count":1,"status":"selected"},{"key":"large","doc_count":1,"status":"available"}]},"colors":{"buckets":[{"key":10,"doc_count":1019},{"key":9,"doc_count":954,"status":"unavailable"}]}}}

profileobject

Profile information about the search execution, if profiling is enabled

scrollstring

Scroll token to be used fo pagination

warningobject

Warnings encountered during the search operation

conversation_uuidstring

Existing or generated conversation id (conversational search)

user_querystring

Original user query (conversational search)

search_querystring

Standalone search query used for KNN retrieval (conversational search)

responsestring

LLM answer as generated (conversational search)

sourcesstring

JSON string containing retrieved source rows used as LLM context (conversational search).

Example response

{
  "hits": {
    "total": 2,
    "hits": [
      {
        "_id": 1,
        "_score": 1,
        "_source": {
          "gid": 11
        }
      },
      {
        "_id": 2,
        "_score": 1,
        "_source": {
          "gid": 20
        }
      }
    ]
  },
  "took": 0,
  "user_query": "What is vector search?",
  "sources": "[{\"id\":1,\"title\":\"Vector Search\",\"content\":\"...\",\"knn_dist\":0.12}]",
  "response": "Vector search finds similar items by comparing embeddings...",
  "profile": "{}",
  "scroll": "scroll",
  "warning": "{}",
  "timed_out": true,
  "search_query": "vector search, embeddings, similarity search",
  "aggregations": {
    "sizes": {
      "buckets": [
        {
          "key": "small",
          "doc_count": 1,
          "status": "selected"
        },
        {
          "key": "large",
          "doc_count": 1,
          "status": "available"
        }
      ]
    },
    "colors": {
      "buckets": [
        {
          "key": 10,
          "doc_count": 1019
        },
        {
          "key": 9,
          "doc_count": 954,
          "status": "unavailable"
        }
      ]
    }
  },
  "conversation_uuid": "docs-chat-001"
}

Changes

Changed in 6 of the 13 revisions of this API.71515

Aug 4, 2026eb39c808303511See the full diff
- ▲
  the hits/hits/items/_id response's property type/format changed from integer/uint64 to / for status 200
  response-property-type-changed
- ○
  added documentId to the hits/hits/items/_id response property allOf list for the response status 200
  response-property-all-of-added
Jul 15, 20262fd450aa5f0715See the full diff
- ▲
  the aggregations response's property type/format changed from object/ to / for status 200
  response-property-type-changed
- ○
  added the optional property conversation_uuid to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property response to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property search_query to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property sources to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property user_query to the response with the 200 status
  response-optional-property-added
This revision also has 5 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog
Jul 31, 202550c351a999401See the full diff
- ▲
  the hits/hits/items/_id response's property type/format changed from integer/uuint64 to integer/uint64 for status 200
  response-property-type-changed
Jun 30, 20251911b776f18a1See the full diff
- ▲
  the hits/hits/items/_id response's property type/format changed from integer/int64 to integer/uuint64 for status 200
  response-property-type-changed
Apr 1, 20250e6cccea382d18See the full diff
- ▲
  the hits/hits/items/ response's property type/format changed from object/ to / for status 200
  response-property-type-changed
- ○
  added the optional property hits/hits/items/_id to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property hits/hits/items/_knn_dist to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property hits/hits/items/_score to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property hits/hits/items/_source to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property hits/hits/items/_type: to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property hits/hits/items/fields to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property hits/hits/items/highlight to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property hits/hits/items/table to the response with the 200 status
  response-optional-property-added
This revision also has 1 change that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog
Nov 14, 202488a0ac494d8e2151See the full diff
- ▲
  the aggregations response's property type/format changed from / to object/ for status 200
  response-property-type-changed
- ▲
  the hits/hits/items/ response's property type/format changed from / to object/ for status 200
  response-property-type-changed
- ●
  removed the optional property conversation_uuid from the response with the 200 status
  response-optional-property-removed
- ●
  removed the optional property error/oneOf[responseErrorDetails]/table from the response with the default status
  response-optional-property-removed
- ●
  removed the optional property hits/hits/items/_id from the response with the 200 status
  response-optional-property-removed
- ●
  removed the optional property hits/hits/items/_knn_dist from the response with the 200 status
  response-optional-property-removed
- ●
  removed the optional property hits/hits/items/_score from the response with the 200 status
  response-optional-property-removed
- ●
  removed the optional property hits/hits/items/_source from the response with the 200 status
  response-optional-property-removed
- ●
  removed the optional property hits/hits/items/_type: from the response with the 200 status
  response-optional-property-removed
- ●
  removed the optional property hits/hits/items/fields from the response with the 200 status
  response-optional-property-removed
- ●
  removed the optional property hits/hits/items/highlight from the response with the 200 status
  response-optional-property-removed
- ●
  removed the optional property hits/hits/items/table from the response with the 200 status
  response-optional-property-removed
- ●
  removed the optional property response from the response with the 200 status
  response-optional-property-removed
- ●
  removed the optional property scroll from the response with the 200 status
  response-optional-property-removed
- ●
  removed the optional property search_query from the response with the 200 status
  response-optional-property-removed
- ●
  removed the optional property sources from the response with the 200 status
  response-optional-property-removed
- ●
  removed the optional property user_query from the response with the 200 status
  response-optional-property-removed
- ○
  added the optional property error/oneOf[responseErrorDetails]/index to the response with the default status
  response-optional-property-added
This revision also has 33 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

Full history