쿼리 레벨 세션 설정

쿼리 레벨 세션 설정 (Query-level Session Settings)

특정 설정과 함께 문을 실행하는 방법은 여러 가지가 있어요. 설정은 레이어로 구성되며, 각 후속 레이어가 이전의 설정값을 재정의해요. 여기서는 설정의 우선순위와 적용 방법을 설명해 드릴게요.

출처: 문서

본문

개요 (Overview)

특정 설정과 함께 문을 실행하는 방법은 여러 가지가 있어요. 설정은 레이어로 구성되고, 각 후속 레이어가 이전의 설정값을 재정의해요.

우선순위 순서 (Order of priority)

설정을 정의하는 우선순위 순서는 다음과 같아요:

  1. 사용자에게 직접 또는 설정 프로필 안에서 설정 적용
    1. SQL (권장)
    2. /etc/clickhouse-server/users.d에 XML 또는 YAML 파일을 하나 이상 추가
  2. 세션 설정
    1. ClickHouse Cloud SQL 콘솔 또는 대화형 모드의 clickhouse client에서 SET setting=value 보내기. 마찬가지로 HTTP 프로토콜에서 ClickHouse 세션을 사용할 수 있어요. 그러려면 session_id HTTP 파라미터를 지정해야 해요.
  3. 쿼리 설정
    1. 비대화형 모드에서 clickhouse client를 시작할 때 시작 파라미터 --setting=value를 설정.
    2. HTTP API를 사용할 때 CGI 파라미터를 전달 (URL?setting_1=value&setting_2=value...).
    3. SELECT 쿼리의 SETTINGS 절에서 설정 정의. 설정값은 해당 쿼리에만 적용되며, 쿼리 실행 후 기본값이나 이전 값으로 리셋돼요.

설정을 기본값으로 되돌리기 (Converting a setting to its default value)

설정을 변경했는데 기본값으로 되돌리고 싶다면 값을 DEFAULT로 설정하면 돼요. 문법은 다음과 같아요:

SET setting_name = DEFAULT

예를 들어 async_insert의 기본값은 0이에요. 그 값을 1로 바꿔 보자면:

SET async_insert = 1;

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

응답은:

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

다음 명령은 값을 0으로 되돌려요:

SET async_insert = DEFAULT;

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

이제 설정이 기본값으로 돌아왔어요:

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

사용자 정의 설정 (Custom settings)

일반적인 설정 외에도 사용자는 사용자 정의 설정을 정의할 수 있어요. 사용자 정의 설정을 사용하면 쿼리, 정책 또는 함수 내에서 참조할 수 있는 세션별 파라미터를 전달할 수 있어요. 이는 다음과 같은 경우에 유용해요:

  • 사용자 신원이나 조직에 따라 데이터 필터링
  • 컨텍스트에 따라 다른 비즈니스 로직 적용
  • 세션의 여러 쿼리에서 상태 정보 유지

사용자 정의 설정 이름은 사용자가 정의한 목록의 미리 정의된 접두사 중 하나로 시작해야 해요. 접두사 목록은 서버 설정 파일에 정의된 custom_settings_prefixes 서버 설정으로 지정할 수 있어요.

아래 예시에서는 SQL_을 사용자 정의 접두사로 선택했어요:

<custom_settings_prefixes>SQL_</custom_settings_prefixes>

참고: ClickHouse Cloud에서는 사용자 정의 접두사를 지정할 수 없어요. 모든 사용자 정의 사용자 설정은 접두사 SQL_로 시작해요.

사용자 정의 설정을 정의하려면 SET 명령을 사용해요:

SET SQL_a = 123;

사용자 정의 설정의 현재 값을 얻으려면 getSetting() 함수를 사용해요:

SELECT getSetting('SQL_a');

예시 (Examples)

이 예시들은 모두 async_insert 설정의 값을 1로 설정하고, 실행 중인 시스템에서 설정을 어떻게 확인하는지 보여줘요.

SQL로 사용자에게 설정을 직접 적용하기

다음은 async_inset = 1 설정을 가진 사용자 ingester를 생성해요:

CREATE USER ingester
IDENTIFIED WITH sha256_hash BY '7e099f39b84ea79559b3e85ea046804e63725fd1f46b37f281276aae20f86dc3'
SETTINGS async_insert = 1
설정 프로필과 할당 확인하기
SHOW ACCESS

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

SQL로 설정 프로필을 만들고 사용자에게 할당하기

다음은 async_inset = 1 설정을 가진 프로필 log_ingest를 생성해요:

CREATE
SETTINGS PROFILE log_ingest SETTINGS async_insert = 1

다음은 사용자 ingester를 만들고 설정 프로필 log_ingest를 할당해요:

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

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>
설정 프로필과 할당 확인하기
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                             │
│ ...                                                                                │
└────────────────────────────────────────────────────────────────────────────────────┘

세션에 설정 할당하기

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

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

쿼리 중에 설정 할당하기

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

더 알아보기 (Learn more)