Template - ClickHouse Documentation

입력	출력	별칭
✔	✔

설명

다른 표준 포맷으로는 부족할 정도로 더 세밀한 사용자 지정이 필요한 경우, Template 형식을 사용하면 값용 placeholder가 포함된 사용자 정의 포맷 문자열을 직접 지정하고, 데이터의 이스케이프 규칙도 지정할 수 있습니다. 다음 설정을 사용합니다:

Setting	Description
`format_template_row`	행의 포맷 문자열이 들어 있는 파일의 경로를 지정합니다.
`format_template_resultset`	행의 포맷 문자열이 들어 있는 파일의 경로를 지정합니다.
`format_template_rows_between_delimiter`	행 사이의 구분자를 지정합니다. 마지막 행을 제외한 각 행 뒤에 출력되거나(또는 입력 시 기대되는 값이며), 기본값은 `\n`입니다.
`format_template_row_format`	행의 포맷 문자열을 인라인으로 지정합니다.
`format_template_resultset_format`	결과 집합 포맷 문자열을 인라인으로 지정합니다.
Some settings of other formats (e.g.`output_format_json_quote_64bit_integers` when using `JSON` escaping

설정 및 이스케이프 규칙

format_template_row

설정 format_template_row는 다음 구문에 사용되는 행의 포맷 문자열이 들어 있는 파일의 경로를 지정합니다:

delimiter_1${column_1:serializeAs_1}delimiter_2${column_2:serializeAs_2} ... delimiter_N

다음과 같습니다.

구문의 부분	설명
`delimiter_i`	값 사이의 구분자(`$` 기호는 `$$`로 이스케이프할 수 있음)
`column_i`	선택하거나 삽입할 값이 들어 있는 컬럼의 이름 또는 인덱스(비어 있으면 해당 컬럼은 건너뜀)
`serializeAs_i`	컬럼 값에 적용할 이스케이프 규칙입니다.

다음 이스케이프 규칙을 지원합니다.

이스케이프 규칙	설명
`CSV`, `JSON`, `XML`	같은 이름의 포맷과 유사합니다
`Escaped`	`TSV`와 유사합니다
`Quoted`	`Values`와 유사합니다
`Raw`	이스케이프 없이 `TSVRaw`와 유사합니다
`None`	이스케이프 규칙이 없음 - 아래 참고

이스케이프 규칙을 생략하면 None이 사용됩니다. XML은 출력에만 적합합니다.

예시를 살펴보겠습니다. 다음 포맷 문자열이 있다고 가정합니다.

Search phrase: ${s:Quoted}, count: ${c:Escaped}, ad price: $$${p:JSON};

다음 값은 SELECT를 사용하는 경우 출력되고 INPUT을 사용하는 경우 기대되며, 각각 컬럼 구분 기호 Search phrase:, , count:, , ad price: $, ; 사이에 위치합니다:

s (이스케이프 규칙 Quoted 적용)
c (이스케이프 규칙 Escaped 적용)
p (이스케이프 규칙 JSON 적용)

예시:

INSERT하는 경우, 아래 줄은 기대되는 Template과 일치하며 값 bathroom interior design, 2166, $3를 컬럼 Search phrase, count, ad price에 읽어옵니다.
SELECT하는 경우, 아래 줄은 출력 결과이며 값 bathroom interior design, 2166, $3가 이미 테이블의 컬럼 Search phrase, count, ad price에 저장되어 있다고 가정합니다.

Search phrase: 'bathroom interior design', count: 2166, ad price: $3;

format_template_rows_between_delimiter

format_template_rows_between_delimiter 설정은 행 사이의 구분자를 지정합니다. 이 구분자는 마지막 행을 제외한 각 행 뒤에 출력되거나(또는 입력에서 필요로 하는 값으로) 사용됩니다(기본값은 \n).

format_template_resultset

format_template_resultset 설정은 결과 집합(result set)의 포맷 문자열이 들어 있는 파일 경로를 지정합니다. 결과 집합의 포맷 문자열은 행에 대한 포맷 문자열과 동일한 구문을 사용합니다. 접두사, 접미사, 일부 추가 정보를 출력하는 방법을 지정할 수 있으며, 컬럼 이름 대신 다음 placeholder를 포함합니다:

data는 format_template_row 포맷의 데이터 행들이며, format_template_rows_between_delimiter로 구분됩니다. 이 placeholder는 포맷 문자열의 첫 번째 placeholder여야 합니다.
totals는 format_template_row 포맷의 합계 값 행입니다(WITH TOTALS 사용 시).
min은 format_template_row 포맷의 최솟값 행입니다(extremes가 1로 설정된 경우).
max는 format_template_row 포맷의 최댓값 행입니다(extremes가 1로 설정된 경우).
rows는 출력 행의 총개수입니다.
rows_before_limit는 LIMIT가 없었을 경우의 최소 행 수입니다. 쿼리에 LIMIT가 포함된 경우에만 출력됩니다. 쿼리에 GROUP BY가 포함된 경우, rows_before_limit_at_least는 LIMIT가 없었을 경우의 정확한 행 수입니다.
time은 요청 실행 시간(초)입니다.
rows_read는 읽은 행 수입니다.
bytes_read는 읽은 바이트 수(비압축 기준)입니다.

data, totals, min, max placeholder에는 이스케이프 규칙을 지정하면 안 됩니다(또는 None을 명시적으로 지정해야 합니다). 나머지 placeholder에는 어떤 이스케이프 규칙이든 지정할 수 있습니다.

format_template_resultset 설정이 빈 문자열이면 기본값으로 ${data}가 사용됩니다.

삽입 쿼리 포맷에서는 접두사나 접미사가 있는 경우 일부 컬럼 또는 필드를 스키핑할 수 있습니다(예시 참조).

인라인 지정

클러스터의 모든 노드에서 디렉터리에 Template 형식의 포맷 구성 (format_template_row, format_template_resultset로 설정)을 배포하는 것은 종종 어렵거나 불가능할 수 있습니다. 또한 포맷이 매우 단순해서 파일에 둘 필요가 없을 수도 있습니다. 이런 경우 format_template_row_format(format_template_row용)과 format_template_resultset_format(format_template_resultset용)을 사용하면, 이를 포함하는 파일의 경로를 지정하는 대신 템플릿 문자열을 쿼리에서 직접 설정할 수 있습니다.

포맷 문자열과 이스케이프 시퀀스에 대한 규칙은 다음과 같습니다:

format_template_row_format를 사용할 때는 format_template_row의 규칙과 동일합니다.
format_template_resultset_format를 사용할 때는 format_template_resultset의 규칙과 동일합니다.

사용 예시

Template 형식을 사용하는 두 가지 예시를 살펴보겠습니다. 먼저 데이터를 선택하는 경우를 보고, 그다음 데이터를 삽입하는 경우를 살펴보겠습니다.

데이터 조회

Query

SELECT SearchPhrase, count() AS c FROM test.hits GROUP BY SearchPhrase ORDER BY c DESC LIMIT 5 FORMAT Template SETTINGS
format_template_resultset = '/some/path/resultset.format', format_template_row = '/some/path/row.format', format_template_rows_between_delimiter = '\n    '

/some/path/resultset.format

<!DOCTYPE HTML>
<html> <head> <title>Search phrases</title> </head>
 <body>
  <table border="1"> <caption>Search phrases</caption>
    <tr> <th>Search phrase</th> <th>Count</th> </tr>
    ${data}
  </table>
  <table border="1"> <caption>Max</caption>
    ${max}
  </table>
  <b>Processed ${rows_read:XML} rows in ${time:XML} sec</b>
 </body>
</html>

/some/path/row.format

<tr> <td>${0:XML}</td> <td>${1:XML}</td> </tr>

Response

<!DOCTYPE HTML>
<html> <head> <title>Search phrases</title> </head>
 <body>
  <table border="1"> <caption>Search phrases</caption>
    <tr> <th>Search phrase</th> <th>Count</th> </tr>
    <tr> <td></td> <td>8267016</td> </tr>
    <tr> <td>bathroom interior design</td> <td>2166</td> </tr>
    <tr> <td>clickhouse</td> <td>1655</td> </tr>
    <tr> <td>spring 2014 fashion</td> <td>1549</td> </tr>
    <tr> <td>freeform photos</td> <td>1480</td> </tr>
  </table>
  <table border="1"> <caption>Max</caption>
    <tr> <td></td> <td>8873898</td> </tr>
  </table>
  <b>Processed 3095973 rows in 0.1569913 sec</b>
 </body>
</html>

데이터 삽입

Some header
Page views: 5, User id: 4324182021466249494, Useless field: hello, Duration: 146, Sign: -1
Page views: 6, User id: 4324182021466249494, Useless field: world, Duration: 185, Sign: 1
Total rows: 2

INSERT INTO UserActivity SETTINGS
format_template_resultset = '/some/path/resultset.format', format_template_row = '/some/path/row.format'
FORMAT Template

/some/path/resultset.format

Some header\n${data}\nTotal rows: ${:CSV}\n

/some/path/row.format

Page views: ${PageViews:CSV}, User id: ${UserID:CSV}, Useless field: ${:CSV}, Duration: ${Duration:CSV}, Sign: ${Sign:CSV}

플레이스홀더 안의 PageViews, UserID, Duration, Sign은 테이블의 컬럼 이름입니다. 행에서 Useless field 뒤에 오는 값과 접미사에서 \nTotal rows: 뒤에 오는 값은 무시됩니다. 입력 데이터의 모든 구분 기호는 지정된 포맷 문자열의 구분 기호와 정확히 일치해야 합니다.

인라인 지정

Markdown 표를 수동으로 포맷하느라 번거로우셨나요? 이 예시에서는 Template 형식과 인라인 지정 설정을 사용해 간단한 작업을 수행하는 방법을 살펴보겠습니다. 즉, system.formats 테이블에서 몇 가지 ClickHouse 포맷의 이름을 SELECT한 뒤 이를 Markdown 표로 포맷하는 방법입니다. 이는 Template 형식과 format_template_row_format, format_template_resultset_format 설정을 사용하면 쉽게 구현할 수 있습니다. 이전 예시에서는 결과 집합과 행 포맷 문자열을 각각 별도의 파일에 지정하고, 해당 파일의 경로를 각각 format_template_resultset 및 format_template_row 설정으로 지정했습니다. 여기서는 템플릿이 Markdown 표를 만드는 데 필요한 몇 개의 |와 -만으로 이루어질 정도로 단순하므로 인라인으로 지정하겠습니다. 결과 집합 템플릿 문자열은 format_template_resultset_format 설정을 사용해 지정합니다. 표 헤더를 만들기 위해 ${data} 앞에 |ClickHouse Formats|\n|---|\n를 추가했습니다. 행 템플릿 문자열 |`{0:XML}`|은 format_template_row_format 설정을 사용해 지정합니다. Template 형식은 지정된 포맷의 행을 ${data} 플레이스홀더에 삽입합니다. 이 예시에서는 컬럼이 하나뿐이지만, 더 추가하려면 행 템플릿 문자열에 {1:XML}, {2:XML} 등을 추가하면 됩니다. 이때 적절한 이스케이프 규칙을 선택하십시오. 이 예시에서는 XML 이스케이프 규칙을 사용했습니다.

Query

WITH formats AS
(
 SELECT * FROM system.formats
 ORDER BY rand()
 LIMIT 5
)
SELECT * FROM formats
FORMAT Template
SETTINGS
 format_template_row_format='|`${0:XML}`|',
 format_template_resultset_format='|ClickHouse Formats|\n|---|\n${data}\n'

보세요! 이제 마크다운 표를 만들 때 그 많은 |와 -를 일일이 직접 추가하는 수고를 덜었습니다:

Response

|ClickHouse Formats|
|---|
|`BSONEachRow`|
|`CustomSeparatedWithNames`|
|`Prometheus`|
|`DWARF`|
|`Avro`|

​설명

​설정 및 이스케이프 규칙

​format_template_row

​format_template_rows_between_delimiter

​format_template_resultset

​인라인 지정

​사용 예시

​데이터 조회

​데이터 삽입

​인라인 지정

설명

설정 및 이스케이프 규칙

format_template_row

format_template_rows_between_delimiter

format_template_resultset

인라인 지정

사용 예시

데이터 조회

데이터 삽입

인라인 지정