pyarrow.Field

class pyarrow.Field

Bases: _Weakrefable

A named field, with a data type, nullability, and optional metadata.

Notes

Do not use this class’s constructor directly; use pyarrow.field

Examples

Create an instance of pyarrow.Field:

>>> import pyarrow as pa
>>> pa.field('key', pa.int32())
pyarrow.Field<key: int32>
>>> pa.field('key', pa.int32(), nullable=False)
pyarrow.Field<key: int32 not null>
>>> field = pa.field('key', pa.int32(),
...                  metadata={"key": "Something important"})
>>> field
pyarrow.Field<key: int32>
>>> field.metadata
{b'key': b'Something important'}

Use the field to create a struct type:

>>> pa.struct([field])
StructType(struct<key: int32>)
__init__(*args, **kwargs)

Methods

__init__(*args, **kwargs)

equals(self, Field other, ...)

Test if this field is equal to the other

flatten(self)

Flatten this field.

remove_metadata(self)

Create new field without metadata, if any

with_metadata(self, metadata)

Add metadata as dict of string keys and values to Field

with_name(self, name)

A copy of this field with the replaced name

with_nullable(self, nullable)

A copy of this field with the replaced nullability

with_type(self, DataType new_type)

A copy of this field with the replaced type

Attributes

metadata

The field metadata.

name

The field name.

nullable

The field nullability.

type

equals(self, Field other, bool check_metadata=False)

Test if this field is equal to the other

Parameters:
otherpyarrow.Field
check_metadatabool, default False

Whether Field metadata equality should be checked as well.

Returns:
is_equalbool

Examples

>>> import pyarrow as pa
>>> f1 = pa.field('key', pa.int32())
>>> f2 = pa.field('key', pa.int32(), nullable=False)
>>> f1.equals(f2)
False
>>> f1.equals(f1)
True
flatten(self)

Flatten this field. If a struct field, individual child fields will be returned with their names prefixed by the parent’s name.

Returns:
fieldsList[pyarrow.Field]

Examples

>>> import pyarrow as pa
>>> f1 = pa.field('bar', pa.float64(), nullable=False)
>>> f2 = pa.field('foo', pa.int32()).with_metadata({"key": "Something important"})
>>> ff = pa.field('ff', pa.struct([f1, f2]), nullable=False)

Flatten a struct field:

>>> ff
pyarrow.Field<ff: struct<bar: double not null, foo: int32> not null>
>>> ff.flatten()
[pyarrow.Field<ff.bar: double not null>, pyarrow.Field<ff.foo: int32>]
metadata

The field metadata.

Examples

>>> import pyarrow as pa
>>> field = pa.field('key', pa.int32(),
...                  metadata={"key": "Something important"})
>>> field.metadata
{b'key': b'Something important'}
name

The field name.

Examples

>>> import pyarrow as pa
>>> field = pa.field('key', pa.int32())
>>> field.name
'key'
nullable

The field nullability.

Examples

>>> import pyarrow as pa
>>> f1 = pa.field('key', pa.int32())
>>> f2 = pa.field('key', pa.int32(), nullable=False)
>>> f1.nullable
True
>>> f2.nullable
False
remove_metadata(self)

Create new field without metadata, if any

Returns:
fieldpyarrow.Field

Examples

>>> import pyarrow as pa
>>> field = pa.field('key', pa.int32(),
...                  metadata={"key": "Something important"})
>>> field.metadata
{b'key': b'Something important'}

Create new field by removing the metadata from the existing one:

>>> field_new = field.remove_metadata()
>>> field_new.metadata
type
with_metadata(self, metadata)

Add metadata as dict of string keys and values to Field

Parameters:
metadatadict

Keys and values must be string-like / coercible to bytes

Returns:
fieldpyarrow.Field

Examples

>>> import pyarrow as pa
>>> field = pa.field('key', pa.int32())

Create new field by adding metadata to existing one:

>>> field_new = field.with_metadata({"key": "Something important"})
>>> field_new
pyarrow.Field<key: int32>
>>> field_new.metadata
{b'key': b'Something important'}
with_name(self, name)

A copy of this field with the replaced name

Parameters:
namestr
Returns:
fieldpyarrow.Field

Examples

>>> import pyarrow as pa
>>> field = pa.field('key', pa.int32())
>>> field
pyarrow.Field<key: int32>

Create new field by replacing the name of an existing one:

>>> field_new = field.with_name('lock')
>>> field_new
pyarrow.Field<lock: int32>
with_nullable(self, nullable)

A copy of this field with the replaced nullability

Parameters:
nullablebool
Returns:
field: pyarrow.Field

Examples

>>> import pyarrow as pa
>>> field = pa.field('key', pa.int32())
>>> field
pyarrow.Field<key: int32>
>>> field.nullable
True

Create new field by replacing the nullability of an existing one:

>>> field_new = field.with_nullable(False)
>>> field_new
pyarrow.Field<key: int32 not null>
>>> field_new.nullable
False
with_type(self, DataType new_type)

A copy of this field with the replaced type

Parameters:
new_typepyarrow.DataType
Returns:
fieldpyarrow.Field

Examples

>>> import pyarrow as pa
>>> field = pa.field('key', pa.int32())
>>> field
pyarrow.Field<key: int32>

Create new field by replacing type of an existing one:

>>> field_new = field.with_type(pa.int64())
>>> field_new
pyarrow.Field<key: int64>