Skip to main content
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.
By default, one query can send up to 1,000,000 AI calls and spend up to $1,000 on them. The Jev functions 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 for ponder(), 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:
An empty 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

Use Struct 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.error names 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

Set web 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, an exa_web_search call 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}. The uri is a redirect link, so show the domain and title to a reader, not the raw uri.
  • 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_search leaves it empty.
With 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.
Use 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:
Read a field of the result as 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 its model 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.
Ponder and Embed describe both functions in full. Flight SQL lists the AI call limits and their error codes.