Scalars

A scalar is a single, typed value drawn from an array — the result of indexing into a column, or of reducing one with an aggregate. Scalars carry their Arrow type and know whether they are null, so a missing value stays distinct from a zero or an empty string.

Getting a scalar

Indexing an array with [] returns a scalar:

a = ma.array([10, None, 30])

first = a[0]
print(first)              # the scalar
print(first.as_py())      # 10 — as a native Python value
print(first.type)       # int64

10
10
int64

Slicing an array and taking an element gives a scalar the same way — the underlying buffer is shared, so neither step copies:

tail = a.slice(2)
print(tail[0], "|", tail[0].as_py(), "|", tail[0].type)

30 | 30 | int64

Null scalars

A null position yields a scalar that reports is_null() and converts to Python None:

missing = a[1]
print("is_null: ", missing.is_null())
print("is_valid:", missing.is_valid())
print("as_py:   ", missing.as_py())

is_null:  True
is_valid: False
as_py:    None

Note

is_valid() and is_null() are exact opposites — a scalar is either present or absent. Absence is not the same as the value 0.

Scalars of every type

Each array type produces a matching scalar, including strings and structs. One known gap: binary and large string scalars report their type as string.

s = ma.array(["hi", None, "there"])
print(s[0], "->", s[0].as_py())

people = ma.array([{"x": 1, "y": 2.0}])
print(people[0], "->", people[0].as_py())

hi -> hi
{1, 2.0} -> {'x': 1, 'y': 2.0}

The scalar API

Method	Returns	Description
.as_py()	Python object	Native value, or None if null
.is_valid()	bool	True if the value is present
.is_null()	bool	True if the value is absent
.type	DataType	The Arrow type of the value

Scalars are also truthy through __bool__, so a boolean scalar can be used directly in a condition:

flag = ma.array([True, False])[0]
print("truthy:", bool(flag))

truthy: True