Python library

Install the featuremesh Python package, run your first local query, then choose local or managed persistence and batch or serving execution.

Installation

FeatureMesh requires Python 3.12 or newer.

pip install featuremesh
bash

Quick start — local mode

Local mode bundles the transpilation engine and persists feature definitions in ./featuremesh.db by default. No server or account is required:

from featuremesh import BatchClient

client = BatchClient()

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

print(result.dataframe)  # Pandas DataFrame
print(result.sql)        # Generated SQL
print(result.success)    # True if query succeeded
python

Translate without executing:

result = client.translate("""
    DEFINE
        ID := INPUT(BIGINT)
    RETURN
        ID,
        DOUBLED := ID * 2
    FOR
        ID := BIND_VALUES(ARRAY[1, 2, 3]);
""")

print(result.sql)
python

Managed mode — batch analytics

For team collaboration with shared feature definitions and access control, switch to managed mode. Transpilation and persistence happen on FeatureMesh infrastructure:

from featuremesh import BatchClient, Backend, RegistryDeployment, set_default

set_default("registry", RegistryDeployment.MANAGED)

# Get your access token from https://console.featuremesh.com/login
ACCESS_TOKEN = "your_access_token"

# Provide a SQL executor for your database
def query_duckdb(sql: str):
    import duckdb
    return duckdb.sql(sql).df()

client = BatchClient(
    access_token=ACCESS_TOKEN,
    backend=Backend.DUCKDB,
    sql_executor=query_duckdb,
)

result = client.query("""
    DEFINE
        ID := INPUT(BIGINT)
    RETURN
        ID,
        DOUBLED := ID * 2
    FOR
        ID := BIND_VALUES(ARRAY[1, 2, 3])
    ;
""")

print(result.dataframe)
python

Real-time serving

Embedded serving runs DataFusion inside the Python process with the local SQLite registry. Install the optional native runtime first:

pip install "featuremesh[serving]"
bash
from featuremesh import RegistryDeployment, ServingClient, ServingDeployment, set_default

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

with ServingClient() as client:
    result = client.query("RETURN F := 1;")
    print(result.dataframe)
python

For production, RegistryDeployment.MANAGED pairs with ServingDeployment.ONPREM: a customer-operated featuremeshd service synchronizes definitions from the managed registry and executes them against real-time sources such as Redis, JDBC, and HTTP. Embedded-serving wheels are platform-specific; see the package release notes for the supported Python and operating-system combinations.

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.
  • Managed: FeatureMesh infrastructure. Requires access token.

Execution — who runs the final SQL:

  • BatchClient: your database (DuckDB, Trino). For analytics, ETL, experimentation.
  • ServingClient: FeatureMesh's DataFusion-based engine, embedded locally or customer-operated through featuremeshd. For real-time serving.

Local mode note: with registry=LOCAL, DuckDB backends get a default in-memory executor; other batch backends need a matching sql_executor.

Use FeatureQL in Jupyter

The %%featureql cell magic lets you write FeatureQL directly in notebook cells and see results as DataFrames. Load the extension first:

%load_ext featuremesh
python

Then set a default client so the magic command knows where to send queries:

from featuremesh import set_default, BatchClient

client = BatchClient()
set_default("client", client)
python

If you skip set_default but have exactly one BatchClient or ServingClient in the notebook namespace, the magic will use it automatically; define several clients, use set_default("client", ...) or --client.

Now you can write FeatureQL directly in cells:

%%featureql

RETURN
    F1 := 1,
    F2 := 2,
    F3 := F1 + F2;
python
F1F2F3
123

Run %%featureql --help for options such as --show-sql, --debug, --optimize, --timeit, and --hook. Python library tools covers validation, diagnosis, help, result types, and notebook details.

Next steps

Last update at: 2026/10/13 08:32:21