---
type: api
title: Create or update an ES|QL data source
description: Creates or replaces a named, type-specific data source configuration for ES|QL data federation.
url: https://www.elastic.co/elastic/docs-builder/docs/4493/api/doc/elasticsearch/operation/operation-esql-put-data-source
resource: https://www.elastic.co/elastic/docs-builder/docs/4493/api/doc/elasticsearch/operation/operation-esql-put-data-source
products:
  - Elasticsearch
---

# Create or update an ES|QL data source

Availability: Experimental since 9.5

## Paths

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

#### Path parameters

- `name` (string) — required
  The data source name to create or update.

## Description

Creates or replaces a named, type-specific data source configuration for ES|QL data federation.
Datasets reference data source configurations to access external data. Names must be lowercase
and follow index or alias naming rules.

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

## Required authorization

- Cluster privileges: `manage`

## Authentication

- Api key: `Authorization: <value>`
  Elasticsearch APIs support key-based authentication.
  You must create an API key and use the encoded value in the request header.
  For example:
  
  
  ```
  curl -X GET "${ES_URL}/_cat/indices?v=true" \
    -H "Authorization: ApiKey ${API_KEY}"
  ```
  
  To get API keys, use the `/_security/api_key` APIs.
- Basic: `Authorization: Basic <credentials>`
- Bearer: `Authorization: Bearer <token>`
  Elasticsearch APIs support the use of bearer tokens in the `Authorization` HTTP header to authenticate with the API.
  For examples, refer to [Token-based authentication services](https://www.elastic.co/docs/deploy-manage/users-roles/cluster-or-deployment-auth/token-based-authentication-services)

## Query string parameters

- `master_timeout` (string · default: 30s) — optional
  Period to wait for a connection to the master node.
- `timeout` (string · default: 30s) — optional
  The time to wait for the request to be completed.

## Request body

`application/json`

- `type` (string) — required
  The data source type. Currently, `s3` is supported.
The value must be lowercase and contain no whitespace.
- `description` (string) — optional
  A free-text description of the data source.
- `settings` (map string to object) — optional
  Type-specific connection and authentication settings.
For `s3`, connection settings include `region` and `endpoint`. Authentication settings
include `auth` and the credentials required by the selected authentication method.

## 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/data_source/prod_s3_logs
{
  "type": "s3",
  "description": "Production S3 logs bucket",
  "settings": {
    "region": "us-east-1",
    "auth": "static_credentials",
    "access_key": "<AWS_ACCESS_KEY_ID>",
    "secret_key": "<AWS_SECRET_ACCESS_KEY>"
  }
}
```

#### JavaScript

```javascript
const response = await client.esql.putDataSource({
  name: "prod_s3_logs",
  type: "s3",
  description: "Production S3 logs bucket",
  settings: {
    region: "us-east-1",
    auth: "static_credentials",
    access_key: "<AWS_ACCESS_KEY_ID>",
    secret_key: "<AWS_SECRET_ACCESS_KEY>",
  },
});
```

#### Python

```python
resp = client.esql.put_data_source(
    name="prod_s3_logs",
    type="s3",
    description="Production S3 logs bucket",
    settings={
        "region": "us-east-1",
        "auth": "static_credentials",
        "access_key": "<AWS_ACCESS_KEY_ID>",
        "secret_key": "<AWS_SECRET_ACCESS_KEY>"
    },
)
```

#### curl

```curl
curl -X PUT "$ELASTICSEARCH_URL/_query/data_source/prod_s3_logs" \
  -H "Authorization: ApiKey $ELASTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "s3",
    "description": "Production S3 logs bucket",
    "settings": {
      "region": "us-east-1",
      "auth": "static_credentials",
      "access_key": "\u003CAWS_ACCESS_KEY_ID\u003E",
      "secret_key": "\u003CAWS_SECRET_ACCESS_KEY\u003E"
    }
  }'
```

#### Java

```java
client.esql().putDataSource(p -> p
    .description("Production S3 logs bucket")
    .name("prod_s3_logs")
    .settings(Map.of("secret_key", JsonData.fromJson("\"<AWS_SECRET_ACCESS_KEY>\""),"auth", JsonData.fromJson("\"static_credentials\""),"access_key", JsonData.fromJson("\"<AWS_ACCESS_KEY_ID>\""),"region", JsonData.fromJson("\"us-east-1\"")))
    .type("s3")
);
```

#### PHP

```php
$resp = $client->esql()->putDataSource([
    "name" => "prod_s3_logs",
    "body" => [
        "type" => "s3",
        "description" => "Production S3 logs bucket",
        "settings" => [
            "region" => "us-east-1",
            "auth" => "static_credentials",
            "access_key" => "<AWS_ACCESS_KEY_ID>",
            "secret_key" => "<AWS_SECRET_ACCESS_KEY>",
        ],
    ],
]);
```

#### Ruby

```ruby
response = client.esql.put_data_source(
  name: "prod_s3_logs",
  body: {
    "type": "s3",
    "description": "Production S3 logs bucket",
    "settings": {
      "region": "us-east-1",
      "auth": "static_credentials",
      "access_key": "<AWS_ACCESS_KEY_ID>",
      "secret_key": "<AWS_SECRET_ACCESS_KEY>"
    }
  }
)
```

## Response examples

#### Data source created

The data source configuration was stored successfully.

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