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

> Configurações em nível de consulta

# Configurações de sessão em nível de consulta

<div id="overview">
  ## Visão geral
</div>

Há várias maneiras de executar instruções com configurações específicas.
As configurações são aplicadas em camadas, e cada camada seguinte substitui os valores definidos na camada anterior.

<div id="order-of-priority">
  ## Ordem de prioridade
</div>

A ordem de prioridade para definir uma configuração é:

1. Aplicar uma configuração diretamente a um usuário ou em um perfil de configurações

   * SQL (recomendado)
   * adicionar um ou mais arquivos XML ou YAML a `/etc/clickhouse-server/users.d`

2. Configurações de sessão

   * Envie `SET setting=value` pelo SQL Console do ClickHouse Cloud ou pelo
     `clickhouse client` no modo interativo. Da mesma forma, você pode usar
     sessões do ClickHouse no protocolo HTTP. Para isso, é necessário especificar o
     parâmetro HTTP `session_id`.

3. Configurações da consulta

   * Ao iniciar o `clickhouse client` no modo não interativo, defina o parâmetro
     de inicialização `--setting=value`.
   * Ao usar a API HTTP, passe parâmetros CGI (`URL?setting_1=value&setting_2=value...`).
   * Defina as configurações na
     cláusula
     [SETTINGS](/pt-BR/reference/statements/select#settings-in-select-query)
     da consulta SELECT. O valor da configuração é aplicado somente àquela consulta
     e é redefinido para o valor padrão ou anterior após a execução da consulta.

<div id="converting-a-setting-to-its-default-value">
  ## Convertendo uma configuração para o valor padrão
</div>

Se você alterar uma configuração e quiser revertê-la ao valor padrão, defina o valor como `DEFAULT`. A sintaxe é a seguinte:

```sql theme={null}
SET setting_name = DEFAULT
```

Por exemplo, o valor padrão de `async_insert` é `0`. Suponha que você altere esse valor para `1`:

```sql theme={null}
SET async_insert = 1;

SELECT value FROM system.settings where name='async_insert';
```

A resposta é:

```response theme={null}
┌─value──┐
│ 1      │
└────────┘
```

O comando a seguir redefine o valor para 0:

```sql theme={null}
SET async_insert = DEFAULT;

SELECT value FROM system.settings where name='async_insert';
```

A configuração agora voltou ao valor padrão:

```response theme={null}
┌─value───┐
│ 0       │
└─────────┘
```

<div id="custom_settings">
  ## Configurações personalizadas
</div>

Além das [configurações](/pt-BR/reference/settings/session-settings) comuns, os usuários podem definir configurações personalizadas.
As configurações personalizadas permitem passar **parâmetros específicos da sessão** que podem ser referenciados em consultas, políticas ou funções. Isso é útil quando você precisa:

* Filtrar dados com base na identidade do usuário ou na organização
* Aplicar lógicas de negócios diferentes de acordo com o contexto
* Manter informações com preservação de estado entre consultas em uma sessão

O nome de uma configuração personalizada deve começar com um dos prefixos predefinidos de uma lista definida por você.
A lista de prefixos pode ser especificada usando a configuração de servidor [`custom_settings_prefixes`](/pt-BR/reference/settings/server-settings/settings#custom_settings_prefixes), definida no arquivo de configuração do servidor.

No exemplo abaixo, `SQL_` é usado como prefixo personalizado:

```xml theme={null}
<custom_settings_prefixes>SQL_</custom_settings_prefixes>
```

<Note>
  No ClickHouse Cloud, não é possível especificar um prefixo personalizado.
  Todas as configurações de usuário personalizadas começam com o prefixo `SQL_`.
</Note>

Para definir uma configuração personalizada, use o comando `SET`:

```sql theme={null}
SET SQL_a = 123;
```

Para obter o valor atual de uma configuração personalizada, use a função `getSetting()`:

```sql theme={null}
SELECT getSetting('SQL_a');
```

<div id="examples">
  ## Exemplos
</div>

Todos estes exemplos definem o valor da configuração `async_insert` como `1` e
mostram como verificar as configurações em um sistema em funcionamento.

<div id="using-sql-to-apply-a-setting-to-a-user-directly">
  ### Usando SQL para aplicar uma configuração diretamente a um usuário
</div>

Isso cria o usuário `ingester` com a configuração `async_inset = 1`:

```sql highlight={3} theme={null}
CREATE USER ingester
IDENTIFIED WITH sha256_hash BY '7e099f39b84ea79559b3e85ea046804e63725fd1f46b37f281276aae20f86dc3'
SETTINGS async_insert = 1
```

<div id="examine-the-settings-profile-and-assignment">
  #### Examine o perfil de configurações e sua atribuição
</div>

```sql theme={null}
SHOW ACCESS
```

```response highlight={3} theme={null}
┌─ACCESS─────────────────────────────────────────────────────────────────────────────┐
│ ...                                                                                │
│ CREATE USER ingester IDENTIFIED WITH sha256_password SETTINGS async_insert = true  │
│ ...                                                                                │
└────────────────────────────────────────────────────────────────────────────────────┘
```

<div id="using-sql-to-create-a-settings-profile-and-assign-to-a-user">
  ### Usando SQL para criar um perfil de configurações e atribuí-lo a um usuário
</div>

Isso cria o perfil `log_ingest` com a configuração `async_inset = 1`:

```sql theme={null}
CREATE
SETTINGS PROFILE log_ingest SETTINGS async_insert = 1
```

Isso cria o usuário `ingester` e atribui a ele o perfil de configurações `log_ingest`:

```sql highlight={3} theme={null}
CREATE USER ingester
IDENTIFIED WITH sha256_hash BY '7e099f39b84ea79559b3e85ea046804e63725fd1f46b37f281276aae20f86dc3'
SETTINGS PROFILE log_ingest
```

<div id="using-xml-to-create-a-settings-profile-and-user">
  ### Criando um perfil de configurações e um usuário com XML
</div>

```xml title=/etc/clickhouse-server/users.d/users.xml highlight={2-6,11} theme={null}
<clickhouse>
    <profiles>
        <log_ingest>
            <async_insert>1</async_insert>
        </log_ingest>
    </profiles>

    <users>
        <ingester>
            <password_sha256_hex>7e099f39b84ea79559b3e85ea046804e63725fd1f46b37f281276aae20f86dc3</password_sha256_hex>
            <profile>log_ingest</profile>
        </ingester>
        <default replace="true">
            <password_sha256_hex>7e099f39b84ea79559b3e85ea046804e63725fd1f46b37f281276aae20f86dc3</password_sha256_hex>
            <access_management>1</access_management>
            <named_collection_control>1</named_collection_control>
        </default>
    </users>
</clickhouse>
```

<div id="examine-the-settings-profile-and-assignment-1">
  #### Verifique o perfil de configurações e a atribuição
</div>

```sql theme={null}
SHOW ACCESS
```

```response highlight={3,5} theme={null}
┌─ACCESS─────────────────────────────────────────────────────────────────────────────┐
│ CREATE USER default IDENTIFIED WITH sha256_password                                │
│ CREATE USER ingester IDENTIFIED WITH sha256_password SETTINGS PROFILE log_ingest   │
│ CREATE SETTINGS PROFILE default                                                    │
│ CREATE SETTINGS PROFILE log_ingest SETTINGS async_insert = true                    │
│ CREATE SETTINGS PROFILE readonly SETTINGS readonly = 1                             │
│ ...                                                                                │
└────────────────────────────────────────────────────────────────────────────────────┘
```

<div id="assign-a-setting-to-a-session">
  ### Definir uma configuração para uma sessão
</div>

```sql theme={null}
SET async_insert =1;
SELECT value FROM system.settings where name='async_insert';
```

```response theme={null}
┌─value──┐
│ 1      │
└────────┘
```

<div id="assign-a-setting-during-a-query">
  ### Definir uma configuração durante uma consulta
</div>

```sql highlight={2} theme={null}
INSERT INTO YourTable
SETTINGS async_insert=1
VALUES (...)
```

<div id="see-also">
  ## Veja também
</div>

* Consulte a página [Configurações](/pt-BR/reference/settings/session-settings) para ver uma descrição das configurações do ClickHouse.
* [Configurações globais do servidor](/pt-BR/reference/settings/server-settings/settings)