> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-parallel-read-in-order-multi-part.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> Documentação do formato ArrowStream

# ArrowStream

| Entrada | Saída | Alias |
| - | - | - |
| ✔ | ✔ | |

## Descrição

`ArrowStream` é o formato no "modo stream" do Apache Arrow. Ele foi projetado para processamento de streams em memória.

## Exemplo de uso

No exemplo abaixo, usamos o conjunto de dados `forex`, que está disponível no
[playground SQL do ClickHouse](https://sql.clickhouse.com). Você pode se conectar a ele
remotamente com `clickhouse-client` usando o host `sql-clickhouse.clickhouse.com`
e o usuário `demo` (que não tem senha). A tabela `forex` está no
banco de dados `forex`, por isso o definimos como banco de dados padrão:

```bash theme={null}
clickhouse-client --secure --host sql-clickhouse.clickhouse.com --user demo --database forex
```

A tabela `forex` armazena taxas de câmbio. Podemos verificar seu tamanho e
o nível de compressão em disco consultando [`system.columns`](/pt-BR/reference/system-tables/columns):

```sql title="Query" theme={null}
SELECT
    table,
    formatReadableSize(sum(data_compressed_bytes)) AS compressed_size,
    formatReadableSize(sum(data_uncompressed_bytes)) AS uncompressed_size,
    sum(data_compressed_bytes) / sum(data_uncompressed_bytes) AS compression_ratio
FROM system.columns
WHERE (database = 'forex') AND (table = 'forex')
GROUP BY table
ORDER BY table ASC
```

```response title="Response" theme={null}
   ┌─table─┬─compressed_size─┬─uncompressed_size─┬───compression_ratio─┐
1. │ forex │ 63.69 GiB       │ 280.48 GiB        │ 0.22708227109363446 │
   └───────┴─────────────────┴───────────────────┴─────────────────────┘
```

Ao contrário do formato [`Arrow`](/pt-BR/reference/formats/Arrow/Arrow) em "modo de arquivo", que
exige o resultado completo antes de poder ser lido, `ArrowStream` é entregue como uma
sequência de lotes de registros que um consumidor pode ler de forma incremental, à medida que
chegam. Isso o torna ideal para transmitir o resultado de uma consulta diretamente para uma
ferramenta de visualização ou analytics sem antes materializar todo o dataset.

Para transmitir o resultado, envie a consulta pela interface HTTP do ClickHouse com uma
requisição `POST` e leia a resposta como um stream Arrow. Desabilitamos a compactação
da saída Arrow por meio da configuração
[`output_format_arrow_compression_method`](/pt-BR/reference/settings/formats/output-format#output_format_arrow_compression_method)
para que os consumidores possam decodificar os lotes diretamente à medida que os recebem.

A saída `ArrowStream` é binária bruta, portanto, em vez de imprimi-la no
terminal, nós a redirecionamos para um consumidor. O stream é autodescritivo (carrega
seu próprio esquema), então aqui o redirecionamos diretamente para o
[`clickhouse-local`](/pt-BR/concepts/features/tools-and-utilities/clickhouse-local), que lê os
lotes recebidos com `--input-format ArrowStream` e faz consultas sobre eles como se fossem uma tabela.
A tabela `forex` é grande, então restringimos a consulta remota com um predicado `WHERE`
e um `LIMIT` para manter este exemplo pequeno:

```bash theme={null}
curl "https://sql-clickhouse.clickhouse.com:8443/?user=demo&database=forex" \
    --data-binary "
        SELECT
            concat(base, '.', quote) AS base_quote,
            datetime AS last_update,
            CAST(bid, 'Float32') AS bid,
            CAST(ask, 'Float32') AS ask,
            ask - bid AS spread
        FROM forex
        WHERE base = 'USD' AND quote = 'CHF'
        ORDER BY datetime ASC
        LIMIT 5
        FORMAT ArrowStream
        SETTINGS output_format_arrow_compression_method='none'" \
  | clickhouse-local --input-format ArrowStream \
      --query "SELECT * FROM table ORDER BY last_update ASC FORMAT PrettyCompact"
```

```response title="Response" theme={null}
   ┌─base_quote─┬─────────────last_update─┬────bid─┬────ask─┬────────────────spread─┐
1. │ USD.CHF    │ 2000-05-30 17:23:44.000 │  1.688 │ 1.6885 │ 0.0005000829696655273 │
2. │ USD.CHF    │ 2000-05-30 17:23:46.000 │ 1.6885 │  1.689 │ 0.0004999637603759766 │
3. │ USD.CHF    │ 2000-05-30 17:23:48.000 │ 1.6886 │ 1.6891 │ 0.0005000829696655273 │
4. │ USD.CHF    │ 2000-05-30 17:23:49.000 │ 1.6888 │ 1.6893 │ 0.0004999637603759766 │
5. │ USD.CHF    │ 2000-05-30 17:24:45.000 │  1.689 │ 1.6895 │ 0.0004999637603759766 │
   └────────────┴─────────────────────────┴────────┴────────┴───────────────────────┘
```

O mesmo stream pode ser consumido de forma incremental por qualquer cliente compatível com Arrow, que
o lê lote por lote, em vez de fazer a bufferização do resultado completo. Por exemplo,
usando a [biblioteca Apache Arrow para JavaScript](https://arrow.apache.org/docs/js/), um
`RecordBatchReader` retorna cada lote de registros assim que ele é transmitido pelo
servidor:

```js theme={null}
const reader = await RecordBatchReader.from(response);
await reader.open();
for await (const recordBatch of reader) {
    const batchTable = new Table(recordBatch);
    const ipcStream = tableToIPC(batchTable, 'stream');
    const bytes = new Uint8Array(ipcStream);
    table.update(bytes);
}
```

Para um passo a passo completo de streaming de dados `ArrowStream` do ClickHouse para uma
visualização em tempo real com [Perspective](https://perspective.finos.org/), consulte
a postagem do blog
[Streaming de visualizações em tempo real com ClickHouse, Apache Arrow e Perspective](https://clickhouse.com/blog/streaming-real-time-visualizations-clickhouse-apache-arrow-perpsective).

## Configurações de formato

`ArrowStream` compartilha as mesmas configurações de formato do formato [`Arrow`](/pt-BR/reference/formats/Arrow/Arrow).

| Configuração | Descrição | Padrão |
| - | - | - |
| `input_format_arrow_allow_missing_columns` | Permite colunas ausentes ao ler formatos de entrada Arrow | `1` |
| `input_format_arrow_case_insensitive_column_matching` | Ignora maiúsculas e minúsculas ao corresponder colunas Arrow com colunas CH. | `0` |
| `input_format_arrow_import_nested` | Configuração obsoleta, não faz nada. | `0` |
| `input_format_arrow_skip_columns_with_unsupported_types_in_schema_inference` | Ignora colunas com tipos não suportados durante a inferência de esquema do formato Arrow | `0` |
| `output_format_arrow_compression_method` | Método de compactação do formato de saída Arrow. Codecs compatíveis: lz4\_frame, zstd, none (sem compactação) | `lz4_frame` |
| `output_format_arrow_date_as_uint16` | Grava valores Date como números simples de 16 bits (lidos de volta como UInt16), em vez de convertê-los para um tipo Arrow DATE32 de 32 bits (lido de volta como Date32). | `0` |
| `output_format_arrow_fixed_string_as_fixed_byte_array` | Usa o tipo Arrow FIXED\_SIZE\_BINARY em vez de Binary para colunas FixedString. | `1` |
| `output_format_arrow_low_cardinality_as_dictionary` | Habilita a saída do tipo LowCardinality como o tipo Arrow Dicionário | `0` |
| `output_format_arrow_record_batch_size` | Número de linhas desejado por lote de registros ao combinar blocos pequenos. A bufferização pode aumentar o uso de memória e atrasar o primeiro lote até o término da consulta. `0` desabilita o alvo de linhas. | `0` |
| `output_format_arrow_record_batch_size_bytes` | Quantidade desejada de bytes de dados de bloco acumulados por lote de registros. A bufferização pode aumentar o uso de memória e atrasar o primeiro lote até o término da consulta. `0` desabilita o alvo de bytes. | `0` |
| `output_format_arrow_string_as_string` | Usa o tipo Arrow String em vez de Binary para colunas String | `1` |
| `output_format_arrow_unsupported_types` | O que gravar para um tipo que não tem equivalente em Arrow (por exemplo, `JSON`, `Dynamic`, `QBit`, `AggregateFunction`): `throw`, `text` (um valor `serializeText` por linha, no tipo Arrow que uma coluna `String` usaria) ou `binary` (um valor `serializeBinary` por linha, como `Binary` do Arrow). Um `AggregateFunction` também é `Binary` no modo `text`, já que sua forma textual é o aggregate state bruto. | `binary` |
| `output_format_arrow_unsupported_types_as_binary` | Substituída por `output_format_arrow_unsupported_types`: `0` significa `throw`, `1` significa `binary`. Só é consultada enquanto essa configuração permanecer em seu valor padrão. | `1` |
| `output_format_arrow_use_64_bit_indexes_for_dictionary` | Sempre usa inteiros de 64 bits para índices de dicionário no formato Arrow | `0` |
| `output_format_arrow_use_signed_indexes_for_dictionary` | Usa inteiros com sinal para índices de dicionário no formato Arrow | `1` |