Начало работы с chDB

В этом руководстве мы начнем работу с вариантом chDB для Python. Сначала мы выполним запрос к JSON‑файлу в S3, затем создадим в chDB таблицу на основе этого JSON‑файла и выполним несколько запросов к данным. Мы также рассмотрим, как получать результаты запросов в разных форматах, включая Apache Arrow и Pandas, и, наконец, узнаем, как выполнять запросы к DataFrame в Pandas.

Настройка

Сначала создадим виртуальное окружение:

python -m venv .venv
source .venv/bin/activate

А теперь установим chDB. Убедитесь, что у вас установлена версия 2.0.3 или выше:

pip install "chdb>=2.0.2"

А теперь установим ipython:

pip install ipython

Для выполнения команд в оставшейся части руководства мы будем использовать ipython, который можно запустить командой:

ipython

В этом руководстве мы также будем использовать Pandas и Apache Arrow, поэтому давайте установим и эти библиотеки:

pip install pandas pyarrow

Запросы к JSON‑файлу в S3

Теперь посмотрим, как выполнять запросы к JSON‑файлу, который хранится в S3 бакете. датасет YouTube dislikes содержит более 4 миллиардов строк с данными о дизлайках к видео на YouTube по состоянию на 2021 год. Мы будем работать с одним из JSON‑файлов из этого датасета. Импортируйте chdb:

import chdb

Можно выполнить следующий запрос, чтобы описать структуру одного из JSON‑файлов:

chdb.query(
  """
  DESCRIBE s3(
    's3://clickhouse-public-datasets/youtube/original/files/' ||
    'youtubedislikes_20211127161229_18654868.1637897329_vid.json.zst',
    'JSONLines'
  )
  SETTINGS describe_compact_output=1
  """
)

"id","Nullable(String)"
"fetch_date","Nullable(String)"
"upload_date","Nullable(String)"
"title","Nullable(String)"
"uploader_id","Nullable(String)"
"uploader","Nullable(String)"
"uploader_sub_count","Nullable(Int64)"
"is_age_limit","Nullable(Bool)"
"view_count","Nullable(Int64)"
"like_count","Nullable(Int64)"
"dislike_count","Nullable(Int64)"
"is_crawlable","Nullable(Bool)"
"is_live_content","Nullable(Bool)"
"has_subtitles","Nullable(Bool)"
"is_ads_enabled","Nullable(Bool)"
"is_comments_enabled","Nullable(Bool)"
"description","Nullable(String)"
"rich_metadata","Array(Tuple(
    call Nullable(String),
    content Nullable(String),
    subtitle Nullable(String),
    title Nullable(String),
    url Nullable(String)))"
"super_titles","Array(Tuple(
    text Nullable(String),
    url Nullable(String)))"
"uploader_badges","Nullable(String)"
"video_badges","Nullable(String)"

Мы также можем подсчитать количество строк в этом файле:

chdb.query(
  """
  SELECT count()
  FROM s3(
    's3://clickhouse-public-datasets/youtube/original/files/' ||
    'youtubedislikes_20211127161229_18654868.1637897329_vid.json.zst',
    'JSONLines'
  )"""
)

Этот файл содержит чуть более 300 000 записей. chdb пока не поддерживает передачу параметров запроса, но мы можем извлечь путь и передать его с помощью f-строки.

path = 's3://clickhouse-public-datasets/youtube/original/files/youtubedislikes_20211127161229_18654868.1637897329_vid.json.zst'

chdb.query(
  f"""
  SELECT count()
  FROM s3('{path}','JSONLines')
  """
)

Это допустимо делать с переменными, определёнными в вашей программе, но не делайте этого с пользовательским вводом, иначе ваш запрос будет уязвим для SQL-инъекции.

Настройка формата вывода

Формат вывода по умолчанию — CSV, но его можно изменить с помощью параметра output_format. chDB поддерживает форматы данных ClickHouse, а также некоторые собственные, включая DataFrame, который возвращает DataFrame в Pandas:

result = chdb.query(
  f"""
  SELECT is_ads_enabled, count()
  FROM s3('{path}','JSONLines')
  GROUP BY ALL
  """,
  output_format="DataFrame"
)

print(type(result))
print(result)

<class 'pandas.core.frame.DataFrame'>
   is_ads_enabled  count()
0           False   301125
1            True    35307

Или, если мы хотим получить таблицу Apache Arrow:

result = chdb.query(
  f"""
  SELECT is_live_content, count()
  FROM s3('{path}','JSONLines')
  GROUP BY ALL
  """,
  output_format="ArrowTable"
)

print(type(result))
print(result)

<class 'pyarrow.lib.Table'>
pyarrow.Table
is_live_content: bool
count(): uint64 not null
----
is_live_content: [[false,true]]
count(): [[315746,20686]]

Создание таблицы из JSON‑файла

Теперь рассмотрим, как создать таблицу в chDB. Для этого нам понадобится другой API, поэтому сначала импортируем его:

from chdb import session as chs

Далее инициализируем сеанс. Если мы хотим сохранить сеанс на диске, нужно указать имя каталога. Если оставить его пустым, сеанс будет временным: chDB хранит данные во временном каталоге на диске и удаляет их при закрытии сеанса, поэтому данные не сохраняются.

sess = chs.Session("gettingStarted.chdb")

chDB запускает один встроенный движок на процесс, поэтому для каталога базы данных (его пути) действуют несколько правил:

Один процесс на путь: каталог данных chDB может быть открыт одновременно только одним процессом операционной системы. Второй процесс, открывающий тот же путь, завершится с ошибкой, пока первый не закроется.
Один путь на процесс: пока открыт сеанс или соединение, попытка открыть другой для другого пути завершится с ошибкой; сначала закройте открытые, чтобы избежать ошибки. Несколько сеансов или соединений на одном и том же пути могут сосуществовать.
Параллелизм: сеансы или соединения на одном пути могут выполнять запросы параллельно.
Сеансы без пути являются общими: без пути сеансы используют общую для всего процесса базу данных :memory: (поэтому пустые сеансы видят таблицы друг друга), а её временный каталог удаляется только после закрытия последнего сеанса.

Затем создадим базу данных:

sess.query("CREATE DATABASE IF NOT EXISTS youtube")

Теперь мы можем создать таблицу dislikes на основе схемы из JSON‑файла, используя приём CREATE...EMPTY AS. Мы будем использовать настройку schema_inference_make_columns_nullable, чтобы не все типы столбцов становились Nullable.

sess.query(f"""
  CREATE TABLE youtube.dislikes
  ORDER BY fetch_date 
  EMPTY AS 
  SELECT * 
  FROM s3('{path}','JSONLines')
  SETTINGS schema_inference_make_columns_nullable=0
  """
)

Затем можно использовать оператор DESCRIBE, чтобы просмотреть схему:

sess.query(f"""
   DESCRIBE youtube.dislikes
   SETTINGS describe_compact_output=1
   """
)

"id","String"
"fetch_date","String"
"upload_date","String"
"title","String"
"uploader_id","String"
"uploader","String"
"uploader_sub_count","Int64"
"is_age_limit","Bool"
"view_count","Int64"
"like_count","Int64"
"dislike_count","Int64"
"is_crawlable","Bool"
"is_live_content","Bool"
"has_subtitles","Bool"
"is_ads_enabled","Bool"
"is_comments_enabled","Bool"
"description","String"
"rich_metadata","Array(Tuple(
    call String,
    content String,
    subtitle String,
    title String,
    url String))"
"super_titles","Array(Tuple(
    text String,
    url String))"
"uploader_badges","String"
"video_badges","String"

Теперь заполним эту таблицу:

sess.query(f"""
  INSERT INTO youtube.dislikes
  SELECT * 
  FROM s3('{path}','JSONLines')
  SETTINGS schema_inference_make_columns_nullable=0
  """
)

Мы также можем выполнить оба шага сразу, используя конструкцию CREATE...AS. Давайте создадим другую таблицу с помощью этой конструкции:

sess.query(f"""
  CREATE TABLE youtube.dislikes2
  ORDER BY fetch_date 
  AS 
  SELECT * 
  FROM s3('{path}','JSONLines')
  SETTINGS schema_inference_make_columns_nullable=0
  """
)

Выполнение запросов к таблице

Напоследок выполним запрос к таблице:

df = sess.query("""
  SELECT uploader, sum(view_count) AS viewCount, sum(like_count) AS likeCount, sum(dislike_count) AS dislikeCount
  FROM youtube.dislikes
  GROUP BY ALL
  ORDER BY viewCount DESC
  LIMIT 10
  """,
  "DataFrame"
)
df

                             uploader  viewCount  likeCount  dislikeCount
                           Jeremih  139066569     812602         37842
                   TheKillersMusic  109313116     529361         11931
LetsGoMartin- Canciones Infantiles  104747788     236615        141467
                  Xiaoying Cuisine   54458335    1031525         37049
                              Adri   47404537     279033         36583
                Diana and Roma IND   43829341     182334        148740
                    ChuChuTV Tamil   39244854     244614        213772
                          Cheez-It   35342270        108            27
                          Anime Uz   33375618    1270673         60013
                  RC Cars OFF Road   31952962     101503         49489

Допустим, затем мы добавим в DataFrame дополнительный столбец, чтобы вычислить соотношение лайков и дизлайков. Можно написать следующий код:

df["likeDislikeRatio"] = df["likeCount"] / df["dislikeCount"]

Выполнение запросов к DataFrame в Pandas

Затем мы можем выполнять запросы к этому DataFrame через chDB:

chdb.query(
  """
  SELECT uploader, likeDislikeRatio
  FROM Python(df)
  """,
  output_format="DataFrame"
)

                             uploader  likeDislikeRatio
                           Jeremih         21.473548
                   TheKillersMusic         44.368536
LetsGoMartin- Canciones Infantiles          1.672581
                  Xiaoying Cuisine         27.842182
                              Adri          7.627395
                Diana and Roma IND          1.225857
                    ChuChuTV Tamil          1.144275
                          Cheez-It          4.000000
                          Anime Uz         21.173296
                  RC Cars OFF Road          2.051021

Вы также можете подробнее прочитать о выполнении запросов к DataFrame в Pandas в руководстве для разработчиков «Выполнение запросов к DataFrame в Pandas».

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

Надеемся, это руководство помогло вам получить общее представление о chDB. Чтобы узнать больше о его использовании, см. следующие руководства для разработчиков: