documentation 시스템 테이블

documentation 시스템 테이블은 시스템의 다양한 구성 요소의 내장 문서를 단일 테이블에 모아요. 각 행은 하나의 엔터티(함수, 테이블 엔진, 데이터 타입 등)에 해당하며, Markdown으로 렌더링된 내장 참조 문서를 담고 있어요.

출처: 문서

본문

Description (설명)

시스템의 균일 구성 요소의 내장 문서를 단일 테이블에 모아요. 각 행은 하나의 엔터티(함수, 테이블 엔진, 데이터 타입 등)에 해당하며 Markdown으로 렌더링된 내장 참조 문서를 담고 있어요. 이 내용은 생성된 웹사이트 문서와 종류별 system.* 테이블을 뒷받침해요. 웹사이트 페이지는 생성된 본문 밖에 MDX 전용 서문이나 지침을 추가할 수 있어요. description은 내장 문서의 구조화된 부분(description, syntax, arguments, examples 등)에서 조합되므로, 단일 열이 엔터티의 완전한 내장 문서를 보유해요. 내장 문서가 description에 전체 참조 페이지를 담고 있을 때(웹사이트 페이지가 그로부터 자동 생성되는 구성 요소의 경우: 테이블 엔진, 데이터베이스 엔진, 데이터 타입, 형식, 테이블 함수), 페이지는 구조화된 메타데이터 필드로 구성된 섹션을 추가하지 않고 그대로 게시돼요. 페이지 본문이 이미 그 내용을 다루기 때문이에요. 별칭은 정식 엔터티에 대한 짧은 참조로 렌더링돼요. 예: Alias of trunc``. 이 테이블은 어떤 면에서 종류별 문서 테이블(system.functions, system.table_engines, system.data_type_families 등)에서 사용 가능한 정보를 수집해요. 특히 클라이언트에서 대화형 help 명령을 뒷받침하기 위한 것이지만 그 자체로도 유용해요. 다음 종류의 엔터티가 수집돼요(type 열의 값은 괄호 안에 표시).

Functions (Function)
Aggregate functions (Aggregate Function)
Table functions (Table Function)
Table engines (Table Engine)
Database engines (Database Engine)
Data types (Data Type)
Dictionary layouts (Dictionary Layout)
Dictionary sources (Dictionary Source)
Aggregate function combinators (Aggregate Function Combinator)
Data skipping index types (Data Skipping Index)
Disk types (Disk Type)
Settings (Setting)
MergeTree settings (MergeTree Setting)
Server settings (Server Setting)
Formats (Format)
Compression codecs (Compression Codec)
Profile events (Profile Event)
Current metrics (Current Metric)
Asynchronous metrics (Asynchronous Metric)
System tables (System Table)
SQL statements (Statement)

설정(어떤 종류든)의 경우 문서는 설정의 설명과 타입, 기본값이에요. 더 이상 사용되지 않는 설정은 노출되지 않아요. 또한 ClickHouse 버전에 걸친 설정 기본값 변경 내역도 담고 있어요. 설정이 도입된 버전과 이후 기본값의 변경마다 이전 값, 새 값, 변경 이유가 기록돼요. 이는 compatibility 설정과 system.settings_changes를 뒷받침하는 것과 같은 데이터이므로, 그 메커니즘이 도입된 이후 기록된 변경만을 다뤄요. 기본값이 변경된 적 없는 오래된 설정은 내역이 없고, compatibility가 다루지 않는 서버 설정도 내역이 없어요. 설정의 별칭 아래 기록된 변경은 compatibility가 적용하는 것처럼 그 설정의 내역에 속하므로, 이름이 바뀐 설정의 내역은 이름 변경에서 잘리지 않아요. 예외는 별칭을 등록하기 위한 목적만으로 별칭 아래 작성된 레코드인데, 이는 별칭 자체의 내역이에요. 별칭은 그 이름 자체의 내역을 담고 있어요. 그 아래에 작성된 모든 레코드와 별칭으로 등록한 레코드(내역 파일이 때로는 같은 설정의 다른 이름 아래 작성하는)가 그것이에요. 시스템 테이블의 경우 설명, 예시, 관련 자료는 lightweight 섹션 마커를 사용해 테이블 메타데이터 주석에 저장돼요. 완전한 생성 페이지 본문은 그 주석과 라이브 열 스키마에서 조합돼요. 이벤트 및 메트릭 카탈로그는 그 레지스트리에서 렌더링되므로, 생성된 세부 사항이 실행 중인 바이너리와 동기화된 상태를 유지해요. SQL 문의 경우 문서는 system.statements가 노출하는 구조화된 필드에서 렌더링되며, 소스 소유 설명에 이미 포함되지 않은 섹션의 구문과 관련 문을 포함해요. source 열은 저장소 루트를 기준으로 한 엔터티의 소스 경로를 보유해요. 대부분의 엔터티에 대해 저장소 루트 기준으로 포착됩니다.

Columns (열)

name (String) — 엔터티의 이름, 예: domainWithoutWWW 또는 MergeTree.
type (Enum8(‘Function’ = 1, ‘Aggregate Function’ = 2, ‘Table Function’ = 3, ‘Table Engine’ = 4, ‘Database Engine’ = 5, ‘Data Type’ = 6, ‘Dictionary Layout’ = 7, ‘Dictionary Source’ = 8, ‘Aggregate Function Combinator’ = 9, ‘Data Skipping Index’ = 10, ‘Disk Type’ = 11, ‘Setting’ = 12, ‘MergeTree Setting’ = 13, ‘Server Setting’ = 14, ‘Format’ = 15, ‘Compression Codec’ = 16, ‘Profile Event’ = 17, ‘Current Metric’ = 18, ‘Asynchronous Metric’ = 19, ‘System Table’ = 20, ‘Statement’ = 21)) — 엔터티의 종류, 예: Function 또는 Table Engine.
description (String) — 내장 문서에서 조합되고 구문, 예시 및 기타 구조화된 부분(있다면)을 포함한 Markdown으로 렌더링된 엔터티의 참조 문서. 웹사이트 페이지는 생성된 본문 밖에 MDX 전용 서문이나 지침을 추가할 수 있어요.
source (String) — 엔터티 문서가 정의된 소스 파일의 저장소 루트 기준 경로. 소스 위치를 알 수 없으면 비어 있음.

Example (예제)

특정 엔터티의 문서를 읽기:

Query (쿼리)

SELECT description
FROM system.documentation
WHERE type = 'Table Engine' AND name = 'MergeTree'
FORMAT TSVRaw;

같은 이름이 여러 종류의 엔터티를 가리킬 수 있으므로(예: file 테이블 함수와 file 사전 소스가 모두 있음), 모든 종류에서 이름을 검색하는 것이 편리해요.

Query (쿼리)

SELECT type, name
FROM system.documentation
WHERE name = 'file'
ORDER BY type;

각 종류의 문서화된 엔터티 수 세기:

Query (쿼리)

SELECT type, count()
FROM system.documentation
GROUP BY type
ORDER BY count() DESC;

설정이 어느 버전에서 도입되었는지와 이후 기본값이 어떻게 변했는지 알아보기:

Query (쿼리)

SELECT description
FROM system.documentation
WHERE type = 'Setting' AND name = 'async_insert_max_data_size'
FORMAT TSVRaw;

documentation 시스템 테이블