본문으로 바로가기
본문으로 바로가기

url 테이블 함수

url 함수는 지정된 format 및 structure를 사용하여 URL로부터 테이블을 생성합니다.

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

구문​

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

매개변수​

ParameterDescription
URLGET 또는 POST 요청을 수신할 수 있는, 작은따옴표로 감싼 HTTP 또는 HTTPS 서버 주소입니다 (SELECT 또는 INSERT 쿼리에 각각 해당). 형식: String.
format데이터의 형식입니다. 형식: String.
structure'UserID UInt64, Name String' 형식의 테이블 구조입니다. 컬럼 이름과 타입을 결정합니다. 형식: String.
headers'headers('key1'='value1', 'key2'='value2')' 형식의 헤더입니다. HTTP 호출에 사용할 헤더를 설정할 수 있습니다.

반환 값​

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

예시​

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의 글롭 패턴​

중괄호 { } 안의 패턴은 세그먼트 집합을 생성하거나 장애 조치(failover) 주소를 지정하는 데 사용됩니다. 지원되는 패턴 유형과 예시는 remote 함수 설명을 참조하십시오. 패턴 내부의 문자 |는 장애 조치 주소를 지정하는 데 사용됩니다. 이 주소들은 패턴에 나열된 순서대로 차례로 사용됩니다. 생성되는 주소 개수는 glob_expansion_max_elements 설정에 의해 제한됩니다.

가상 컬럼​

  • _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는 무시됩니다.

예시

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 이상이어야 합니다.