> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-fix-nav-issues.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Primeros pasos con chDB

> chDB es un motor SQL OLAP integrado en el proceso y basado en ClickHouse

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.

<div id="setup">
  ## Configuración
</div>

Primero, creemos un entorno virtual:

```bash theme={null}
python -m venv .venv
source .venv/bin/activate
```

Y ahora instalaremos chDB.
Asegúrate de tener la versión 2.0.3 o posterior:

```bash theme={null}
pip install "chdb>=2.0.2"
```

Ahora vamos a instalar [ipython](https://ipython.org/):

```bash theme={null}
pip install ipython
```

Vamos a usar `ipython` para ejecutar los comandos del resto de la guía, que puedes iniciar con:

```bash theme={null}
ipython
```

También usaremos Pandas y Apache Arrow en esta guía, así que instalemos esas bibliotecas también:

```bash theme={null}
pip install pandas pyarrow
```

<div id="querying-a-json-file-in-s3">
  ## Consultar un archivo JSON en S3
</div>

Veamos ahora cómo consultar un archivo JSON almacenado en un bucket de S3.
El [conjunto de datos de «No me gusta» de YouTube](/es/get-started/sample-datasets/youtube-dislikes) 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:

```python theme={null}
import chdb
```

Podemos usar la siguiente consulta para describir la estructura de uno de los archivos JSON:

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

```text theme={null}
"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:

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

```text theme={null}
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.

```python theme={null}
path = 's3://clickhouse-public-datasets/youtube/original/files/youtubedislikes_20211127161229_18654868.1637897329_vid.json.zst'
```

```python theme={null}
chdb.query(
  f"""
  SELECT count()
  FROM s3('{path}','JSONLines')
  """
)
```

<Warning>
  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.
</Warning>

<div id="configuring-the-output-format">
  ## Configuración del formato de salida
</div>

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](/es/products/chdb/reference/data-formats), incluido `DataFrame`, que devuelve un DataFrame de Pandas:

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

print(type(result))
print(result)
```

```text theme={null}
<class 'pandas.core.frame.DataFrame'>
   is_ads_enabled  count()
0           False   301125
1            True    35307
```

O, si queremos recuperar una tabla de Apache Arrow:

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

print(type(result))
print(result)
```

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

<div id="creating-a-table-from-json-file">
  ## Creación de una tabla a partir de un archivo JSON
</div>

A continuación, veamos cómo crear una tabla en chDB.
Necesitamos usar una API diferente para hacerlo, así que primero importémosla:

```python theme={null}
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.

```python theme={null}
sess = chs.Session("gettingStarted.chdb")
```

A continuación, crearemos una base de datos:

```python theme={null}
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`](/es/reference/settings/formats#schema_inference_make_columns_nullable) para evitar que todos los tipos de columna se conviertan en `Nullable`.

```python theme={null}
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:

```python theme={null}
sess.query(f"""
   DESCRIBE youtube.dislikes
   SETTINGS describe_compact_output=1
   """
)
```

```text theme={null}
"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:

```python theme={null}
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:

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

<div id="querying-a-table">
  ## Consultar una tabla
</div>

Por último, consultemos la tabla:

```sql theme={null}
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
```

```text theme={null}
                             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:

```python theme={null}
df["likeDislikeRatio"] = df["likeCount"] / df["dislikeCount"]
```

<div id="querying-a-pandas-dataframe">
  ## Consultar un DataFrame de Pandas
</div>

Luego, podemos consultar ese DataFrame desde chDB:

```python theme={null}
chdb.query(
  """
  SELECT uploader, likeDislikeRatio
  FROM Python(df)
  """,
  output_format="DataFrame"
)
```

```text theme={null}
                             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](/es/products/chdb/guides/querying-pandas).

<div id="next-steps">
  ## Próximos pasos
</div>

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:

* [Consulta de DataFrames de Pandas](/es/products/chdb/guides/querying-pandas)
* [Consulta de Apache Arrow](/es/products/chdb/guides/querying-apache-arrow)
* [Uso de chDB en JupySQL](/es/products/chdb/guides/jupysql)
* [Uso de chDB con una base de datos existente de clickhouse-local](/es/products/chdb/guides/clickhouse-local)