---
type: api
title: Get ES|QL datasets
description: **All methods and paths for this operation:**
url: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/elasticsearch-serverless/operation/operation-esql-get-dataset
resource: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/elasticsearch-serverless/operation/operation-esql-get-dataset
products:
  - Elasticsearch Serverless
---

# Get ES|QL datasets


Availability:

## Paths

- `GET` `/_query/dataset/{name}`
- `GET` `/_query/dataset`

- [Api key auth](/elastic/docs-builder/docs/4371/api/doc/elasticsearch-serverless/authentication#apikeyauth)

#### Path Parameters

- `name` (union Name | [] Name) — optional, leave it out to use `/_query/dataset`
  A comma-separated list of dataset names or wildcard patterns. Omit to return all datasets.

## Description

Returns one or more datasets used in ES|QL data federation.
A concrete-name miss returns `404`; a wildcard pattern or list-all request with no match
returns `200` with an empty array.

## Required authorization

* Index privileges: `manage`

[ES|QL Data Federation](https://www.elastic.co/docs/reference/query-languages/esql/esql-data-federation)

## Query String Parameters

- `master_timeout` (string Duration · default: 30s)
  Period to wait for a connection to the master node.

## Response

`application/json`

- `datasets` ([] ESQLDataset)
  The matching datasets.
  - `name` (string Name)
    The dataset name.
  - `data_source` (string Name)
    The name of the referenced data source.
  - `resource` (string)
    The URI that identifies the data to read, resolved against the referenced data source.
It can include glob patterns, for example a recursive pattern that matches
Parquet files under `s3://logs-bucket/access`.
  - `description` (string)
    A free-text description.
  - `settings` (map string to object)
    Format- and parsing-specific settings that configure how the resource is read.
Common keys include `format` and `partition_detection`. Additional keys depend on the format reader;
compression can be inferred from the resource URI.
  - `mappings` ({} DatasetMapping)
    The user-declared mapping on the dataset definition.
    - `dynamic` (enum Dynamic · default: true)
      The policy for columns that are not declared in `properties`.
`true` (the default) infers undeclared columns and overlays the declarations; `false` makes the declaration the entire schema, so undeclared columns are not queryable.
      Values: `true`, `false`
    - `properties` (map string to DatasetFieldMapping)
      The per-column declarations, keyed by logical column name.
      Map values ({} DatasetFieldMapping)
      - `type` (string)
        The declared column type.
      - `path` (string)
        The underlying file column that this logical column reads from.
This is a read-path rename: the physical column becomes this single logical column.
      - `format` (string)
        The date-parse pattern for a declared `date` column, mirroring the index date-field `format`.
    - `_id` ({} IdPath)
      The `_id` meta-field configuration, sourcing the document identity from a column.
      - `path` (string)
        The name of the column that provides the document identity.
## Code Examples

#### Console

```console
GET /_query/dataset/access_logs
```

#### JavaScript

```javascript
const response = await client.esql.getDataset({
  name: "access_logs",
});
```

#### Python

```python
resp = client.esql.get_dataset(
    name="access_logs",
)
```

#### curl

```curl
curl -X GET "$ELASTICSEARCH_URL/_query/dataset/access_logs" \
  -H "Authorization: ApiKey $ELASTIC_API_KEY"
```

#### Java

```java
client.esql().getDataset(g -> g
    .name("access_logs")
);
```

#### PHP

```php
$resp = $client->esql()->getDataset([
    "name" => "access_logs",
]);
```

#### Ruby

```ruby
response = client.esql.get_dataset(
  name: "access_logs"
)
```

## Response Examples

#### Dataset details

The response contains the requested dataset definition.

```json
{
  "datasets": [
    {
      "name": "access_logs",
      "data_source": "prod_s3_logs",
      "resource": "s3://logs-bucket/access/**/*.parquet",
      "description": "Production access logs",
      "settings": {
        "partition_detection": "hive"
      }
    }
  ]
}
```

#### No datasets matched

A wildcard or list-all request with no matches returns an empty array.

```json
{
  "datasets": []
}
```