ponder(), embed(), and the Jev functions are SQL
functions on the same Flight SQL connection that you use for
the pools. You can also call them in a Plot, and over
SQL over HTTP. Named arguments use =>. Do not mix
named and positional arguments.
Each call goes to a paid AI model:
ponder()sends one call for each row that reaches it.embed()sends up to 32 rows in one call.- Each Jev function sends one call for each row that reaches it.
ask, noul, choice, and score count
against the same limits. A query that would pass a limit stops with
RESOURCE_EXHAUSTED and error code QL-SQ-010 (calls) or QL-SQ-011
(cost). Do not retry it. Call the function over fewer rows instead. While you
develop a query, filter the input, keep a LIMIT, or
sample the table.
A call to a model that Parable has no price for yet is refused, because the
cost limit could not count it. The query stops with FAILED_PRECONDITION and
error code QL-SQ-012, and the message names the function, the model and its
processor. Name a model that has a price, such as the default. The
dry run tells you, before
you run a query, the most AI calls that each function in it can make.
To call a function over every row of a large table, put the SQL in a
Pipeline. A Refresh keeps each answer and runs under its own
limits. workspace.query_runs records what each Plot run spent (see
Workspace).
ponder()
ponder() runs a language model once per row and returns a typed value.
Classify Linear issues with the default model:
Choose the model
A call that names a model runs that model. A call that names no model runs the Workspace’s default model forponder(), which a Workspace administrator
sets in the AI policy. Without a Workspace default, it runs Parable’s default,
Gemini 3.5 Flash-Lite on Vertex (gemini-3.5-flash-lite).
The Workspace’s AI policy lists the routes that ponder() can use. Parable
allows only vertex. server => 'vertex' runs in the Workspace’s own Vertex
project when it has one. A call that the policy refuses fails before Parable
sends any row, with error code QL-MP-001. If Parable cannot read the
policy, the query fails with QL-MP-002. Run it again.
This call names its model:
Name a model once with model()
model() packs a model’s coordinates into one value that you pass to
ponder() as model. Its arguments are positional:
date means latest. An empty server uses the Provider’s default
route. tokens can be NULL. request_timeout_seconds must be positive.
model() itself calls no model. Inline coordinates and model() name a model
the same way, so the same AI policy rules apply to both.
Return a struct
UseStruct when your SQL needs more than one typed field. The result has
the fields of your schema and a reserved meta field. Do not put meta in
your schema.
meta.status is one of these values:
ok: every required field is present.partial: the response parsed, but at least one required field is missing.meta.errornames the missing fields.error: the model call failed.
meta also has token usage, latency, and the model that ran. A failed call
with a primitive output type returns NULL. The rest of the query continues.
An argument that ponder() refuses, such as an unknown argument or a
Struct output without schema, fails before Parable sends any row. The
error code is QL-PL-013.
Search the live web
Setweb to let the model search the live web and ground its answer in what
it finds. It works on a Vertex Gemini model only; any other model with web
set is refused with QL-PL-013. Use it when the answer depends on current
information the model’s training does not have.
exa_web_search: the recommended value. The model searches Exa’s index through Vertex, not Google’s. It needs an Exa API key configured for the environment (EXA_API_KEY); without one, anexa_web_searchcall is refused.enterprise_web_search: Google’s web search tool that keeps no logs of the searches.google_search: the standard Google Search tool. Google keeps the search logs for three days.
google_search and enterprise_web_search cost the same: Gemini 3 and later
bill 14 USD per 1,000 search queries (the first 5,000 a month are free across
the account). exa_web_search adds Exa’s own search price, billed by Exa.
Each grounded call records its queries on the search_query meter, so the
query’s AI cost cap counts them like any other model cost. A grounded call on
a model that has no search_query price is refused before any call, with
QL-SQ-012.
A grounded call asks the model for text, so its answer is less strictly shaped
than a normal Struct call. Ask for a small Struct (for example one
answer field) or a Utf8 output. Only a Struct output carries
meta.web. An answer that the output type cannot read is an error row.
meta.web is one JSON text object, present only on a grounded call:
sources: a list of{title, domain, uri}. Theuriis a redirect link, so show thedomainandtitleto a reader, not the rawuri.search_queries: the queries the model ran.search_suggestions: Google Search Suggestions as ready-to-render HTML. Only the Google tools (google_search,enterprise_web_search) set it;exa_web_searchleaves it empty.
google_search or enterprise_web_search, a product that shows a
grounded answer to people must render search_suggestions next to the
answer. Google’s grounding terms require it. exa_web_search instead follows
Exa’s terms for how its results are used.
embed()
embed() returns one unit-length vector per row. Only input is required.
The default model is Google gemini-embedding, version 001, on vertex,
with 768 dimensions. A Workspace cannot set a different default for
embed().
A
NULL or empty input returns NULL. If a call to the model fails, the
affected rows are NULL and the query continues.
purpose => 'document' for stored text and purpose => 'query' for a
search phrase. A constant phrase is embedded once per batch, not once per
row. Rank issues by distance from a search phrase:
Keep vectors comparable
Vectors are comparable only when they come from the same model: the same provider, name, variant, version, dimensions, and normalization.server
only routes the call. It does not change the vector.
A query that compares vectors from two different models fails before Parable
embeds anything. The error code is QL-PL-008. Equal dimensions are not
enough.
A Pipeline that selects embed(...) keeps the vectors in its own table, with
the model that wrote them. Parable makes no separate vector table. If a query
cannot read a Plot’s vector column, run the Plot again.
Jev: typed judgments
The Jev functions ask a model a question about each row and return a typed answer with its confidence. Use them to classify, score, or filter rows when a probability or a label with a confidence is more useful than free text.
Use
CASE, COALESCE, NVL, IFNULL, or NVL2 to ask Jev only when a row
needs a judgment. CASE WHEN instructions IS NOT NULL THEN noul(state, instructions) END skips rows with NULL instructions. COALESCE(known, noul(state, 'Q?')) skips rows that already have a value. Skipped calls make
no request and cost nothing.
A condition that calls Jev, a volatile function such as random(), or a
subquery does not skip rows in later branches. A Jev call inside a conditional
subquery also judges every row, as before. To skip rows on an earlier judgment
or volatile value in both queries and Pipelines, store those results in a
separate query first. A direct query can also read an earlier judgment from a
subquery SELECT list or CTE.
Classify Linear issues and read the label and its confidence:
kind['label'] or kind['confidence']. A
noul answer near 0.5 means that the model cannot tell yes from no. It does
not mean a medium amount.
Ask two questions about each row in one call with ask:
questions must be constant text, because it fixes the fields of the result
when Parable plans the query. A column or a bound parameter there is refused
with QL-PL-013, and so is any other argument that Jev cannot use. A Jev
call directly in ORDER BY, GROUP BY, DISTINCT ON, a window, or an outer
join condition is refused with QL-PL-013 too. Compute the call in a subquery
SELECT list, then sort, group, or join on its column alias.
The model and the AI policy
A Jev call runs the model that itsmodel argument names. Without one, it
runs the Workspace’s default from its AI policy, and without that, Parable’s
default.
Jev runs on the TYPESAFE AI processor, with Parable’s default
jev-1.13.0. When the Workspace’s AI policy does not allow TYPESAFE, a Jev
call that names no model runs on a decision model that Google serves on the
VERTEX AI processor, DeepSeek V4.1 Flash (deepseek-v4.1-flash-decide-1).
It gives answers of the same shape as Jev, not the same answers. It takes at
most 255 Choice options, 10 Score levels and 1,048,576 input tokens per
decision. A question over a limit fails with an error that names the model
and its limit. A Workspace administrator can choose the other decision model,
Gemini 3.1 Flash-Lite (gemini-3.1-flash-lite-decide-1), for the Workspace.
When the AI policy allows neither processor, or does not allow the processor
of the model a call names, Parable refuses the call while it plans the query,
with QL-MP-001, before it sends any row. When Parable cannot read the
policy, the query fails with QL-MP-002. Run it again. Ask a Workspace
administrator to allow TYPESAFE or VERTEX in the AI policy to use Jev.
By default, a Jev call that fails stops the query. If the model service does
not answer, the error code is QL-IN-010. Try again with backoff.