FeatureMesh

FeatureQL transpiler and client. Translate and execute FeatureQL queries locally or via managed FeatureMesh infrastructure.

Quick Start

Works immediately after install -- no server, no account, no config:

pip install featuremesh

from featuremesh import BatchClient

client = BatchClient()

result = client.query("""
    SELECT
        F1 := 1,
        F2 := 2,
        F3 := F1 + F2;
""")

print(result.dataframe)
#    F1  F2  F3
# 0   1   2   3

For common patterns and discovery commands, run featuremesh.help() in a Python shell.

How It Works

FeatureMesh has two independent axes:

Transpilation + Persistence -- where FeatureQL is translated and feature definitions are stored:

• Local (default): bundled engine + SQLite. No network, no account.
• Managed: FeatureMesh infrastructure. Requires an access token.

Execution -- who runs the final SQL:

• BatchClient: your database runs it (DuckDB, Trino, BigQuery). For analytics, ETL, experimentation.
• ServingClient: the Backend.SERVING stack runs either embedded in Python or in your customer-operated featuremeshd deployment. FeatureMesh never operates a serving plane that receives your row data.

Managed Mode

For team collaboration with shared feature definitions and access control:

from featuremesh import BatchClient, RegistryDeployment, set_default

set_default("registry", RegistryDeployment.MANAGED)

client = BatchClient(
    access_token="your_access_token",  # from https://console.featuremesh.com
    sql_executor=your_sql_executor,
)

Real-Time Serving

ServingClient exposes the same productivity APIs as BatchClient (query, translate, validate, describe, help, diagnose, sltest, sltest_stream).

query vs documentation SLT (important)

client.query(...), HTTP POST /query, and MCP featuremesh_query take a FeatureQL string only (the body under the SLT directive line). They do not parse authored SLT harness syntax.

The default HTTP/MCP response field named slt is an output format (a website-style snippet built from the query result). It does not mean you can POST a full .slt file block as the request body.

For realtime tutorial chains (Postgres/Redis fixtures → EXTERNAL_* → PREPARED_STATEMENT → prepared calls), run the documentation suite with backend="serving" via sltest, or paste only the FeatureQL bodies into query after fixtures already exist in the session.

Embedded serving runs inside the Python process with the local SQLite registry:

pip install "featuremesh[serving]"

from featuremesh import RegistryDeployment, ServingDeployment, ServingClient, set_default

set_default("registry", RegistryDeployment.LOCAL)
set_default("serving", ServingDeployment.EMBEDDED)

with ServingClient() as client:
    result = client.query("SELECT F := 1;")
    client.query("REFRESH FEATURES ALL;")

The first native release supports Python 3.12–3.14 on Linux x86_64/aarch64 and Python 3.13 on macOS arm64. The wheel contains DataFusion and the serving connectors; its measured download size is published with each release.

ONPREM serving uses a customer-operated featuremeshd service over HTTP:

from featuremesh import RegistryDeployment, ServingDeployment, ServingClient, set_default

set_default("registry", RegistryDeployment.MANAGED)
set_default("serving", ServingDeployment.ONPREM)
set_default("serving.host", "http://host.docker.internal:10090")  # local featuremeshd
client = ServingClient(access_token="your_access_token")
result = client.query("SELECT ...")
summary = client.sltest(where="NAME LIKE '%array%#%'")

REFRESH FEATURES A.B.C, ...; and REFRESH FEATURES ALL; are synchronous serving control queries and return QueryResult. Embedded mode reads the local registry and atomically swaps the loaded source/prepared-statement snapshot; ONPREM mode asks featuremeshd to synchronize from the managed registry.

Jupyter Notebooks

%load_ext featuremesh

from featuremesh import BatchClient, set_default
set_default("client", BatchClient())

Then use %%featureql in cells. Options: --client, --show-sql, --debug, --hide-dataframe, --show-slt, --hook VARIABLE.

--hook puts a plain dict in the notebook namespace: the same shape as QueryResult.to_dict(). It is JSON-friendly; the "dataframe" key is either None or a list of row dicts, not a pandas.DataFrame. Use attribute access only on a real QueryResult from client.query(...), not on the hooked dict.

Getting a real DataFrame in Jupyter:

• Call the client: qr = client.query("""..."""); df = qr.dataframe.
• Or rely on the magic return value: without --hide-dataframe, %%featureql returns the DataFrame; in the next cell use df = _ (or Out[n]). With --hide-dataframe, the magic returns None by design.
• To rebuild a frame from a hook dict: pd.DataFrame(hook["dataframe"]) when that key is not None.

If you do not call set_default("client", client), the magic uses the only BatchClient/ServingClient in the notebook namespace when there is exactly one; otherwise set a default or pass --client.

For embedded serving, prefer with ServingClient() as client: and close a long-lived notebook client explicitly before replacing it. Garbage collection uses non-blocking best-effort cleanup; only close() guarantees deterministic connector and runtime shutdown.

FastAPI and process ownership

Create embedded clients in the FastAPI lifespan after worker processes have forked, and close them on shutdown. Native calls are blocking: use synchronous def endpoints so FastAPI runs them in its thread pool, or explicitly offload them from async def endpoints.

from contextlib import asynccontextmanager

from fastapi import FastAPI
from featuremesh import RegistryDeployment, ServingDeployment, ServingClient, set_default

@asynccontextmanager
async def lifespan(app: FastAPI):
    set_default("registry", RegistryDeployment.LOCAL)
    set_default("serving", ServingDeployment.EMBEDDED)
    app.state.serving = ServingClient()
    try:
        yield
    finally:
        app.state.serving.close()

app = FastAPI(lifespan=lifespan)

Do not construct the client in a preloaded Gunicorn master or at module import before a fork. A PID check rejects inherited clients. Each Uvicorn/Gunicorn worker owns an independent DataFusion engine, memory pool, and connector pools; run one worker when only one engine copy is desired. Set serving.memory_limit_bytes before construction to bound each engine independently (the default is 1 GiB). A client owns its native runtime, connectors, and local-registry connection; do not share those resources across processes, and call close() in the owning process.

Result objects

Use json.dumps(..., cls=FeatureMeshJSONEncoder) for result objects.

More

• Documentation: featuremesh.com/docs
• Quick reference: featuremesh.help() in Python
• FeatureQL discovery: SHOW SIGNATURES, SHOW DOCS, SHOW TESTS (run as queries)
• Type stubs: Ships with py.typed — full type-checking support in mypy, pyright, etc.
• Support: info@featuremesh.com

License

FeatureMesh Proprietary License 1.0 Copyright (c) 2026 FeatureMesh