Convert record sequences
You have nested Python lists or tuples and need a Polars DataFrame.
Polars · Function
pl.from_records
Constructs a Polars DataFrame from a two-dimensional sequence of records. It supports explicit schemas, type overrides, orientation control, strict conversion, and bounded schema inference.
How it works
from_records constructs a DataFrame from two-dimensional sequence data. It clones the input, can accept an explicit schema or schema overrides, and infers whether the data represents columns or rows when orientation is omitted; unresolved cases default to column orientation.
Syntax
polars.from_records(data: Sequence[Any], schema: SchemaDefinition | None = None, *, schema_overrides: SchemaDict | None = None, strict: bool = True, orient: Orientation | None = None, infer_schema_length: int | None = 100) → DataFrameParameters
| Name | Type | Description |
|---|---|---|
data | Sequence[Any] | Two-dimensional data represented as a sequence of sequences. |
schema | SchemaDefinition | None | DataFrame schema, supplied as column names, name-type pairs, or a name-to-data-type mapping. |
schema_overrides | SchemaDict | None | Optional per-column data-type overrides. |
strict | bool | Whether conversion must use strict type handling. |
orient | Orientation | None | Interpret the two-dimensional input as columns or rows; valid values are None, 'col', and 'row'. |
infer_schema_length | int | None | Number of records used for schema inference; defaults to 100, and None scans all data. |
Returns
DataFrame
Key points
- The function creates a DataFrame from two-dimensional sequence input.
- The
dataargument expects nested sequence values rather than a single flat sequence. - You can provide schema information in multiple supported forms, including names, name-type pairs, or a mapping.
- Use
orientto choose whether nested values describe columns or rows. - Ambiguous automatic orientation resolves to column interpretation.
Common mistakes
- Input data is copied rather than reused in place.
- For column-oriented inputs where performance matters, a columnar constructor can be faster.
- Leaving
orientunset can make interpretation depend on the shape of the data. - Using
infer_schema_length=Nonemay increase inference cost because all records can be scanned.
Example: Build a DataFrame from records
import polars as pl
data = [[1, 2, 3], [4, 5, 6]]
df = pl.from_records(data, schema=["a", "b", "c"])
print(df)Creates a DataFrame from row-oriented records and assigns the three column names.
When to use it
Declare a schema
Column names or types are known before construction.
Control orientation
The nested input could be interpreted in more than one direction.
Adjust schema inference
Early records are not representative of the complete dataset.
Interview questions
QWhat does polars.from_records construct?
It accepts a two-dimensional sequence and returns a DataFrame. The input is cloned, and the function can use a declared schema, schema overrides, strict type handling, orientation, and a schema-inference limit.
Follow-up: What happens when orientation is omitted? The function compares column and data dimensions; if that is inconclusive, it uses column orientation.
QHow does orientation selection work?
orient controls whether the two-dimensional input is interpreted as columns or rows. With None, Polars infers the orientation from the dimensions and falls back to column orientation when it cannot decide.
Follow-up: Why might explicitly setting orient be preferable? It removes ambiguity when the input dimensions do not uniquely identify the intended layout.
QWhat is the purpose and trade-off of infer_schema_length?
infer_schema_length defaults to 100, limiting how many records are inspected for schema inference. Setting it to None allows the full input to be scanned, which the documentation notes is slow.
Follow-up: When could a larger inference scan be useful? It can help when early records do not represent later values well, at the cost of additional scanning.
Related
from_records()