Connect an Elasticsearch or OpenSearch cluster

FlatQL talks to the cluster over its HTTP API with the credential you give it. Nothing is installed on the cluster, no plugin, no agent and no extra cluster user.

What you need#

• The endpoint URL, for example https://es.example.internal:9243, or an Elastic Cloud ID.
• One credential: an API key, a username and password, or a bearer token.
• Read access to the indices you want to query, whether you write SQL or raw Query DSL requests.

Open Connections, choose New connection, and work down the form. Every section below matches a section of that form.

01 Basics: name, environment, endpoint#

Give the connection a name (letters, digits, dashes) and pick an environment: Production, Staging or Local. Production turns on write confirmations by default, and your workspace guardrails can make production connections start read-only.

URL#

Enter scheme, host and port:

https://es.example.internal:9243

If you omit the scheme FlatQL assumes http://. Plain http:// to a production cluster shows a warning because credentials would travel unencrypted.

Elastic Cloud ID#

Switch the endpoint field to Cloud ID and paste the value from the deployment page:

my-deployment:dXMtY2VudHJhbDEuZ2NwLmNsb3VkLmVzLmlvJGFiYyRkZWY=

Press Decode. FlatQL turns the Cloud ID into the https://<es-uuid>.<host>:443 endpoint and fills the URL field, which you can still edit. Pair it with an API key from the same deployment.

02 Authentication#

API key#

Paste the encoded value returned by POST /_security/api_key. If you only have the two parts, choose enter id and key separately; FlatQL base64-encodes id:api_key for you. A key pasted as id:api_key in plain text is encoded as well.

Basic auth#

Enter the username and password. The password is stored encrypted on the server and never shown again; the form only tells you a secret is stored.

Amazon OpenSearch Service#

Use the domain endpoint as the URL and Basic with the master user name and password. FlatQL does not sign requests with IAM credentials (SigV4), so the domain needs user and password access rather than IAM-only access.

Note Amazon OpenSearch Service answers 401 "Your request: '/x' is not allowed" for APIs the domain does not expose. FlatQL reports this as a rejected path, not as bad credentials.

03 Access layer#

If the cluster sits behind an identity proxy or a bastion, pick one:

• Cloudflare Access: a service token sent as CF-Access-Client-Id and CF-Access-Client-Secret.
• Custom headers: for Nginx, Kong, Traefik and similar gateways that expect a header such as X-Api-Key.
• SSH tunnel: bastion host, port, user, private key path or password, and the remote host and port as seen from the bastion. FlatQL opens the tunnel and dials 127.0.0.1 on a local port.

04 TLS for self-hosted clusters#

Verify server certificate is on by default. Turn it off only for a local cluster with a self-signed certificate you trust. For a private CA paste the PEM into Custom CA certificate. Clusters that require client certificates (mTLS) take a certificate and private key in PEM format under Client certificate.

05 Safety and defaults#

Read-only mode blocks PUT, POST, DELETE and bulk writes for this connection. GET, HEAD and OPTIONS always pass, and so do the POST endpoints that only read: _search, _count, _msearch, _field_caps, _sql, _plugins/_sql, _explain, _mget and the scroll and point-in-time endpoints. A team owner or admin can switch writes on for a session; the change is written to the audit log.

Confirm destructive operations asks before deletes and similar requests, and Require typing the index name to delete it adds a second check for index deletes.

Two timeouts:

Lower the connect timeout so a cluster that is down reports it sooner instead of spending the whole request timeout. A Default index pattern such as companies_* is pre-selected in Browse and the console.

Test the connection#

Test runs five steps in order and stops at the first failure: DNS, TLS, Access layer, Authentication, Cluster. Authentication calls GET /_security/_authenticate, falls back to GET /_plugins/_security/api/account on OpenSearch, and reports the user and the first few roles. The cluster step shows the name, version, distribution, node count and health. What gets sent shows the exact request and has Copy as curl for debugging outside FlatQL.

Permissions the credential needs#

FlatQL runs these calls on your behalf:

• GET /<index>/_field_caps to read field types
• POST /<index>/_search, including scroll, plus POST /_search/scroll and DELETE /_search/scroll
• GET / and GET /_cluster/health during the connection test

A role that can search the indices and read their field capabilities is enough. Writes are only ever sent when you run an Elasticsearch request such as PUT or DELETE yourself, and read-only mode blocks those.

Next: run your first query. For how teams share connections without handing out credentials, see Teams and Security. For the wider picture of what FlatQL does once connected, see FlatQL as an Elasticsearch GUI.