Ponder - Parable

Ponder is a first-party Plot Plugin that runs a language model for every input row and returns a typed SQL value. Use it for classification, extraction, and other row-wise reasoning that is awkward to express with ordinary SQL.

Every row that reaches ponder() creates a model call. Filter the source and keep a LIMIT while developing. Scheduled Plots should also set external-call and cost budgets.

Classify rows

Named arguments use =>. Supply model coordinates inline or leave them out to use the default model, make the instruction and output type constant strings, and label every input with named_struct.

Classify Linear issues

SELECT
  id,
  title,
  ponder(
    provider => 'google',
    name => 'gemini',
    variant => '2.5',
    version => 'flash',
    server => 'vertex',
    instruction => 'Classify the issue. Reply with one of: bug, feature, question, other.',
    output => 'Utf8',
    inputs => named_struct('title', title, 'body', description)
  ) AS category
FROM providers.linear.issues
WHERE title IS NOT NULL
LIMIT 20

Arguments

Argument	Requirement	Meaning
`provider`, `name`, `variant`, `version`	Required with inline configuration	Model identity coordinates.
`model`	Alternative to inline coordinates	An existing model configuration expression. Do not combine it with inline coordinates.
(none of the above)	Optional	Omit every model argument to run the default model (see Choose the model).
`instruction`	Required	Constant system instruction sent for every row.
`output`	Required	Constant Arrow output type.
`inputs`	Required	A `named_struct` whose field names become prompt labels.
`schema`	Required for `Struct`	JSON Schema object encoded as a constant SQL string.
`date`	Optional	Model date; defaults to `latest`.
`effort`	Optional	Provider-specific reasoning effort.
`tokens`	Optional	Maximum output tokens; omission uses the service default.
`server`	Optional	Provider route: `vertex`, `anthropic` or `openrouter`. The Workspace’s AI policy decides which routes it may use.
`request_timeout_seconds`	Optional	Positive per-call timeout no greater than the query timeout budget.

Do not mix named and positional arguments. The named form is the documented interface; Parable lowers it to the positional DataFusion function before planning. An argument ponder() refuses, such as an unknown argument name, a Struct output without schema, or an output type it does not support, fails while the query is planned, before any row is sent. Through Query Layer it returns gRPC INVALID_ARGUMENT with error code QL-PL-013 (INVALID_FUNCTION_ARGUMENT). The message names the argument and what it must be, never the value you gave, for example Missing required ponder() argument 'schema' for Struct output.

Choose the model

A call that names a model, inline or through model, runs that model. A call that names none runs the Workspace’s default model for ponder(), which a Workspace administrator sets in the Workspace’s AI policy. Without a Workspace default it runs Parable’s default, Gemini 3.5 Flash-Lite on Vertex (model id gemini-3.5-flash-lite). Vertex serves that model from its global endpoint, so Google chooses the region that processes each call.

Use the default model

SELECT
  id,
  ponder(
    instruction => 'Classify the issue. Reply with one of: bug, feature, question, other.',
    output => 'Utf8',
    inputs => named_struct('title', title)
  ) AS category
FROM providers.linear.issues
LIMIT 20

Every model runs on an AI processor, named by its server:

`server`	Processor
`vertex`	`VERTEX`, in the Workspace’s own Vertex project when it has one
`anthropic`	`ANTHROPIC`
`openrouter`	`OPENROUTER_ZDR`: every call asks OpenRouter for zero data retention, no data collection, and providers that honour every request parameter

The Workspace’s AI policy lists the processors ponder() may use; production allows only vertex. A call whose processor the policy does not allow, a call that names no model when no default’s processor is allowed, and any call while the Workspace’s policy cannot be read are refused while the query is planned, before any row is sent:

Code	Meaning
`QL-MP-001`	The Workspace’s AI policy refuses the call. The message names the reason, such as `PROCESSOR_NOT_ELIGIBLE` or `NO_ELIGIBLE_PROCESSOR`.
`QL-MP-002`	The Workspace’s AI policy could not be read, so no AI function runs. Retry the query.

A scheduled Plot run records the same code when the policy refuses it, and the run fails: a refused call never produces NULL. A run whose planning could not read the policy is retried at the Plot’s next fire.

Choose an output type

Primitive output supports Utf8, Int64, Float64, Boolean, Date32, and Timestamp. A failed call produces NULL for a primitive cell while the rest of the query continues. Use Struct when downstream SQL needs more than one typed field:

Extract structured output

SELECT
  id,
  classified.category,
  classified.reason,
  classified.meta.status,
  classified.meta.error
FROM (
  SELECT
    id,
    ponder(
      provider => 'google',
      name => 'gemini',
      variant => '2.5',
      version => 'flash',
      server => 'vertex',
      instruction => 'Extract a category and a one-sentence reason.',
      output => 'Struct',
      schema => '{"type":"object","properties":{"category":{"type":"string"},"reason":{"type":"string"}},"required":["category","reason"]}',
      inputs => named_struct('title', title)
    ) AS classified
  FROM providers.linear.issues
  LIMIT 20
) AS classified_rows

All declared Struct fields are nullable in Arrow. Ponder appends a reserved meta Struct; do not declare meta in the supplied schema.

`meta` field	Meaning
`status`	`ok`, `partial`, or `error`.
`error`	Missing required fields or provider failure details.
`usage`	Input, output, and total token counts when reported.
`latency_ms`	Provider-call latency.
`model_*` and `finish_reason`	Resolved model identity and completion details.
`request` and `cached`	Request trace material and cache state when available.

partial means the response parsed but omitted at least one required field. error means the model call failed. Struct output keeps the metadata alongside the row so SQL can inspect either state.

Execution and limits

Interactive queries execute Ponder as an asynchronous DataFusion scalar function. Scheduled Plot runs split it into a separate inference stage, pin the output-affecting model and instruction content, and account provider calls and cost before completing the result. A scheduled run pins the model it resolved, including a Workspace default, and the AI policy it planned under: a later policy change reaches the next run, never one already planned. A new default is a new model, so the Plot’s next run recomputes its results. The inference stage runs the same Ponder code as a query. Every row gets the same prompt, with its inputs labelled as named_struct names them, and a Report run stores the value a Preview returns: every output type, NULL for a failed primitive call, and meta for a Struct. The run records each column with its output type, so the Report reads it back as the Preview returns it. Report runs planned before Plots recorded these types stored every non-Utf8 ponder() column as String, which does not match the stored table, so their Plot output cannot be read; the Plot’s next Report run records the real types. A scheduled run retries a failed call before it stores the failure, and is charged one external call for each request that reached the provider. A call that cannot reach its provider at all, such as a route without a configured credential, fails the query with its cause instead of returning a NULL per row. A scheduled run fails with QR-QU-010 and is charged nothing, and its Report shows that the Plot’s AI functions could not reach their AI processor. When every input is constant, such as inputs => named_struct('topic', 'billing'), every row has the same prompt. A query sends it once for each batch of rows the engine passes to ponder(), at most PONDER_MAX_CONCURRENCY rows (8 by default), and every row in the batch reads that answer. A scheduled run asks it once. The service caps input rows and concurrency. A longer per-call timeout can lower the effective row cap because it consumes more of the query timeout budget. Run ponder() with the same SDK query method as any other Parable SQL. See Query with the SDKs.

​Classify rows

​Arguments

​Choose the model

​Choose an output type

​Execution and limits

Classify rows

Arguments

Choose the model

Choose an output type

Execution and limits