url

url

url 함수는 주어진 format과 structure로 URL에서 테이블을 만드는 테이블 함수예요. url 함수는 URL 테이블의 데이터에 대한 SELECT 및 INSERT 쿼리에서 사용할 수 있어요.

출처: 문서

본문

구문(Syntax)

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

인자(Parameters)

인자 (Parameter) 설명 (Description)
URL 백엔드를 선택하는 스킴(scheme)이 있는 단일 따옴표 URL. http/https(또는 인식되지 않는) URL은 GET 또는 POST 요청(SELECT 또는 INSERT 쿼리에 각각 해당)을 받는 서버 주소예요. 인식되는 비-HTTP 스킴(file://, s3://, az://, hdfs://, …)은 일치하는 테이블 함수로 위임됩니다 — URL 스킴별 위임 참고. 타입: String.
format 데이터의 형식(Format). 타입: String.
structure 'UserID UInt64, Name String' 형식의 테이블 구조. 컬럼 이름과 타입을 결정해요. 타입: String.
headers 'headers('key1'='value1', 'key2'='value2')' 형식의 헤더. HTTP 호출에 헤더를 설정할 수 있어요.

반환 값(Returned value)

지정된 형식과 구조를 가지며 정의된 URL의 데이터를 담은 테이블.

예시(Examples)

CSV 형식으로 응답하는 HTTP 서버에서 String 및 UInt32 타입 컬럼을 포함한 테이블의 처음 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 스킴별 위임 (Dispatching by URL scheme)

url 함수는 다른 파일·객체 저장소 테이블 함수 위에 있는 통합 래퍼 역할을 해요. URL 스킴에 따라 올바른 백엔드로 위임합니다. 이를 통해 단일하고 통일된 구문으로 지원되는 어떤 위치에서든 읽을 수 있어요.

스킴 (Scheme) 위임 대상 (Dispatches to)
http, https (및 인식되지 않는 스킴) URL 엔진 자체 (HTTP GET/POST)
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, …)은 지역별이라 기본 엔드포인트 매핑이 없으므로, cos://… URL은 인식되지 않는 스킴으로 취급되어 오류로 보고됩니다. 그런 백엔드에는 (필요 시 url_scheme_mappers를 설정한) s3 함수를 직접 사용하세요. 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 호출은 쿼리를 받은 노드에서 읽힙니다: parallel_replicas_for_cluster_engines 팬아웃이 적용되지 않아요. 읽기를 레플리카에 분산하려면 해당 클러스터 함수를 직접 사용하세요.

URL 안의 글로브 (Globs in URL)

{ } 안의 패턴은 샤드 집합을 만들거나 장애 조치(failover) 주소를 지정하는 데 사용돼요. 지원되는 패턴 유형과 예시는 remote 함수 설명을 참고하세요. 패턴 안의 | 문자는 장애 조치 주소 지정에 사용됩니다. 패턴에 나열된 순서대로 반복됩니다. 생성되는 주소의 개수는 glob_expansion_max_elements 설정으로 제한돼요. URL 경로의 경로 글로브 구문(*, {a,b}, {N..M}, ** 등)은 경로 안의 글로브 (Globs in path)를 참고하세요. ?는 URL에서 쿼리 문자열을 시작하므로 경로 구성 요소의 와일드카드로 쓸 수 없는 점에 주의하세요.

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

url과 URL 테이블 엔진의 경우, ClickHouse는 HTTP 인덱스 페이지(HTML 또는 일반 텍스트)를 가져와 응답 본문에서 URL을 추출해 와일드카드를 확장할 수 있어요. 이를 통해 서버가 디렉터리 목록을 노출할 때 /**/ 같은 패턴을 지원합니다. 참고:

  • 상대 URL은 인덱스 페이지 URL을 기준으로 해석됩니다.
  • URL 템플릿은 인덱스 페이지를 가져오기 전에 확장되며, 쉼표·숫자 범위 샤드 확장과 경로 구성 요소 밖의 | 장애 조치 옵션을 포함해요.
  • 경로 구성 요소 안의 | 장애 조치 패턴은 HTTP 인덱스 페이지 확장에서 지원되지 않아요.
  • 와일드카드 매칭은 URL 경로 구성 요소에 적용됩니다.
  • 나열된 URL에 이미 쿼리 문자열이나 프래그먼트가 있으면 소스 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_url_wildcard_from_index_pages = 1;

가상 컬럼 (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)).

use_hive_partitioning 설정

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

예시(Example)

Hive 스타일 파티셔닝으로 만들어진 가상 컬럼 사용하기

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

상대 URL 해석 (Resolving relative URLs)

url_base 설정을 사용하면 url 함수에 상대 URL을 전달할 수 있어요. url_base가 설정되어 있고 함수 인자가 상대 참조면 RFC 3986에 따라 기준 URL에 대해 해석됩니다. 해석 규칙:

  • 경로 상대 (Path-relative) (예: 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가 됩니다. 점 세그먼트(./과 ../)는 정규화됩니다.
  • 호스트 상대 (Host-relative) (예: /test/data.csv): 기준 URL의 스킴과 호스트를 사용해 해석됨.
  • 스킴 상대 (Scheme-relative) (예: //other.com/test/data.csv): 기준 URL의 스킴을 사용해 해석됨.
  • 쿼리 전용 (Query-only) (예: ?x=1): 전체 기준 경로에 추가되며 기존 쿼리나 프래그먼트를 교체함.
  • 프래그먼트 전용 (Fragment-only) (예: #frag): 기준 URL에 추가되며 쿼리는 유지하고 기존 프래그먼트를 교체함.
  • 빈 값 (Empty): 프래그먼트 없이 기준 URL을 반환함.
  • 절대 URL (Absolute URL): 변경 없이 그대로 통과됨; url_base는 무시됩니다. URL은 scheme://로 시작할 때만 절대 URL로 간주됩니다: RFC 3986이 스킴 report를 가진 절대 URI로 파싱할 첫 경로 세그먼트에 콜론이 있는 이름(예: report:2026.csv)은, 그런 이름은 사용 가능한 URL이 아니므로 대신 경로 상대 참조로 해석됩니다.
  • 스킴 전용 기준 (Scheme-only base) (예: file://): 경로 상대 URL이 기준에 직접 추가됨: file:// + data.csv = file://data.csv. 이는 file:// 스킴에 대해 user_files 디렉터리(clickhouse-local에서는 현재 디렉터리) 기준 상대 경로를 의미해요. 이 경우 점 세그먼트는 그대로 유지됩니다.

예시(Example)

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

저장소 설정 (Storage Settings)

  • engine_url_skip_empty_files — 읽기 중 빈 파일을 건너뛸 수 있게 함. 기본값은 비활성.
  • enable_url_encoding — uri에서 경로의 디코딩/인코딩을 켜거나 끔. 기본값은 활성.
  • url_base — url 함수에 전달된 상대 URL을 해석하기 위한 기준 URL.

권한 (Permissions)

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

더 알아보기 (Learn more)