jev to ask several questions about the same text in one request, or a typed function to work with one answer directly in SQL.
Setup
- Open Settings → Config → Environment for your organization.
- Click Add variable.
- Set Key to
TYPESAFE_API_KEY, enter your TypeSafe API key in Value, and click Add.
Arguments and input
All four functions take text as their first argument, calledstate. It can be a string literal, a text column, or an expression producing text. Cast non-text values explicitly. Bloom sends the text unchanged, including strings that look like JSON.
Question definitions must be constant. jev takes a non-null JSON string literal; typed functions take non-null text instructions and constant SQL MAP or array expressions. Named arguments can follow positional arguments, as in the examples below. Positional-only calls also work.
A SQL NULL state returns SQL NULL without an API request. Empty strings are evaluated. When using your own tables, filter unwanted inputs and put LIMIT in an input CTE before evaluation.
All functions currently request jev-latest, which can move to a newer model release.
Batch questions with jev
questions is a nonempty JSON object mapping question IDs to definitions. Each non-null input row sends one request containing all named questions, subject to retries. Separate typed function calls make separate requests; use jev when questions share the same state.
After parsing
evaluation, read values such as answers.asks_for_help.noul, answers.intent.choice, and answers.hostility.score. On failure, the row contains an error object instead of a successful response envelope.
Each definition needs type and instructions. Choice criteria are an object with 1–255 option names; Score criteria are an array of 2–10 ordered levels; Noul criteria are an optional object with "true"/"false" descriptions. General jev JSON also supports objects or arrays for instructions and descriptions, while typed functions use strings. See TypeSafe’s question guide for the question formats.
Use single quotes around SQL strings and double quotes inside JSON. Double an apostrophe inside a SQL string, for example 'What''s new?'.
Typed results
The typed functions return native SQL structs. Give the result a name in a CTE, then access its fields through the CTE alias, such ase.intent.choice or e.hostility.error.kind. No JSON parsing is needed for these results.
Every typed result also has a nullable
error STRUCT<kind VARCHAR, status INTEGER>:
- Success: answer fields are populated and
erroris SQLNULL. - Evaluation failure: answer fields are SQL
NULLanderroris populated. - SQL
NULLinput: the entire result struct is SQLNULL.
confidence is TypeSafe’s reported value, not a value Bloom recomputes from the winning probability. Typed results expose the fields above; use general jev when you need model, usage, or additional provider fields.
jev_noul
jev_noul(text, instructions => '...') returns a probability from 0 to 1 in noul, rather than a Boolean. Optional criteria use MAP<VARCHAR, VARCHAR> with only true and/or false keys and non-null descriptions. Omitting criteria or passing criteria => NULL sends no criteria.
jev_choice
jev_choice(text, instructions => '...', criteria => MAP {...}) requires a map with 1–255 unique option names. Descriptions are strings and may be NULL when the option name is sufficient. The selected option is returned in choice; probabilities maps option names to probabilities.
jev_score
jev_score(text, instructions => '...', criteria => ['...', '...']) requires an array of 2–10 non-null descriptions, ordered from lowest to highest. With N levels, score ranges from 0 to N−1 and can be fractional. The three-level rubric below spans 0 to 2. Both legend and probabilities use zero-based BIGINT level numbers as map keys.
The CASE expression checks for missing text and evaluation errors before interpreting the score. Replace the sample text literal with NULL to test the no input branch. The 1.5 threshold is an example decision rule you can adjust.
Errors
Missing, blank, or unusableTYPESAFE_API_KEY values and invalid question definitions fail planning, before input evaluation or API calls. Check that definitions are constant and that instructions and criteria have the required types. Queries without Jev functions do not need this key.
API failures are per-row results, so other rows continue and the overall query can still succeed. Inspect errors before using an answer. General jev returns JSON text like {"error":{"kind":"http","status":429}}; typed functions put those fields in their error struct.
For non-HTTP failures, JSON errors omit
status and typed error.status is SQL NULL. Raw provider error bodies are discarded.