Skip to main content

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.

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_STATEMENTprepared 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

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

No source distribution files available for this release.See tutorial on generating distribution archives.

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

featuremesh-0.3.0-cp314-cp314-manylinux_2_34_x86_64.whl (51.3 MB view details)

Uploaded CPython 3.14manylinux: glibc 2.34+ x86-64

featuremesh-0.3.0-cp314-cp314-manylinux_2_34_aarch64.whl (49.1 MB view details)

Uploaded CPython 3.14manylinux: glibc 2.34+ ARM64

featuremesh-0.3.0-cp313-cp313-manylinux_2_34_x86_64.whl (51.8 MB view details)

Uploaded CPython 3.13manylinux: glibc 2.34+ x86-64

featuremesh-0.3.0-cp313-cp313-manylinux_2_34_aarch64.whl (49.0 MB view details)

Uploaded CPython 3.13manylinux: glibc 2.34+ ARM64

featuremesh-0.3.0-cp313-cp313-macosx_13_0_arm64.whl (23.2 MB view details)

Uploaded CPython 3.13macOS 13.0+ ARM64

featuremesh-0.3.0-cp312-cp312-manylinux_2_34_x86_64.whl (52.9 MB view details)

Uploaded CPython 3.12manylinux: glibc 2.34+ x86-64

featuremesh-0.3.0-cp312-cp312-manylinux_2_34_aarch64.whl (50.0 MB view details)

Uploaded CPython 3.12manylinux: glibc 2.34+ ARM64

File details

Details for the file featuremesh-0.3.0-cp314-cp314-manylinux_2_34_x86_64.whl.

File metadata

File hashes

Hashes for featuremesh-0.3.0-cp314-cp314-manylinux_2_34_x86_64.whl
Algorithm Hash digest
SHA256 60d5e580eb8c3029b084cc57dc5875cc5a25ada98375f14869e872f435d5bf84
MD5 3ad2e0ec922ebaf33ad6640068f3360a
BLAKE2b-256 a326701690b9d5418d39450d44170a47e58041d4483ac6aff8122135d2591786

See more details on using hashes here.

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

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file featuremesh-0.3.0-cp314-cp314-manylinux_2_34_aarch64.whl.

File metadata

File hashes

Hashes for featuremesh-0.3.0-cp314-cp314-manylinux_2_34_aarch64.whl
Algorithm Hash digest
SHA256 017309ac51e460e6762d4a6552b30abcf2539e8c5a9541e869d05a8128c481aa
MD5 c7aefc18a9e2e5150613196412a4c485
BLAKE2b-256 ca299d6731126da3eab3f5f493a5c9a3a32defefd6bc521a8ef74a91dd19bc8f

See more details on using hashes here.

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

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file featuremesh-0.3.0-cp313-cp313-manylinux_2_34_x86_64.whl.

File metadata

File hashes

Hashes for featuremesh-0.3.0-cp313-cp313-manylinux_2_34_x86_64.whl
Algorithm Hash digest
SHA256 048b712667cbf3fb7bd2b735551acf0a2381f07885313de847bdc88f791da227
MD5 39265fa45451dea6f35e85a8b2bc4c5b
BLAKE2b-256 bb95e0c17376cb3d81c6499ab93981b3a73ee01a9cb555630e0406e535d1a7a1

See more details on using hashes here.

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

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file featuremesh-0.3.0-cp313-cp313-manylinux_2_34_aarch64.whl.

File metadata

File hashes

Hashes for featuremesh-0.3.0-cp313-cp313-manylinux_2_34_aarch64.whl
Algorithm Hash digest
SHA256 10c0c95ec4ac5ec8dc0d47fd730aa40571477ac989d24635fbe7fc99ec602f36
MD5 975034eca4aa9c6270753bb3f072d915
BLAKE2b-256 84269dbb02565e1e99fd8399401f227e83befbe214a689aa6899aaeca858679a

See more details on using hashes here.

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

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file featuremesh-0.3.0-cp313-cp313-macosx_13_0_arm64.whl.

File metadata

File hashes

Hashes for featuremesh-0.3.0-cp313-cp313-macosx_13_0_arm64.whl
Algorithm Hash digest
SHA256 4b45a018eb4a42a34bf80e4141c069d9ebaa9979a2c83cd30e21e3a577ac1d40
MD5 56dfbc8f8311cf3b365690e889672dfe
BLAKE2b-256 69d1c2497c88f757b89f9c04aa77dfc1e3a367dc72e0096916df5eb5b5872d14

See more details on using hashes here.

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

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file featuremesh-0.3.0-cp312-cp312-manylinux_2_34_x86_64.whl.

File metadata

File hashes

Hashes for featuremesh-0.3.0-cp312-cp312-manylinux_2_34_x86_64.whl
Algorithm Hash digest
SHA256 c1051b069ca30eba66ee5770f48d33c3b7949a34467f51263acc238a9d287b4e
MD5 c9e9e877ca5ece2f5d2b3b77af415a12
BLAKE2b-256 6ed1ac7cf06b99bebaabb1802aa9b3916ae5fa0de554718f503603399abb5b62

See more details on using hashes here.

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

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file featuremesh-0.3.0-cp312-cp312-manylinux_2_34_aarch64.whl.

File metadata

File hashes

Hashes for featuremesh-0.3.0-cp312-cp312-manylinux_2_34_aarch64.whl
Algorithm Hash digest
SHA256 921afdce2ecdd7e04be090dc5bd7bb3bc9b3d78f22c2b210dbb654324f194e40
MD5 fe83955f67ad8e94cbd11f2487101032
BLAKE2b-256 bd3ab3c47338631b88904a070d565c15a64a54fd83e20084b8a0f28700f298cb

See more details on using hashes here.

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

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

0.3.0 This release

7 files

0.2.0

7 files

0.1.3

2 files

0.1.2

2 files

0.1.1

2 files

0.1.0

2 files

0.0.1

2 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page