URL 테이블 엔진 - ClickHouse Documentation

원격 HTTP/HTTPS 서버에서 데이터를 조회하거나 서버로 전송합니다. 이 엔진은 File 엔진과 유사합니다. URL 엔진은 URL 스킴에 따라 올바른 백엔드로 디스패치하는 통합 래퍼이기도 하므로, 인식 가능한 비HTTP 스킴은 해당 엔진으로 위임됩니다. 아래의 URL 스킴별 디스패치을 참조하십시오. 구문: URL(URL [,Format] [,CompressionMethod])

URL 매개변수는 Uniform Resource Locator 구조를 따라야 합니다. http/https URL(기본 백엔드)의 경우 HTTP 또는 HTTPS를 사용하는 서버를 가리켜야 하며, 서버에서 응답을 받기 위해 추가 헤더는 필요하지 않습니다. 인식 가능한 비HTTP 스킴(file://, s3://, az://, hdfs://, …)이 있는 URL은 대신 해당 엔진으로 위임됩니다. 아래의 URL 스킴별 디스패치을 참조하십시오.
Format은 ClickHouse가 SELECT 쿼리에서 사용할 수 있어야 하며, 필요한 경우 INSERTs에서도 사용할 수 있어야 합니다. 지원되는 포맷의 전체 목록은 Formats를 참조하십시오. 이 인수를 지정하지 않으면 ClickHouse가 URL 매개변수의 접미사를 기반으로 포맷을 자동으로 감지합니다. URL 매개변수의 접미사가 지원되는 포맷과 일치하지 않으면 테이블 생성에 실패합니다. 예를 들어 엔진 표현식 URL('http://localhost/test.json')에는 JSON 포맷이 적용됩니다.
CompressionMethod는 HTTP 본문을 압축할지 여부를 나타냅니다. 압축이 활성화되면 URL 엔진이 보내는 HTTP 패킷에는 어떤 압축 방식이 사용되었는지 나타내는 ‘Content-Encoding’ 헤더가 포함됩니다.

압축을 활성화하기 전에 먼저 URL 매개변수가 가리키는 원격 HTTP 엔드포인트가 해당 압축 알고리즘을 지원하는지 확인하십시오. 지원되는 CompressionMethod는 다음 중 하나여야 합니다.

gzip or gz
deflate
brotli or br
lzma or xz
zstd or zst
lz4
bz2
snappy
none
auto

CompressionMethod를 지정하지 않으면 기본값은 auto입니다. 즉, ClickHouse가 URL 매개변수의 접미사를 기반으로 압축 방식을 자동으로 감지합니다. 접미사가 위에 나열된 압축 방식 중 하나와 일치하면 해당 압축이 적용되고, 그렇지 않으면 압축이 적용되지 않습니다. 예를 들어 엔진 표현식 URL('http://localhost/test.gzip')에는 gzip 압축 방식이 적용되지만, URL('http://localhost/test.fr')의 경우 접미사 fr이 위의 어떤 압축 방식과도 일치하지 않으므로 압축이 적용되지 않습니다.

URL 스킴별 디스패치

URL 엔진은 다른 파일 및 객체 스토리지 엔진 위에 구축된 통합 wrapper로, URL 스킴에 따라 적절한 백엔드로 디스패치합니다. http/https(및 인식되지 않는 모든 스킴)는 URL 엔진 자체에서 처리하고, file://는 File 엔진이, s3://, gs://, gcs://, oss://는 S3 엔진이, az://, azure://, abfss://, abfs://는 AzureBlobStorage 엔진이, hdfs://는 HDFS 엔진이 처리합니다. 추가 구성 없이 S3 URI mapper가 구체적인 엔드포인트로 해석할 수 있는 S3 스킴(s3 및 gs/gcs/oss)만 디스패치됩니다. 그 밖의 S3-compatible 공급업체 스킴(cos, obs, eos, …)은 Region별로 달라지며 기본 엔드포인트 매핑도 없으므로, 이런 URL을 URL 엔진에 전달하면 인식되지 않는 스킴으로 간주되어 오류로 보고됩니다. 이러한 백엔드에는 S3 엔진을 직접 사용하십시오(url_scheme_mappers 구성 필요). url_base 설정은 스킴 디스패치 전에 적용되므로, 상대 참조는 먼저 base를 기준으로 해석된 뒤 해당 엔진으로 라우팅됩니다.

CREATE TABLE file_via_url (a UInt32, b String) ENGINE = URL('file://data.csv', CSV);
CREATE TABLE s3_via_url (a UInt32, b String) ENGINE = URL('s3://bucket/key.csv', CSV);

사용법

INSERT 및 SELECT 쿼리는 각각 POST 및 GET 요청으로 변환됩니다. POST 요청을 처리하려면 원격 서버에서 청크 전송 인코딩을 지원해야 합니다. max_http_get_redirects 설정을 사용하여 HTTP GET 리디렉션의 최대 홉 수를 제한할 수 있습니다.

HTTP 인덱스 페이지의 와일드카드

allow_experimental_url_wildcard_from_index_pages가 활성화되면 URL 테이블 엔진은 HTTP 인덱스 페이지를 가져와 그 안의 링크를 추출해 와일드카드를 확장할 수 있습니다. 이는 url 테이블 함수와 동일한 메커니즘입니다. 확장은 가져온 각 인덱스 페이지마다 max_http_index_page_size로 제한되며, 재귀적 디렉터리 순회는 url_wildcard_max_directories_to_read로 제한됩니다.

예시

1. 서버에 url_engine_table 테이블을 생성합니다:

CREATE TABLE url_engine_table (word String, value UInt64)
ENGINE=URL('http://127.0.0.1:12345/', CSV)

2. 표준 Python 3 도구를 사용하여 간단한 HTTP 서버를 만들고 시작하세요:

from http.server import BaseHTTPRequestHandler, HTTPServer

class CSVHTTPServer(BaseHTTPRequestHandler):
    def do_GET(self):
        self.send_response(200)
        self.send_header('Content-type', 'text/csv')
        self.end_headers()

        self.wfile.write(bytes('Hello,1\nWorld,2\n', "utf-8"))

if __name__ == "__main__":
    server_address = ('127.0.0.1', 12345)
    HTTPServer(server_address, CSVHTTPServer).serve_forever()

$ python3 server.py

3. 데이터 요청:

SELECT * FROM url_engine_table

┌─word──┬─value─┐
│ Hello │     1 │
│ World │     2 │
└───────┴───────┘

구현 세부 사항

읽기와 쓰기는 병렬로 수행할 수 있습니다.
다음은 지원되지 않습니다:
- ALTER 및 SELECT...SAMPLE 작업
- 인덱스
- 복제

가상 컬럼

_path — URL의 경로입니다. 유형: LowCardinality(String).
_file — URL 리소스의 이름입니다. 유형: LowCardinality(String).
_size — 리소스의 크기(바이트)입니다. 유형: Nullable(UInt64). 크기를 알 수 없으면 값은 NULL입니다.
_time — 파일의 최종 수정 시간입니다. 유형: Nullable(DateTime). 시간을 알 수 없으면 값은 NULL입니다.
_headers - HTTP 응답 헤더입니다. 유형: Map(LowCardinality(String), LowCardinality(String)).

상대 URL 해석

url_base 설정을 사용하면 URL 엔진에서 상대 URL을 사용할 수 있습니다. url_base가 설정되어 있으면 엔진에 전달된 URL은 RFC 3986에 따라 url_base를 기준으로 해석됩니다. 해석 규칙에 대한 전체 설명은 url 테이블 함수 문서를 참조하십시오. 예시

SET url_base = 'http://127.0.0.1:12345/';
CREATE TABLE url_engine_table (word String, value UInt64) ENGINE = URL('hello.csv', CSV);
SELECT * FROM url_engine_table;

스토리지 설정

engine_url_skip_empty_files - 읽을 때 빈 파일을 건너뛸 수 있습니다. 기본적으로 비활성화되어 있습니다.
enable_url_encoding - URI 경로의 디코딩/인코딩을 활성화하거나 비활성화할 수 있습니다. 기본적으로 활성화되어 있습니다.
url_base - 엔진에 전달된 상대 URL을 해석하기 위한 기준 URL입니다.

​URL 스킴별 디스패치

​사용법

​HTTP 인덱스 페이지의 와일드카드

​예시

​구현 세부 사항

​가상 컬럼

​상대 URL 해석

​스토리지 설정