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.SERVINGstack 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.
| Input | Use |
|---|---|
FeatureQL (SELECT …, CREATE FEATURES …, REFRESH FEATURES …, …) |
query / POST /query / featuremesh_query (use backend="serving" for realtime) |
Full SLT block (query …, ----, expected rows, # depends:, # match:, ``client validate |
help |
Fixture SQL/Redis (statement ok using postgres, using redis, …) |
sltest only (named / server serving_executors) |
Prepared-statement calls (prepared FM.… + NDJSON inputs) |
sltest only, or ServingClient.execute_prepared_statement(...) — not query |
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,%%featureqlreturns theDataFrame; in the next cell usedf = _(orOut[n]). With--hide-dataframe, the magic returnsNoneby design. - To rebuild a frame from a hook dict:
pd.DataFrame(hook["dataframe"])when that key is notNone.
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
| Method | Returns | Notable fields / behavior |
|---|---|---|
client.query(fql) |
QueryResult |
FeatureQL input only. .dataframe, .sql, .slt (output), .success, .errors, .warnings, timings, .column_types, .display(), .to_dict() |
client.translate(fql) |
TranslateResult |
.sql, .success, .errors, .warnings, .debug_logs, .display() |
client.help(*terms) |
HelpResult |
.text, structured row lists, .display() |
client.describe(*prefixes) |
DescribeResult |
.text, .features_list, .display() |
client.validate(query) |
ValidateResult |
.text, .formatted_featureql, .output_schema, .display() |
client.sltest(...) |
list[dict] |
Full authored SLT (incl. using / prepared); flat rows (status / backend / client / batch_id / depends); where is FeatureQL, optional order_by (ASC/DESC on NAME) / offset / limit; # depends: expansion needs a DuckDB fetch_client when execute backend differs; optional source=, serving_executors=, max_workers=, labels= |
client.sltest_multi([c1, c2], ...) / sltest_multi(...) |
list[dict] |
Same flat rows; fetch once; clients concurrent; independent advance; labels_by_backend= / max_workers_by_backend= |
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
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distributions
Built Distributions
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file featuremesh-0.3.0-cp314-cp314-manylinux_2_34_x86_64.whl.
File metadata
- Download URL: featuremesh-0.3.0-cp314-cp314-manylinux_2_34_x86_64.whl
- Upload date:
- Size: 51.3 MB
- Tags: CPython 3.14, manylinux: glibc 2.34+ x86-64
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
60d5e580eb8c3029b084cc57dc5875cc5a25ada98375f14869e872f435d5bf84
|
|
| MD5 |
3ad2e0ec922ebaf33ad6640068f3360a
|
|
| BLAKE2b-256 |
a326701690b9d5418d39450d44170a47e58041d4483ac6aff8122135d2591786
|
Provenance
The following attestation bundles were made for featuremesh-0.3.0-cp314-cp314-manylinux_2_34_x86_64.whl:
Publisher:
publish-pypi.yml on featuremesh/featuremesh-client-py
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
featuremesh-0.3.0-cp314-cp314-manylinux_2_34_x86_64.whl -
Subject digest:
60d5e580eb8c3029b084cc57dc5875cc5a25ada98375f14869e872f435d5bf84 - Sigstore transparency entry: 2344881665
- Sigstore integration time:
-
Permalink:
featuremesh/featuremesh-client-py@13f0378d7ebc3c56cf5aabc19a9379806765a506 -
Branch / Tag:
refs/heads/main - Owner: https://github.com/featuremesh
-
Access:
private
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
publish-pypi.yml@13f0378d7ebc3c56cf5aabc19a9379806765a506 -
Trigger Event:
workflow_dispatch
-
Statement type:
File details
Details for the file featuremesh-0.3.0-cp314-cp314-manylinux_2_34_aarch64.whl.
File metadata
- Download URL: featuremesh-0.3.0-cp314-cp314-manylinux_2_34_aarch64.whl
- Upload date:
- Size: 49.1 MB
- Tags: CPython 3.14, manylinux: glibc 2.34+ ARM64
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
017309ac51e460e6762d4a6552b30abcf2539e8c5a9541e869d05a8128c481aa
|
|
| MD5 |
c7aefc18a9e2e5150613196412a4c485
|
|
| BLAKE2b-256 |
ca299d6731126da3eab3f5f493a5c9a3a32defefd6bc521a8ef74a91dd19bc8f
|
Provenance
The following attestation bundles were made for featuremesh-0.3.0-cp314-cp314-manylinux_2_34_aarch64.whl:
Publisher:
publish-pypi.yml on featuremesh/featuremesh-client-py
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
featuremesh-0.3.0-cp314-cp314-manylinux_2_34_aarch64.whl -
Subject digest:
017309ac51e460e6762d4a6552b30abcf2539e8c5a9541e869d05a8128c481aa - Sigstore transparency entry: 2344881751
- Sigstore integration time:
-
Permalink:
featuremesh/featuremesh-client-py@13f0378d7ebc3c56cf5aabc19a9379806765a506 -
Branch / Tag:
refs/heads/main - Owner: https://github.com/featuremesh
-
Access:
private
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
publish-pypi.yml@13f0378d7ebc3c56cf5aabc19a9379806765a506 -
Trigger Event:
workflow_dispatch
-
Statement type:
File details
Details for the file featuremesh-0.3.0-cp313-cp313-manylinux_2_34_x86_64.whl.
File metadata
- Download URL: featuremesh-0.3.0-cp313-cp313-manylinux_2_34_x86_64.whl
- Upload date:
- Size: 51.8 MB
- Tags: CPython 3.13, manylinux: glibc 2.34+ x86-64
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
048b712667cbf3fb7bd2b735551acf0a2381f07885313de847bdc88f791da227
|
|
| MD5 |
39265fa45451dea6f35e85a8b2bc4c5b
|
|
| BLAKE2b-256 |
bb95e0c17376cb3d81c6499ab93981b3a73ee01a9cb555630e0406e535d1a7a1
|
Provenance
The following attestation bundles were made for featuremesh-0.3.0-cp313-cp313-manylinux_2_34_x86_64.whl:
Publisher:
publish-pypi.yml on featuremesh/featuremesh-client-py
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
featuremesh-0.3.0-cp313-cp313-manylinux_2_34_x86_64.whl -
Subject digest:
048b712667cbf3fb7bd2b735551acf0a2381f07885313de847bdc88f791da227 - Sigstore transparency entry: 2344881310
- Sigstore integration time:
-
Permalink:
featuremesh/featuremesh-client-py@13f0378d7ebc3c56cf5aabc19a9379806765a506 -
Branch / Tag:
refs/heads/main - Owner: https://github.com/featuremesh
-
Access:
private
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
publish-pypi.yml@13f0378d7ebc3c56cf5aabc19a9379806765a506 -
Trigger Event:
workflow_dispatch
-
Statement type:
File details
Details for the file featuremesh-0.3.0-cp313-cp313-manylinux_2_34_aarch64.whl.
File metadata
- Download URL: featuremesh-0.3.0-cp313-cp313-manylinux_2_34_aarch64.whl
- Upload date:
- Size: 49.0 MB
- Tags: CPython 3.13, manylinux: glibc 2.34+ ARM64
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
10c0c95ec4ac5ec8dc0d47fd730aa40571477ac989d24635fbe7fc99ec602f36
|
|
| MD5 |
975034eca4aa9c6270753bb3f072d915
|
|
| BLAKE2b-256 |
84269dbb02565e1e99fd8399401f227e83befbe214a689aa6899aaeca858679a
|
Provenance
The following attestation bundles were made for featuremesh-0.3.0-cp313-cp313-manylinux_2_34_aarch64.whl:
Publisher:
publish-pypi.yml on featuremesh/featuremesh-client-py
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
featuremesh-0.3.0-cp313-cp313-manylinux_2_34_aarch64.whl -
Subject digest:
10c0c95ec4ac5ec8dc0d47fd730aa40571477ac989d24635fbe7fc99ec602f36 - Sigstore transparency entry: 2344881976
- Sigstore integration time:
-
Permalink:
featuremesh/featuremesh-client-py@13f0378d7ebc3c56cf5aabc19a9379806765a506 -
Branch / Tag:
refs/heads/main - Owner: https://github.com/featuremesh
-
Access:
private
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
publish-pypi.yml@13f0378d7ebc3c56cf5aabc19a9379806765a506 -
Trigger Event:
workflow_dispatch
-
Statement type:
File details
Details for the file featuremesh-0.3.0-cp313-cp313-macosx_13_0_arm64.whl.
File metadata
- Download URL: featuremesh-0.3.0-cp313-cp313-macosx_13_0_arm64.whl
- Upload date:
- Size: 23.2 MB
- Tags: CPython 3.13, macOS 13.0+ ARM64
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
4b45a018eb4a42a34bf80e4141c069d9ebaa9979a2c83cd30e21e3a577ac1d40
|
|
| MD5 |
56dfbc8f8311cf3b365690e889672dfe
|
|
| BLAKE2b-256 |
69d1c2497c88f757b89f9c04aa77dfc1e3a367dc72e0096916df5eb5b5872d14
|
Provenance
The following attestation bundles were made for featuremesh-0.3.0-cp313-cp313-macosx_13_0_arm64.whl:
Publisher:
publish-pypi.yml on featuremesh/featuremesh-client-py
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
featuremesh-0.3.0-cp313-cp313-macosx_13_0_arm64.whl -
Subject digest:
4b45a018eb4a42a34bf80e4141c069d9ebaa9979a2c83cd30e21e3a577ac1d40 - Sigstore transparency entry: 2344881437
- Sigstore integration time:
-
Permalink:
featuremesh/featuremesh-client-py@13f0378d7ebc3c56cf5aabc19a9379806765a506 -
Branch / Tag:
refs/heads/main - Owner: https://github.com/featuremesh
-
Access:
private
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
publish-pypi.yml@13f0378d7ebc3c56cf5aabc19a9379806765a506 -
Trigger Event:
workflow_dispatch
-
Statement type:
File details
Details for the file featuremesh-0.3.0-cp312-cp312-manylinux_2_34_x86_64.whl.
File metadata
- Download URL: featuremesh-0.3.0-cp312-cp312-manylinux_2_34_x86_64.whl
- Upload date:
- Size: 52.9 MB
- Tags: CPython 3.12, manylinux: glibc 2.34+ x86-64
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
c1051b069ca30eba66ee5770f48d33c3b7949a34467f51263acc238a9d287b4e
|
|
| MD5 |
c9e9e877ca5ece2f5d2b3b77af415a12
|
|
| BLAKE2b-256 |
6ed1ac7cf06b99bebaabb1802aa9b3916ae5fa0de554718f503603399abb5b62
|
Provenance
The following attestation bundles were made for featuremesh-0.3.0-cp312-cp312-manylinux_2_34_x86_64.whl:
Publisher:
publish-pypi.yml on featuremesh/featuremesh-client-py
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
featuremesh-0.3.0-cp312-cp312-manylinux_2_34_x86_64.whl -
Subject digest:
c1051b069ca30eba66ee5770f48d33c3b7949a34467f51263acc238a9d287b4e - Sigstore transparency entry: 2344881852
- Sigstore integration time:
-
Permalink:
featuremesh/featuremesh-client-py@13f0378d7ebc3c56cf5aabc19a9379806765a506 -
Branch / Tag:
refs/heads/main - Owner: https://github.com/featuremesh
-
Access:
private
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
publish-pypi.yml@13f0378d7ebc3c56cf5aabc19a9379806765a506 -
Trigger Event:
workflow_dispatch
-
Statement type:
File details
Details for the file featuremesh-0.3.0-cp312-cp312-manylinux_2_34_aarch64.whl.
File metadata
- Download URL: featuremesh-0.3.0-cp312-cp312-manylinux_2_34_aarch64.whl
- Upload date:
- Size: 50.0 MB
- Tags: CPython 3.12, manylinux: glibc 2.34+ ARM64
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
921afdce2ecdd7e04be090dc5bd7bb3bc9b3d78f22c2b210dbb654324f194e40
|
|
| MD5 |
fe83955f67ad8e94cbd11f2487101032
|
|
| BLAKE2b-256 |
bd3ab3c47338631b88904a070d565c15a64a54fd83e20084b8a0f28700f298cb
|
Provenance
The following attestation bundles were made for featuremesh-0.3.0-cp312-cp312-manylinux_2_34_aarch64.whl:
Publisher:
publish-pypi.yml on featuremesh/featuremesh-client-py
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
featuremesh-0.3.0-cp312-cp312-manylinux_2_34_aarch64.whl -
Subject digest:
921afdce2ecdd7e04be090dc5bd7bb3bc9b3d78f22c2b210dbb654324f194e40 - Sigstore transparency entry: 2344881579
- Sigstore integration time:
-
Permalink:
featuremesh/featuremesh-client-py@13f0378d7ebc3c56cf5aabc19a9379806765a506 -
Branch / Tag:
refs/heads/main - Owner: https://github.com/featuremesh
-
Access:
private
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
publish-pypi.yml@13f0378d7ebc3c56cf5aabc19a9379806765a506 -
Trigger Event:
workflow_dispatch
-
Statement type: