Prediction Output

model.predict(...) returns a pyarrow.Table. Without postprocessing, each row corresponds to one processed observation. Output has two columns: retained inputs and model predictions.

For an order model with returned=rf.Boolean(mask=True), one request can omit the target:

request_id: order-42
amount: 86.50
items:
  - sku: coat-17
    quantity: 1
  - sku: scarf-03
    quantity: 2

# model is trained; request_table is an application-supplied Arrow table.
result = model.predict(request_table, retain=("request_id",))

Arrow tables and record batches are accepted directly. A nonempty sequence of mappings is also supported for small interactive requests. Use a typed Arrow object for empty input: relflow preserves the output schema and skips the forward pass.

Read a field

Prediction keys are full, slash-prefixed schema addresses. A return target is the literal struct field /returned; a model-level embedding uses /. See Names And Addresses.

import pyarrow.compute as pc
import relflow as rf

returned = pc.struct_field(result["predictions"], rf.Address("returned"))
content = pc.struct_field(returned, "content")
probability = pc.struct_field(content, "probability")

One output record has this shape. Angle-bracket values describe the output; they are placeholders, not measured predictions.

inputs:
  request_id: order-42
predictions:
  /returned:
    state:
      valued: <probability>
      "null": <probability>
      padded: <probability>
      masked: <probability>
      other: <probability>
    content:
      probability: <probability of true>
    inferred: true

state gives probabilities for the five value states. content holds the field’s decoded value. Consider both if the application distinguishes a value from a missing or unavailable result. inferred records whether reconstruction was requested at that position; it is not a confidence score.

What appears in output

Only configured prediction addresses appear: deterministic reconstructions with an extension output, requested embeddings, or both. Visible input fields are not automatically echoed. embed=True adds an L2-normalized embedding; branch embeddings contain no decoded value.

Field type	Decoded output
`Boolean`	`content.probability`: probability of `True`
`Number`	`content`: floating-point reconstruction
`Quantile`	`content`: floating-point reconstruction in source units; null before learning a distribution
`Vector`	`content`: fixed-width list
`Category`, `Enum`	`content.value`, `content.probability`, `content.topk` candidates
`Set`	`content`: list of value/probability candidates
`Cluster`	`cluster.value`, `cluster.probability`, plus content value/probability
`Text`, `Hash`, `DateParts`	No decoded public value; embeddings are available

Number and Quantile predict in the units supplied after preprocessing. Their internal transformations do not change the output units. Quantile clips the inverse transformation to its learned minimum and maximum. Vector predicts the supplied coordinates and writes zeros where the most likely state is not valued. If your preprocessor transforms units, reverse that application transform in a postprocessor. Category, Enum, and Set labels are Arrow large_string values. Category and Enum always include topk, even when empty. A Set threshold can vary the number of returned candidates.

The Arrow row dimension always means observations. A repeated branch appears as fixed-width lists inside each leaf’s output, including length-one branches. Vectors and embeddings also keep their width axis. A branch embedding’s shape follows its reduction output. The generated root singleton is omitted; a one-row request has the same nested schema as a larger batch.

Retain source columns

retain selects processed top-level columns copied into inputs:

Argument	Retained inputs
`retain=()`	None; `inputs` is an Arrow null column
`retain=("request_id",)`	Only that named column
`retain="*"`	All processed source columns

Retention does not change model inputs. A missing retained column is an error. When no prediction address has writable output, predictions is also a null column, with the observation count preserved.

Use postprocessors to reshape this table, batch inference to write it to Parquet, or serving for an HTTP endpoint.