Skip to main content
Connect Elasticsearch to Basedash to run SQL analytics on your indices and data streams. Basedash connects directly through the Elasticsearch SQL API and queries your data in place. This works with Elastic Cloud and self-hosted clusters.

​
Prerequisites

  • An Elasticsearch cluster with the SQL API enabled
  • The Elasticsearch REST endpoint for your cluster
  • An API key, or a username and password, with read access to the indices you want to query

​
Connection setup

  1. Open the Data page and click Add data source
  2. Select Elasticsearch
  3. Enter your Elasticsearch endpoint (e.g., https://example.es.cloud.es.io:443). Use the Elasticsearch REST URL, not the Kibana URL, and include the port if needed
  4. Choose an authentication method:
    • API key: paste the encoded API key from Elasticsearch
    • Username and password: enter the credentials for a dedicated user
  5. Click Connect. Basedash checks the connection, then opens the new data source and starts syncing its schema.
The Elasticsearch connection form in Basedash with an Elasticsearch endpoint filled in and API key selected as the authentication method

​
Required permissions

Grant the API key or user these index privileges on the indices and data streams you want to query:
  • read
  • view_index_metadata

​
Best practices

  • Create a dedicated API key or user for Basedash
  • Limit privileges to the indices Basedash needs
  • Regularly rotate API keys and passwords

​
Troubleshooting

For what each connection error means and how to fix it, see Connection settings.
  • If you see an “SQL endpoint not found” error, check that you used the Elasticsearch endpoint (not Kibana) and that the SQL API is enabled
  • Verify the API key or user has read and view_index_metadata on the target indices
  • Use unique column aliases in SQL; Elasticsearch rejects results with duplicate column names

​
Next steps: Add custom context

You can add custom context to help the AI better understand your data structure and business logic. Consider adding context at the database or schema level if you notice the AI struggling to locate or understand specific data.

​
When to add context

  • Nested or object fields: When the AI needs help understanding document structure
  • Unclear naming conventions: If index or field names don’t clearly indicate their purpose
  • Time-based indices: When the AI should know which index pattern or timestamp field to use
For detailed guidance, see our custom context documentation.