> ## Documentation Index
> Fetch the complete documentation index at: https://docs.parable.work/llms.txt
> Use this file to discover all available pages before exploring further.

# Ponder

> Use the first-party Ponder Plot Plugin to return typed model output from SQL.

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.

<Warning>
  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.
</Warning>

## Classify rows

Named arguments use `=>`. Supply model coordinates inline, make the instruction
and output type constant strings, and label every input with `named_struct`.

```sql Classify Linear issues theme={null}
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:

```sql Extract structured output theme={null}
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](/protocols/sql/query-with-sdks).