> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Como consultar dados em um bucket do S3

> Aprenda a consultar dados em um bucket do S3 com o chDB.

Grande parte dos dados do mundo está em buckets do Amazon S3.
Neste guia, aprenderemos a consultar esses dados usando o chDB.

<div id="setup">
  ## Configuração
</div>

Primeiro, vamos criar um ambiente virtual:

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

E agora vamos instalar o chDB.
Certifique-se de ter a versão 2.0.2 ou mais recente:

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

Agora vamos instalar o IPython:

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

Vamos usar o `ipython` para executar os comandos no restante do guia, e você pode iniciá-lo com:

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

Você também pode usar o código em um script Python ou no notebook de sua preferência.

<div id="listing-files-in-an-s3-bucket">
  ## Listando arquivos em um bucket do S3
</div>

Vamos começar listando todos os arquivos em [um bucket do S3 que contém avaliações da Amazon](/docs/pt-BR/get-started/sample-datasets/amazon-reviews).
Para isso, podemos usar a [função de tabela `s3`](/docs/pt-BR/reference/functions/table-functions/s3) e informar o caminho para um arquivo ou um caractere curinga para um conjunto de arquivos.

<Tip>
  Se você passar apenas o nome do bucket, será gerada uma exceção.
</Tip>

Também vamos usar o formato de entrada [`One`](/docs/pt-BR/reference/formats/One) para que o arquivo não seja processado; em vez disso, uma única linha é retornada por arquivo, e podemos acessar o arquivo pela coluna virtual `_file` e o caminho pela coluna virtual `_path`.

```python theme={null}
import chdb

chdb.query("""
SELECT
    _file,
    _path
FROM s3('s3://datasets-documentation/amazon_reviews/*.parquet', One)
SETTINGS output_format_pretty_row_numbers=0
""", 'PrettyCompact')
```

```text theme={null}
┌─_file───────────────────────────────┬─_path─────────────────────────────────────────────────────────────────────┐
│ amazon_reviews_2010.snappy.parquet  │ datasets-documentation/amazon_reviews/amazon_reviews_2010.snappy.parquet  │
│ amazon_reviews_1990s.snappy.parquet │ datasets-documentation/amazon_reviews/amazon_reviews_1990s.snappy.parquet │
│ amazon_reviews_2013.snappy.parquet  │ datasets-documentation/amazon_reviews/amazon_reviews_2013.snappy.parquet  │
│ amazon_reviews_2015.snappy.parquet  │ datasets-documentation/amazon_reviews/amazon_reviews_2015.snappy.parquet  │
│ amazon_reviews_2014.snappy.parquet  │ datasets-documentation/amazon_reviews/amazon_reviews_2014.snappy.parquet  │
│ amazon_reviews_2012.snappy.parquet  │ datasets-documentation/amazon_reviews/amazon_reviews_2012.snappy.parquet  │
│ amazon_reviews_2000s.snappy.parquet │ datasets-documentation/amazon_reviews/amazon_reviews_2000s.snappy.parquet │
│ amazon_reviews_2011.snappy.parquet  │ datasets-documentation/amazon_reviews/amazon_reviews_2011.snappy.parquet  │
└─────────────────────────────────────┴───────────────────────────────────────────────────────────────────────────┘
```

Este bucket contém apenas arquivos Parquet.

<div id="querying-files-in-an-s3-bucket">
  ## Consultando arquivos em um bucket do S3
</div>

A seguir, vamos aprender a consultar esses arquivos.
Se quisermos contar o número de linhas em cada um desses arquivos, podemos executar a consulta a seguir:

```python theme={null}
chdb.query("""
SELECT
    _file,
    count() AS count,
    formatReadableQuantity(count) AS readableCount    
FROM s3('s3://datasets-documentation/amazon_reviews/*.parquet')
GROUP BY ALL
SETTINGS output_format_pretty_row_numbers=0
""", 'PrettyCompact')
```

```text theme={null}
┌─_file───────────────────────────────┬────count─┬─readableCount───┐
│ amazon_reviews_2013.snappy.parquet  │ 28034255 │ 28.03 million   │
│ amazon_reviews_1990s.snappy.parquet │   639532 │ 639.53 thousand │
│ amazon_reviews_2011.snappy.parquet  │  6112495 │ 6.11 million    │
│ amazon_reviews_2015.snappy.parquet  │ 41905631 │ 41.91 million   │
│ amazon_reviews_2012.snappy.parquet  │ 11541011 │ 11.54 million   │
│ amazon_reviews_2000s.snappy.parquet │ 14728295 │ 14.73 million   │
│ amazon_reviews_2014.snappy.parquet  │ 44127569 │ 44.13 million   │
│ amazon_reviews_2010.snappy.parquet  │  3868472 │ 3.87 million    │
└─────────────────────────────────────┴──────────┴─────────────────┘
```

Também podemos passar a URI HTTP de um bucket do S3 e obteremos os mesmos resultados:

```python theme={null}
chdb.query("""
SELECT
    _file,
    count() AS count,
    formatReadableQuantity(count) AS readableCount    
FROM s3('https://datasets-documentation.s3.eu-west-3.amazonaws.com/amazon_reviews/*.parquet')
GROUP BY ALL
SETTINGS output_format_pretty_row_numbers=0
""", 'PrettyCompact')
```

Vamos ver o schema desses arquivos Parquet usando a cláusula `DESCRIBE`:

```python theme={null}
chdb.query("""
DESCRIBE s3('s3://datasets-documentation/amazon_reviews/*.parquet')
SETTINGS describe_compact_output=1
""", 'PrettyCompact')
```

```text theme={null}
    ┌─name──────────────┬─type─────────────┐
 1. │ review_date       │ Nullable(UInt16) │
 2. │ marketplace       │ Nullable(String) │
 3. │ customer_id       │ Nullable(UInt64) │
 4. │ review_id         │ Nullable(String) │
 5. │ product_id        │ Nullable(String) │
 6. │ product_parent    │ Nullable(UInt64) │
 7. │ product_title     │ Nullable(String) │
 8. │ product_category  │ Nullable(String) │
 9. │ star_rating       │ Nullable(UInt8)  │
10. │ helpful_votes     │ Nullable(UInt32) │
11. │ total_votes       │ Nullable(UInt32) │
12. │ vine              │ Nullable(Bool)   │
13. │ verified_purchase │ Nullable(Bool)   │
14. │ review_headline   │ Nullable(String) │
15. │ review_body       │ Nullable(String) │
    └───────────────────┴──────────────────┘
```

Vamos agora calcular as categorias de produtos com mais avaliações, bem como a média de estrelas:

```python theme={null}
chdb.query("""
SELECT product_category, count() AS reviews, round(avg(star_rating), 2) as avg
FROM s3('s3://datasets-documentation/amazon_reviews/*.parquet')
GROUP BY ALL
LIMIT 10
""", 'PrettyCompact')
```

```text theme={null}
    ┌─product_category─┬──reviews─┬──avg─┐
 1. │ Toys             │  4864056 │ 4.21 │
 2. │ Apparel          │  5906085 │ 4.11 │
 3. │ Luggage          │   348644 │ 4.22 │
 4. │ Kitchen          │  4880297 │ 4.21 │
 5. │ Books            │ 19530930 │ 4.34 │
 6. │ Outdoors         │  2302327 │ 4.24 │
 7. │ Video            │   380596 │ 4.19 │
 8. │ Grocery          │  2402365 │ 4.31 │
 9. │ Shoes            │  4366757 │ 4.24 │
10. │ Jewelry          │  1767667 │ 4.14 │
    └──────────────────┴──────────┴──────┘
```

<div id="querying-files-in-a-private-s3-bucket">
  ## Consultando arquivos em um bucket do S3 privado
</div>

Se estivermos consultando arquivos em um bucket do S3 privado, precisamos fornecer uma chave de acesso e uma chave secreta.
Podemos passar essas credenciais para a função de tabela `s3`:

```python theme={null}
chdb.query("""
SELECT product_category, count() AS reviews, round(avg(star_rating), 2) as avg
FROM s3('s3://datasets-documentation/amazon_reviews/*.parquet', 'access-key', 'secret')
GROUP BY ALL
LIMIT 10
""", 'PrettyCompact')
```

<Note>
  Esta consulta não vai funcionar porque é um bucket público!
</Note>

Uma alternativa é usar [named collections](/docs/pt-BR/concepts/features/configuration/server-config/named-collections), mas essa abordagem ainda não é compatível com o chDB.