docs: BI docs twins — publish the structural gaps, retire the Custom SQL workaround

documentation/client/bi_tools.md

@@ -2,21 +2,37 @@
 
 SoftClient4ES connects to common BI and SQL tools through the **JDBC driver** (`jdbc:elastic://host:port`, driver class `app.softnetwork.elastic.jdbc.ElasticDriver`) or the **Arrow Flight SQL** server (`grpc://host:32010`).
 
-Full, step-by-step guides — connect, browse your indices, and run a cross-index JOIN — live on the website. This page is an index; the website carries the screenshots and per-tool detail.
+Where a supported connection path exists, a full step-by-step guide — connect, browse your indices, and run a cross-index JOIN — lives on the website. This page is an index; the website carries the screenshots and per-tool detail, and states the blocker for the tools that cannot connect.
 
-## Tested vs Compatible
+## Tested, Compatible, Unproven, and no path today
 
-**Tested** tools are exercised against SoftClient4ES. **Compatible** tools speak a working protocol but have not been through formal regression (best-effort).
+Four tiers, each a different claim:
 
-| Tool | Tier | Path | Guide |
+- **Tested** — exercised against SoftClient4ES.
+- **Compatible** — speaks a working protocol, but has not been through formal regression (best-effort).
+- **Unproven** — a connection path exists on paper, but nobody has connected it yet. Not a promise.
+- **No path today** — cannot connect without software that does not exist, for reasons on the tool's
+  own side.
+
+| Tool | Status | Path | Guide |
 |---|---|---|---|
 | Apache Superset | Tested (dedicated dialect) | Arrow Flight SQL | https://softclient4es.dev/integrations/superset/ |
 | DBeaver | Tested | JDBC or Arrow Flight SQL | https://softclient4es.dev/integrations/dbeaver/ |
 | Grafana | Tested (via Arrow Flight SQL) | Arrow Flight SQL | https://softclient4es.dev/integrations/grafana/ |
 | Tableau | Compatible (not formally tested) | JDBC | https://softclient4es.dev/integrations/tableau/ |
-| Power BI | Compatible (not formally tested) | JDBC | https://softclient4es.dev/integrations/power-bi/ |
-| Metabase | Compatible (not formally tested) | JDBC | https://softclient4es.dev/integrations/metabase/ |
+| Power BI | **Unproven** — Power Query's generic connectors are ODBC and OData, never JDBC. The one candidate path is a generic Arrow Flight SQL ODBC driver pointed at the sidecar; it has not been connected yet | ODBC (unproven) | https://softclient4es.dev/integrations/power-bi/ |
+| Metabase | **No path today** — Metabase has no generic JDBC database type. Connecting needs a community driver plugin, and we do not ship one | — | https://softclient4es.dev/integrations/metabase/ |
+| Looker | **No path today** — Looker-maintained drivers only, with a per-dialect JDBC parameter allowlist. Structural, not commercial: a licence would not close it | — | — |
+
+*(Each blocker was checked against the vendor's own connection documentation — Metabase, Microsoft
+Power Query and Looker — on 2026-08-31 and 2026-09-01.)*
 
 ## Honest-gap note
 
-Every tool runs the superpower of this release — a **cross-index JOIN** that Elasticsearch can't do — best through explicit `JOIN … ON …` SQL. Some BI tools auto-generate nested subqueries (Tableau live connections, Power BI DirectQuery relationships, the Metabase GUI Question builder); subqueries and CTEs are not in this release yet. Use Extract / Import / Native-SQL mode with explicit JOINs as the workaround. Full BI-tool subquery / CTE support is coming in the next release (Quarter 4 2026). See the website's Known Limitations page for the full picture.
+The superpower of this release is a **cross-index JOIN** that Elasticsearch can't do, and it runs best
+through explicit `JOIN … ON …` SQL — from any tool where you control the statement that is sent (Superset
+SQL Lab, DBeaver, Grafana). Some BI tools compose SQL for you: subqueries and CTEs are not in this release
+yet, and neither is the quoted, fully-qualified identifier form Tableau generates. Tableau's Custom SQL is
+not a way around that — Tableau wraps a custom query inside a `SELECT … FROM ( … )`, which is a derived
+table (Tableau's Custom SQL documentation, checked 2026-09-01). Full BI-tool subquery / CTE support is coming in the next release (Quarter 4 2026). See the
+website's Known Limitations page for the full picture.

documentation/sql/known_limitations.md

@@ -8,16 +8,50 @@ SoftClient4ES runs a large, practical subset of ANSI SQL on Elasticsearch — in
 
 ## Using a BI tool? Read this first
 
-If your BI tool just failed on a subquery or a CTE, you're in the right place. Some BI tools auto-generate nested SQL (subqueries / derived tables) even when your logical query has none. Until the next release lands full subquery support, send **explicit JOIN SQL** instead of letting the tool compose nested queries:
+Two different things can stop a BI tool here, and it is worth separating them.
 
-- **Tableau** — Tableau **live** connections can auto-generate subqueries. Use **Extract** mode (Tableau runs the extract locally, subquery-free), or write **Custom SQL** with explicit JOINs instead of letting Tableau compose the query.
-- **Power BI** — DirectQuery / query folding can compose nested SQL. Prefer **Import** mode (folds locally, nothing nested is pushed), or author explicit-JOIN queries; avoid relationships that force generated subqueries until the next release.
-- **Looker** — BI tools that build **derived tables / measures** (e.g. Looker) can compose subqueries. Model **explicit JOINs** in the SQL the tool sends rather than relying on tool-composed derived tables; avoid symmetric-aggregate measures that force derived tables until the next release.
-- **Metabase** — the GUI Question builder can emit subqueries for multi-stage questions. Use **Native (SQL)** queries with explicit `JOIN … ON …` instead of the visual builder for any query that would otherwise nest.
+### One tool has a path nobody has walked yet
 
-> **General rule:** prefer **explicit JOIN SQL** over tool-generated nested SQL. If you control the query, a cross-index JOIN is fully supported in the current release.
+- **Power BI** — Power Query's generic connectors are ODBC and OData, never JDBC. The one candidate path
+  is a generic Arrow Flight SQL ODBC driver pointed at the sidecar. It is **unproven**: nobody has
+  connected it, so treat it as a lead to follow rather than a supported route.
+  See [Power BI](../client/bi_tools.md).
 
-Tableau, Power BI, and Metabase are **Compatible** (work via the JDBC/ADBC spec, not formally tested by us). **Apache Superset** (dedicated dialect), **DBeaver**, and **Grafana** (via Arrow Flight SQL) are **Tested**.
+### Some tools cannot connect at all — and that is on their side
+
+- **Metabase** — no generic JDBC database type exists; anything not on Metabase's own driver list needs a
+  community driver plugin, which is code nobody has written for SoftClient4ES. See [Metabase](../client/bi_tools.md).
+- **Looker** — Looker connects only through drivers it maintains itself, and it allowlists JDBC parameters
+  per dialect, so a customer-supplied driver cannot be introduced. This gap is **structural, not
+  commercial** — a licence would not close it.
+
+Neither is a gap we can close from our side: each needs either a change by the vendor or a driver plugin
+that nobody has written.
+
+*(Each blocker checked against the vendor's own connection documentation — Metabase, Microsoft Power Query
+and Looker — on 2026-08-31 and 2026-09-01.)*
+
+### Tools that connect, but generate SQL we do not accept yet
+
+Some BI tools auto-generate nested SQL (subqueries / derived tables) even when your logical query has none.
+Until the next release lands full subquery support, send **explicit JOIN SQL** instead of letting the tool
+compose nested queries — where the tool lets you:
+
+- **Apache Superset / DBeaver / Grafana** — you control the SQL. Write explicit JOINs for anything that
+  would otherwise nest, and everything in **Works in this release** below is available to you.
+- **Tableau** — connecting and browsing work; queries are the constrained part. Drag-and-drop worksheets
+  quote and fully qualify every identifier, a form we do not accept yet, and **Custom SQL is not a way
+  around it**: Tableau documents that it *"must wrap the custom SQL statement within a select statement"* (Tableau's Custom SQL
+  documentation, checked 2026-09-01),
+  which turns your query into a derived table. **Extract** mode narrows the exposure but does not remove
+  it — the extract is still built by querying the source.
+  See [Tableau](../client/bi_tools.md).
+
+> **General rule:** prefer **explicit JOIN SQL** over tool-generated nested SQL. If you control the query, a
+> cross-index JOIN is fully supported in the current release.
+
+**Apache Superset** (dedicated dialect), **DBeaver**, and **Grafana** (via Arrow Flight SQL) are **Tested**.
+**Tableau** is **Compatible** — the connection path works, but it is not yet in our formal regression suite.
 
 ## Works in this release