Skip to main content
Bloom provides four scalar functions for evaluating text with TypeSafe’s Jev model. Use jev to ask several questions about the same text in one request, or a typed function to work with one answer directly in SQL.
Bloom’s Jev integration is in beta. Its syntax and behavior may change.

Setup

  1. Open Settings → Config → Environment for your organization.
  2. Click Add variable.
  3. Set Key to TYPESAFE_API_KEY, enter your TypeSafe API key in Value, and click Add.
Bloom automatically recognizes the saved key for all four Jev functions on subsequent runs. Run these queries on Bloom; the functions are available in both local and distributed execution. The examples below use sample text and do not require any tables.

Arguments and input

All four functions take text as their first argument, called state. 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.
The result is a JSON object encoded as a SQL string. Bloom validates the response and preserves the response envelope and additional answer fields. 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 as e.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 error is SQL NULL.
  • Evaluation failure: answer fields are SQL NULL and error is populated.
  • SQL NULL input: the entire result struct is SQL NULL.
For Choice and Score, 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 unusable TYPESAFE_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.