> ## 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.

> Opções adicionais para o ClickHouse Connect

# Opções adicionais

O ClickHouse Connect oferece diversas opções adicionais para casos de uso avançados.

<div id="global-settings">
  ## Configurações globais
</div>

Há algumas configurações que controlam globalmente o comportamento do ClickHouse Connect. Elas são acessadas no pacote `common` de nível superior:

```python theme={null}
from clickhouse_connect import common

common.set_setting('autogenerate_session_id', False)
common.get_setting('invalid_setting_action')
'drop'
```

<Note>
  Essas configurações comuns `autogenerate_session_id`, `product_name` e `readonly` devem *sempre* ser modificadas antes de criar um cliente com o método `clickhouse_connect.get_client`. Alterar essas configurações após a criação do cliente não afeta o comportamento dos clientes existentes.
</Note>

No momento, as seguintes configurações globais estão definidas:

| Setting Name                           | Default | Options                 | Description                                                                                                                                                                                                                                                                                               |
| -------------------------------------- | ------- | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| autogenerate\_session\_id              | True    | True, False             | Gera automaticamente um novo ID de sessão UUID(1) (se não for fornecido) para cada sessão do cliente. Se nenhum ID de sessão for fornecido (seja no nível do cliente ou da consulta), o ClickHouse gerará um ID interno aleatório para cada consulta.                                                     |
| dict\_parameter\_format                | 'json'  | 'json', 'map'           | Controla se consultas parametrizadas convertem um dicionário Python em sintaxe JSON ou map do ClickHouse. `json` deve ser usado para inserts em colunas JSON; `map`, para colunas map do ClickHouse.                                                                                                      |
| invalid\_setting\_action               | 'error' | 'drop', 'send', 'error' | Ação a ser tomada quando uma configuração inválida ou readonly é fornecida (seja para a sessão do cliente ou para a consulta). Se for `drop`, a configuração será ignorada; se for `send`, a configuração será enviada ao ClickHouse; se for `error`, um ProgrammingError será gerado no lado do cliente. |
| max\_connection\_age                   | 600     |                         | Número máximo de segundos em que uma connection HTTP Keep alive será mantida aberta/reutilizada. Isso evita concentrar connections em um único nó do ClickHouse atrás de um load balancer/proxy. O padrão é 10 minutos.                                                                                   |
| product\_name                          |         |                         | Uma String passada com a consulta ao ClickHouse para rastrear o aplicativo que usa o ClickHouse Connect. Deve estar no formato \<nome do produto;\&gl/\<versão do produto>.                                                                                                                               |
| readonly                               | 0       | 0, 1                    | Configuração implícita de ClickHouse "read\_only" para versões anteriores à 19.17. Pode ser definida para corresponder ao valor "read\_only" de configurações do ClickHouse, permitindo a operação com versões muito antigas do ClickHouse.                                                               |
| send\_os\_user                         | True    | True, False             | Inclui o usuário do sistema operacional detectado nas informações do cliente enviadas ao ClickHouse (string HTTP user-agent).                                                                                                                                                                             |
| send\_integration\_tags                | True    | True, False             | Inclui as bibliotecas/versões de integração usadas (por exemplo, Pandas/SQLAlchemy/etc.) nas informações do cliente enviadas ao ClickHouse (string HTTP user-agent).                                                                                                                                      |
| use\_protocol\_version                 | True    | True, False             | Usa a versão do protocol do cliente. Isso é necessário para colunas `DateTime` com timezone, mas não funciona com a versão atual do chproxy.                                                                                                                                                              |
| max\_error\_size                       | 1024    |                         | Número máximo de caracteres retornados em mensagens de error do cliente. Use 0 nessa configuração para obter a mensagem de error completa do ClickHouse. O padrão é 1024 caracteres.                                                                                                                      |
| http\_buffer\_size                     | 10MB    |                         | Tamanho (em bytes) do buffer "em memória" usado para consultas HTTP streaming.                                                                                                                                                                                                                            |
| preserve\_pandas\_datetime\_resolution | False   | True, False             | Quando True e com pandas 2.x, preserva a resolution do dtype datetime64/timedelta64 (por exemplo, 's', 'ms', 'us', 'ns'). Se False (ou no pandas \<2.x), faz a coerção para resolução de nanossegundos ('ns') por compatibilidade.                                                                        |

<div id="compression">
  ## Compressão
</div>

O ClickHouse Connect oferece suporte a compressão lz4, zstd, brotli e gzip tanto para resultados de consultas quanto para inserção. Tenha sempre em mente que o uso de compressão normalmente envolve um equilíbrio entre largura de banda/velocidade de transferência da rede e uso de CPU (tanto no cliente quanto no servidor).

Para receber dados comprimidos, a configuração `enable_http_compression` do servidor ClickHouse deve estar definida como 1, ou o usuário deve ter permissão para alterar essa configuração por consulta.

A compressão é controlada pelo parâmetro `compress` ao chamar o método factory `clickhouse_connect.get_client`. Por padrão, `compress` é definido como `True`, o que acionará as configurações padrão de compressão. Para consultas executadas com os métodos de cliente `query`, `query_np` e `query_df`, o ClickHouse Connect adicionará o header `Accept-Encoding` com
as codificações `lz4`, `zstd`, `br` (brotli, se a biblioteca brotli estiver instalada), `gzip` e `deflate` às consultas executadas com o método de cliente `query` (e, indiretamente, `query_np` e `query_df`). (Na maioria das requisições, o servidor ClickHouse
retornará um payload comprimido com `zstd`.) Para inserção, por padrão, o ClickHouse Connect comprimirá blocos de inserção com compressão `lz4` e enviará o header HTTP `Content-Encoding: lz4`.

O parâmetro `compress` de `get_client` também pode ser definido como um método de compressão específico, entre `lz4`, `zstd`, `br` ou `gzip`. Esse método será então usado tanto para inserção quanto para resultados de consultas (se tiver suporte no servidor ClickHouse). As bibliotecas de compressão `zstd` e `lz4` necessárias agora são instaladas por padrão com o ClickHouse Connect. Se `br`/brotli for especificado, a biblioteca brotli deverá ser instalada separadamente.

Observe que os métodos de cliente `raw*` não usam a compressão especificada na configuração do cliente.

Também recomendamos não usar compressão `gzip`, pois ela é significativamente mais lenta do que as alternativas, tanto para comprimir quanto para descomprimir dados.

<div id="http-proxy-support">
  ## Suporte a proxy HTTP
</div>

O ClickHouse Connect oferece suporte básico a proxy HTTP usando a biblioteca `urllib3`. Ele reconhece as variáveis de ambiente padrão `HTTP_PROXY` e `HTTPS_PROXY`. Observe que o uso dessas variáveis de ambiente se aplicará a qualquer cliente criado com o método `clickhouse_connect.get_client`. Como alternativa, para configurar cada cliente individualmente, você pode usar os argumentos `http_proxy` ou `https_proxy` no método `get_client`. Para mais detalhes sobre a implementação do suporte a proxy HTTP, consulte a documentação do [urllib3](https://urllib3.readthedocs.io/en/stable/advanced-usage.html#http-and-https-proxies).

Para usar um proxy SOCKS, você pode passar um `urllib3` `SOCKSProxyManager` como argumento `pool_mgr` para `get_client`. Observe que isso exigirá a instalação da biblioteca PySocks, diretamente ou usando a opção `[socks]` da dependência `urllib3`.

<div id="old-json-data-type">
  ## tipo de dado JSON "antigo"
</div>

O tipo de dado experimental `Object` (ou `Object('json')`) está descontinuado e deve ser evitado em um ambiente de produção. O ClickHouse Connect continua oferecendo suporte limitado a esse tipo de dado por compatibilidade com versões anteriores. Observe que esse suporte não inclui consultas que devem retornar valores JSON de "nível superior" ou "pai" como dicionários, ou equivalente, e essas consultas resultarão em uma exceção.

<div id="new-variantdynamicjson-datatypes-experimental-feature">
  ## Tipos de dados Variant/Dynamic/JSON "novos" (recurso experimental)
</div>

A partir do lançamento 0.8.0, `clickhouse-connect` oferece suporte experimental aos novos tipos do ClickHouse — também experimentais — Variant, Dynamic e JSON.

<div id="usage-notes">
  ### Notas de uso
</div>

* Os dados JSON podem ser inseridos na forma de um dicionário Python ou de uma string JSON contendo um objeto JSON `{}`. Outras formas de dados JSON não são aceitas.
* As consultas que usam subcolunas/caminhos para esses tipos retornarão o tipo da subcoluna.
* Consulte a [documentação](/pt-BR/) principal do ClickHouse para ver outras notas de uso.

<div id="known-limitations">
  ### Limitações conhecidas
</div>

* Cada um desses tipos deve ser habilitado nas configurações do ClickHouse antes do uso.
* O "novo" tipo JSON está disponível a partir do lançamento 24.8 do ClickHouse
* Devido a alterações no formato interno, `clickhouse-connect` só é compatível com tipos Variant a partir do lançamento 24.7 do ClickHouse
* Os objetos JSON retornados incluirão apenas a quantidade de elementos definida por `max_dynamic_paths` (cujo valor padrão é 1024). Isso será corrigido em um lançamento futuro.
* Inserções em colunas `Dynamic` sempre usarão a representação em String do valor em Python. Isso será corrigido em um lançamento futuro, assim que [https://github.com/ClickHouse/ClickHouse/issues/70395](https://github.com/ClickHouse/ClickHouse/issues/70395) for corrigido.
* A implementação dos novos tipos não foi otimizada em código C, portanto o desempenho pode ser um pouco mais lento do que com tipos de dados mais simples e já consolidados.