Use SQL parameters¶

Pass values through params instead of inserting them into a SQL string. Session.sql(...) and Session.sql_reader(...) support the same placeholder styles.

Style	SQL placeholder	Python value
Positional	`$1`, `$2`, ...	`list` or `tuple`
Named	`$name`	`dict`

This example runs one query with each style:

from __future__ import annotations

import pyarrow as pa

import timeseries_table_format as ttf


def run() -> list[pa.Table]:
    sess = ttf.Session()

    out_positional = sess.sql(
        "select cast($1 as bigint) as x, cast($2 as varchar) as y",
        params=[1, "hello"],
    )
    out_named = sess.sql(
        "select cast($a as bigint) as x, cast($b as varchar) as y",
        params={"a": 2, "b": "world"},
    )

    return [out_positional, out_named]


def main() -> None:
    out_positional, out_named = run()
    print(out_positional)
    print(out_named)


if __name__ == "__main__":
    main()

Supported values¶

Parameters accept None, bool, int in the Int64 range, float, str, and bytes.

DataFusion usually infers a parameter type from its context. A placeholder in a SELECT projection may need an explicit cast:

SELECT CAST($1 AS BIGINT) AS value;

For UInt64 values above i64::MAX, see Integer ordered indexes.