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, 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.
`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. Production permits the `vertex` route.
`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.

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. 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 an output type

​Execution and limits

Classify rows

Arguments

Choose an output type

Execution and limits