pandas.Series.struct.field#

Series.struct.field(name_or_index)[source]#

Extract a child field of a struct as a Series.

Parameters:

name_or_indexstr | bytes | int | expression | list

Name or index of the child field to extract.

For list-like inputs, this will index into a nested struct.

Returns:

pandas.Series: The data corresponding to the selected child field.

See also

Series.struct.explode: Return all child fields as a DataFrame.

Notes

The name of the resulting Series will be set using the following rules:

For string, bytes, or integer name_or_index (or a list of these, for a nested selection), the Series name is set to the selected field’s name.
For a pyarrow.compute.Expression, this is set to the string form of the expression.
For list-like name_or_index, the name will be set to the name of the final field selected.

Examples

>>> import pyarrow as pa
>>> s = pd.Series(
...     [
...         {"version": 1, "project": "pandas"},
...         {"version": 2, "project": "pandas"},
...         {"version": 1, "project": "numpy"},
...     ],
...     dtype=pd.ArrowDtype(
...         pa.struct([("version", pa.int64()), ("project", pa.string())])
...     ),
... )

Extract by field name.

>>> s.struct.field("project")
0    pandas
1    pandas
2     numpy
Name: project, dtype: string[pyarrow]

Extract by field index.

>>> s.struct.field(0)
0    1
1    2
2    1
Name: version, dtype: int64[pyarrow]

Or an expression

>>> import pyarrow.compute as pc
>>> s.struct.field(pc.field("project"))
0    pandas
1    pandas
2     numpy
Name: project, dtype: string[pyarrow]

For nested struct types, you can pass a list of values to index multiple levels:

>>> version_type = pa.struct(
...     [
...         ("major", pa.int64()),
...         ("minor", pa.int64()),
...     ]
... )
>>> s = pd.Series(
...     [
...         {"version": {"major": 1, "minor": 5}, "project": "pandas"},
...         {"version": {"major": 2, "minor": 1}, "project": "pandas"},
...         {"version": {"major": 1, "minor": 26}, "project": "numpy"},
...     ],
...     dtype=pd.ArrowDtype(
...         pa.struct([("version", version_type), ("project", pa.string())])
...     ),
... )
>>> s.struct.field(["version", "minor"])
0     5
1     1
2    26
Name: minor, dtype: int64[pyarrow]
>>> s.struct.field([0, 0])
0    1
1    2
2    1
Name: major, dtype: int64[pyarrow]