Search APIs
Siren Federate introduces two new search actions, /siren/[INDICES]/_search
that replaces the /[INDICES]/_search
Elasticsearch’s action, and /siren/[INDICES]/_msearch
that replaces the /[INDICES]/_msearch
Elasticsearch’s action.
Both actions are extensions of the original Elasticsearch’s actions and therefore supports the same API. One must use
these actions with the join
query clause, as the join
query clause is not supported by the original Elasticsearch
actions.
Search API
The search API allows you to execute a search query and get back search hits that match the query.
The endpoint for it is /siren/[INDICES]/_search
.
Multi search API
The multi search API allows you to execute several search requests within the same API. The endpoint for it is
/siren/[INDICES]/_msearch
.
Search request
The syntax for the body of the search request is identical to the one supported by Elasticsearch’s search API, with
the additional support for the join
query clause in the Query DSL.
Parameters
In addition to the parameters supported by Elasticsearch’s search API, Federate’s search API introduces the following additional parameters:
| A task timeout, bounding a task to be executed within the specified time value (in milliseconds) and returns
with the values accumulated up to that point when expired. Defaults to no timeout ( |
| To retrieve debug information from the query planner. Defaults to |
Search response
The response returned by Federate’s search API is similar to the response returned by Elasticsearch’s search API.
It extends the response with a planner
object which includes information about the query plan execution. If the
task_timeout
was activated, it will include the flag is_pruned
to indicate that the search results are pruned and
probably incomplete. If the debug
parameter was enabled, it will also include the information and statistics about
the query plan execution.
Cancelling a Request
A search or a multi search request can be canceled explicitly by a user through HTTP headers. In order to do so, you
need to pass an X-Opaque-Id
header which is used to identify the request. The endpoint for canceling a request is
/_siren/job/<ID>/_cancel
.
Usage
Let’s identity a search request with the ID my-request
:
$ curl -H "Content-Type: application/json" -H "X-Opaque-Id: my-request" 'http://localhost:9200/siren/_search'
Then to cancel it, issue a request as follows:
$ curl -XPOST -H "Content-Type: application/json" 'localhost:9200/_siren/job/my-request/_cancel'
If successful, the response will acknowledge the request and give a listing of the canceled tasks:
{ "acknowledged" : true, "tasks" : [ { "node" : "5ILUA44uSee-VxsBsNbsNA", "id" : 947, "type" : "transport", "action" : "indices:siren/plan", "description" : "federate query", "start_time_in_millis" : 1524815599457, "running_time_in_nanos" : 199131478, "cancellable" : true, "headers" : { "X-Opaque-Id" : "my-request" } } ] }