# Siren Federate User Guide

print

- Prev
- Next

## 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:

`task_timeout` | 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 (`-1`).
`debug` | To retrieve debug information from the query planner. Defaults to `false`.

### 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"
          }
        }
      ]
    }

## Search results

No results found

- Prev
- Next