}`. Passe os valores como um dicionário Python.
Use `None` do Python para valores anuláveis. Valores `None` aninhados são compatíveis dentro de parâmetros `Array` e `Tuple` e dentro de literais `Map` quando `dict_parameter_format` está definido como `"map"`.
* Vinculação no servidor com dicionário Python, valor DateTime e valor String
```python theme={null}
import datetime
my_date = datetime.datetime(2022, 10, 1, 15, 20, 5)
parameters = {
"table": "my_table",
"v1": my_date,
"v2": "a string with a single quote'",
}
client.query(
"SELECT * FROM {table:Identifier} "
"WHERE date >= {v1:DateTime} AND string ILIKE {v2:String}",
parameters=parameters,
)
```
Isso equivale a:
```sql theme={null}
SELECT *
FROM my_table
WHERE date >= '2022-10-01 15:20:05'
AND string ILIKE 'a string with a single quote\''
```
A vinculação no servidor tem suporte para consultas `SELECT`. Ela não funciona com `ALTER`, `DELETE`, `INSERT` nem com outros tipos de instrução SQL.
#### Vinculação no lado do cliente
O ClickHouse Connect também oferece suporte à vinculação de parâmetros no lado do cliente, o que pode proporcionar mais flexibilidade na geração de consultas SQL com template. Para a vinculação no lado do cliente, o argumento `parameters` deve ser um dicionário ou uma sequência. A vinculação no lado do cliente usa a formatação de strings no [estilo "printf" do Python](https://docs.python.org/3/library/stdtypes.html#old-string-formatting) para a substituição de parâmetros.
Observe que, diferentemente da vinculação no servidor, a vinculação no lado do cliente não funciona para identificadores de banco de dados, como nomes de database, table ou coluna, já que a formatação no estilo Python não consegue distinguir entre os diferentes types de strings, e elas precisam ser formatadas de maneira diferente (backticks ou aspas duplas para identificadores de banco de dados, aspas simples para valores de dados).
* Exemplo com Dicionário Python, valor DateTime e escape de string
```python theme={null}
import datetime
my_date = datetime.datetime(2022, 10, 1, 15, 20, 5)
parameters = {"v1": my_date, "v2": "a string with a single quote'"}
client.query(
"SELECT * FROM my_table "
"WHERE date >= %(v1)s AND string ILIKE %(v2)s",
parameters=parameters,
)
```
Isso gera a seguinte consulta no servidor:
```sql theme={null}
SELECT *
FROM my_table
WHERE date >= '2022-10-01 15:20:05'
AND string ILIKE 'a string with a single quote\''
```
* Exemplo com Sequence do Python (Tuple), Float64 e IPv4Address
```python theme={null}
import ipaddress
parameters = (35200.44, ipaddress.IPv4Address(0x443d04fe))
client.query(
"SELECT * FROM some_table WHERE metric >= %s AND ip_address = %s",
parameters=parameters,
)
```
Isso gera a seguinte consulta no servidor:
```sql theme={null}
SELECT *
FROM some_table
WHERE metric >= 35200.44
AND ip_address = '68.61.4.254'
```
A vinculação de `datetime` trata valores sem timezone como horário local. O cliente formata um `datetime` sem timezone tal como está. O ClickHouse o interpreta usando o timezone declarado em um placeholder no servidor, como `{dt:DateTime('Europe/Berlin')}`, depois `session_timezone`, quando definido, e por fim o timezone do servidor. Um `datetime` com timezone é convertido para o timezone declarado no placeholder, quando presente; caso contrário, para o timezone do servidor informado no momento da conexão. Se a configuração `session_timezone` for diferente desse timezone do servidor, declare um timezone no placeholder para preservar o instante desejado para valores com timezone.
Para compatibilidade temporária com a conversão local do host mais antiga, defina `common.set_setting("naive_datetime_binding", "legacy")` antes de vincular parâmetros. Para preservar um instante, anexe o `tzinfo` pretendido ao valor `datetime` antes de passá-lo como parâmetro. Inserts por meio de `client.insert` interpretam valores `datetime` sem timezone no timezone local do processo por padrão. Defina a configuração global `naive_datetime_insert` como `"server"` para interpretá-los como horário local no timezone da coluna ou, quando a coluna não tiver um, no timezone do servidor. Consulte [objetos datetime sem timezone](/pt-BR/integrations/language-clients/python/advanced-inserting#timezone-naive-datetime-objects).
Para um placeholder `{value:DateTime64(precision)}` no servidor, o tipo declarado preserva automaticamente a precisão de frações de segundo, inclusive dentro de indicações `Array` e `Tuple`.
A vinculação `%s` no lado do cliente não tem tipo declarado. Envolva um `datetime` em `DT64Param` quando ele precisar ser formatado com precisão de frações de segundo:
```python theme={null}
from datetime import datetime
from clickhouse_connect.driver.binding import DT64Param
query = "SELECT toDateTime64(%s, 6)"
parameters = [DT64Param(datetime.now())]
client.query(query, parameters=parameters)
```
Para compatibilidade retroativa, um nome de parâmetro de dicionário terminado em `_64` também solicita a formatação DateTime64 quando esse nome exato com sufixo não está presente na consulta.
Um parâmetro `datetime.time` ou `datetime.timedelta` é formatado como um literal `[-]HH:MM:SS[.ffffff]` para colunas `Time` e `Time64` do ClickHouse, em ambos os estilos de vinculação e dentro de valores `Array` e `Tuple`. O cliente adiciona as aspas, portanto, não coloque aspas no placeholder na consulta. Um `timedelta` pode ser negativo e pode exceder 24 horas. Um `Timedelta` do pandas mantém seus nanossegundos e formata uma fração de nove dígitos para `Time64(9)`. As informações de timezone em um `time` com timezone são ignoradas porque o `Time` do ClickHouse não tem timezone.
### Argumento `settings`
Todos os principais métodos "insert" e "select" do cliente ClickHouse Connect aceitam um argumento nomeado opcional `settings` para passar [configurações de usuário](/pt-BR/reference/settings/session-settings) do servidor ClickHouse para a instrução SQL correspondente. O argumento `settings` deve ser um dicionário. Cada item deve conter o nome de uma configuração do ClickHouse e o respectivo valor. Observe que os valores serão convertidos em strings quando enviados ao servidor como parâmetros de consulta.
Assim como acontece com as configurações no nível do cliente, o ClickHouse Connect descartará todas as configurações que o servidor marcar como *readonly*=*1*, com a respectiva mensagem de log. As configurações que se aplicam apenas a consultas feitas pela interface HTTP do ClickHouse são sempre válidas. Essas configurações são descritas na [API](#settings-argument) `get_client`.
Exemplo de uso das configurações do ClickHouse:
```python theme={null}
settings = {
"merge_tree_min_rows_for_concurrent_read": 65535,
"session_id": "session_1234",
"use_skip_indexes": False,
}
client.query(
"SELECT event_type, sum(timeout) "
"FROM event_errors WHERE event_time > '2022-08-01'",
settings=settings,
)
```
## Método `command` do Client
Use `Client.command` para instruções que não retornam um conjunto de dados tabular ou para consultas que retornam um valor primitivo ou uma linha. Dependendo da resposta, ele retorna uma string, um inteiro, uma sequência de strings ou `QuerySummary`. Uma leitura que produz um conjunto de resultados vazio retorna uma string vazia.
| Parâmetro | Tipo | Padrão | Descrição |
| ------------------- | ---------------- | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| cmd | str | *Obrigatório* | Uma instrução SQL do ClickHouse que retorna um único valor ou uma única linha de valores. |
| parameters | dict or sequence | *None* | Veja a [descrição dos parâmetros](#parameters-argument). |
| data | str or bytes | *None* | Dados opcionais a serem incluídos no comando como corpo da requisição POST. |
| settings | dict | *None* | Veja a [descrição das configurações](#settings-argument-1). |
| use\_database | bool | True | Usa o banco de dados do Client (especificado ao criar o Client). False significa que o comando usará o banco de dados padrão do servidor ClickHouse para o usuário conectado. |
| external\_data | ExternalData | *None* | Um objeto `ExternalData` que contém dados de arquivo ou dados binários para uso com a consulta. Veja [Consultas avançadas (dados externos)](/pt-BR/integrations/language-clients/python/advanced-querying#external-data) |
| transport\_settings | dict | *None* | Dicionário opcional de cabeçalhos HTTP a serem incluídos nesta solicitação. Cada par chave-valor é adicionado como um cabeçalho HTTP (por exemplo, `{'X-Custom-Header': 'value'}`). Útil para autenticação de proxy, rastreamento de solicitações ou para encaminhar cabeçalhos exigidos pela infraestrutura intermediária. |
### Exemplos do comando
#### Instruções DDL
```python theme={null}
import clickhouse_connect
client = clickhouse_connect.get_client()
# Create a table. A successful DDL returns QuerySummary.
summary = client.command(
"CREATE TABLE test_command "
"(col_1 String, col_2 DateTime) "
"ENGINE MergeTree ORDER BY tuple()"
)
print(summary.query_id())
# Show table definition
result = client.command("SHOW CREATE TABLE test_command")
print(result)
# Output:
# CREATE TABLE default.test_command
# (
# `col_1` String,
# `col_2` DateTime
# )
# ENGINE = MergeTree
# ORDER BY tuple()
# Drop table
client.command("DROP TABLE test_command")
```
#### Consultas simples que retornam valores individuais
```python theme={null}
import clickhouse_connect
client = clickhouse_connect.get_client()
# Single value result
count = client.command("SELECT count() FROM system.tables")
print(count)
# Server version
version = client.command("SELECT version()")
print(version)
```
#### Comandos com parâmetros
```python theme={null}
import clickhouse_connect
client = clickhouse_connect.get_client()
# Usando parâmetros no cliente
table_name = "system"
result = client.command(
"SELECT count() FROM system.tables WHERE database = %(db)s",
parameters={"db": table_name}
)
# Usando parâmetros no servidor
result = client.command(
"SELECT count() FROM system.tables WHERE database = {db:String}",
parameters={"db": "system"}
)
```
#### Comandos com configurações
```python theme={null}
import clickhouse_connect
client = clickhouse_connect.get_client()
# Executa comando com configurações específicas
result = client.command(
"OPTIMIZE TABLE large_table FINAL",
settings={"optimize_throw_if_noop": 1}
)
```
## Método `query` do Client
`Client.query` recupera um conjunto de dados tabular no formato Native do ClickHouse e retorna um `QueryResult`. O resultado completo é materializado quando uma propriedade do resultado é acessada. Use um método de streaming para resultados que não devem ser mantidos na memória.
| Parâmetro | Tipo | Padrão | Descrição |
| -------------------- | ---------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `query` | str | Obrigatório | consulta do ClickHouse que retorna um resultado tabular, geralmente `SELECT` ou `DESCRIBE`. Pode ser omitida quando fornecida por `context`. |
| `parameters` | dict or sequence | `None` | Veja [Argumento Parameters](#parameters-argument). |
| `settings` | dict | `None` | Veja [Argumento `settings`](#settings-argument-1). |
| `query_formats` | dict | `None` | Formato de leitura por tipo do ClickHouse. Veja [Formatos de leitura](/pt-BR/integrations/language-clients/python/advanced-querying#read-formats). |
| `column_formats` | dict | `None` | Formato de leitura por coluna do resultado, incluindo mapeamentos de formato para o tipo Nested. |
| `encoding` | str | `None` | Codificação de colunas String. O padrão é UTF-8. |
| `use_none` | bool | `True` | Retorna `None` para SQL NULL. Quando false, retorna o valor nulo padrão do tipo. Os métodos de NumPy/Pandas escolhem padrões voltados para desempenho. |
| `column_oriented` | bool | `False` | Orienta o resultado em colunas em vez de linhas. |
| `use_numpy` | bool | `False` | Lê colunas de resultado compatíveis em arrays do NumPy dentro do `QueryResult`. Prefira `query_np` quando o resultado desejado for uma única matriz NumPy. |
| `max_str_len` | int | `0` | Com `use_numpy`, usa um dtype Unicode de largura fixa para colunas String até esse comprimento. Zero usa arrays de objetos. |
| `context` | `QueryContext` | `None` | Contexto de consulta reutilizável. Argumentos explícitos do método substituem os valores do contexto. |
| `query_tz` | str or `tzinfo` | `None` | Timezone aplicado a todas as colunas de resultado `DateTime` e `DateTime64`. |
| `column_tzs` | dict | `None` | Mapeamento de timezone por coluna. |
| `external_data` | `ExternalData` | `None` | Arquivo externo ou dados binários. Veja [Dados externos](/pt-BR/integrations/language-clients/python/advanced-querying#external-data). |
| `transport_settings` | dict | `None` | HTTP headers adicionados a esta solicitação. |
| `tz_mode` | str | Padrão do Client | Substituição por consulta para o tratamento de timezone `"naive_utc"`, `"aware"` ou `"schema"`. |
### Exemplos de consulta
#### Consulta básica
```python theme={null}
import clickhouse_connect
client = clickhouse_connect.get_client()
# Simple SELECT query
result = client.query(
"SELECT number, toString(number) AS label FROM numbers(3)"
)
# Access results as rows
for row in result.result_rows:
print(row)
# Output:
# (0, '0')
# (1, '1')
# (2, '2')
# Access column names and types
print(result.column_names)
# Output: ('number', 'label')
print([col_type.name for col_type in result.column_types])
# Output: ['UInt64', 'String']
```
#### Acessando os resultados da consulta
```python theme={null}
import clickhouse_connect
client = clickhouse_connect.get_client()
result = client.query("SELECT number, toString(number) AS str FROM system.numbers LIMIT 3")
# Row-oriented access (default)
print(result.result_rows)
# Output: [(0, '0'), (1, '1'), (2, '2')]
# Column-oriented access
print(result.result_columns)
# Output: [[0, 1, 2], ['0', '1', '2']]
# Named results (list of dictionaries)
for row_dict in result.named_results():
print(row_dict)
# Output:
# {'number': 0, 'str': '0'}
# {'number': 1, 'str': '1'}
# {'number': 2, 'str': '2'}
# First row as dictionary
print(result.first_item)
# Output: {'number': 0, 'str': '0'}
# First row as tuple
print(result.first_row)
# Output: (0, '0')
```
#### Consulta com parâmetros no cliente
```python theme={null}
import clickhouse_connect
client = clickhouse_connect.get_client()
# Usando parâmetros de dicionário (no estilo printf)
query = "SELECT * FROM system.tables WHERE database = %(db)s AND name LIKE %(pattern)s"
parameters = {"db": "system", "pattern": "%query%"}
result = client.query(query, parameters=parameters)
# Usando parâmetros de tupla
query = "SELECT * FROM system.tables WHERE database = %s LIMIT %s"
parameters = ("system", 5)
result = client.query(query, parameters=parameters)
```
#### Consulta com parâmetros do lado do servidor
```python theme={null}
import clickhouse_connect
client = clickhouse_connect.get_client()
# Binding server-side (mais seguro, melhor desempenho para consultas SELECT)
query = "SELECT * FROM system.tables WHERE database = {db:String} AND name = {tbl:String}"
parameters = {"db": "system", "tbl": "query_log"}
result = client.query(query, parameters=parameters)
```
#### Consulta com configurações
```python theme={null}
import clickhouse_connect
client = clickhouse_connect.get_client()
# Passar as configurações do ClickHouse junto com a consulta
result = client.query(
"SELECT sum(number) FROM numbers(1000000)",
settings={
"max_block_size": 100000,
"max_execution_time": 30
}
)
```
### O objeto `QueryResult`
O método base `query` retorna um objeto `QueryResult` com as seguintes propriedades públicas:
* `result_rows` -- Matriz de resultados orientada por linhas.
* `result_columns` -- Matriz de resultados orientada por colunas.
* `result_set` -- `result_rows` ou `result_columns`, de acordo com a orientação da consulta.
* `column_names` -- Tupla com os nomes das colunas do resultado.
* `column_types` -- Tupla de objetos `ClickHouseType`.
* `row_count` -- Número de linhas de resultado materializadas.
* `query_id` -- ID da consulta informado ou gerado para a requisição. Uma string vazia significa que nenhum estava disponível.
* `summary` -- Dicionário decodificado do cabeçalho de resposta `X-ClickHouse-Summary`.
* `first_item` -- Primeira linha como um dicionário, ou `None` para um resultado vazio.
* `first_row` -- Primeira linha como uma sequência, ou `None` para um resultado vazio.
* `column_block_stream`, `row_block_stream` e `rows_stream` -- Contextos internos de streaming. Use os métodos de streaming correspondentes do cliente.
Consulte [Consultas em streaming](/pt-BR/integrations/language-clients/python/advanced-querying#streaming-queries) para ver as APIs `StreamContext` compatíveis.
## Consumindo resultados de consultas com NumPy, Pandas ou Arrow
O ClickHouse Connect fornece métodos de consulta especializados para os formatos de dados NumPy, Pandas e Arrow. Para informações detalhadas sobre como usar esses métodos, incluindo exemplos, recursos de streaming e tratamento avançado de tipos, consulte [Consultas avançadas (consultas com NumPy, Pandas e Arrow)](/pt-BR/integrations/language-clients/python/advanced-querying#numpy-pandas-and-arrow-queries).
## Métodos de consulta em streaming do cliente
Para transmitir grandes conjuntos de resultados, o ClickHouse Connect oferece vários métodos de streaming. Consulte [Consultas avançadas (consultas em streaming)](/pt-BR/integrations/language-clients/python/advanced-querying#streaming-queries) para mais detalhes e exemplos.
## Método `insert` do Client
Para o caso de uso comum de inserir vários registros no ClickHouse, existe o método `Client.insert`. Ele aceita os seguintes parâmetros:
| Parâmetro | Tipo | Padrão | Descrição |
| -------------------- | --------------------------- | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `table` | str | Obrigatório | Tabela de destino. É permitido usar um nome qualificado com banco de dados. Pode ser omitido quando fornecido por `context`. |
| `data` | Sequence of Sequences | Obrigatório | Matriz de dados orientada a linhas ou orientada a colunas. Pode ser fornecida depois por meio de um `InsertContext`. |
| `column_names` | str or Sequence\[str] | `"*"` | Colunas em ordem. `"*"` executa uma consulta de metadados para descobrir todas as colunas em que é possível inserir dados. |
| `database` | str or None | Banco de dados do Client | Banco de dados de destino quando `table` não estiver qualificada. |
| `column_types` | Sequence\[`ClickHouseType`] | `None` | Tipos de coluna explícitos. Evita a consulta de metadados quando fornecidos. |
| `column_type_names` | Sequence\[str] | `None` | Nomes de tipos do ClickHouse explícitos. Alternativa a `column_types`. |
| `column_oriented` | bool | `False` | Interpreta `data` como colunas em vez de linhas. |
| `settings` | dict | `None` | Consulte [Argumento `settings`](#settings-argument-1). |
| `context` | `InsertContext` | `None` | Contexto de inserção reutilizável. Consulte [InsertContexts](/pt-BR/integrations/language-clients/python/advanced-inserting#insertcontexts). |
| `transport_settings` | dict | `None` | Cabeçalhos HTTP adicionados a esta requisição. |
Esse método retorna `QuerySummary`. Seu dicionário `summary` contém valores informados pelo servidor. `written_rows` é uma propriedade de conveniência, enquanto `written_bytes()` e `query_id()` retornam os valores correspondentes. Uma falha na inserção gera uma exceção.
Para métodos especializados de inserção que funcionam com Pandas DataFrames, tabelas PyArrow e DataFrames com Arrow como backend, consulte [Advanced Inserting (Specialized Insert Methods)](/pt-BR/integrations/language-clients/python/advanced-inserting#specialized-insert-methods).
Um array NumPy é uma Sequence of Sequences válida e pode ser usado como argumento `data` no método `insert` principal, portanto não é necessário um método especializado.
### Exemplos
Os exemplos abaixo partem do pressuposto de que já existe uma tabela `users` com o esquema `(id UInt32, name String, age UInt8)`.
#### Inserção básica orientada por linhas
```python theme={null}
import clickhouse_connect
client = clickhouse_connect.get_client()
# Row-oriented data: each inner list is a row
data = [
[13, "user_1", 25],
[79, "user_2", 30],
]
client.insert("users", data, column_names=["id", "name", "age"])
```
#### Inserção orientada a colunas
```python theme={null}
import clickhouse_connect
client = clickhouse_connect.get_client()
# Column-oriented data: each inner list is a column
data = [
[13, 79], # id column
["user_1", "user_2"], # name column
[25, 30], # age column
]
client.insert("users", data, column_names=["id", "name", "age"], column_oriented=True)
```
#### Inserir com tipos de coluna explícitos
```python theme={null}
import clickhouse_connect
client = clickhouse_connect.get_client()
# Useful when you want to avoid a DESCRIBE query to the server
data = [
[13, "user_1", 25],
[79, "user_2", 30],
]
client.insert(
"users",
data,
column_names=["id", "name", "age"],
column_type_names=["UInt32", "String", "UInt8"],
)
```
#### Inserir em um banco de dados específico
```python theme={null}
import clickhouse_connect
client = clickhouse_connect.get_client()
data = [
[13, "user_1", 25],
[79, "user_2", 30],
]
# Insert into a table in a specific database
client.insert(
"users",
data,
column_names=["id", "name", "age"],
database="production",
)
```
## Inserções a partir de arquivos
Para inserir dados diretamente de arquivos em tabelas do ClickHouse, consulte [Inserção avançada (Inserções a partir de arquivos)](/pt-BR/integrations/language-clients/python/advanced-inserting#file-inserts).
## API bruta
Para casos de uso avançados que exigem acesso direto às interfaces HTTP do ClickHouse, sem transformações de tipo, consulte [Uso avançado (API bruta)](/pt-BR/integrations/language-clients/python/advanced-usage#raw-api).
## Python DB-API 2.0
O módulo `clickhouse_connect.dbapi` implementa a interface de conexão e cursor do PEP 249. Ele declara nível de API 2.0, `threadsafety=2` e `paramstyle="pyformat"`. O módulo também fornece os construtores de tipo do PEP 249 `Date`, `Time`, `Timestamp` e `Binary`, e as funções `DateFromTicks`, `TimeFromTicks` e `TimestampFromTicks`.
```python theme={null}
from clickhouse_connect import dbapi
connection = dbapi.connect(
host="localhost",
username="default",
password="password",
database="default",
)
cursor = connection.cursor()
try:
cursor.execute(
"SELECT name FROM system.tables "
"WHERE database = %(database)s ORDER BY name LIMIT 5",
{"database": "system"},
)
print(cursor.description)
print(cursor.fetchall())
finally:
cursor.close()
connection.close()
```
`Cursor.execute` e `Cursor.executemany` aceitam os argumentos nomeados adicionais `settings` e `query_formats`. `settings` passa configurações do ClickHouse. `query_formats` aplica formatos de leitura por tipo do ClickHouse quando uma instrução retorna linhas, usando o mesmo mapeamento de `Client.query`. `executemany` usa o caminho nativo de inserção em massa do driver para instruções `INSERT ... VALUES` compatíveis com uma sequência materializada de linhas. `fetchone`, `fetchmany` e `fetchall` consomem o resultado materializado atual.
`Cursor.description` deriva `null_ok` do tipo de cada coluna de resultado. Tipos não anuláveis retornam `False`, e tipos anuláveis retornam `True`, incluindo wrappers `Nullable`, `Variant` e `Dynamic`. `None` significa que a anulabilidade é desconhecida. Quando uma consulta que começa com `SELECT` ou `WITH`, ignorando comentários iniciais, não retorna linhas nem metadados de coluna, o cursor executa uma consulta de metadados `LIMIT 0` para preencher `description`. Se essa consulta de metadados falhar, `description` permanece vazio.
O ClickHouse não oferece transações tradicionais por meio desta interface HTTP. `Connection.commit()` e `Connection.rollback()` são operações sem efeito. As [regras de concorrência de ID de sessão](/pt-BR/integrations/language-clients/python/advanced-usage#managing-clickhouse-session-ids) ainda se aplicam quando uma conexão é compartilhada.
## Classes utilitárias e funções
Os módulos a seguir fornecem helpers públicos adicionais usados por aplicativos cliente.
A versão do pacote instalado é exposta como a string `clickhouse_connect.__version__`.
### Exceções
Exceções personalizadas, incluindo a hierarquia de exceções da DB-API 2.0, são definidas em `clickhouse_connect.driver.exceptions`. `DatabaseError` e `OperationalError` expõem um atributo numérico `code` com o código de erro do ClickHouse e um atributo `name` com o nome simbólico, como `UNKNOWN_TABLE`, para que os aplicativos possam tomar decisões com base em `exc.code` em vez de analisar a mensagem. `code` é definido mesmo quando `show_clickhouse_errors` está desabilitado, enquanto `name` requer detalhes do erro (`True` ou `"scrub"`). Ambos são `None` quando indisponíveis, como em erros de transporte. Use `show_clickhouse_errors="scrub"` quando os usuários finais precisarem ver erros de SQL sem informações de host ou versão do servidor. A configuração também controla mensagens de `StreamFailureError` no meio do stream e mensagens genéricas de transporte. Ela controla apenas `str(exc)`. Os erros de transporte ainda são anexados como `__cause__`, e os rastreamentos de pilha podem conter o host, a URL ou o texto de erro da biblioteca original.
### Utilitários de ClickHouse SQL
As funções e a classe DT64Param no módulo `clickhouse_connect.driver.binding` podem ser usadas para construir e escapar corretamente consultas em ClickHouse SQL. Da mesma forma, as funções no módulo `clickhouse_connect.driver.parser` podem ser usadas para analisar nomes de tipos de dados do ClickHouse.
## Casos de uso multithread, multiprocesso e assíncronos/orientados a eventos
Para mais informações sobre como usar o ClickHouse Connect em aplicações multithread, multiprocesso e assíncronas/orientadas a eventos, consulte [Uso avançado (Casos de uso multithread, multiprocesso e assíncronos/orientados a eventos)](/pt-BR/integrations/language-clients/python/advanced-usage#multithreaded-multiprocess-and-asyncevent-driven-use-cases).
## AsyncClient
Para usar o asyncio de forma nativa, consulte [Uso avançado (AsyncClient)](/pt-BR/integrations/language-clients/python/advanced-usage#asyncclient).
## Gerenciando IDs de sessão do ClickHouse
Para obter informações sobre como gerenciar IDs de sessão do ClickHouse em aplicações multithread ou concorrentes, consulte [Uso avançado (Gerenciando IDs de sessão do ClickHouse)](/pt-BR/integrations/language-clients/python/advanced-usage#managing-clickhouse-session-ids).
## Personalizando o pool de conexões HTTP
Para saber como personalizar o pool de conexões HTTP em aplicações grandes e multithread, consulte [Uso avançado (Personalizando o pool de conexões HTTP)](/pt-BR/integrations/language-clients/python/advanced-usage#customizing-the-http-connection-pool).