Polars Series struct.schema() – Explained by Examples

The polars.Series.struct.schema property in Polars is used to get the schema of a struct-type Series. When you have a Series where each element is a struct (similar to a nested record or dictionary with named fields), struct.schema returns a dictionary describing the field names and their data types within that struct.

In this article, I will describe the Polars Series struct.schema() method, including its syntax, parameters, and usage, and details how it returns a Python dictionary that maps field names to their corresponding Polars data types.

Key Points –

struct.schema() returns the schema of a struct Series in Polars.
It is a property of a Polars Series with Struct dtype.
Does not require parentheses since it’s a property, not a method.
Reflects the schema of the inner fields inside the struct elements.
Can handle nested structs, where a field’s type can be another Struct.
If all values are null or the Series is empty, it returns an empty dictionary ({}).
Supports all Polars data types, including Int64, Utf8, Boolean, Float64, and others.
Allows drilling down into nested struct schemas by accessing the nested struct as a Series and then using struct.schema again.

Polars Series struct.schema() Introduction

Let’s know the syntax of the series struct.schema() method.


# Syntax of Series struct.schema()
Series.struct.schema = {}

Following are the parameters of the series struct.schema() method.

series must be a polars.Series whose dtype is Struct.
The expression returns a regular Python dict that maps each field name inside the struct to its Polars data type (pl.Int64, pl.Utf8, pl.Struct, etc.).
Because it’s a property, you don’t add parentheses—no ().

Usage of Polars Series struct.schema()

Series.struct.schema() returns the schema of a Polars Series whose elements are structs. Specifically, it provides a list of tuples describing each field name and its data type within the struct. This lets you see the structure, field names, and types of the nested data inside the Series.

First, let’s create a Polars Series.


import polars as pl

# Create a struct Series
ser = pl.Series("tech_col", [
    {"Courses": "Spark", "Fees": 20000},
    {"Courses": "PySpark", "Fees": 30000},
    {"Courses": "Hadoop", "Fees": 40000}
])
print("Original Series:\n", ser)

Yields below output.

A Polars Series with a struct data type that includes integer and string fields. Below is a straightforward example demonstrating a struct Series with integer and string fields, along with how to retrieve its schema.


# Inspect the inner-struct schema
ser2 = ser.struct.schema
print("Struct schema:", ser2)

Here,

Courses are inferred as Utf8 (string).
Fees are inferred as Int64.

Struct with Nested Struct Inside

A Polars Series containing a nested struct, demonstrating how to create such a Series and how to examine the schema at both the outer and inner struct levels. Each element in the Series is a struct that includes another struct nested within it.


import polars as pl

# Create a struct Series with a nested struct field
ser = pl.Series(
    "nested_struct",
    [
        {"id": 1, "info": {"age": 25, "city": "NY"}},
        {"id": 2, "info": {"age": 30, "city": "LA"}},
    ]
)

# Outer struct schema
outer_schema = ser.struct.schema
print("\nOuter struct schema:\n",outer_schema)

# Extract nested struct 'info' as a Series and get its schema
info_struct = ser.struct.field("info")
nested_schema = info_struct.struct.schema
print("Nested struct 'info' schema:\n",nested_schema)

# Output:
# Outer struct schema:
# Schema({'id': Int64, 'info': Struct({'age': Int64, 'city': String})})

# Nested struct 'info' schema:
# Schema({'age': Int64, 'city': String})

Here,

The outer struct has fields "id" (int) and "info" (nested struct).
The nested struct "info" has "age" (int) and "city" (string).
You use struct.schema to get the schema at any struct level.
Use struct.field("field_name") to access a nested struct as a Series, then struct.schema again to inspect its schema.

Struct with Float and Boolean Fields

A Polars Series in which each element is a struct with a float and a boolean field. Here's a simple example demonstrating how to create such a Series and check its schema.


import polars as pl

# Struct Series with float and boolean fields
ser = pl.Series(
    "metrics",
    [
        {"score": 9.5, "passed": True},
        {"score": 7.3, "passed": False},
    ]
)

# Inspect inner-struct schema (property, no parentheses)
ser2 = ser.struct.schema
print("Struct schema:\n", ser2)

# Output:
# Struct schema:
# Schema({'score': Float64, 'passed': Boolean})

Here,

Fields: score (Float64), passed (Boolean).
The struct.schema property is read-only and returns a standard Python dictionary that maps each field name to its corresponding Polars data type.

Struct with Optional (Null) Fields

A struct field can be optional, allowing it to contain null values in certain rows. While the values may be missing, the field still adheres to a consistent schema across all entries.


import polars as pl

# Struct Series with optional (nullable) fields
ser = pl.Series(
    "person",
    [
        {"name": "Alice", "age": 30},
        {"name": "Bob", "age": None},     # 'age' is null here
        {"name": None, "age": 45},        # 'name' is null here
    ]
)

# Schema inspection
ser2 = ser.struct.schema
print("\nStruct schema:\n", ser2)

# Output:
# Struct schema:
# {'name': pl.Utf8, 'age': pl.Int64}

Here,

Even if some values are null, the schema continues to represent the actual data types: "name" is of type Utf8 (string), and "age" is of type Int64 (integer).
Polars infers types from non-null values, so as long as at least one row contains a valid (non-null) value, it knows the type.

Conclusion

In conclusion, the struct.schema property in Polars is a useful feature for examining the structure of complex or nested data. Whether the struct fields hold integers, strings, floats, booleans, or even other structs, struct.schema provides a clear and easy way to view each field's name and data type.

Happy Learning!!

Reference

https://docs.pola.rs/api/python/version/0.18/reference/series/api/polars.Series.struct.unnest.html

Polars Series struct.schema() – Explained by Examples

Polars Series struct.schema() Introduction

Usage of Polars Series struct.schema()

Struct with Nested Struct Inside

Struct with Float and Boolean Fields

Struct with Optional (Null) Fields

Conclusion

Related Articles

Reference