URL 테이블 엔진

URL 엔진은 원격 HTTP/HTTPS 서버에서 데이터를 쿼리하고, 그 서버로 데이터를 쿼리해요. File 엔진과 유사하며, URL 스킴에 따라 올바른 백엔드로 위임하는 통합 래퍼입니다. INSERT와 SELECT 쿼리는 각각 POST와 GET 요청으로 변환됩니다.

출처: 문서

본문

원격 HTTP/HTTPS 서버에서/으로 데이터를 쿼리합니다. 이 엔진은 File 엔진과 유사해요.

URL 엔진은 URL 스킴에 따라 올바른 백엔드로 위임하는 통합 래퍼이기도 합니다. 따라서 인식된 비-HTTP 스킴은 일치하는 엔진에 위임됩니다 — 아래 "URL 스킴에 따른 위임 (Dispatching by URL scheme)"을 참조하세요.

구문: URL(URL [,Format] [,CompressionMethod])

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

압축을 활성화하려면 먼저 URL 매개변수가 가리키는 원격 HTTP 엔드포인트가 해당 압축 알고리즘을 지원하는지 확인하세요.

지원되는 CompressionMethod는 다음 중 하나여야 합니다:

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

CompressionMethod가 지정되지 않으면 기본값은 auto입니다. 이는 ClickHouse가 URL 매개변수의 접미사에서 압축 방법을 자동으로 감지한다는 뜻입니다. 접미사가 위에 나열된 압축 방법 중 하나와 일치하면 해당 압축이 적용되고, 그렇지 않으면 압축이 활성화되지 않습니다.

예를 들어 URL('http://localhost/test.gzip')이라는 엔진 표현식에는 gzip 압축 방법이 적용되지만, URL('http://localhost/test.fr')에는 압축이 활성화되지 않습니다. 접미사 fr이 위의 압축 방법과 일치하지 않기 때문입니다.

URL 스킴에 따른 위임 (Dispatching by URL scheme)

URL 엔진은 다른 파일 및 객체 스토리지 엔진 위의 통합 래퍼입니다. URL 스킴에 따라 올바른 백엔드로 위임합니다. http/https(및 인식되지 않은 스킴)는 URL 엔진 자체가 처리하고, file://는 File 엔진이, s3://, gs://, gcs://, oss://는 S3 엔진이, az://, azure://, abfss://, abfs://는 AzureBlobStorage 엔진이, hdfs://는 HDFS 엔진이 처리합니다.

S3 URI 매퍼가 추가 구성 없이 구체적인 엔드포인트로 해석하는 S3 스킴(s3, 그리고 gs/gcs/oss)만 위임됩니다. 다른 S3 호환 벤더 스킴(cos, obs, eos, …)은 지역별(region-specific)이고 기본 엔드포인트 매핑이 없으므로, 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);

사용 (Usage)

INSERT와 SELECT 쿼리는 각각 POST와 GET 요청으로 변환됩니다. POST 요청을 처리하려면 원격 서버가 Chunked transfer encoding을 지원해야 합니다.

max_http_get_redirects 설정을 사용하여 최대 HTTP GET 리다이렉트 홉 수를 제한할 수 있어요.

HTTP 인덱스 페이지와 와일드카드 (Wildcards with HTTP index pages)

allow_url_wildcard_from_index_pages가 활성화되면 URL 테이블 엔진은 HTTP 인덱스 페이지를 가져와서 링크를 추출하여 와일드카드를 확장할 수 있습니다. 이것은 url 테이블 함수와 동일한 메커니즘입니다. 확장은 각 가져온 인덱스 페이지에 대해 max_http_index_page_size로, 재귀 디렉토리 탐색에 대해 url_wildcard_max_directories_to_read로 제한됩니다.

예시 (Example)

서버에 url_engine_table 테이블을 만듭니다:

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

표준 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

데이터를 요청합니다:

SELECT * FROM url_engine_table

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

구현 세부사항 (Details of Implementation)

읽기와 쓰기는 병렬로 수행될 수 있어요
지원하지 않음:
- ALTER 및 SELECT...SAMPLE 연산.
- 인덱스(Indexes).
- 레플리케이션(Replication).

가상 컬럼 (Virtual columns)

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

상대 URL 해석 (Resolving relative URLs)

url_base 설정을 사용하면 URL 엔진에서 상대 URL을 사용할 수 있어요. url_base가 설정되면 엔진에 전달된 URL은 RFC 3986에 따라 그것을 기준으로 해석됩니다. 해석 규칙에 대한 전체 설명은 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;

스토리지 설정 (Storage settings)

engine_url_skip_empty_files - 읽는 동안 빈 파일을 건너뛸 수 있게 합니다. 기본적으로 비활성화됨.
enable_url_encoding - uri에서 경로 디코딩/인코딩을 활성화/비활성화합니다. 기본적으로 활성화됨.
url_base - 엔진에 전달된 상대 URL을 해석하기 위한 기본 URL.

URL 테이블 엔진