Client tooling overview
Once you leave the browser playground, FeatureQL runs through a client — usually the Python library, sometimes an HTTP service or MCP tools for an assistant. This section covers that client surface: how to run queries, check drafts, look up help, and run the conformance suite on the databases you already use.
You do not need this to learn the language. Come here when FeatureQL should live in a notebook, a script, CI, or a local stack next to your warehouse.
Pick how you want to work
The same operations exist in three places. Most people start with Python.
| How you work | What you use |
|---|---|
| Notebooks, scripts, data science workflows | BatchClient — pip install featuremesh |
| An AI assistant with tool calling | Local MCP tools (featuremesh_query, featuremesh_validate, …) |
| Your own service / automation talking HTTP | The Batch HTTP API on the demos or self-hosted stack |
from featuremesh import BatchClient
client = BatchClient()
client.query("SELECT F := 1;") # run and get a DataFrame
client.validate("SELECT F := 1;") # format, types, dry-run
client.help("getting_started") # concepts and examples
client.sltest(where="NAME LIKE '%array%#%'") # run conformance testsIf you use HTTP or MCP instead, the names match: client.query ↔ POST /query ↔ featuremesh_query.
What the operations do
| You want to… | Call |
|---|---|
| Run FeatureQL and get rows | query |
| See the generated SQL without running it | translate |
| Check a draft (formatting, types, feature graph) before trusting results | validate |
| Pinpoint which feature in a large query is failing | diagnose |
| Look up concepts, signatures, and runnable examples by name | help |
| Inspect features you already persisted under a namespace | describe |
| Prove doc examples (and your backends) match expected results | sltest |
Day to day: validate, then query. When something fails in a big graph, diagnose. When you want confidence across DuckDB / Trino / BigQuery / serving, run the conformance suite .
If you run the demos or Docker stack
The demos container (and similar local stacks) usually expose:
| Port | What it is for |
|---|---|
| 8101 | HTTP API for scripts and integrations — run FeatureQL end to end |
| 8100 | MCP — connect your AI client here |
| 8001 | Registry alone — translation only, no query execution |
Ask the stack what it supports with GET http://localhost:8101/capabilities (host name may differ on your machine).
Most interactive work does not need those ports at all: BatchClient() in Python talks to a local engine directly. Use HTTP/MCP when something outside Python (CI, another service, an assistant) needs the same API.
Calling the HTTP API yourself
In Python, results already include the DataFrame, SQL, and errors.
If you call HTTP (or some MCP setups) yourself, set "structured": true in the JSON body when you want those fields back. The default response is a short text/SLT view — useful for display, incomplete for debugging.
curl -s -X POST "http://localhost:8101/query" \
-H "Content-Type: application/json" \
-d '{"query": "SELECT F := 1;", "backend": "duckdb", "structured": true}'Your data stays with you
There is no FeatureMesh-hosted MCP and no FeatureMesh-operated run of your warehouse SQL. Execution and MCP stay on machines you control. See FeatureQL with AI .
In this section
| Page | When to read it |
|---|---|
| Productivity tools | Using validate, diagnose, help, and describe |
| Conformance tests | Running the 4,000+ tests on your backends |
| Working with an assistant | A simple loop when you or an LLM are iterating on a query |
| HTTP Batch API | Exact request and response fields for automation |
Related
- Install and modes: Python library
- Language tour: FeatureQL for the Impatient
- AI setups: FeatureQL with AI