---
title: Data source settings reference for ES|QL Data Federation
description: Configure how ES|QL Data Federation data sources connect and authenticate to Amazon S3, including endpoint, region, and credential settings.
url: https://www.elastic.co/elastic/docs-builder/docs/4492/reference/query-languages/esql/esql-data-federation-data-source-settings
products:
  - Elasticsearch
applies_to:
  - Elastic Cloud Serverless: Unavailable
  - Elastic Stack: Experimental since 9.5
---

# Data source settings reference for ES|QL Data Federation
Data source settings control how Elasticsearch connects and authenticates to an external storage system. Add settings to the `settings` object when you [create or update a data source](/elastic/docs-builder/docs/4492/reference/query-languages/esql/esql-data-federation-sources#create-or-update-a-data-source), or fill in the matching fields in the **Connect data source** flyout in Kibana. The available settings depend on the data source `type`.
<warning>
  This feature is experimental. It is not intended for production use and there are no guarantees around performance, scale, or stability in this release.
</warning>


## Amazon S3

The following settings apply to data sources with `type` set to `s3`.

### Connection settings

These settings control which endpoint Elasticsearch sends S3 requests to and how it addresses buckets.

<definitions>
  <definition term="endpoint">
    An Amazon S3 endpoint override, for example `https://s3.us-east-1.amazonaws.com`.
    - **Default:** None. The endpoint is resolved from the region.
    - **Valid values:**
      - <applies-to>Elastic Stack: Planned</applies-to> An absolute URL naming a supported AWS S3 endpoint. Refer to [S3 endpoint requirements](#s3-endpoint-requirements).
    - <applies-to>Elastic Stack: Experimental in 9.5</applies-to> Any endpoint URL. The value isn't validated.
    - **Related:** `addressing_style`, `region`
    Omit `endpoint` to resolve the endpoint from the region, which is the recommended configuration.
    <dropdown title="S3 endpoint requirements" applies-to="Elastic Stack: Planned">
      The `endpoint` value must be an absolute `https` URL naming a supported AWS S3 endpoint. Elasticsearch accepts the following endpoint forms. Every AWS partition supports the regional, historical, and VPC interface forms, and only the commercial partition supports the global form:
    </dropdown>
    - Regional: `https://s3.us-east-1.amazonaws.com`
    - Historical: `https://s3-us-west-2.amazonaws.com`
    - VPC interface: `https://bucket.vpce-0a1b2c3d.s3.us-east-1.vpce.amazonaws.com`
    - Global: `https://s3.amazonaws.com`
    A regional endpoint must name a region that your Elasticsearch version knows about. Elasticsearch rejects a region that AWS added after that release until you upgrade, or until a node permits its host with `esql.external.allowed_endpoint_hosts`.
    <note>
      `https://s3.amazonaws.com` has no region. When you set `endpoint`, the AWS SDK stops following cross-region redirects, so this global endpoint only reaches `us-east-1` buckets. Other regions get an error. Omit `endpoint` to let the AWS SDK resolve the correct regional endpoint from the `region` setting.
    </note>
    Elasticsearch rejects every other AWS endpoint family, including FIPS endpoints, dual-stack endpoints, transfer acceleration, access points, object lambda, Outposts, the account-level control plane, the legacy `s3-external-1` alias, and S3 Express. It also rejects a bucket-qualified endpoint such as `https://mybucket.s3.us-east-1.amazonaws.com`. Name the regional endpoint instead, and let the bucket come from the dataset. It also rejects plain `http`, a value without a scheme, and a host that the URL syntax doesn't allow, such as one with an underscore or a non-numeric port.
    A node can permit additional hosts with the `esql.external.allowed_endpoint_hosts` node setting, a list of `host:port` patterns in `elasticsearch.yml` that defaults to empty. A host it names is also accepted over plain `http` for `endpoint`. The `sts_endpoint` setting always requires `https`.
    <warning>
      A data source created before these endpoint restrictions were introduced keeps working for queries, but updating it requires an endpoint that meets these requirements.
    </warning>
  </definition>
</definitions>


<definitions>
  <definition term="addressing_style Elastic Stack: Planned">
    The URL addressing style for S3 requests.
    - **Default:** `auto`
    - **Valid values:**
      - `auto`: Uses path-style when `endpoint` is set, and the AWS SDK default otherwise.
    - `path`: Always uses path-style.
    - `virtual_hosted`: Lets the AWS SDK decide. Bare-IP endpoints fall back to path-style.
    - **Related:** `endpoint`
    Because `auto` resolves to path-style whenever `endpoint` is set, set `virtual_hosted` if reads through a VPC interface endpoint fail with an addressing error.
  </definition>
</definitions>


<definitions>
  <definition term="region Elastic Stack: Planned for deprecation, Elastic Stack: Experimental in 9.5">
    The AWS region used for the S3 client.
    <applies-to>Elastic Stack: Planned</applies-to> The `region` setting on a data source is deprecated and has no effect. Set `region` in the [dataset settings](/elastic/docs-builder/docs/4492/reference/query-languages/esql/esql-data-federation-dataset-settings#amazon-s3-region) instead, or omit it to let Elasticsearch detect the region automatically. When no `endpoint` is set, the AWS SDK redirects transparently. When one is set, Elasticsearch issues a `HeadBucket` probe on the first request and caches the discovered region. The cache is cleared after a few minutes without requests, and the next request discovers the region again.
    <applies-to>Elastic Stack: Experimental in 9.5</applies-to> Set `region` on the data source. Datasets don't accept a `region` setting.
  </definition>
</definitions>


### Authentication settings

These settings select the [authentication model](/elastic/docs-builder/docs/4492/reference/query-languages/esql/esql-data-federation-sources#authentication) and supply the values it needs. For the AWS Identity and Access Management (IAM) permissions the configured identity needs, refer to [grant read access in Amazon S3](/elastic/docs-builder/docs/4492/reference/query-languages/esql/esql-data-federation-s3#s3-permissions).

<definitions>
  <definition term="auth">
    The authentication model the data source uses.
    - **Default:** `auto`
    - **Valid values:**
      - `auto`: Infers the model from the other settings. Federated identity settings such as `role_arn` select `federated_identity`, and `access_key` with `secret_key` selects `static_credentials`. A data source with both, or with neither, is rejected. `auto` never selects `anonymous` or `managed_identity`, so set those explicitly.
    - `anonymous`
    - `static_credentials`
    - `managed_identity`
    - `federated_identity`
    The **Requires** line on each of the following settings names the model the setting belongs to. When `auth` is `auto` or omitted, it refers to the model Elasticsearch infers.
  </definition>
</definitions>


<definitions>
  <definition term="access_key">
    The AWS access key ID.
    - **Default:** None
    - **Requires:** `auth` set to `static_credentials`
    - **Related:** `secret_key`, `session_token`
  </definition>
</definitions>


<definitions>
  <definition term="secret_key">
    The AWS secret access key.
    - **Default:** None
    - **Requires:** `auth` set to `static_credentials`
    - **Related:** `access_key`, `session_token`
  </definition>
</definitions>


<definitions>
  <definition term="session_token">
    The AWS session token for temporary security credentials issued by AWS Security Token Service (STS).
    - **Default:** None
    - **Requires:** `auth` set to `static_credentials`, with `access_key` and `secret_key` from the same temporary credentials
    - **Related:** `access_key`, `secret_key`
    Temporary credentials expire. When they do, requests from the data source fail until you update all three values with new credentials.
  </definition>
</definitions>


<definitions>
  <definition term="role_arn">
    The Amazon Resource Name (ARN) of the IAM role Elasticsearch assumes through STS.
    - **Default:** None. Required when `auth` is set to `federated_identity`.
    - **Requires:** `auth` set to `federated_identity`
    - **Related:** `jwt_audience`, `role_session_name`, `sts_endpoint`, `sts_region`
  </definition>
</definitions>


<definitions>
  <definition term="jwt_audience">
    Overrides the JWT audience claim sent to STS.
    - **Default:** `sts.amazonaws.com`
    - **Requires:** `auth` set to `federated_identity`
    - **Related:** `role_arn`
  </definition>
</definitions>


<definitions>
  <definition term="role_session_name">
    A label for the assumed-role session.
    - **Default:** `elasticsearch-esql-datasource`
    - **Requires:** `auth` set to `federated_identity`
    - **Related:** `role_arn`
  </definition>
</definitions>


<definitions>
  <definition term="sts_endpoint Elastic Stack: Planned">
    An STS endpoint override, for example `https://sts.us-east-1.amazonaws.com`.
    - **Default:** None
    - **Valid values:** An absolute `https` URL that meets the same [S3 endpoint requirements](#s3-endpoint-requirements) as `endpoint`, but for STS hosts
    - **Requires:** `auth` set to `federated_identity`
    - **Related:** `sts_region`
    Any host permitted through `esql.external.allowed_endpoint_hosts` receives the node's OIDC token, so only add hosts on trusted network paths.
  </definition>
</definitions>


<definitions>
  <definition term="sts_region">
    The AWS region of the STS endpoint.
    - **Default:**
      - <applies-to>Elastic Stack: Planned</applies-to> The dataset's `region` setting, or `us-east-1` if the dataset has no region
    - <applies-to>Elastic Stack: Experimental in 9.5</applies-to> The data source's `region` setting, or `us-east-1` if no region is set
    - **Requires:** `auth` set to `federated_identity`
    - **Related:** `sts_endpoint`, `region`
    <applies-to>Elastic Stack: Planned</applies-to> A `region` set on the data source no longer applies to STS. If a `federated_identity` data source relied on it, set `sts_region` on the data source, or `region` on each dataset, to keep calling STS in that region.
  </definition>
</definitions>