MATERIALIZED VIEW가 이 엔진에 연결되면 S3Queue 테이블 엔진이 백그라운드에서 데이터 수집을 시작합니다.
테이블 생성
S3Queue의 매개변수는 S3 테이블 엔진이 지원하는 매개변수와 동일합니다. 매개변수 섹션은 여기를 참조하십시오.
예시
설정
system.s3_queue_settings 테이블을 사용하십시오. 24.10부터 사용할 수 있습니다.
설정 이름 (24.7+)버전 24.7부터는
s3queue_ 접두사(prefix) 유무와 관계없이 S3Queue 설정을 지정할 수 있습니다.- 최신 구문 (24.7+):
processing_threads_num,tracked_file_ttl_sec등 - 레거시 구문 (모든 버전):
s3queue_processing_threads_num,s3queue_tracked_file_ttl_sec등
모드
- unordered — unordered 모드에서는 이미 처리된 모든 파일의 집합을 ZooKeeper의 영구 노드로 추적합니다.
- ordered — ordered 모드에서는 파일이 사전식 순서로 처리됩니다. 즉, 어느 시점에 ‘BBB’라는 이름의 파일이 처리된 뒤 나중에 ‘AA’라는 이름의 파일이 버킷에 추가되면, 해당 파일은 무시됩니다. ZooKeeper에는 성공적으로 처리된 파일 중 사전식 기준으로 가장 큰 이름과, 로드 시도에 실패하여 다시 시도할 파일의 이름만 저장됩니다.
ordered입니다. 24.6부터는 기본값이 없으며, 이 설정을 수동으로 지정해야 합니다. 이전 버전에서 생성된 테이블은 호환성을 위해 기본값이 계속 Ordered로 유지됩니다.
after_processing
- keep.
- delete.
- move.
- tag.
keep.
move를 사용하려면 추가 설정이 필요합니다. 동일한 버킷 내에서 이동하는 경우 새 경로 접두사를 after_processing_move_prefix로 지정해야 합니다.
다른 S3 버킷으로 이동하려면 대상 버킷 URI를 after_processing_move_uri로, S3 자격 증명을 after_processing_move_access_key_id 및 after_processing_move_secret_access_key로 지정해야 합니다.
예시:
after_processing_move_connection_string에 Blob Storage 연결 문자열을, after_processing_move_container에 컨테이너 이름을 지정해야 합니다. 자세한 내용은 AzureQueue 설정을 참조하십시오.
태그를 지정하려면 after_processing_tag_key와 after_processing_tag_value에 태그 키와 값을 제공해야 합니다.
after_processing_retries
- 0 이상의 정수.
10.
after_processing_move_access_key_id
- String.
after_processing_move_prefix
- String.
after_processing_move_secret_access_key
- String.
after_processing_move_uri
- String.
after_processing_tag_key
after_processing='tag'인 경우, 성공적으로 처리된 파일에 태그를 추가할 때 사용하는 태그 키입니다.
가능한 값:
String.
after_processing_tag_value
after_processing='tag'인 경우, 성공적으로 처리된 파일에 지정할 태그 값입니다.
가능한 값:
- String.
keeper_path
s3queue_default_zookeeper_path, 데이터베이스 UUID, 테이블 UUID를 기반으로 경로를 구성합니다. 절대값(/로 시작하는 값)은 지정된 그대로 사용되며, 상대값은 구성된 접두사에 추가됩니다. {database} 또는 {uuid}와 같은 매크로는 엔진이 ZooKeeper에 연결되기 전에 확장됩니다.
보조 ZooKeeper 클러스터를 대상으로 하려면 값 앞에 구성된 이름을 접두사로 붙이십시오. 예: analytics_keeper:/clickhouse/queue/orders. 이 이름은 <auxiliary_zookeepers>에 존재해야 하며, 그렇지 않으면 엔진이 Unknown auxiliary ZooKeeper name ...를 보고합니다. 전체 문자열(접두사 포함)은 SHOW CREATE TABLE에 그대로 보존되므로 해당 구문을 수정 없이 그대로 복제할 수 있습니다.
가능한 값:
- String.
/.
loading_retries
- 양의 정수.
0.
processing_threads_num
Unordered 모드에서만 적용됩니다.
기본값: CPU 수 또는 16입니다.
parallel_inserts
processing_threads_num은 하나의 INSERT만 생성하므로, 파일 다운로드와 파싱만 여러 스레드로 수행됩니다.
하지만 이렇게 하면 병렬성이 제한되므로, 더 높은 처리량을 위해 parallel_inserts=true를 사용하세요. 이렇게 하면 데이터를 병렬로 삽입할 수 있습니다(단, MergeTree 엔진 계열에서는 생성되는 데이터 파트 수가 더 많아질 수 있다는 점에 유의하십시오).
INSERT는 max_process*_before_commit 설정에 따라 생성됩니다.false.
enable_logging_to_s3queue_log
system.s3queue_log에 로깅을 기록하도록 설정합니다.
기본값: 0.
polling_min_timeout_ms
- 양의 정수.
1000.
polling_max_timeout_ms
- 양의 정수.
10000.
polling_backoff_ms
- 양의 정수.
0.
tracked_files_limit
unordered 모드를 사용하는 경우 ZooKeeper 노드 수를 제한할 수 있으며, ordered 모드에서는 적용되지 않습니다.
제한에 도달하면 가장 오래 전에 처리된 파일이 ZooKeeper 노드에서 삭제되고 다시 처리됩니다.
가능한 값:
- 양의 정수.
1000.
tracked_file_ttl_sec
- 양의 정수.
0.
cleanup_interval_min_ms
10000.
cleanup_interval_max_ms
30000.
buckets
24.6부터 사용할 수 있습니다. S3Queue 테이블에 여러 레플리카가 있고 각 레플리카가 Keeper의 동일한 메타데이터 디렉터리를 사용하는 경우, buckets 값은 최소한 레플리카 수 이상이어야 합니다. processing_threads 설정도 함께 사용하는 경우에는 buckets 설정이 S3Queue 처리의 실제 병렬성을 결정하므로, 이 값을 더 크게 설정하는 것이 좋습니다.
use_persistent_processing_nodes
persistent_processing_nodes_ttl_seconds
use_persistent_processing_nodes가 활성화되어 있으면 제거되지 않은 processing 노드가 남아 있을 수 있습니다. 이 설정은 이러한 processing 노드를 안전하게 정리할 수 있는 시간 주기를 정의합니다.
기본값: 3600 (1시간)입니다.
S3 관련 설정
S3 역할 기반 접근
extra_credentials 매개변수를 통해 roleARN을 전달할 수 있습니다:
S3Queue ordered 모드
S3Queue 처리 모드를 사용하면 ZooKeeper에 저장하는 메타데이터를 줄일 수 있지만, 나중 시점에 추가되는 파일은 영숫자 기준으로 더 큰 이름이어야 한다는 제한이 있습니다.
S3Queue의 ordered 모드는 unordered와 마찬가지로 (s3queue_)processing_threads_num 설정(s3queue_ 접두사는 선택 사항)을 지원하며, 이 설정으로 서버에서 S3 파일을 로컬로 처리하는 스레드 수를 제어할 수 있습니다.
파티셔닝 없이 ordered 모드를 사용하는 경우, ClickHouse는 전체 접두사 이력을 다시 나열하지 않기 위해 마지막으로 처리한 키부터 S3 목록 조회를 재개할 수 있습니다. 버킷 기반 ordered 모드에서는 처리되지 않은 파일이 스키핑되는 것을 방지하기 위해, 모든 버킷에서 처리된 키 중 가장 작은 키를 재개 지점으로 보수적으로 선택합니다.
이 목록 조회 재개 최적화는 파티셔닝이 없는 ordered 모드의 S3 기반 큐에서만 사용됩니다(AzureQueue에는 사용되지 않으며, partitioning_mode가 설정된 경우에도 사용되지 않습니다).
또한 ordered 모드에는 “(s3queue_)buckets”라는 또 다른 설정이 도입되며, 이는 “논리 스레드”를 의미합니다. 즉, 분산 환경에서 S3Queue 테이블 레플리카가 있는 여러 서버를 사용할 때 이 설정이 처리 단위 수를 정의합니다. 예를 들어 각 S3Queue 레플리카의 각 처리 스레드는 처리를 위해 특정 bucket을 잠그려고 시도하며, 각 bucket은 파일 이름의 해시에 따라 특정 파일에 할당됩니다. 따라서 분산 환경에서는 (s3queue_)buckets 설정을 최소한 레플리카 수와 같거나 그보다 크게 설정하는 것을 강력히 권장합니다. 버킷 수가 레플리카 수보다 많아도 문제없습니다. 가장 최적의 시나리오는 (s3queue_)buckets 설정이 number_of_replicas와 (s3queue_)processing_threads_num의 곱과 같을 때입니다.
(s3queue_)processing_threads_num 설정은 버전 24.6 이전에서는 사용을 권장하지 않습니다.
(s3queue_)buckets 설정은 버전 24.6부터 사용할 수 있습니다.
S3Queue 테이블 엔진에서 SELECT
stream_like_engine_allow_direct_select를 True로 지정해야 합니다.
S3Queue 엔진에는 SELECT 쿼리용 특수 설정인 commit_on_select가 있습니다. 읽은 후에도 큐에 데이터를 유지하려면 False로 설정하고, 제거하려면 True로 설정하십시오.
설명
SELECT는 스트리밍 가져오기에는(디버깅 용도 제외) 그다지 유용하지 않습니다. 대신 materialized view를 사용해 실시간 스레드를 만드는 것이 더 실용적입니다. 이를 위해 다음을 수행합니다.
- 엔진을 사용해 S3의 지정된 경로에서 데이터를 읽어 오는 테이블을 만들고, 이를 데이터 스트림으로 간주합니다.
- 원하는 구조의 테이블을 만듭니다.
- 엔진의 데이터를 변환해 앞서 만든 테이블에 넣는 materialized view를 생성합니다.
MATERIALIZED VIEW를 엔진에 연결하면 백그라운드에서 데이터 수집이 시작됩니다.
예시:
가상 컬럼
_path— 파일 경로입니다._file— 파일 이름입니다._size— 파일 크기입니다._time— 파일 생성 시간입니다.
경로 내 와일드카드
path 인수에는 bash 스타일의 와일드카드를 사용해 여러 파일을 지정할 수 있습니다. 처리할 파일은 실제로 존재해야 하며 전체 경로 패턴과 일치해야 합니다. 파일 목록은 CREATE 시점이 아니라 SELECT 시점에 결정됩니다.
*— 빈 문자열을 포함해/를 제외한 임의의 문자 0개 이상을 대체합니다.**— 빈 문자열을 포함해/를 포함한 임의의 문자 0개 이상을 대체합니다.?— 임의의 단일 문자를 대체합니다.{some_string,another_string,yet_another_one}—'some_string','another_string','yet_another_one'문자열 중 하나를 대체합니다.{N..M}— N부터 M까지 범위의 임의의 숫자를 양 끝값을 포함해 대체합니다. N과 M 앞에는 0이 올 수 있습니다. 예:000..078.
{} 구문은 remote 테이블 함수와 유사합니다.
제한 사항
- 중복된 행은 다음과 같은 이유로 발생할 수 있습니다.
-
파일 처리 도중 파싱 중 예외가 발생하고
s3queue_loading_retries를 통해 재시도가 활성화된 경우 -
S3Queue가 ZooKeeper의 동일한 경로를 가리키도록 여러 서버에 구성되어 있고, 한 서버가 처리된 파일을 커밋하기 전에 Keeper 세션이 만료되면 다른 서버가 해당 파일 처리를 이어받을 수 있으며, 이 경우 첫 번째 서버가 이미 해당 파일을 일부 또는 전체 처리했을 수 있습니다. 다만use_persistent_processing_nodes = 1인 경우, 버전 25.8부터는 더 이상 해당하지 않습니다. - 서버가 비정상적으로 종료된 경우
S3Queue가 ZooKeeper의 동일한 경로를 가리키도록 여러 서버에 구성되어 있고Ordered모드를 사용하는 경우s3queue_loading_retries는 작동하지 않습니다. 이는 곧 수정될 예정입니다.
내부 검사
system.s3queue_metadata_cache stateless 테이블과 system.s3queue_log 영속 테이블을 사용합니다.
system.s3queue_metadata_cache. 이 테이블은 영속적이지 않으며S3Queue의 메모리 내 상태를 보여줍니다. 즉, 현재 처리 중인 파일과 처리 완료되었거나 실패한 파일을 확인할 수 있습니다.
system.s3queue_log. 영속 테이블입니다.system.s3queue_metadata_cache와 동일한 정보를 제공하지만,processed및failed파일에 대한 정보입니다.
system.s3queue_log를 사용하려면 서버 구성 파일에 해당 구성을 정의하십시오: