Query tools

FeatureQL includes built-in tools for inspecting, debugging, and exploring your features — all accessible from within the query language itself.

Inspecting queries with EXPLAIN

Prefix any query with EXPLAIN to see the generated SQL, output schema, and entity relationships without executing it:

EXPLAIN SELECT feature1 := 1, feature2 := feature1 + 1;

This is the fastest way to check what SQL FeatureQL will produce for a given query. The query_sql field shows the CTE structure, query_outputs lists the result columns with their types, and entities shows any entity relationships discovered.

Inspecting features with DESCRIBE

DESCRIBE shows metadata about a specific feature — its function, parameters, dependencies, and type information:

CREATE TEMPORARY FEATURES AS SELECT feature1 := 1, feature2 := feature1 + 1;
DESCRIBE FEATURE2;

Use this when you need to understand how a feature is defined, what it depends on, or what type it produces. It works with both temporary and persisted features.

Formatting queries with FORMAT

FORMAT rewrites a query into its canonical form without executing it. This is useful for normalizing syntax and auto fixing non strict constructs.

Use FORMAT (ESCAPED) to get output with markers instead of actual newlines, which is useful for programmatic comparisons.

Strict mode and FIX

By default, FeatureQL operates in strict mode. Constructs like STRUCT, LIST, and type aliases like INT64 are rejected. Add /* NON-STRICT */ to bypass strict checks, and combine with FORMAT (FIX) to rewrite them into canonical forms:

@fql-playground(fix_combined_struct_list_escaped)

FIX rewrites STRUCT to ROW(...), LIST to ARRAY[...], normalizes bracket/parenthesis mismatches on ROW and ARRAY, and moves BIND_VALUES from the WITH clause to a FOR clause.

Alias normalization

FORMAT always normalizes function aliases (LEN → LENGTH, MOD → MODULO, POWER → POW, NOW → CURRENT_TIMESTAMP) and type aliases (INT64 → BIGINT, FLOAT64 → DOUBLE, STRING → VARCHAR, BOOL → BOOLEAN, INTEGER → INT) to their canonical names.

@fql-playground(func_alias_multiple)

Recreating features with SHOW CREATE

SHOW CREATE FEATURES returns the FeatureQL code needed to recreate one or more features. This is useful for understanding how features are stored internally and for exporting definitions.

For temporary features:

START TRANSACTION;
CREATE TEMPORARY FEATURES AS SELECT feature1 := 1, feature2 := feature1 + 1;
SHOW CREATE FEATURES FEATURE1, FEATURE2;
COMMIT;

Notice that FeatureQL reorders features by dependency layer and may rewrite syntax — 1 becomes VALUE(1), for example. The semantics are preserved even when the surface syntax changes.

For persisted features, the output includes full namespace paths:

CREATE OR REPLACE FEATURES AS
SELECT
    FM.TUTORIALS.QUERYTOOLS.FEATURE1 := 1,
    FM.TUTORIALS.QUERYTOOLS.FEATURE2 := FM.TUTORIALS.QUERYTOOLS.FEATURE1 + 1
;

SHOW CREATE FEATURES FM.TUTORIALS.QUERYTOOLS.FEATURE2;

Features are topologically ordered by their dependency graph, making the output self-contained — you can run it directly to recreate the features.

Cross-dialect SQL output

Specify a target dialect to see the actual SQL that would run in a specific backend:

SHOW CREATE FEATURES (LANGUAGE DUCKDB)
    FM.TUTORIALS.QUERYTOOLS.FEATURE1,
    FM.TUTORIALS.QUERYTOOLS.FEATURE2
;

Supported dialects: DUCKDB, TRINO, BIGQUERY, DATAFUSION. The output includes CTEs, stage comments, and dialect-specific syntax — useful for understanding how FeatureQL maps to your backend.

Exploring documentation

SHOW DOCS lets you search the built-in documentation without leaving the query environment:

SHOW DOCS (
    EXCLUDE (content),
    INCLUDE (LENGTH(name) as lname)
)
WHERE lname>30 and category = 'DOC_PAGE'
ORDER BY name ASC
LIMIT 5

Filter by category, search content with LIKE, and sort results to find relevant pages, code samples, and function references. Combined with SHOW FUNCTIONS and SHOW SIGNATURES (covered in Operators & Functions ), these tools make FeatureQL largely self-documenting.

Warnings

FeatureQL returns warnings alongside successful translation or execution (for example UNUSED-FEATURE when a WITH feature is not reachable from the SELECT list). They do not block the query; they surface in query(), translate(), validate(), and the warnings field on API responses.

Each warning includes a stable acknowledgement token derived from its code and message, appended as (acknowledge with ACK-XXXX). To silence a warning you accept, put that token in any line or block comment in the same query (-- ACK-XXXX or /* … ACK-XXXX … */); placement does not matter. A comment that contains an ACK-XXXX token with no matching warning produces STALE-WARNING-ACK — remove the leftover token from the query.

Client-side productivity tools

The Python client (BatchClient) wraps the query tools above into higher-level methods designed for iterative development and LLM-assisted workflows. Each method orchestrates one or more FeatureQL queries and returns structured results.

All four return a result object with .text (markdown) and structured fields. Call .display() in a notebook to render the markdown directly.

These methods are also exposed as HTTP endpoints (POST /validate, /diagnose, /help, /describe on port 8101) and as MCP tools for LLM agents.

Code samples

They represent end to end tests for capabilities. They use the SLT formalism to describe the test.

# name_of_the_test
query FEATURE1:I,FEATURE2:I,?:I [rowsort]
SELECT
    FEATURE1 := 1,
    FEATURE2 := 2,
    FEATURE1 + FEATURE2
;
----
1   2   3

The line query represent the expected output of the query: column names and types.

Types in SLT queries are represented as: