greptimedb/docs/how-to/jev.md

Natural-language filtering with Jev (experimental MVP)

jev(text, statement, threshold) returns whether Jev judges the statement true for the text with probability greater than or equal to the threshold. It is an asynchronous SQL scalar function usable in WHERE and SELECT.

Start GreptimeDB

Jev is compiled and registered by the default-enabled Cargo feature ai_functions. Enable API evaluation separately in the server process:

export GREPTIMEDB_EXPERIMENTAL_JEV=true
export JEV_API_KEY='<your TypeSafe API key>'
cargo run -p cmd -- standalone start

If your key is already exported in ~/.zshrc, run source ~/.zshrc first. The optional JEV_MODEL defaults to jev-latest; JEV_ENDPOINT defaults to https://api.typesafe.ai/v1/systemone (the full evaluation endpoint URL). The MVP uses environment variables rather than TOML configuration. The Cargo feature includes the SQL function in the build; the runtime environment variables enable and configure its API calls. Default compilation does not turn on external API calls. To enable the feature explicitly, use --features ai_functions.

Query

For a new example table, quote service and message in the DDL because the current parser treats them as keywords:

CREATE TABLE events (
    occurred_at TIMESTAMP TIME INDEX,
    "service" STRING,
    "message" STRING,
    PRIMARY KEY ("service")
);

SELECT occurred_at, service, message
FROM events
WHERE occurred_at >= '2026-09-19T00:00:00Z'
  AND occurred_at <  '2026-09-20T00:00:00Z'
  AND service = 'payments'
  AND jev(
    (message),
    'The event reports that a payment still failed after retries.',
    0.8
  )
ORDER BY occurred_at;

The first two arguments are strings and the third is a number in [0, 1]. (message) is an ordinary parenthesized string expression. For several columns, combine them explicitly, for example concat(service, ': ', message). Any null argument produces SQL NULL, which WHERE excludes, without an API call.

MVP behavior

• Each non-null row makes one HTTP request: the text is state, and the statement is a noul question's instructions. The returned noul probability is compared with the threshold locally; this is not the separate Choice/Score confidence.
• Up to eight requests run concurrently per expression/batch invocation, not per query or process. Concurrent partitions and queries can exceed eight requests in total. Each request has a 30-second timeout. Errors (including rate limits and invalid responses) fail the query. There is no automatic retry or cross-query cache.
• Start with small, time-bounded queries. Ordinary SQL predicates can reduce the candidate set, but SQL does not guarantee left-to-right predicate evaluation or that LIMIT bounds the number of API calls.
• Text passed to the function is sent to the configured TypeSafe endpoint. The API key remains in the server environment, not in SQL.
• This MVP is intended for standalone use. A distributed deployment would need the environment on every node evaluating the function and separate validation.

API reference: https://docs.typesafe.ai/api

Before stabilizing

The experimental MVP still needs the following controls before stabilization:

• A process-wide concurrency limit shared by Jev invocations, such as a semaphore.
• Bounded retries with exponential backoff for HTTP 429 and 529, following TypeSafe's rate-limit guidance.
• Request budgets and metrics for API calls, latency, retries, and rate-limit errors.

These are follow-up work, not guarantees provided by the current implementation.

Validation

Check both the default build (where jev is registered) and an isolated common-function build without default features. Jev's regular tests use a local HTTP server and need no API key:

cargo nextest run -p common-function
cargo nextest run -p common-function --no-default-features
cargo nextest run -p common-function --no-default-features --features ai_functions

The sqlness runner explicitly includes ai_functions when building its test binary:

cargo sqlness bare -t jev

If using --bins-dir, provide a binary built with ai_functions (included by default). CI covers the AI-enabled path through the regular unit tests and sqlness tests; the feature-off checks above can be run locally when needed.

An opt-in test calls the real service on synthetic payment events:

source ~/.zshrc
GREPTIMEDB_EXPERIMENTAL_JEV=true cargo nextest run -p common-function \
  -E 'test(test_jev_live)' --run-ignored ignored-only