---
type: api
title: Create or update an ES|QL dataset
description: Creates or replaces a dataset that references a data source in ES|QL data federation.
url: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/elasticsearch/v9/operation/operation-esql-put-dataset
resource: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/elasticsearch/v9/operation/operation-esql-put-dataset
products:
  - Elasticsearch
---

# Create or update an ES|QL dataset

Availability:

## Paths

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

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

#### Path Parameters

- `name` (string Name)
  The dataset name to create or update.

## Description

Creates or replaces a dataset that references a data source in ES|QL data federation.
Dataset names participate in the index namespace and must follow index or alias naming rules.
Returns `404` if the referenced data source does not exist.

## 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.
- `timeout` (string Duration · default: 30s)
  The time to wait for the request to be completed.

## Request Body

`application/json`

- `data_source` (string Name) — required
  The name of the referenced data source. The data source must already exist.
- `resource` (string) — required
  The URI that identifies the data to read, resolved against the referenced data source.
It can include glob patterns. For example, a recursive pattern can match
all Parquet files under the `s3://logs-bucket/access` prefix.
- `description` (string) — optional
  A free-text description of the dataset.
- `mappings` ({} DatasetMapping) — optional
  User-declared mapping on the dataset definition
  - `dynamic` (enum Dynamic · default: true) — optional
    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) — optional
    The per-column declarations, keyed by logical column name.
    Map values ({} DatasetFieldMapping)
    - `type` (string) — required
      The declared column type.
    - `path` (string) — optional
      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) — optional
      The date-parse pattern for a declared `date` column, mirroring the index date-field `format`.
  - `_id` ({} IdPath) — optional
    The `_id` meta-field configuration, sourcing the document identity from a column.
    - `path` (string) — required
      The name of the column that provides the document identity.
- `settings` (map string to object) — optional
  Format and parsing-specific settings that configure how the resource is read.
Common keys include `format`, which explicitly selects a registered format, and
`partition_detection`, which accepts `auto`, `hive`, `template`, or `none`. Additional
keys depend on the format reader. Compression can be inferred from the resource URI.

## Response

`application/json`

- `acknowledged` (boolean)
  For a successful response, this value is always true. On failure, an exception is returned instead.
## Code Examples

#### Console

```console
PUT /_query/dataset/access_logs
{
  "data_source": "prod_s3_logs",
  "resource": "s3://logs-bucket/access/**/*.parquet",
  "description": "Production access logs",
  "settings": {
    "partition_detection": "hive"
  }
}
```

#### JavaScript

```javascript
const response = await client.esql.putDataset({
  name: "access_logs",
  data_source: "prod_s3_logs",
  resource: "s3://logs-bucket/access/**/*.parquet",
  description: "Production access logs",
  settings: {
    partition_detection: "hive",
  },
});
```

#### Python

```python
resp = client.esql.put_dataset(
    name="access_logs",
    data_source="prod_s3_logs",
    resource="s3://logs-bucket/access/**/*.parquet",
    description="Production access logs",
    settings={
        "partition_detection": "hive"
    },
)
```

#### curl

```curl
curl -X PUT "$ELASTICSEARCH_URL/_query/dataset/access_logs" \
  -H "Authorization: ApiKey $ELASTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "data_source": "prod_s3_logs",
    "resource": "s3://logs-bucket/access/**/*.parquet",
    "description": "Production access logs",
    "settings": {
      "partition_detection": "hive"
    }
  }'
```

#### Java

```java
client.esql().putDataset(p -> p
    .dataSource("prod_s3_logs")
    .description("Production access logs")
    .name("access_logs")
    .resource("s3://logs-bucket/access/**/*.parquet")
    .settings("partition_detection", JsonData.fromJson("\"hive\""))
);
```

#### C#

```c#
var response = await client.Esql
    .PutDatasetAsync(name: "access_logs", d1 => d1
        .DataSource("prod_s3_logs")
        .Description("Production access logs")
        .Resource("s3://logs-bucket/access/**/*.parquet")
        .Settings(new Dictionary<string, object>()
        {
            { "partition_detection", "hive" }
        })
    );
```

#### PHP

```php
$resp = $client->esql()->putDataset([
    "name" => "access_logs",
    "body" => [
        "data_source" => "prod_s3_logs",
        "resource" => "s3://logs-bucket/access/**/*.parquet",
        "description" => "Production access logs",
        "settings" => [
            "partition_detection" => "hive",
        ],
    ],
]);
```

#### Ruby

```ruby
response = client.esql.put_dataset(
  name: "access_logs",
  body: {
    "data_source": "prod_s3_logs",
    "resource": "s3://logs-bucket/access/**/*.parquet",
    "description": "Production access logs",
    "settings": {
      "partition_detection": "hive"
    }
  }
)
```

## Response Examples

#### Dataset created

The dataset definition was stored successfully.

```json
{
  "acknowledged": true
}
```