---
type: api
title: Get SQL search results
description: **All methods and paths for this operation:**
url: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/elasticsearch/operation/operation-sql-query
resource: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/elasticsearch/operation/operation-sql-query
products:
  - Elasticsearch
---

# Get SQL search results


Availability: 6.3+

## Paths

- `POST` (also `GET`) `/_sql`

- [Api key auth](/elastic/docs-builder/docs/4371/api/doc/elasticsearch/authentication#apikeyauth)
- [Basic auth](/elastic/docs-builder/docs/4371/api/doc/elasticsearch/authentication#basicauth)
- [Bearer auth](/elastic/docs-builder/docs/4371/api/doc/elasticsearch/authentication#bearerauth)

## Description

Run an SQL request.

## Required authorization

* Index privileges: `read`

## Query String Parameters

- `format` (enum SqlFormat)
  The format for the response.
You can also specify a format using the `Accept` HTTP header.
If you specify both this parameter and the `Accept` HTTP header, this parameter takes precedence.
  Values: `csv`, `json`, `tsv`, `txt`, `yaml`, `cbor`, `smile`

## Request Body

`application/json`

- `allow_partial_search_results` (boolean · default: false) — optional
  If `true`, the response has partial results when there are shard request timeouts or shard failures.
If `false`, the API returns an error with no partial results.
- `catalog` (string) — optional
  The default catalog (cluster) for queries.
If unspecified, the queries execute on the data in the local cluster only.
- `columnar` (boolean · default: false) — optional
  If `true`, the results are in a columnar fashion: one row represents all the values of a certain column from the current page of results.
The API supports this parameter only for CBOR, JSON, SMILE, and YAML responses.
- `cursor` (string) — optional
  The cursor used to retrieve a set of paginated results.
If you specify a cursor, the API only uses the `columnar` and `time_zone` request body parameters.
It ignores other request body parameters.
- `fetch_size` (number · default: 1000) — optional
  The maximum number of rows (or entries) to return in one response.
- `field_multi_value_leniency` (boolean · default: false) — optional
  If `false`, the API returns an exception when encountering multiple values for a field.
If `true`, the API is lenient and returns the first value from the array with no guarantee of consistent results.
- `filter` ({} QueryContainer · default: none) — optional
  The Elasticsearch query DSL for additional filtering.
  See [QueryContainer](https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/elasticsearch/types/_types-query_dsl-querycontainer)
- `index_using_frozen` (boolean · default: false) — optional
  If `true`, the search can run on frozen indices.
- `keep_alive` (string Duration · default: 5d) — optional
  The retention period for an async or saved synchronous search.
- `keep_on_completion` (boolean · default: false) — optional
  If `true`, Elasticsearch stores synchronous searches if you also specify the `wait_for_completion_timeout` parameter.
If `false`, Elasticsearch only stores async searches that don't finish before the `wait_for_completion_timeout`.
- `page_timeout` (string Duration · default: 45s) — optional
  The minimum retention period for the scroll cursor.
After this time period, a pagination request might fail because the scroll cursor is no longer available.
Subsequent scroll requests prolong the lifetime of the scroll cursor by the duration of `page_timeout` in the scroll request.
- `params` ([] object) — optional
  The values for parameters in the query.
- `query` (string) — optional
  The SQL query to run.
- `request_timeout` (string Duration · default: 90s) — optional
  The timeout before the request fails.
- `runtime_mappings` (RuntimeFields) — optional
  One or more runtime fields for the search request.
These fields take precedence over mapped fields with the same name.
- `time_zone` (string · default: Z) — optional
  The ISO-8601 time zone ID for the search.
- `wait_for_completion_timeout` (string Duration) — optional
  The period to wait for complete results.
It defaults to no timeout, meaning the request waits for complete search results.
If the search doesn't finish within this period, the search becomes async.

To save a synchronous search, you must specify this parameter and the `keep_on_completion` parameter.

## Response

`application/json`

- `columns` ([] Column)
  Column headings for the search results. Each object is a column.
  - `name` (string Name)
  - `type` (string)
- `cursor` (string)
  The cursor for the next set of paginated results.
For CSV, TSV, and TXT responses, this value is returned in the `Cursor` HTTP header.
- `id` (string Id)
  The identifier for the search.
This value is returned only for async and saved synchronous searches.
For CSV, TSV, and TXT responses, this value is returned in the `Async-ID` HTTP header.
- `is_running` (boolean)
  If `true`, the search is still running.
If `false`, the search has finished.
This value is returned only for async and saved synchronous searches.
For CSV, TSV, and TXT responses, this value is returned in the `Async-partial` HTTP header.
- `is_partial` (boolean)
  If `true`, the response does not contain complete search results.
If `is_partial` is `true` and `is_running` is `true`, the search is still running.
If `is_partial` is `true` but `is_running` is `false`, the results are partial due to a failure or timeout.
This value is returned only for async and saved synchronous searches.
For CSV, TSV, and TXT responses, this value is returned in the `Async-partial` HTTP header.
- `rows` ([] Row)
  The values for the search results.
## Code Examples

#### Console

```console
POST _sql?format=txt
{
  "query": "SELECT * FROM library ORDER BY page_count DESC LIMIT 5"
}
```

#### JavaScript

```javascript
const response = await client.sql.query({
  format: "txt",
  query: "SELECT * FROM library ORDER BY page_count DESC LIMIT 5",
});
```

#### Python

```python
resp = client.sql.query(
    format="txt",
    query="SELECT * FROM library ORDER BY page_count DESC LIMIT 5",
)
```

#### curl

```curl
curl -X POST "$ELASTICSEARCH_URL/_sql?format=txt" \
  -H "Authorization: ApiKey $ELASTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "SELECT * FROM library ORDER BY page_count DESC LIMIT 5"
  }'
```

#### Java

```java
client.sql().query(q -> q
    .format(SqlFormat.Txt)
    .query("""
        SELECT * FROM library ORDER BY page_count DESC LIMIT 5
        """)
);
```

#### C#

```c#
var response = await client.Sql
    .QueryAsync(d1 => d1
        .Format(SqlFormat.Txt)
        .Query("SELECT * FROM library ORDER BY page_count DESC LIMIT 5")
    );
```

#### PHP

```php
$resp = $client->sql()->query([
    "format" => "txt",
    "body" => [
        "query" => "SELECT * FROM library ORDER BY page_count DESC LIMIT 5",
    ],
]);
```

#### Ruby

```ruby
response = client.sql.query(
  format: "txt",
  body: {
    "query": "SELECT * FROM library ORDER BY page_count DESC LIMIT 5"
  }
)
```