메인 콘텐츠로 건너뛰기
Query API endpoint 기능을 사용하면 ClickHouse Cloud 콘솔에 저장된 모든 SQL 쿼리로부터 API 엔드포인트를 직접 생성할 수 있습니다. 네이티브 드라이버로 ClickHouse Cloud 서비스에 연결하지 않아도 HTTP를 통해 API 엔드포인트에 액세스하여 저장된 쿼리를 실행할 수 있습니다.

​
사전 요구 사항

계속하기 전에 다음 항목이 준비되어 있는지 확인하십시오:
  • 적절한 권한이 부여된 API Key
  • 관리자 Console 역할
아직 없다면 이 가이드를 따라 API Key를 생성할 수 있습니다.
최소 권한API 엔드포인트를 쿼리하려면 API Key에 Query Endpoints 서비스 액세스가 포함된 Member 조직 역할이 필요합니다. 데이터베이스 역할은 엔드포인트를 생성할 때 구성됩니다.
1

​
저장된 쿼리 만들기

이미 저장된 쿼리가 있으면 이 단계는 건너뛰어도 됩니다.새 쿼리 탭을 여십시오. 예시로는 약 45억 개의 레코드가 포함된 youtube 데이터셋을 사용하겠습니다. “Create table” 섹션의 단계에 따라 Cloud 서비스에 테이블을 생성하고 데이터를 삽입하십시오.
행 수를 LIMIT로 제한예시 데이터셋 튜토리얼에서는 46억 5천만 개의 행을 삽입하므로 시간이 다소 걸릴 수 있습니다. 이 가이드에서는 LIMIT 절을 사용해 더 적은 양의 데이터를 삽입하는 것을 권장합니다. 예를 들어 1천만 개의 행만 삽입할 수 있습니다.
예시 쿼리에서는 사용자가 입력한 year 매개변수를 기준으로 동영상당 평균 조회수가 높은 상위 10명의 업로더를 반환합니다.
WITH sum(view_count) AS view_sum,
  round(view_sum / num_uploads, 2) AS per_upload
SELECT
  uploader,
  count() AS num_uploads,
  formatReadableQuantity(view_sum) AS total_views,
  formatReadableQuantity(per_upload) AS views_per_video
FROM
  youtube
WHERE
  toYear(upload_date) = {year: UInt16}
GROUP BY uploader
ORDER BY per_upload desc
  LIMIT 10
이 쿼리에는 위 코드 조각에서 강조 표시된 매개변수(year)가 포함되어 있습니다. 쿼리 매개변수는 { } 안에 매개변수 유형과 함께 지정할 수 있습니다. SQL 콘솔 쿼리 편집기는 ClickHouse 쿼리 매개변수 표현식을 자동으로 감지하고 각 매개변수에 대한 입력 필드를 제공합니다.이제 SQL Editor 오른쪽의 쿼리 변수 입력 상자에 연도 2010을 입력하여 쿼리가 정상적으로 동작하는지 빠르게 확인해 보겠습니다:다음으로 쿼리를 저장합니다:저장된 쿼리에 관한 자세한 내용은 “Saving a query” 섹션에서 확인할 수 있습니다.
2

​
Query API endpoint 구성

쿼리 보기에서 Share 버튼을 클릭한 다음 API Endpoint를 선택하면 Query API endpoint를 직접 구성할 수 있습니다. 그러면 어떤 API Key가 엔드포인트에 접근할 수 있는지 지정하라는 안내가 표시됩니다:API Key를 선택한 후에는 다음 항목을 설정해야 합니다:
  • 쿼리 실행에 사용할 데이터베이스 역할 선택 (Full access, Read only 또는 Create a custom role)
  • CORS(Cross-Origin Resource Sharing) 허용 도메인 지정
이 옵션을 선택하면 Query API endpoint가 자동으로 프로비저닝됩니다.테스트 요청을 보낼 수 있도록 예시 curl 명령도 표시됩니다:편의를 위해 인터페이스에 표시되는 curl 명령을 아래에도 제공합니다:
curl -H "Content-Type: application/json" -s --user '<key_id>:<key_secret>' '<API-endpoint>?format=JSONEachRow&param_year=<value>'
3

​
Query API 매개변수

쿼리 매개변수는 {parameter_name: type} 구문으로 지정할 수 있습니다. 이러한 매개변수는 자동으로 감지되며, 예시 요청 payload에는 queryVariables 객체가 포함되어 이 객체를 통해 매개변수를 전달할 수 있습니다.
4

​
테스트 및 모니터링

Query API endpoint가 생성되면 curl 또는 다른 HTTP 클라이언트를 사용해 정상적으로 동작하는지 테스트할 수 있습니다:첫 번째 요청을 보내면 Share 버튼 바로 오른쪽에 새 버튼이 즉시 나타납니다. 이 버튼을 클릭하면 쿼리에 대한 모니터링 데이터가 포함된 플라이아웃이 열립니다:

​
구현 세부 사항

이 엔드포인트는 저장된 Query API endpoint에서 쿼리를 실행합니다. 여러 버전, 유연한 응답 포맷, 매개변수화된 쿼리, 선택적 스트리밍 응답(버전 2만 지원)을 지원합니다. 엔드포인트: 
GET /query-endpoints/{queryEndpointId}/run
POST /query-endpoints/{queryEndpointId}/run

​
HTTP 메서드

메서드사용 사례매개변수
GET매개변수가 있는 단순 쿼리URL 매개변수(?param_name=value)를 통해 쿼리 변수를 전달합니다
POST복잡한 쿼리이거나 요청 본문을 사용하는 경우요청 본문(queryVariables 객체)으로 쿼리 변수를 전달합니다
GET를 사용하는 경우:
  • 복잡하게 중첩된 데이터가 없는 단순 쿼리
  • 매개변수를 URL 인코딩하기 쉬운 경우
  • 캐싱이 HTTP GET의 의미 체계로 이점을 얻을 수 있는 경우
POST를 사용하는 경우:
  • 복잡한 쿼리 변수(배열, 객체, 긴 문자열)
  • 보안 또는 개인정보 보호를 위해 요청 본문을 사용하는 것이 바람직한 경우
  • 스트리밍 파일 업로드 또는 대용량 데이터

​
인증

필수: 예 메서드: OpenAPI Key/Secret 기반 Basic Auth 권한: 쿼리 엔드포인트에 대한 적절한 권한

​
요청 구성

​
URL 매개변수

매개변수필수설명
queryEndpointId예실행할 쿼리 엔드포인트의 고유 식별자

​
쿼리 매개변수

매개변수필수설명예시
format아니요응답 포맷(모든 ClickHouse 포맷 지원)?format=JSONEachRow
param_:name아니요요청 본문이 스트림일 때 사용하는 쿼리 변수입니다. :name을 변수 이름으로 바꾸십시오?param_year=2024
request_timeout아니요쿼리 타임아웃(밀리초, 기본값: 30000)?request_timeout=60000
:clickhouse_setting아니요지원되는 모든 ClickHouse 설정?max_threads=8

​
헤더

헤더필수 여부설명값
x-clickhouse-endpoint-version아니요endpoint 버전을 지정합니다1 또는 2 (기본값: 마지막으로 저장된 버전)
x-clickhouse-endpoint-upgrade아니요endpoint 버전 업그레이드를 실행합니다(버전 헤더와 함께 사용)업그레이드 시 1

​
요청 본문

​
매개변수

매개변수유형필수설명
queryVariables객체아니요쿼리에서 사용할 변수
formatstring아니요응답 포맷

​
지원되는 포맷

버전지원 포맷
버전 2ClickHouse에서 지원하는 모든 포맷
버전 1 (제한적)TabSeparated
TabSeparatedWithNames
TabSeparatedWithNamesAndTypes
JSON
JSONEachRow
CSV
CSVWithNames
CSVWithNamesAndTypes

​
응답

​
성공

상태: 200 OK 쿼리가 정상적으로 실행되었습니다.

​
오류 코드

상태 코드설명
400 Bad Request요청 형식이 올바르지 않습니다
401 Unauthorized인증 정보가 없거나 필요한 권한이 없습니다
404 Not Found지정한 쿼리 엔드포인트를 찾을 수 없습니다

​
오류 처리 모범 사례

  • 요청에 유효한 인증 자격 증명이 포함되어 있는지 확인하세요
  • 전송하기 전에 queryEndpointId와 queryVariables를 검증하세요
  • 적절한 오류 메시지와 함께 안정적으로 오류를 처리하도록 구현하세요

​
엔드포인트 버전 업그레이드

버전 1에서 버전 2로 업그레이드하려면 다음을 수행하세요.
  1. x-clickhouse-endpoint-upgrade 헤더를 1로 설정해 포함합니다
  2. x-clickhouse-endpoint-version 헤더를 2로 설정해 포함합니다
이렇게 하면 다음과 같은 버전 2 기능을 사용할 수 있습니다.
  • 모든 ClickHouse 포맷 지원
  • 응답 스트리밍 capability
  • 향상된 성능 및 기능

​
예시

​
기본 요청

Query API 엔드포인트 SQL: 
SELECT database, name AS num_tables FROM system.tables LIMIT 3;

​
버전 1

curl -X POST 'https://console-api.clickhouse.cloud/.api/query-endpoints/<endpoint id>/run' \
--user '<openApiKeyId:openApiKeySecret>' \
-H 'Content-Type: application/json' \
-d '{ "format": "JSONEachRow" }'

​
버전 2

curl 'https://console-api.clickhouse.cloud/.api/query-endpoints/<endpoint id>/run?format=JSONEachRow' \
--user '<openApiKeyId:openApiKeySecret>' \
-H 'x-clickhouse-endpoint-version: 2'
응답
{"database":"INFORMATION_SCHEMA","num_tables":"COLUMNS"}
{"database":"INFORMATION_SCHEMA","num_tables":"KEY_COLUMN_USAGE"}
{"database":"INFORMATION_SCHEMA","num_tables":"REFERENTIAL_CONSTRAINTS"}

​
쿼리 변수와 JSONCompactEachRow 포맷 버전 2를 사용한 요청

Query API 엔드포인트 SQL: 
SELECT name, database FROM system.tables WHERE match(name, {tableNameRegex: String}) AND database = {database: String};

curl 'https://console-api.clickhouse.cloud/.api/query-endpoints/<endpoint id>/run?format=JSONCompactEachRow&param_tableNameRegex=query.*&param_database=system' \
--user '<openApiKeyId:openApiKeySecret>' \
-H 'x-clickhouse-endpoint-version: 2'
응답
["query_cache", "system"]
["query_log", "system"]
["query_views_log", "system"]

​
쿼리 변수에 배열이 포함되어 있고 테이블에 데이터를 삽입하는 요청

테이블 SQL: 
CREATE TABLE default.t_arr
(
    `arr` Array(Array(Array(UInt32)))
)
ENGINE = MergeTree
ORDER BY tuple()
Query API 엔드포인트 SQL: 
INSERT INTO default.t_arr VALUES ({arr: Array(Array(Array(UInt32)))});

curl -X POST 'https://console-api.clickhouse.cloud/.api/query-endpoints/<endpoint id>/run' \
--user '<openApiKeyId:openApiKeySecret>' \
-H 'Content-Type: application/json' \
-H 'x-clickhouse-endpoint-version: 2' \
-d '{
  "queryVariables": {
    "arr": [[[12, 13, 0, 1], [12]]]
  }
}'

​
ClickHouse 설정 max_threads를 8로 지정한 요청

Query API 엔드포인트 SQL: 
SELECT * FROM system.tables;

curl 'https://console-api.clickhouse.cloud/.api/query-endpoints/<endpoint id>/run?max_threads=8' \
--user '<openApiKeyId:openApiKeySecret>' \
-H 'x-clickhouse-endpoint-version: 2'

​
응답을 요청해 스트림으로 파싱하기`

Query API 엔드포인트 SQL: 
SELECT name, database FROM system.tables;

async function fetchAndLogChunks(
  url: string,
  openApiKeyId: string,
  openApiKeySecret: string
) {
  const auth = Buffer.from(`${openApiKeyId}:${openApiKeySecret}`).toString(
    "base64"
  );

  const headers = {
    Authorization: `Basic ${auth}`,
    "x-clickhouse-endpoint-version": "2",
  };

  const response = await fetch(url, {
    headers,
    method: "POST",
    body: JSON.stringify({ format: "JSONEachRow" }),
  });

  if (!response.ok) {
    console.error(`HTTP error! Status: ${response.status}`);
    return;
  }

  const reader = response.body as unknown as Readable;
  reader.on("data", (chunk) => {
    console.log(chunk.toString());
  });

  reader.on("end", () => {
    console.log("Stream ended.");
  });

  reader.on("error", (err) => {
    console.error("Stream error:", err);
  });
}

const endpointUrl =
  "https://console-api.clickhouse.cloud/.api/query-endpoints/<endpoint id>/run?format=JSONEachRow";
const openApiKeyId = "<myOpenApiKeyId>";
const openApiKeySecret = "<myOpenApiKeySecret>";
// 사용 예시
fetchAndLogChunks(endpointUrl, openApiKeyId, openApiKeySecret).catch((err) =>
  console.error(err)
);
출력
> npx tsx index.ts
> {"name":"COLUMNS","database":"INFORMATION_SCHEMA"}
> {"name":"KEY_COLUMN_USAGE","database":"INFORMATION_SCHEMA"}
...
> Stream ended.

​
파일에서 스트림을 테이블에 삽입하기

다음 내용으로 ./samples/my_first_table_2024-07-11.csv 파일을 생성하세요: 
"user_id","json","name"
"1","{""name"":""John"",""age"":30}","John"
"2","{""name"":""Jane"",""age"":25}","Jane"
테이블 생성 SQL: 
create table default.my_first_table
(
    user_id String,
    json String,
    name String,
) ENGINE = MergeTree()
ORDER BY user_id;
Query API 엔드포인트 SQL: 
INSERT INTO default.my_first_table

cat ./samples/my_first_table_2024-07-11.csv | curl --user '<openApiKeyId:openApiKeySecret>' \
                                                   -X POST \
                                                   -H 'Content-Type: application/octet-stream' \
                                                   -H 'x-clickhouse-endpoint-version: 2' \
                                                   "https://console-api.clickhouse.cloud/.api/query-endpoints/<endpoint id>/run?format=CSV" \
                                                   --data-binary @-
마지막 수정일 2026년 6월 10일