narwhals.Schema

Ordered mapping of column names to their data type.

Parameters:

Name	Type	Description	Default
schema	Mapping[str, DType] | Iterable[tuple[str, DType]] | None	The schema definition given by column names and their associated instantiated Narwhals data type. Accepts a mapping or an iterable of tuples.	None

Examples:

Define a schema by passing instantiated data types.

>>> import narwhals as nw
>>> schema = nw.Schema({"foo": nw.Int8(), "bar": nw.String()})
>>> schema
Schema({'foo': Int8, 'bar': String})

Access the data type associated with a specific column name.

>>> schema["foo"]
Int8

Access various schema properties using the names, dtypes, and len methods.

>>> schema.names()
['foo', 'bar']
>>> schema.dtypes()
[Int8, String]
>>> schema.len()
2

names

names() -> list[str]

Get the column names of the schema.

dtypes

dtypes() -> list[DType]

Get the data types of the schema.

from_arrow classmethod

from_arrow(schema: IntoArrowSchema) -> Self

Construct a Schema from a pyarrow Schema.

Parameters:

Name	Type	Description	Default
schema	IntoArrowSchema	A pyarrow Schema or mapping of column names to pyarrow data types.	required

Examples:

>>> import pyarrow as pa
>>> import narwhals as nw
>>>
>>> mapping = {
...     "a": pa.timestamp("us", "UTC"),
...     "b": pa.date32(),
...     "c": pa.string(),
...     "d": pa.uint8(),
... }
>>> native = pa.schema(mapping)
>>>
>>> nw.Schema.from_arrow(native)
Schema({'a': Datetime(time_unit='us', time_zone='UTC'), 'b': Date, 'c': String, 'd': UInt8})

>>> nw.Schema.from_arrow(mapping) == nw.Schema.from_arrow(native)
True

from_native classmethod

from_native(
    schema: (
        IntoArrowSchema
        | IntoPolarsSchema
        | IntoPandasSchema
    ),
) -> Self

Construct a Schema from a native schema representation.

Parameters:

Name	Type	Description	Default
schema	IntoArrowSchema | IntoPolarsSchema | IntoPandasSchema	A native schema object, or mapping of column names to instantiated native data types.	required

Examples:

>>> import datetime as dt
>>> import pyarrow as pa
>>> import narwhals as nw
>>>
>>> data = {"a": [1], "b": ["a"], "c": [dt.time(1, 2, 3)], "d": [[2]]}
>>> native = pa.table(data).schema
>>>
>>> nw.Schema.from_native(native)
Schema({'a': Int64, 'b': String, 'c': Time, 'd': List(Int64)})

from_pandas_like classmethod

from_pandas_like(schema: IntoPandasSchema) -> Self

Construct a Schema from a pandas-like schema representation.

Parameters:

Name	Type	Description	Default
schema	IntoPandasSchema	A mapping of column names to pandas-like data types.	required

Examples:

>>> import numpy as np
>>> import pandas as pd
>>> import pyarrow as pa
>>> import narwhals as nw
>>>
>>> data = {"a": [1], "b": ["a"], "c": [False], "d": [9.2]}
>>> native = pd.DataFrame(data).convert_dtypes().dtypes.to_dict()
>>>
>>> nw.Schema.from_pandas_like(native)
Schema({'a': Int64, 'b': String, 'c': Boolean, 'd': Float64})
>>>
>>> mapping = {
...     "a": pd.DatetimeTZDtype("us", "UTC"),
...     "b": pd.ArrowDtype(pa.date32()),
...     "c": pd.StringDtype("python"),
...     "d": np.dtype("uint8"),
... }
>>>
>>> nw.Schema.from_pandas_like(mapping)
Schema({'a': Datetime(time_unit='us', time_zone='UTC'), 'b': Date, 'c': String, 'd': UInt8})

from_polars classmethod

from_polars(schema: IntoPolarsSchema) -> Self

Construct a Schema from a polars Schema.

Parameters:

Name	Type	Description	Default
schema	IntoPolarsSchema	A polars Schema or mapping of column names to instantiated polars data types.	required

Examples:

>>> import polars as pl
>>> import narwhals as nw
>>>
>>> mapping = {
...     "a": pl.Datetime(time_zone="UTC"),
...     "b": pl.Date(),
...     "c": pl.String(),
...     "d": pl.UInt8(),
... }
>>> native = pl.Schema(mapping)
>>>
>>> nw.Schema.from_polars(native)
Schema({'a': Datetime(time_unit='us', time_zone='UTC'), 'b': Date, 'c': String, 'd': UInt8})

>>> nw.Schema.from_polars(mapping) == nw.Schema.from_polars(native)
True

len

len() -> int

Get the number of columns in the schema.

to_arrow

to_arrow() -> pa.Schema

Convert Schema to a pyarrow Schema.

Examples:

>>> import narwhals as nw
>>> schema = nw.Schema({"a": nw.Int64(), "b": nw.Datetime("ns")})
>>> schema.to_arrow()
a: int64
b: timestamp[ns]

to_pandas

to_pandas(
    dtype_backend: (
        DTypeBackend | Iterable[DTypeBackend]
    ) = None,
) -> dict[str, Any]

Convert Schema to an ordered mapping of column names to their pandas data type.

Parameters:

Name	Type	Description	Default
dtype_backend	DTypeBackend | Iterable[DTypeBackend]	Backend(s) used for the native types. When providing more than one, the length of the iterable must be equal to the length of the schema.	None

Examples:

>>> import narwhals as nw
>>> schema = nw.Schema({"a": nw.Int64(), "b": nw.Datetime("ns")})
>>> schema.to_pandas()
{'a': 'int64', 'b': 'datetime64[ns]'}

>>> schema.to_pandas("pyarrow")
{'a': 'Int64[pyarrow]', 'b': 'timestamp[ns][pyarrow]'}

to_polars

to_polars() -> pl.Schema

Convert Schema to a polars Schema.

Examples:

>>> import narwhals as nw
>>> schema = nw.Schema({"a": nw.Int64(), "b": nw.Datetime("ns")})
>>> schema.to_polars()
Schema({'a': Int64, 'b': Datetime(time_unit='ns', time_zone=None)})