Интерактивный Arrow Memory Layout Viewer

Зачем нужен Memory Layout Viewer

В предыдущих уроках мы изучили каждый слой отдельно: fixed-width буферы, variable-width offsets, validity bitmaps, вложенные типы, IPC format. Теперь соберём всё вместе — в интерактивном viewer, который показывает реальную побайтовую структуру Arrow массивов в памяти.

Viewer ниже представляет 6 типов массивов с их буферами, byte offsets и bit-level деталями. Это то, что вы увидите при инспекции Arrow массива через pyarrow.Array.buffers() или при отладке через GDB/LLDB.

Выберите тип массива и кликайте на буферы, чтобы увидеть побайтовое содержимое.

Как читать viewer

Метаданные массива

Верхний блок — метаданные текущего массива:

• layout — физический тип размещения (Primitive, Variable-Width, Struct, Dictionary)
• length — количество элементов в массиве
• nulls — количество null-значений (null_count)
• buffers — количество буферов (validity + offsets/data + children)
• total — суммарный размер буферов (без учёта 64-byte padding)

Validity Bitmap

Каждый массив начинается с validity bitmap (фиолетовый буфер):

• Бит 1 = элемент определён (valid)
• Бит 0 = элемент null
• Биты упакованы LSB first: бит 0 байта 0 = элемент 0
• Если null_count = 0, bitmap может быть опущен (указатель = NULL)

Переключитесь на Nullable Int32 в viewer, чтобы увидеть bitmap с тремя null-слотами.

Offsets и Data

Для variable-width типов (Utf8, Binary, List) viewer показывает два буфера:

• Offsets (синий) — массив int32/int64, где string[i] = data[offsets[i]..offsets[i+1]]
• Data (зелёный) — непрерывный буфер байтов всех значений

Вложенные типы

List и Struct используют child arrays:

• List — offsets буфер + child array (элементы всех списков подряд)
• Struct — только validity bitmap + children (по одному на поле)

Переключитесь на Struct в viewer. Обратите внимание: struct с null в bitmap имеет undefined данные в child arrays — движок проверяет struct bitmap первым.

Dictionary

Dictionary хранит данные как индексы в словарь уникальных значений:

• Indices (синий) — int32 индексы в dictionary values array
• Dictionary Values (зелёный) — Utf8 массив уникальных строк

Переключитесь на Dictionary — при 8 элементах и 3 уникальных строках: 32 байта индексов + 28 байтов словаря = 60 байтов вместо ~50 байтов прямого хранения. Выигрыш становится существенным при миллионах строк.

Инспекция реального массива

В viewer мы используем предопределённые данные. В реальной работе вы будете инспектировать массивы через PyArrow:

import pyarrow as pa

# Создание массива
arr = pa.array([10, 20, None, 40, 50], type=pa.int32())

# Инспекция буферов
print(f"Type: {arr.type}") # int32
print(f"Length: {len(arr)}") # 5
print(f"Null count: {arr.null_count}") # 1
print(f"Buffers: {len(arr.buffers())}") # 2

# Побайтовый доступ
validity = arr.buffers()[0]
data = arr.buffers()[1]
print(f"Validity: {validity.hex()}") # 1b = 00011011
print(f"Data size: {data.size}") # 20 bytes (5 × 4)

# Для Utf8
names = pa.array(["Alice", "Боб", None])
bufs = names.buffers()
print(f"Offsets: {bufs[1].hex()}") # 3 × int32 offsets
print(f"Data: {bufs[2].hex()}") # UTF-8 bytes

Паттерны инспекции

Ключевые выводы

1. Каждый тип = фиксированный набор буферов. Int32 — 2 буфера (validity + data). Utf8 — 3 (validity + offsets + data). Struct — только validity + children. Viewer показывает это наглядно.

2. Null-слоты занимают место. В data buffer null-элемент имеет слот с undefined bytes. Это сохраняет O(1) random access: data[i × sizeof] всегда валидный offset, значение проверяется по bitmap.

3. Offsets = N+1 элементов. Для N строк нужен N+1 offset — последний указывает конец данных. Это позволяет вычислить длину любого элемента за O(1).

4. Children — полноценные arrays. В List и Struct child arrays имеют собственные буферы, bitmap, и тип. Структура рекурсивна: List<Struct<name:Utf8, scores:List<Float64>>> = 4 уровня вложенности.

5. Dictionary = indices + values. Выигрыш при low cardinality: 1M строк × 10 уникальных → 4MB indices + ~100B dict вместо ~10MB строк.