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

Configurações em nível de consulta

​

Visão geral

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.

​

Ordem de prioridade

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 SETTINGS cláusula 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.

​

Convertendo uma configuração para o valor padrão

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

SET setting_name = DEFAULT

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

SET async_insert = 1;

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

A resposta é:

┌─value──┐
│ 1      │
└────────┘

O comando a seguir redefine o valor para 0:

SET async_insert = DEFAULT;

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

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

┌─value───┐
│ 0       │
└─────────┘

​

Configurações personalizadas

Além das configurações 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, definida no arquivo de configuração do servidor.

No exemplo abaixo, SQL_ é usado como prefixo personalizado:

<custom_settings_prefixes>SQL_</custom_settings_prefixes>

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

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

SET SQL_a = 123;

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

SELECT getSetting('SQL_a');

​

Exemplos

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.

​

Usando SQL para aplicar uma configuração diretamente a um usuário

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

CREATE USER ingester
IDENTIFIED WITH sha256_hash BY '7e099f39b84ea79559b3e85ea046804e63725fd1f46b37f281276aae20f86dc3'
SETTINGS async_insert = 1

​

Examine o perfil de configurações e sua atribuição

SHOW ACCESS

┌─ACCESS─────────────────────────────────────────────────────────────────────────────┐
│ ...                                                                                │
│ CREATE USER ingester IDENTIFIED WITH sha256_password SETTINGS async_insert = true  │
│ ...                                                                                │
└────────────────────────────────────────────────────────────────────────────────────┘

​

Usando SQL para criar um perfil de configurações e atribuí-lo a um usuário

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

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:

CREATE USER ingester
IDENTIFIED WITH sha256_hash BY '7e099f39b84ea79559b3e85ea046804e63725fd1f46b37f281276aae20f86dc3'
SETTINGS PROFILE log_ingest

​

Criando um perfil de configurações e um usuário com XML

/etc/clickhouse-server/users.d/users.xml

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

​

Verifique o perfil de configurações e a atribuição

SHOW ACCESS

┌─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                             │
│ ...                                                                                │
└────────────────────────────────────────────────────────────────────────────────────┘

​

Definir uma configuração para uma sessão

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

┌─value──┐
│ 1      │
└────────┘

​

Definir uma configuração durante uma consulta

INSERT INTO YourTable
SETTINGS async_insert=1
VALUES (...)

​

Veja também

• Consulte a página Configurações para ver uma descrição das configurações do ClickHouse.
• Configurações globais do servidor