Productivity tools

Helpers around query for when you are writing FeatureQL in a notebook, a script, or with an assistant. The same methods exist in Python, over HTTP, and as MCP tools. Field-level HTTP detail is in HTTP Batch API .

validate — check a draft before you trust it

validate does not return business rows. It:

1. Normalizes syntax with FORMAT (FIX)
2. Builds the feature graph (types, grain, dependencies)
3. Dry-runs the generated SQL when an executor is available

result = client.validate("""
    SELECT A := 1, B := A + 1;
""")
print(result.formatted_featureql)
print(result.output_schema)
print(result.warnings)

Use validate while you are still shaping the query; switch to query when you want real results.

diagnose — find the first broken feature

When a large query fails and the error is hard to place, diagnose adds features one at a time and stops at the first failure.

result = client.diagnose("""
    SELECT A := 1, B := CONCAT(1, 2) + A;
""")
print(result.failed_step)
print(result.steps[result.failed_step].error)

Each step’s error is a list of objects with code, message, location, and sometimes a dependency path. Fix the failing feature, validate again, then run.

help — look up concepts and examples

client.help("mental_model", "getting_started").display()
client.help("extend", detail="full", examples=3)

Start with mental_model and getting_started. Fuzzy search: help("?", "rolling"). The same pages are what a connected assistant should load instead of scraping the website.

describe — inspect persisted features

client.describe("FM.DEMO.").display()

Pass at least one namespace prefix. Useful after CREATE FEATURES, and before you ask someone (or an assistant) to build on a shared registry.

Warnings you can acknowledge

Some warnings include an ACK token (ACK-EXWX…). After you have reviewed the warning and accept it, put that token in a comment on the query so it stops repeating. Works the same on validate and query.

Conformance tests (sltest)

Running the documentation suite — filters, # depends:, selective runs, multi-backend checks — is covered here:

→ Conformance tests

To assert contracts of these productivity methods (and translate) inside SLT without pinning full payloads, use # match: jmespath + client validate|help|describe|diagnose|translate — see the focused-payloads section on that page.

What Python returns

Next

• Conformance tests
• Working with an assistant
• HTTP Batch API