• has_header — when true, the first row supplies column names. When false, every row is treated as data and column names are synthesised as "column1", "column2", … in declaration order; the first data row fixes the column count, so a later wider row's trailing cells are dropped under the lenient default (set strict_column_count = true to reject a ragged row instead).
• delimiter — field separator passed through to NyaCSV.
• infer_schema_rows — number of leading rows scanned when guessing each column's dtype. 0 (or any value <= 0) lifts the cap and scans every row (Polars' infer_schema_length=None), trading a slower inference pass for never mis-guessing a column from a prefix. Cells past a finite window are still parsed under the chosen dtype; one that doesn't fit is handled per on_parse_error.
• null_values — raw strings that should be treated as null cells (both for type inference, which skips them, and for the final typed column, where they become None). The default [""] matches the empty string only, which is how an absent CSV cell is typically represented. Read it back through the null_values() accessor: the field itself is private, and both it and the constructor copy, so the token list a reader uses cannot be changed after the options are built.
• strict_column_count — when true, every data row must have exactly as many cells as the header declares; a ragged row (too few or too many cells) raise ParseError instead of being silently null-padded (short row) or truncated (long row). Defaults to false, preserving the lenient behaviour that tolerates ragged rows (a permissive CSV idiom, and the reader's long-standing default).
• on_parse_error — what to do when a non-null cell past the inference window fails to parse under its column's locked-in dtype. Raise (default) fails with ParseError(Cell(...)); Null downgrades the offending cell to a null cell and keeps the column's inferred dtype (Polars' ignore_errors=True).
• allow_nonfinite_floats — when true (default), the float probe accepts every non-finite result: the nan / inf / infinity literals, and a finite literal that overflows Double to a signed Infinity (1e999), so a column of those tokens infers as Float. When false, the probe rejects them, so such a column falls back to String instead of being silently retyped to Float (a non-finite token past the window is then a parse failure handled per on_parse_error).
• strict_quotes — when true, the input is pre-scanned and an unterminated quoted field, text after a closing quote, or a bare quote inside an unquoted field raise ParseError instead of being repaired by the lenient tokeniser. Defaults to false.

• header — when true, the first emitted row is the column names; when false, only data rows are written.
• delimiter — field separator written between cells.
• null_value — the literal string written in place of a null cell. The default empty string round-trips with the reader's default null_values.
• sanitize_formulas — when true, a String cell beginning with =, +, -, @, a tab, or a carriage return is prefixed with a single quote so a spreadsheet reads it as text. Deliberately lossy: such a cell reads back with the leading quote. Defaults to false.
• line_terminator — the string written after every row, Polars' knob of the same name. The default "\n" (LF) matches every mainstream writer; RFC 4180's letter calls for "\r\n" (CRLF), and the reader accepts LF, CRLF, and CR alike, so either choice round-trips. Must not be empty — an empty terminator would fuse the rows into one.

• Col / Lit / LitSeries — leaves (col, lit / lit_*, lit_series); a LitSeries embeds a pre-materialised Series;
• Binary — arithmetic + - * /, comparisons, Kleene & / |;
• Unary — -e, .not(), the null / NaN probes, and .abs() / .floor() / .ceil() / .sign() / .round();
• Agg — .sum() / .mean() / … reductions;
• Str — the .str_* namespace;
• Cast — .cast(dtype); Alias — .with_alias(name);
• Ternary — when(c).then(a).otherwise(b);
• FillNull / FillNan — .fill_null(v) / .fill_nan(v), dedicated nodes (not lowered to a Ternary) so the operand appears once and a chained coalesce stays linear;
• IsIn / IsBetween — the membership / range predicates, likewise dedicated so the operand is evaluated once;
• Map / MapBatches — the row-wise / batched closure escape hatches (.map_elements() / map_many() / .map_batches()), the function opaque so each is identified by its (label, inputs) (MapBatches also by its returns_scalar flag).

• max_rows — cap the number of data rows. None (the default) renders every row; Some(n) shows the first n and appends a <tfoot> banner (... (K more rows)) for the remainder. A negative n clamps to 0 (header + banner, no data rows), matching the Markdown renderer's row cap.
• table_class — value of the <table class="..."> attribute. None (the default) omits the attribute.
• caption — text of a leading <caption> element. None (the default) omits it.
• escape — when true (the default) every emitted string — caption, header names, cell values, and the class attribute — has & / < / > / " / ' rewritten to their HTML entities, so untrusted data can't inject markup. Pass escape=false for trusted input that intentionally carries HTML.

• on — the key expressions, evaluated over both frames (Polars' IntoExpr). A bare col("id") matches on an existing column; a derived key such as col("ts") / lit_int(86400) matches on the computed value. ["region", "product"]-style multi-key joins become [col("region"), col("product")], matched on the tuple. An empty key list is invalid for on — a non-Cross join requires at least one key (DataFrame::join raises InvalidOperation); use JoinOptions::cross() for a Cartesian product.
• left_on / right_on — paired key expressions evaluated on the left and right frame respectively, for joining on differently-named or differently-derived keys (left_on([col("a")]) against right_on([col("b")])). Mutually exclusive with on, and the two lists must name the same number of keys; key i on the left is matched against key i on the right.
• how — Inner (the on / left_on default), Left, Right, Outer, or Cross.
• suffix — appended to a right column whose name also occurs in the left frame (default "_right"); the left column keeps its name.
• coalesce — whether each key column is merged into a single output column. None (the default) auto-selects by how, matching Polars: an inner / left / right join coalesces (the key appears once), while Outer does not (the right key is kept as <key><suffix>, null wherever its row had no match, so matched and unmatched rows are distinguishable). Some(true) always coalesces; Some(false) never does. Coalescing only applies when keying by on whose every key is a bare col(...) (the precondition for the key to name a single column on both sides); left_on / right_on and any derived key turn it off, keeping both key columns (Polars' "join on a non-column expression turns off coalescing"). When coalesced the single key takes its value from whichever side is present on that row (the two are equal on a matched pair) — the left on Inner / Left, the right on Right, and the present side per row on Outer. The three key lists are priv, read through the copying on_keys() / left_keys() / right_keys(). A public Array field is readable, and reading an array hands over the array itself — enough to push a key into an options value a LazyFrame::join already captured, changing what a built plan collects. The constructors copy on the way in for the same reason; these accessors close the way out. The remaining fields are immutable values, so they stay public.

• Inner — keep only rows whose key matches on both sides.
• Left — keep every left row; where it has no right match, the right-hand columns are filled with nulls.
• Right — the mirror of Left: keep every right row; where it has no left match, the left-hand columns are filled with nulls. The output still leads with the left columns (only the row set changes to "all right rows").
• Outer — the full outer join: keep matched pairs plus every unmatched row from both sides (the missing side's columns null). Left rows (matched and unmatched) come first in left order, then the unmatched right rows in right order.
• Cross — the Cartesian product (every left row paired with every right row); takes no key columns.

• infer_schema_rows — number of leading records inspected when guessing each column's dtype. 0 (or any value <= 0) lifts the cap and scans every record (Polars' infer_schema_length=None). Records past a finite window are still parsed under the chosen dtype; one that doesn't fit is handled per on_parse_error.
• on_parse_error — what to do when a non-null cell past the inference window fails to parse under its column's locked-in dtype: Raise (default) fails with ParseError(Cell(...)); Null downgrades the offending cell to a null and continues (Polars' ignore_errors=True).
• reject_duplicate_keys — whether an object repeating a key is an error. The default false keeps the serde / pandas / Polars behaviour: a repeated key survives only as its last value, the earlier ones silently dropped. true rejects the read instead — ParseError(Message(...)) naming the key and the 1-based object it repeated in — so a payload that would silently lose cells fails loudly. Nested objects are scanned too, and key spellings are compared decoded ("a" and "\u0061" are the same key). The scan runs before the parse and only when the option is on, so the default read pays nothing.

• First keeps the earliest occurrence of each distinct row;
• Last keeps the latest;
• None keeps only rows that have no duplicate at all — every row of a duplicated set is dropped (Polars' keep='none').

• Raise (every reader's default) — surface ParseError(Cell(...)), failing the whole read. The strict, lossless behaviour: a malformed cell is never silently dropped.
• Null — downgrade the offending cell to a null cell and keep going, the resilient behaviour Polars exposes as ignore_errors=True (pandas tolerates the same). The column keeps its inferred dtype; only the unparseable cells become null.

Example

test "col: renders as a reference" {
  inspect(col("qty").to_string(), content="col(qty)")
}

Example

test "cols: shorthand for the reference list" {
  debug_inspect(
    cols(["a", "b"]).map(e => e.to_string()),
    content="[\"col(a)\", \"col(b)\"]",
  )
}

Example

test "lit: embeds any Scalar" {
  inspect(lit(@types.Scalar::Int(3L)).to_string(), content="3")
}

Example

test "lit_bool: renders bare" {
  inspect(lit_bool(true).to_string(), content="true")
}

Example

test "lit_float: whole values keep their point" {
  inspect(lit_float(2.0).to_string(), content="2.0")
}

Example

test "lit_int: renders bare" {
  inspect(lit_int(5L).to_string(), content="5")
}

Example

test "lit_series: names its column after the series" {
  let s = @series.Series::from_ints("score", [1, 2])
  inspect(lit_series(s).output_name(), content="score")
}

Example

test "lit_str: renders quoted" {
  inspect(lit_str("ab").to_string(), content="\"ab\"")
}

Example

test "map_many: drops to a host closure" {
  let total = map_many(label="total", [col("a"), col("b")], cells => {
    @types.Scalar::Int(cells[0].as_int() + cells[1].as_int())
  })
  inspect(total.to_string(), content="map(\"total\", [col(a), col(b)])")
}

• projection — the optimizer narrows the leaf to the columns the pipeline provably consumes, and only those are parsed, so scan_csv("sales.csv").select([col("region"), col("revenue")]).collect() never builds the columns it drops;
• predicate — a filter sitting on the leaf moves into the read: the reader builds the predicate's columns, asks which rows survive, then parses the remaining columns for the survivors alone. Only the first such filter is absorbed; a second stays a node above the scan.

Example

test "when: the chain is the only construction route" {
  let tagged = when(col("qty").gt(lit_int(5)))
    .then(lit_str("big"))
    .otherwise(lit_str("small"))
  inspect(
    tagged.to_string(),
    content="when((col(qty) > 5)).then(\"big\").otherwise(\"small\")",
  )
}