Операции ввода-вывода DataStore

Чтение и запись данных с помощью DataStore — все поддерживаемые форматы и пункты назначения

DataStore поддерживает чтение из различных форматов файлов и источников данных, а также запись в различные форматы и пункты назначения.

​

Чтение данных

​

CSV-файлы

read_csv(filepath_or_buffer, sep=',', header='infer', names=None, 
         usecols=None, dtype=None, nrows=None, skiprows=None,
         compression=None, encoding=None, **kwargs)

Примеры:

from chdb import datastore as pd

# Базовое чтение CSV
ds = pd.read_csv("data.csv")

# С параметрами
ds = pd.read_csv(
    "data.csv",
    sep=";",                    # Пользовательский разделитель
    header=0,                   # Индекс строки заголовка
    names=['a', 'b', 'c'],      # Пользовательские имена столбцов
    usecols=['a', 'b'],         # Читать только указанные столбцы
    dtype={'a': 'Int64'},       # Указать типы данных
    nrows=1000,                 # Читать только первые 1000 строк
    skiprows=1,                 # Пропустить первую строку
    compression='gzip',         # Сжатый файл
    encoding='utf-8'            # Кодировка
)

# Из URL
ds = pd.read_csv("https://example.com/data.csv")

​

Файлы Parquet

Рекомендуется для больших датасетов — столбцовый формат с более эффективным сжатием.

read_parquet(path, columns=None, **kwargs)

Примеры:

# Базовое чтение Parquet
ds = pd.read_parquet("data.parquet")

# Чтение только указанных столбцов (эффективно — считываются только нужные данные)
ds = pd.read_parquet("data.parquet", columns=['col1', 'col2', 'col3'])

# Из S3
ds = pd.read_parquet("s3://bucket/data.parquet")

​

JSON‑файлы

read_json(path_or_buf, orient=None, lines=False, **kwargs)

Примеры:

# Стандартный JSON
ds = pd.read_json("data.json")

# JSON Lines (с разделением переносом строки)
ds = pd.read_json("data.jsonl", lines=True)

# JSON с заданной ориентацией
ds = pd.read_json("data.json", orient='records')

​

Файлы Excel

read_excel(io, sheet_name=0, header=0, names=None, **kwargs)

Примеры:

# Чтение первого листа
ds = pd.read_excel("data.xlsx")

# Чтение конкретного листа
ds = pd.read_excel("data.xlsx", sheet_name="Sheet1")
ds = pd.read_excel("data.xlsx", sheet_name=2)  # Третий лист

# Чтение нескольких листов (возвращает dict)
sheets = pd.read_excel("data.xlsx", sheet_name=['Sheet1', 'Sheet2'])

​

SQL-базы данных

read_sql(sql, con, **kwargs)

Примеры:

# Чтение из SQL-запроса
ds = pd.read_sql("SELECT * FROM users", connection)
ds = pd.read_sql("SELECT * FROM orders WHERE date > '2024-01-01'", connection)

​

Другие форматы

# Feather (Arrow)
ds = pd.read_feather("data.feather")

# ORC
ds = pd.read_orc("data.orc")

# Pickle
ds = pd.read_pickle("data.pkl")

# Формат с фиксированной шириной полей
ds = pd.read_fwf("data.txt", widths=[10, 20, 15])

# HTML-таблицы
ds = pd.read_html("https://example.com/table.html")[0]

---

​

Запись данных

​

to_csv

Экспорт в формате CSV.

to_csv(path_or_buf=None, sep=',', na_rep='', header=True, 
       index=True, mode='w', compression=None, **kwargs)

Примеры:

ds = pd.read_parquet("data.parquet")

# Базовый экспорт
ds.to_csv("output.csv")

# С параметрами
ds.to_csv(
    "output.csv",
    sep=";",                    # Произвольный разделитель
    index=False,                # Не включать индекс
    header=True,                # Включить заголовок
    na_rep='NULL',              # Представлять NaN как 'NULL'
    compression='gzip'          # Сжать вывод
)

# В строку
csv_string = ds.to_csv()

​

to_parquet

Экспорт в формате Parquet (рекомендуется для больших объёмов данных).

to_parquet(path, engine='pyarrow', compression='snappy', **kwargs)

Примеры:

# Базовый экспорт
ds.to_parquet("output.parquet")

# С параметрами сжатия
ds.to_parquet("output.parquet", compression='gzip')
ds.to_parquet("output.parquet", compression='zstd')

# Партиционированный вывод
ds.to_parquet(
    "output/",
    partition_cols=['year', 'month']
)

​

to_json

Экспорт в формате JSON.

to_json(path_or_buf=None, orient='records', lines=False, **kwargs)

Примеры:

# Стандартный JSON (массив записей)
ds.to_json("output.json", orient='records')

# JSON Lines (один объект JSON на строку)
ds.to_json("output.jsonl", lines=True)

# Различные ориентации
ds.to_json("output.json", orient='split')    # {columns, data, index}
ds.to_json("output.json", orient='records')  # [{col: val}, ...]
ds.to_json("output.json", orient='columns')  # {col: {idx: val}}

# В строку
json_string = ds.to_json()

​

to_excel

Экспорт в формате Excel.

to_excel(excel_writer, sheet_name='Sheet1', index=True, **kwargs)

Примеры:

# Один лист
ds.to_excel("output.xlsx")
ds.to_excel("output.xlsx", sheet_name="Data", index=False)

# Несколько листов
with pd.ExcelWriter("output.xlsx") as writer:
    ds1.to_excel(writer, sheet_name="Sales")
    ds2.to_excel(writer, sheet_name="Inventory")

​

to_sql

Экспорт в базу данных SQL или создание SQL-строки.

to_sql(name=None, con=None, schema=None, if_exists='fail', **kwargs)

Примеры:

# Сгенерировать SQL-запрос (без выполнения)
sql = ds.to_sql()
print(sql)
# SELECT ...
# FROM ...
# WHERE ...

# Записать в базу данных
ds.to_sql("table_name", connection, if_exists='replace')

​

Другие способы экспорта

# В pandas DataFrame
df = ds.to_df()
df = ds.to_pandas()

# В Arrow Table
table = ds.to_arrow()

# В массив NumPy
arr = ds.to_numpy()

# В словарь
d = ds.to_dict()
d = ds.to_dict(orient='records')  # Список словарей
d = ds.to_dict(orient='list')     # Словарь списков

# В записи (список кортежей)
records = ds.to_records()

# В строку
s = ds.to_string()
s = ds.to_string(max_rows=100)

# В Markdown
md = ds.to_markdown()

# В HTML
html = ds.to_html()

# В LaTeX
latex = ds.to_latex()

# В буфер обмена
ds.to_clipboard()

# В pickle
ds.to_pickle("output.pkl")

# В feather
ds.to_feather("output.feather")

---

​

Сравнение форматов файлов

Формат	Скорость чтения	Скорость записи	Размер файла	Схема	Лучше всего подходит для
Parquet	Высокая	Высокая	Небольшой	Да	Крупных наборов данных, аналитики
CSV	Средняя	Высокая	Большой	Нет	Совместимости, простых данных
JSON	Низкая	Средняя	Большой	Частично	API, вложенных данных
Excel	Низкая	Низкая	Средний	Частично	Обмена с нетехническими пользователями
Feather	Очень высокая	Очень высокая	Средний	Да	Межпроцессного обмена, pandas

​

Рекомендации

1. Для аналитических рабочих нагрузок: используйте Parquet

   • Столбцовый формат позволяет считывать только нужные столбцы
   • Отличное сжатие
   • Сохраняет типы данных

2. Для обмена данными: используйте CSV или JSON

   • Универсальная совместимость
   • Удобочитаемый формат

3. Для интеграции с pandas: используйте Feather или Arrow

   • Самая быстрая сериализация
   • Сохранение типов

---

​

Поддержка сжатия

​

Чтение сжатых файлов

# Автоопределение по расширению
ds = pd.read_csv("data.csv.gz")
ds = pd.read_csv("data.csv.bz2")
ds = pd.read_csv("data.csv.xz")
ds = pd.read_csv("data.csv.zst")

# Явное указание сжатия
ds = pd.read_csv("data.csv", compression='gzip')

​

Запись сжатых файлов

# CSV со сжатием
ds.to_csv("output.csv.gz", compression='gzip')
ds.to_csv("output.csv.bz2", compression='bz2')

# Parquet (всегда со сжатием)
ds.to_parquet("output.parquet", compression='snappy')  # По умолчанию
ds.to_parquet("output.parquet", compression='gzip')
ds.to_parquet("output.parquet", compression='zstd')    # Лучшая степень сжатия
ds.to_parquet("output.parquet", compression='lz4')     # Быстрее всего

​

Параметры сжатия

Сжатие	Скорость	Степень сжатия	Сценарий использования
snappy	Очень высокая	Низкая	По умолчанию для Parquet
lz4	Очень высокая	Низкая	Приоритет — скорость
gzip	Средняя	Высокая	Совместимость
zstd	Высокая	Очень высокая	Оптимальный баланс
bz2	Низкая	Очень высокая	Максимальное сжатие

---

​

Потоковый ввод-вывод

Для очень больших файлов, не помещающихся в память:

​

Чтение по фрагментам

# Чтение фрагментами
for chunk in pd.read_csv("large.csv", chunksize=100000):
    # Обработка каждого фрагмента
    process(chunk)

# Использование итератора
reader = pd.read_csv("large.csv", iterator=True)
chunk = reader.get_chunk(10000)

​

Использование стриминга в ClickHouse

from chdb.datastore import DataStore

# Потоковое чтение из файла без загрузки всего содержимого в память
ds = DataStore.from_file("huge.parquet")

# Операции ленивые — вычисляется только то, что необходимо
result = ds.filter(ds['amount'] > 1000).head(100)

---

​

Удалённые источники данных

​

HTTP/HTTPS

# Чтение по URL
ds = pd.read_csv("https://example.com/data.csv")
ds = pd.read_parquet("https://example.com/data.parquet")

​

S3

from chdb.datastore import DataStore

# Анонимный доступ
ds = DataStore.uri("s3://bucket/data.parquet?nosign=true")

# С учётными данными
ds = DataStore.from_s3(
    "s3://bucket/data.parquet",
    access_key_id="KEY",
    secret_access_key="SECRET"
)

​

GCS, Azure, HDFS

См. Factory Methods, чтобы узнать о вариантах облачных хранилищ.

---

​

Рекомендации

​

1. Используйте формат Parquet для больших файлов

# Конвертируйте CSV в Parquet для повышения производительности
ds = pd.read_csv("large.csv")
ds.to_parquet("large.parquet")

# Последующее чтение выполняется значительно быстрее
ds = pd.read_parquet("large.parquet")

​

2. Выбирайте только нужные столбцы

# Эффективно — считывает только col1 и col2
ds = pd.read_parquet("data.parquet", columns=['col1', 'col2'])

# Неэффективно — считывает все столбцы, затем фильтрует
ds = pd.read_parquet("data.parquet")[['col1', 'col2']]

​

3. Используйте сжатие

# Меньший размер файла, как правило быстрее из-за меньшего объёма операций ввода/вывода
ds.to_parquet("output.parquet", compression='zstd')

​

4. Батч-записи

# Записать один раз, а не в цикле
result = process_all_data(ds)
result.to_parquet("output.parquet")

# НЕ так (неэффективно)
for chunk in chunks:
    chunk.to_parquet(f"output_{i}.parquet")