Skip to main content

Search REST API

API version

All the API endpoints start with the api/v1/ prefix. v1 indicates that we are currently using version 1 of the API.

Parameters

Parameters passed in the URL must be properly URL-encoded, using the UTF-8 encoding for non-ASCII characters.

GET [..]/search?query=barack%20obama

Error handling

Successful requests return a 2xx HTTP status code.

Failed requests return a 4xx HTTP status code. The response body of failed requests holds a JSON object containing an error_message field that describes the error.

{
"error_message": "Failed to parse query"
}

Endpoints

Search in an index

GET api/v1/indexes/<index id>/search?query=searchterm

Search for documents matching a query in the given index <index id>.

Path variable

VariableDescription
index idThe index id

Get parameters

VariableTypeDescriptionDefault value
queryStringQuery text. See the query language doc (mandatory)
startTimestampi64If set, restrict search to documents with a timestamp >= start_timestamp
endTimestampi64If set, restrict search to documents with a timestamp < end_timestamp
startOffsetIntegerNumber of documents to skip0
maxHitsIntegerMaximum number of hits to return (by default 20)20
searchField[String]Fields to search on if no field name is specified in the query. Comma-separated list, e.g. "field1,field2"index_config.search_settings.default_search_fields
formatEnumThe output format. Allowed values are "json" or "prettyjson"prettyjson

Response

The response for the is a JSON object, and the content type is application/json; charset=UTF-8.

FieldDescriptionType
hitsResults of the query[hit]
numHitsTotal number of matchesnumber
elapsedTimeMicrosProcessing time of the querynumber

Search stream in an index

GET api/v1/indexes/<index id>/search/stream?query=searchterm

Streams field values from ALL documents matching a search query in the given index <index id>, in a specified output format among the following:

note

The endpoint will return 10 million values if 10 million documents match the query. This is expected, this endpoint is made to support queries matching millions of document and return field values in a reasonable response time.

Path variable

VariableDescription
index idThe index id

Get parameters

VariableTypeDescriptionDefault value
queryStringQuery text. See the query language doc (mandatory)
fastFieldStringName of a field to retrieve from documents. This field must be marked as "fast" in the index config. (mandatory)
searchField[String]Fields to search on. Comma-separated list, e.g. "field1,field2"index_config.search_settings.default_search_fields
startTimestampi64If set, restrict search to documents with a timestamp >= start_timestamp
endTimestampi64If set, restrict search to documents with a timestamp < end_timestamp
outputFormatStringResponse output format. csv or clickHouseRowBinarycsv

Response

The response is an HTTP stream. Depending on the client's capability, it is an HTTP1.1 chunked transfer encoded stream or an HTTP2 stream.

It returns a list of all the field values from documents matching the query. The field must be marked as "fast" in the index config for this to work. The formatting is based on the specified output format.

On error, an "X-Stream-Error" header will be sent via the trailers channel with information about the error, and the stream will be closed via sender.abort(). Depending on the client, the trailer header with error details may not be shown. The error will also be logged in quickwit ("Error when streaming search results").