SQL interoperability
FeatureQL is the language of record. SQL interoperability lets existing clients, BI tools, and warehouses use that record without adopting a separate semantic definition.
Three doors
| Door | What you author | What the client sees | When to use it |
|---|---|---|---|
| Hybrid queries | FEATUREQL(...) inside /* SQL */ | A subquery or CTE that compiles FeatureQL on each request | Ad-hoc SQL around live FeatureQL, BI wrappers, incremental adoption |
| Persisted views | CREATE VIEW FMV.schema.table AS a FeatureQL query | A frozen SQL relation named fmv.schema.table | A stable table for JDBC, Flight SQL, and warehouse scans |
| JDBC catalog | The same views | SHOW JDBC/* / JDBC metadata: catalog fmv, TABLE_TYPE VIEW | Tools that discover tables before they run SQL |
Pick one door per task. Hybrid recompiles FeatureQL every time. A view compiles FeatureQL once (DuckDB, Trino, and serving) and stores SQL artifacts; later scans substitute that SQL and do not re-parse FeatureQL.
The FeatureQL body is the same on those engines when the compiler can rewrite SQL to match. What it normalizes, and what the engine still owns: Same answer across backends .
Language mode
:8101 and FeatureQL HTTP stay FeatureQL unless you mark the request:
/* FEATUREQL */ -- parse as FeatureQL (the default on :8101)
/* SQL */ -- parse as SQLJDBC and Flight SQL are SQL by protocol, so those clients do not need /* SQL */. An unmarked FROM FMV.… on :8101 is still FeatureQL, and a persisted view is not a FeatureQL source (UE/VIEW-NOT-A-FEATUREQL-SOURCE). Scan the view with /* SQL */ or through JDBC.
What this section is not
The opposite direction — SQL into FeatureQL — lives elsewhere:
- Mapping data sources pulls warehouse tables and configured serving sources into the feature graph.
- External JDBC is a serving source, not the catalog of persisted views.
CREATE FEATURES still persists FeatureQL definitions under FM.. A view persists a compiled SQL artifact under FMV.. You cannot store a /* SQL */ block as a feature.
Next
Start with hybrid queries if a SQL tool must wrap live FeatureQL. Start with persisted views if that tool should see an ordinary table. If you are choosing DuckDB vs Trino vs serving, read Same answer across backends first. To have queries read values your own orchestrator precomputed, follow Datakey caches . Declarations a mapping makes about columns and keys, which the compiler trusts without reading the warehouse, are Data contracts .