url

url 함수는 지정된 포맷과 구조를 사용해 URL에서 테이블을 생성합니다.

url 함수는 URL 테이블의 데이터에 대한 SELECT 및 INSERT 쿼리에서 사용할 수 있습니다.

구문

url(URL [,format] [,structure] [,headers])

매개변수

매개변수	설명
`URL`	스킴에 따라 백엔드를 선택하는 작은따옴표로 묶인 URL입니다. `http`/`https`(또는 인식되지 않는) URL은 `GET` 또는 `POST` 요청을 받을 수 있는 서버 주소이며(`SELECT` 또는 `INSERT` 쿼리에 각각 해당), 인식되는 비HTTP 스킴(`file://`, `s3://`, `az://`, `hdfs://`, …)은 해당 테이블 함수로 전달됩니다. Dispatching by URL scheme를 참조하십시오. 유형: String.
`format`	데이터의 포맷입니다. 유형: String.
`structure`	`'UserID UInt64, Name String'` 포맷의 테이블 구조입니다. 컬럼 이름과 타입을 결정합니다. 유형: String.
`headers`	`'headers('key1'='value1', 'key2'='value2')'` 포맷의 헤더입니다. HTTP 호출에 사용할 헤더를 설정할 수 있습니다.

반환 값

지정된 포맷과 구조를 가지며, 지정된 URL의 데이터를 포함하는 테이블입니다.

예시

String 및 UInt32 타입의 컬럼이 포함된 테이블에서, CSV 포맷으로 응답하는 HTTP 서버를 통해 처음 3개 행을 가져옵니다.

SELECT * FROM url('http://127.0.0.1:12345/', CSV, 'column1 String, column2 UInt32', headers('Accept'='text/csv; charset=utf-8')) LIMIT 3;

URL에서 테이블로 데이터 삽입:

CREATE TABLE test_table (column1 String, column2 UInt32) ENGINE=Memory;
INSERT INTO FUNCTION url('http://127.0.0.1:8123/?query=INSERT+INTO+test_table+FORMAT+CSV', 'CSV', 'column1 String, column2 UInt32') VALUES ('http interface', 42);
SELECT * FROM test_table;

URL 스킴별 디스패치

url 함수는 다른 파일 및 객체 스토리지 테이블 함수 위에서 동작하는 통합 래퍼 역할을 합니다. URL 스킴에 따라 적절한 백엔드로 디스패치합니다. 이를 통해 지원되는 모든 위치에서 하나의 일관된 구문으로 읽을 수 있습니다.

스킴	디스패치 대상
`http`, `https` (및 인식되지 않는 모든 스킴)	`URL` 엔진 자체(HTTP `GET`/`POST`)
`file`	`file` 함수
`s3`, `gs`, `gcs`, `oss`	`s3` 함수
`az`, `azure`, `abfss`, `abfs`	`azureBlobStorage` 함수
`hdfs`	`hdfs` 함수

추가 구성 없이 S3 URI mapper가 구체적인 endpoint로 확인할 수 있는 S3 스킴(s3와 gs/gcs/oss)만 디스패치됩니다. 다른 S3-compatible 공급업체 스킴(cos, obs, eos, …)은 Region별로 다르고 기본 endpoint 매핑이 없으므로, cos://… URL은 인식되지 않는 스킴으로 처리되어 오류로 보고됩니다. 이러한 백엔드에는 s3 함수를 직접 사용하십시오(url_scheme_mappers 구성 필요).

file://의 경우 상대 경로(file://data.csv)는 user_files 디렉터리 내부에서 확인되며, 절대 경로(file:///home/user/data.csv)는 일반적인 경우와 마찬가지로 해당 디렉터리 내부를 가리켜야 합니다.

format, structure, compression_method 인수와 url_base 설정은 디스패치 대상과 관계없이 동일하게 동작합니다.

SELECT * FROM url('file://data.csv', CSV, 'a UInt32, b String');
SELECT * FROM url('s3://clickhouse-public-datasets/hits_compatible/hits.csv');

스킴 디스패치는 아직 urlCluster에 연결되지 않았습니다. urlCluster에 http(s)가 아닌 스킴을 전달하면 오류가 발생하며 거부됩니다. 이러한 백엔드에는 대신 해당 클러스터 함수(s3Cluster, azureBlobStorageCluster, hdfsCluster, …)를 사용하십시오.

URL의 글롭 패턴

{ } 안의 패턴은 세그먼트 집합을 생성하거나 장애 조치 주소를 지정하는 데 사용됩니다. 지원되는 패턴 유형과 예시는 remote 함수 설명을 참조하십시오. 패턴 안의 문자 |는 장애 조치 주소를 지정하는 데 사용됩니다. 주소는 패턴에 나열된 순서대로 순회됩니다. 생성되는 주소 수는 glob_expansion_max_elements 설정에 의해 제한됩니다. URL 경로의 글롭 패턴 구문(*, {a,b}, {N..M}, ** 등)은 경로의 글롭 패턴을 참조하십시오. URL에서 ?는 쿼리 문자열의 시작을 나타내므로 경로 구성 요소에서는 와일드카드로 사용할 수 없습니다.

HTTP 인덱스 페이지를 사용한 와일드카드

url 및 URL 테이블 엔진에서 ClickHouse는 HTTP 인덱스 페이지(HTML 또는 plaintext)를 가져오고 응답 본문에서 URL을 추출하여 와일드카드를 확장할 수 있습니다. 이를 통해 서버가 디렉터리 목록을 제공할 때 /**/와 같은 패턴을 사용할 수 있습니다.

참고:

상대 URL은 인덱스 페이지 URL을 기준으로 해석됩니다.
URL 템플릿은 인덱스 페이지를 가져오기 전에 확장되며, 여기에는 쉼표 및 숫자 범위 세그먼트 확장과 경로 구성 요소 외부의 | 장애 조치 옵션이 포함됩니다.
경로 구성 요소 내부의 | 장애 조치 패턴은 HTTP 인덱스 페이지 확장에서는 지원되지 않습니다.
와일드카드 매칭은 URL 경로 구성 요소에 적용됩니다.
목록에 있는 URL에 이미 쿼리 문자열(query string) 또는 프래그먼트(fragment)가 포함되어 있으면 소스 URL의 값보다 우선합니다. 그렇지 않으면 소스 URL의 쿼리 문자열과 프래그먼트가 사용됩니다.
빈 목록도 허용되지만, 인덱스 페이지에 대한 HTTP 오류(예: 404)는 예외를 발생시킵니다.
최대 인덱스 페이지 크기는 max_http_index_page_size로 제한됩니다.
재귀 확장 중 읽을 수 있는 최대 디렉터리 수는 url_wildcard_max_directories_to_read로 제한됩니다.

예시:

SELECT count()
FROM url('https://ftp.gnu.org/gnu/wget/wget-1.21*.tar.gz', 'RawBLOB')
SETTINGS max_threads = 1, allow_experimental_url_wildcard_from_index_pages = 1;

가상 컬럼

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

use_hive_partitioning 설정

use_hive_partitioning 설정을 1로 지정하면 ClickHouse가 경로(/name=value/)에서 Hive 스타일 파티셔닝을 감지하고, 쿼리에서 파티션 컬럼을 가상 컬럼으로 사용할 수 있습니다. 이러한 가상 컬럼은 파티셔닝된 경로에 있는 이름과 동일한 이름을 가집니다.

예시

Hive 스타일 파티셔닝으로 생성된 가상 컬럼 사용

SELECT * FROM url('http://data/path/date=*/country=*/code=*/*.parquet') WHERE date > '2020-01-01' AND country = 'Netherlands' AND code = 42;

상대 URL 해석

url_base 설정을 사용하면 url 함수에 상대 URL을 전달할 수 있습니다. url_base가 설정되어 있고 함수 인수가 상대 참조인 경우 RFC 3986에 따라 기준 URL을 기준으로 이를 해석합니다.

해석 규칙은 다음과 같습니다:

경로 상대 (예: data.csv): 기준 URL 경로에 머지되며 기준 경로에서 마지막 / 뒤의 모든 내용이 대체됩니다. 끝의 슬래시 유무가 중요합니다. https://example.com/dir/ + data.csv는 https://example.com/dir/data.csv가 되지만, https://example.com/dir + data.csv는 https://example.com/data.csv가 됩니다. 점 세그먼트(./ 및 ../)는 정규화됩니다.
호스트 상대 (예: /test/data.csv): 기준 URL의 스킴과 호스트를 사용해 해석합니다.
스킴 상대 (예: //other.com/test/data.csv): 기준 URL의 스킴을 사용해 해석합니다.
쿼리만 있는 경우 (예: ?x=1): 전체 기준 경로 뒤에 추가되며 기존 쿼리나 프래그먼트는 대체됩니다.
프래그먼트만 있는 경우 (예: #frag): 기준 URL 뒤에 추가되며 쿼리는 유지되고 기존 프래그먼트는 대체됩니다.
비어 있는 경우: 프래그먼트가 없는 기준 URL을 반환합니다.
절대 URL: 변경 없이 그대로 전달되며 url_base는 무시됩니다. URL은 scheme://로 시작하는 경우에만 절대 URL로 간주됩니다. 첫 번째 경로 세그먼트에 콜론이 포함된 이름(예: report:2026.csv)은 RFC 3986에서 스킴이 report인 절대 URI로 파싱되지만, 이러한 이름은 사용할 수 있는 URL이 아니므로 대신 경로 상대 참조로 해석됩니다.
스킴만 있는 기준 URL (예: file://): 경로 상대 URL은 기준 URL에 직접 추가됩니다. file:// + data.csv = file://data.csv이며, file:// 스킴에서는 user_files 디렉터리(clickhouse-local의 현재 디렉터리)를 기준으로 하는 경로를 의미합니다. 이 경우 점 세그먼트는 있는 그대로 유지됩니다.

예시

SET url_base = 'https://raw.githubusercontent.com/ClickHouse/ClickHouse/master/';
SELECT * FROM url('tests/queries/0_stateless/data_csv/data.csv', CSV) LIMIT 3;

스토리지 설정

engine_url_skip_empty_files - 읽는 중 비어 있는 파일을 건너뛸 수 있습니다. 기본적으로 비활성화되어 있습니다.
enable_url_encoding - URI의 경로 인코딩/디코딩을 활성화하거나 비활성화할 수 있습니다. 기본적으로 활성화되어 있습니다.
url_base - url 함수에 전달된 상대 URL을 해석하는 데 사용하는 기준 URL입니다.

권한

url 함수는 CREATE TEMPORARY TABLE 권한이 필요합니다. 따라서 readonly = 1로 설정된 사용자에게는 작동하지 않습니다. 최소 readonly = 2가 필요합니다.

가상 컬럼