FlatQL FAQ: SQL on Elasticsearch, answered
The questions people ask before and after connecting a cluster, with a link to the page that has the long answer.
How to use this page#
Each answer below is deliberately short and points at the page with the details, the exact rules or the SQL example. If your question is about an error message, start with troubleshooting; if it is about what SQL is supported, start with the SQL overview. For a tour of the product from the first connection to the first pushed-down query, read querying Elasticsearch with SQL. Anything not covered here goes to the contact page.
Questions
Does FlatQL install anything on the cluster?
No. It uses the HTTP API with the credentials you give a connection. No plugin, no agent, no cluster users for team members. See security.
Which Elasticsearch and OpenSearch versions work?
Elasticsearch 6 to 9 and OpenSearch 1 to 2, on Elastic Cloud, Amazon OpenSearch Service, Open Distro and self-hosted clusters. See connect a cluster.
Can I JOIN two indices?
Yes. Each index is fetched with its filters pushed to the cluster and the join runs in the embedded engine, on at most about 50,000 rows per index per statement. See joins.
What runs on the cluster and what runs in FlatQL?
Filters, sorts, limits and GROUP BY that translate exactly become Query DSL. JOINs, CTEs, window functions, UNION, HAVING and QUALIFY run in the engine. Every result shows the split. See pushdown.
Why did my statement scan 50,000 rows?
Part of its WHERE clause could not be sent to the cluster, so the index was read up to the fetch cap and filtered in the engine. Rewrite the predicate as a plain comparison on a filterable field. See troubleshooting.
Can I see the Query DSL my SQL became?
Yes. The DSL view next to every result shows the exact request body per index, and query history keeps it. See Show as DSL.
Can I use the cluster's own SQL instead?
Yes. Cluster SQL mode sends the statement to x-pack SQL or the OpenSearch SQL plugin as-is, without joins or subqueries. See Cluster SQL mode.
How large an export can I make?
Up to 5,000,000 rows per download to CSV, TSV or JSON, streamed straight to the file. Excel files stop at 100,000 rows. Exports need Pro. See export.
Does Ask FlatQL run queries on its own?
No. It writes SQL or DSL into the worksheet and explains it; nothing runs until you press Run. Free includes 20 questions a day. See Ask FlatQL.
Can team members use a connection without seeing its password?
Yes. Credentials are encrypted on FlatQL's servers and never shown again. Members get read or write grants per index pattern, checked on every request. See teams.
Who can see the query history?
Owners and admins see every statement in the team; members see their own. Free keeps one day, Pro keeps everything. See query history.
Can I load a CSV into a new index?
Yes, on Pro. CSV, Excel, JSON, NDJSON or a paginated JSON API, previewed first and loaded in batches of 1,000. See load data.
My cluster is on localhost or behind a VPN. Can FlatQL reach it?
Not from the web app, which calls the cluster from FlatQL's servers. The desktop app runs on your machine and reaches whatever it can. It is coming soon, macOS first. See desktop app.
Where are my credentials stored?
On the web, encrypted at rest with a key kept apart from the database. In the desktop app, encrypted locally with a key in the OS keychain. See security.
Does FlatQL keep my result rows?
No. Rows pass through for the duration of a request or export and are not retained. Query history stores the statement and its metrics only. See security.
Is Pro a subscription?
No. Pro is a $199 one-time licence per user that never renews. Free covers one cluster with the full engine. See pricing and licensing.
Why does my text field not GROUP BY?
A text field is analysed and cannot be aggregated on the cluster; FlatQL uses its keyword sub-field when there is one. Map the field as keyword, or query the sub-field. See keyword vs text.