Быстрый старт с DataStore

Начните работу с DataStore: установка, однострочная миграция с pandas и базовое использование

Начните работу с DataStore за считанные минуты. В этом руководстве описаны установка, миграция с pandas и базовые сценарии использования.

​

Установка

Установите chDB с помощью pip:

pip install "chdb>=4.0"

Для дополнительных зависимостей:

# Для поддержки pandas DataFrame
pip install "chdb[pandas]>=4.0"

# Для поддержки PyArrow
pip install "chdb[arrow]>=4.0"

# Все необязательные зависимости
pip install "chdb[all]>=4.0"

​

Проверьте установку

import chdb
print(chdb.__version__)  # Должно вывести 4.x.x или выше

from chdb import datastore as pd
print("DataStore ready!")

​

Однострочная миграция с Pandas

Чтобы начать использовать DataStore, достаточно изменить оператор импорта:

# До (pandas)
import pandas as pd

# После (DataStore)
from chdb import datastore as pd

Вот и всё! Ваш существующий код на pandas теперь будет использовать DataStore и получит преимущества SQL-оптимизации.

​

Пример миграции

from pathlib import Path
Path("employees.csv").write_text("""\
name,age,city,salary,department,dept_id,status,email
Alice,28,NYC,75000,Engineering,1,active,[e-mail]
Bob,35,LA,85000,Engineering,1,active,[e-mail]
Charlie,52,NYC,95000,Product,2,active,[e-mail]
Diana,32,SF,70000,Design,3,active,[e-mail]
Eve,23,LA,48000,Product,2,inactive,[e-mail]
""")

# Оригинальный код на pandas
import pandas as pd

df = pd.read_csv("employees.csv")
result = (df[df['salary'] > 50000]
          .groupby('department')['salary']
          .agg(['mean', 'count'])
          .sort_values('mean', ascending=False))
print(result)

# Версия DataStore — просто замените импорт!
from chdb import datastore as pd

df = pd.read_csv("employees.csv")
result = (df[df['salary'] > 50000]
          .groupby('department')['salary']
          .agg(['mean', 'count'])
          .sort_values('mean', ascending=False))
print(result)  # Тот же результат, быстрее выполнение!

​

Базовое использование

​

Создание DataStore

from chdb import datastore as pd

# Из словаря
ds = pd.DataFrame({
    'name': ['Alice', 'Bob', 'Charlie'],
    'age': [25, 30, 35],
    'city': ['NYC', 'LA', 'NYC']
})

# Из pandas DataFrame
import pandas
pdf = pandas.DataFrame({'a': [1, 2, 3], 'b': [4, 5, 6]})
ds = pd.DataFrame(pdf)

# Из CSV-файла
ds = pd.read_csv("data.csv")

# Из файла Parquet (рекомендуется для больших наборов данных)
ds = pd.read_parquet("data.parquet")

​

Фильтрация данных

from chdb import datastore as pd

ds = pd.read_csv("employees.csv")

# Одно условие
senior = ds[ds['age'] > 30]

# Несколько условий (побитовое И)
senior_nyc = ds[(ds['age'] > 30) & (ds['city'] == 'NYC')]

# Несколько условий (ИЛИ)
young_or_senior = ds[(ds['age'] < 25) | (ds['age'] > 50)]

# Использование метода filter (в стиле SQL)
result = ds.filter(ds['salary'] > 50000)

​

Выбор столбцов

# Стиль Pandas
subset = ds[['name', 'age']]

# Стиль SQL
subset = ds.select('name', 'age')

​

Сортировка

# Стиль Pandas
sorted_ds = ds.sort_values('salary', ascending=False)

# Стиль SQL
sorted_ds = ds.sort('salary', ascending=False)

​

Группировка и агрегация

from pathlib import Path
Path("sales.csv").write_text("""\
region,product,category,amount,quantity,price,date,order_id
East,Widget,Electronics,5200,10,120,2024-01-15,1001
West,Gadget,Electronics,800,5,160,2024-02-20,1002
East,Gizmo,Home,6500,3,100,2024-03-10,1003
North,Widget,Electronics,4500,6,150,2024-06-18,1004
West,Gadget,Electronics,2000,8,250,2024-09-14,1005
""")

from chdb import datastore as pd

ds = pd.read_csv("sales.csv")

# Группировка по одному столбцу
by_region = ds.groupby('region')['amount'].sum()

# Группировка по нескольким столбцам
by_region_product = ds.groupby(['region', 'product']).agg({
    'amount': ['sum', 'mean'],
    'quantity': 'sum'
})

# Несколько агрегаций
summary = ds.groupby('category').agg({
    'price': ['min', 'max', 'mean'],
    'quantity': 'sum'
})

​

JOIN DataStore

from pathlib import Path
Path("departments.csv").write_text("""\
dept_id,department_name
1,Engineering
2,Product
3,Design
""")

from chdb import datastore as pd

employees = pd.read_csv("employees.csv")
departments = pd.read_csv("departments.csv")

# Внутренний JOIN
result = employees.join(departments, on='dept_id', how='inner')

# Левый JOIN
result = employees.join(departments, on='dept_id', how='left')

# Использование merge (стиль pandas)
result = pd.merge(employees, departments, on='dept_id')

​

Получение результатов

DataStore использует отложенное вычисление — операции выполняются только тогда, когда вам нужны результаты.

​

Запуск запроса

# Автоматические триггеры
print(ds)           # Отображение результатов
len(ds)             # Получение количества строк
ds.columns          # Доступ к свойствам
list(ds)            # Преобразование в список

# Явное преобразование
df = ds.to_df()     # Преобразование в pandas DataFrame
df = ds.to_pandas() # Аналог to_df()

​

Просмотр сгенерированного SQL

Query

# Посмотреть, какой SQL выполнит DataStore
query = ds.filter(ds['age'] > 25).groupby('city').agg({'salary': 'mean'})
print(query.to_sql())

Response

SELECT city, AVG(salary) AS mean
FROM file('data.csv', 'CSVWithNames')
WHERE age > 25
GROUP BY city

​

Работа с разными источниками данных

​

Локальные файлы

from chdb import datastore as pd

# CSV
ds = pd.read_csv("data.csv")

# Parquet (лучшая производительность)
ds = pd.read_parquet("data.parquet")

# JSON
ds = pd.read_json("data.json")

​

Облачное хранилище

from chdb.datastore import DataStore

# S3 (анонимно)
ds = DataStore.uri("s3://bucket/data.parquet?nosign=true")

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

# HTTP/HTTPS
ds = DataStore.uri("https://example.com/data.csv")

​

Базы данных

from chdb.datastore import DataStore

# MySQL
ds = DataStore.from_mysql(
    host="localhost",
    database="mydb",
    table="users",
    user="root",
    password="pass"
)

# PostgreSQL
ds = DataStore.from_postgresql(
    host="localhost",
    database="mydb",
    table="users",
    user="postgres",
    password="pass"
)

# Использование URI
ds = DataStore.uri("mysql://user:pass@localhost:3306/mydb/users")

​

Операции со строками и DateTime

​

Операции со строками

# Все методы pandas .str работают
ds['name_upper'] = ds['name'].str.upper()
ds['name_len'] = ds['name'].str.len()
ds['has_a'] = ds['name'].str.contains('a')

​

Операции с типом DateTime

# Все методы pandas .dt работают
ds['year'] = ds['date'].dt.year
ds['month'] = ds['date'].dt.month
ds['day_of_week'] = ds['date'].dt.dayofweek

​

Расширения ClickHouse

# Парсинг URL (недоступно в pandas!)
ds['domain'] = ds['url'].url.domain()

# Извлечение JSON
ds['user_name'] = ds['json_data'].json.get_string('name')

# Операции с IP-адресами
ds['is_ipv4'] = ds['ip_addr'].ip.is_ipv4_string()

​

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

​

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

# CSV - медленнее, читает весь файл
ds = pd.read_csv("large_data.csv")

# Parquet - быстрее, столбцовый формат, читает только нужные столбцы
ds = pd.read_parquet("large_data.parquet")

​

2. Фильтруйте как можно раньше

# Хорошо — сначала фильтрация, затем агрегация
result = (ds
    .filter(ds['date'] >= '2024-01-01')
    .groupby('category')['amount'].sum()
)

# Менее оптимально — сначала агрегация
result = ds.groupby('category')['amount'].sum()

​

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

# Хорошо — выбираем конкретные столбцы
result = ds.select('name', 'age', 'city').filter(ds['age'] > 25)

# Менее оптимально — работаем со всеми столбцами
result = ds.filter(ds['age'] > 25)

​

4. Используйте SQL для выполнения сложных операций

# Для сложных запросов используйте SQL напрямую
ds = DataStore()
result = ds.sql("""
    SELECT category, 
           SUM(amount) as total,
           COUNT(*) as count,
           AVG(amount) as avg
    FROM file('sales.csv', 'CSVWithNames')
    WHERE date >= '2024-01-01'
    GROUP BY category
    HAVING total > 10000
    ORDER BY total DESC
    LIMIT 10
""")

​

Следующие шаги

• Узнайте обо всех фабричных методах для создания DataStore
• Изучите раздел Построение запросов, посвящённый операциям в стиле SQL
• Ознакомьтесь с аксессорами для работы со строками, датой и временем и не только
• Прочитайте Performance Guide, чтобы узнать, как повысить производительность