Saltar al contenido principal
En esta guía, vamos a empezar a usar la variante de Python de chDB. Primero consultaremos un archivo JSON en S3 y, después, crearemos una tabla en chDB a partir de ese archivo JSON para realizar algunas consultas sobre los datos. También veremos cómo hacer que las consultas devuelvan datos en distintos formatos, incluidos Apache Arrow y Pandas, y, por último, aprenderemos a consultar DataFrames de Pandas.

​
Configuración

Primero, creemos un entorno virtual: 
python -m venv .venv
source .venv/bin/activate
Y ahora instalaremos chDB. Asegúrate de tener la versión 2.0.3 o posterior: 
pip install "chdb>=2.0.2"
Ahora vamos a instalar ipython: 
pip install ipython
Vamos a usar ipython para ejecutar los comandos del resto de la guía, que puedes iniciar con: 
ipython
También usaremos Pandas y Apache Arrow en esta guía, así que instalemos esas bibliotecas también: 
pip install pandas pyarrow

​
Consultar un archivo JSON en S3

Veamos ahora cómo consultar un archivo JSON almacenado en un bucket de S3. El conjunto de datos de «No me gusta» de YouTube contiene más de 4 mil millones de filas con marcas de «No me gusta» en vídeos de YouTube hasta 2021. Vamos a trabajar con uno de los archivos JSON de ese conjunto de datos. Importa chdb: 
import chdb
Podemos usar la siguiente consulta para describir la estructura de uno de los archivos 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)"
También podemos contar cuántas filas hay en ese archivo: 
chdb.query(
  """
  SELECT count()
  FROM s3(
    's3://clickhouse-public-datasets/youtube/original/files/' ||
    'youtubedislikes_20211127161229_18654868.1637897329_vid.json.zst',
    'JSONLines'
  )"""
)

336432
Este archivo contiene algo más de 300.000 registros. chdb todavía no admite pasar parámetros de consulta, pero podemos extraer la ruta y pasarla mediante una f-string. 
path = 's3://clickhouse-public-datasets/youtube/original/files/youtubedislikes_20211127161229_18654868.1637897329_vid.json.zst'

chdb.query(
  f"""
  SELECT count()
  FROM s3('{path}','JSONLines')
  """
)
Está bien hacerlo con variables definidas en tu programa, pero no lo hagas con datos proporcionados por el usuario; de lo contrario, tu consulta será vulnerable a inyecciones SQL.

​
Configuración del formato de salida

El formato de salida predeterminado es CSV, pero podemos cambiarlo mediante el parámetro output_format. chDB admite los formatos de datos de ClickHouse, así como algunos propios, incluido DataFrame, que devuelve un DataFrame de 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
O, si queremos recuperar una tabla de 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]]

​
Creación de una tabla a partir de un archivo JSON

A continuación, veamos cómo crear una tabla en chDB. Necesitamos usar una API diferente para hacerlo, así que primero importémosla: 
from chdb import session as chs
A continuación, inicializaremos una sesión. Si queremos que la sesión se conserve en disco, debemos proporcionar un nombre de directorio. Si lo dejamos en blanco, la base de datos permanecerá en memoria y se perderá en cuanto matemos el proceso de Python. 
sess = chs.Session("gettingStarted.chdb")
A continuación, crearemos una base de datos: 
sess.query("CREATE DATABASE IF NOT EXISTS youtube")
Ahora podemos crear una tabla dislikes a partir del esquema del archivo JSON, mediante la técnica CREATE...EMPTY AS. Usaremos la configuración schema_inference_make_columns_nullable para evitar que todos los tipos de columna se conviertan en 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
  """
)
A continuación, podemos usar la cláusula DESCRIBE para examinar el esquema: 
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"
A continuación, vamos a insertar datos en esa tabla: 
sess.query(f"""
  INSERT INTO youtube.dislikes
  SELECT * 
  FROM s3('{path}','JSONLines')
  SETTINGS schema_inference_make_columns_nullable=0
  """
)
También podríamos hacer ambos pasos de una sola vez usando la técnica CREATE...AS. Creemos otra tabla usando esa técnica: 
sess.query(f"""
  CREATE TABLE youtube.dislikes2
  ORDER BY fetch_date 
  AS 
  SELECT * 
  FROM s3('{path}','JSONLines')
  SETTINGS schema_inference_make_columns_nullable=0
  """
)

​
Consultar una tabla

Por último, consultemos la tabla: 
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
0                             Jeremih  139066569     812602         37842
1                     TheKillersMusic  109313116     529361         11931
2  LetsGoMartin- Canciones Infantiles  104747788     236615        141467
3                    Xiaoying Cuisine   54458335    1031525         37049
4                                Adri   47404537     279033         36583
5                  Diana and Roma IND   43829341     182334        148740
6                      ChuChuTV Tamil   39244854     244614        213772
7                            Cheez-It   35342270        108            27
8                            Anime Uz   33375618    1270673         60013
9                    RC Cars OFF Road   31952962     101503         49489
Supongamos que luego añadimos una columna adicional al DataFrame para calcular la proporción entre «me gusta» y «no me gusta». Podríamos escribir el siguiente código: 
df["likeDislikeRatio"] = df["likeCount"] / df["dislikeCount"]

​
Consultar un DataFrame de Pandas

Luego, podemos consultar ese DataFrame desde chDB: 
chdb.query(
  """
  SELECT uploader, likeDislikeRatio
  FROM Python(df)
  """,
  output_format="DataFrame"
)

                             uploader  likeDislikeRatio
0                             Jeremih         21.473548
1                     TheKillersMusic         44.368536
2  LetsGoMartin- Canciones Infantiles          1.672581
3                    Xiaoying Cuisine         27.842182
4                                Adri          7.627395
5                  Diana and Roma IND          1.225857
6                      ChuChuTV Tamil          1.144275
7                            Cheez-It          4.000000
8                            Anime Uz         21.173296
9                    RC Cars OFF Road          2.051021
También puedes obtener más información sobre cómo consultar DataFrames de Pandas en la guía para desarrolladores sobre consulta de DataFrames de Pandas.

​
Próximos pasos

Esperamos que esta guía te haya proporcionado una buena visión general de chDB. Para obtener más información sobre cómo usarlo, consulta las siguientes guías para desarrolladores:
Última modificación el 10 de junio de 2026