Working with an assistant

A simple loop for getting a FeatureQL query right — useful whether you type every call yourself or an assistant drives the same Python / HTTP / MCP tools. For the language itself, see FeatureQL for the Impatient .

1. Give the model a small amount of FeatureQL context

Ask for (or load yourself):

client.help("mental_model", "getting_started")

For harder modeling, add getting_started_more and query_methodology. Pull tags like extend or related only when the query needs them. Pasting the whole documentation site into a prompt is slower and noisier than these short help pages.

Static copies of the same corpus: /llms/getting_started.md and /llms/index.md .

2. Draft, then validate

Write ordinary FeatureQL. Run validate before you trust a result:

• Fix reported errors first (use the error code and location)
• Keep working from the returned formatted_featureql when it differs from your draft
• Skim the feature list for unexpected grain or dependency layers
• Read warnings by their code; only acknowledge ones you have reviewed

3. If the failure is hard to locate, diagnose

diagnose runs the query one feature at a time and stops at the first bad step. Look at which feature was added, the error code, and any dependency path in the response. Shrink the query to that feature plus what it needs, fix it, validate again.

4. Run when the graph looks sound

query returns rows (and the generated SQL). Use translate only when you want SQL without execution.

Pass FeatureQL to query — not SLT test harness text. To assert expected rows against the test runner, use sltest ( Conformance tests ).

5. Optionally assert expected rows

When you already know the answer, sltest can check it in one shot (handy for assistants that should not “eyeball” a DataFrame):

client.sltest(source="""
SELECT
    NAME := 'check#001.ok',
    CONTENT := '# schema: BIGINT|BIGINT
query A:I,B:I
SELECT A := 1, B := A + 1;
----
1	2
';
""")

Details and pitfalls: Conformance tests (including where / limit depends expansion via a DuckDB fetch client, and transient retries).

6. Reuse session state on a long-lived stack

If you use the demos HTTP/MCP stack, tables and persisted features loaded once stay available until the process restarts. Load setup once, then iterate with validate/query — you do not need to re-run the whole conformance file for every edit.

Same tools everywhere

See also

• Overview
• Productivity tools
• Conformance tests
• FeatureQL with AI — how to connect an assistant