Python SDK

A self-contained client for Python 3.9+. The engine ships inside the wheel.

pip install jevql

That is the whole install. The wheel for your platform carries the jevql engine; the package itself is standard library only.

Embedded engine

from jevql import Jevql, JevqlError

with Jevql() as db:      # starts a private engine on localhost on first use
    res = db.query(
        "SELECT name, jev_prob(people, 'could work from home') AS p FROM people WHERE country = 'PT' ORDER BY p DESC LIMIT 5",
        threshold=0.6,
    )
    res.columns        # ["name", "p"]
    res.rows           # [["Miguel Costa", 0.94], ...]
    res.stats.usd      # 0.00005

    for row in db.query_dicts("SELECT * FROM tickets WHERE jev(tickets, 'is about billing')"):
        print(row["subject"])

Leaving the with block, calling close(), or exiting the interpreter stops the engine. It reads DATABASE_URL, PG*, TYPESAFE_API_KEY, TYPESAFE_API_URL and JEV_THRESHOLD from the environment, like the CLI. Override with keyword arguments:

Jevql(database_url="postgres://...", api_key="tsk_...", model="jev-latest", threshold=0.5, max_rows=2500, cache_path="~/.cache/jevql/cache.db")

Remote engine

db = Jevql(url="https://jev.internal", token=os.environ["JEVQL_TOKEN"])

Run the shared engine with jevql serve --listen 0.0.0.0:7433 --token secret behind your own TLS proxy.

Engine discovery

engine_path=, then JEVQL_ENGINE_PATH, then the binary bundled in the wheel, then jevql on PATH. If none exists, JevqlError with code transport tells you how to install one.

Errors

try:
    db.query("SELECT * FROM nope")
except JevqlError as e:
    print(e.code, e.status, e)   # "sql", 400, 'relation "nope" does not exist'

code is one of sql, budget, api, auth, internal, transport.

Types

QueryResult, Stats and Explain are dataclasses with from_dict. QueryResult.dicts() zips columns and rows.

Edit this page on GitHub ↗