> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-detect-table-modification.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# AI 기반 SQL 생성
> 이 가이드에서는 ClickHouse Client 또는 clickhouse-local에서 AI를 사용해 SQL 쿼리를 생성하는 방법을 설명합니다.
ClickHouse 25.7부터 [ClickHouse Client](/ko/concepts/features/interfaces/cli)와 [clickhouse-local](/ko/concepts/features/tools-and-utilities/clickhouse-local)에서 자연어 설명을 SQL 쿼리로 변환하는 [AI 기반 기능](/ko/concepts/features/interfaces/cli#ai-sql-generation)을 사용할 수 있습니다. 이 기능을 사용하면 필요한 데이터를 일반 텍스트로 설명할 수 있고, 시스템이 이를 해당 SQL 문으로 변환합니다.
이 기능은 복잡한 SQL 구문에 익숙하지 않거나 탐색적 데이터 분석을 위해 쿼리를 빠르게 생성해야 할 때 특히 유용합니다. 표준 ClickHouse 테이블에서 작동하며, 필터링, 집계, 조인을 포함한 일반적인 쿼리 패턴을 지원합니다.
다음과 같은 내장 도구/함수를 사용해 이를 수행합니다:
* `list_databases` - ClickHouse 인스턴스에서 사용할 수 있는 모든 데이터베이스를 나열합니다
* `list_tables_in_database` - 특정 데이터베이스의 모든 테이블을 나열합니다
* `get_schema_for_table` - 특정 테이블의 `CREATE TABLE` 문(스키마)을 가져옵니다
## 사전 요구 사항
Anthropic 또는 OpenAI 키를 환경 변수로 설정해야 합니다:
```bash theme={null}
export ANTHROPIC_API_KEY=your_api_key
export OPENAI_API_KEY=your_api_key
```
또는 [설정 파일을 지정할 수 있습니다](/ko/concepts/features/interfaces/cli#ai-sql-generation-configuration).
## ClickHouse SQL playground에 연결하기
[ClickHouse SQL playground](https://sql.clickhouse.com/)를 사용해 이 기능을 살펴보겠습니다.
다음 명령으로 ClickHouse SQL playground에 연결할 수 있습니다:
```bash theme={null}
clickhouse client -mn \
--host sql-clickhouse.clickhouse.com \
--secure \
--user demo --password ''
```
ClickHouse가 설치되어 있다고 가정합니다. 아직 설치하지 않았다면 [설치 가이드](/ko/get-started/setup/install)를 참조하십시오
## 자연어로 ClickHouse에 질문하기
이제 질문을 시작할 차례입니다!
텍스트를 SQL로 변환하는 기능은 사실상 일회성 쿼리 생성 도구입니다. 대화 이력을 유지하지 않으므로 질문에 가능한 한 많은 유용한 맥락을 포함하십시오. 다음 사항을 구체적으로 작성하세요:
시간 범위 또는 날짜 범위
원하는 분석 유형(평균, 합계, 순위 등)
필터링 기준
### 주택 가격이 비싼 시장 찾기
먼저 주택 가격에 대한 질문부터 해보겠습니다. SQL playground에는 영국 주택 가격 데이터셋이 포함되어 있어 AI가 이를 자동으로 찾아냅니다:
```sql theme={null}
?? Can you tell me the most expensive place to buy a house in 2021?;
```
Enter를 누르면 AI가 질문에 답하는 동안 어떤 사고 과정을 거치는지 확인할 수 있습니다.
```text theme={null}
• Starting AI SQL generation with schema discovery...
─────────────────────────────────────────────────
🧠 thinking...[INFO] Text generation successful - model: claude-3-5-sonnet-latest, response_id: msg_01QpQd35ZD8HM9QSYFZuQ8Wh
🔧 Calling: list_databases [toolu_01...]
🧠 thinking✓ list_databases completed
└─ Found 37 databases: - amazon - bluesky - country - covid - default - dns - en...
🔧 Calling: list_databases [toolu_01...]
✓ list_databases completed
└─ Found 37 databases: - amazon - bluesky - country - covid - default - dns - en...
🧠 thinking[INFO] Text generation successful - model: claude-3-5-sonnet-latest, response_id: msg_016DxK8SMVKGrUPfFwi43AzE
🔧 Calling: list_tables_in_database [toolu_01...]
└─ Args: {"database":"uk"}
🧠 thinking.✓ list_tables_in_database completed
└─ Found 9 tables in database 'uk': - uk_codes - uk_postcode_to_iso - uk_price_p...
🔧 Calling: list_tables_in_database [toolu_01...]
└─ Args: {"database":"uk"}
✓ list_tables_in_database completed
└─ Found 9 tables in database 'uk': - uk_codes - uk_postcode_to_iso - uk_price_p...
🧠 thinking.[INFO] Text generation successful - model: claude-3-5-sonnet-latest, response_id: msg_015giF12wm619beNGC5aTrmw
🔧 Calling: get_schema_for_table [toolu_01...]
└─ Args: {"database":"uk","table":"uk_price_paid"}
✓ get_schema_for_table completed
└─ Schema for uk.uk_price_paid: CREATE TABLE uk.uk_price_paid ( `price` UInt...
🔧 Calling: get_schema_for_table [toolu_01...]
└─ Args: {"database":"uk","table":"uk_price_paid"}
🧠 thinking..✓ get_schema_for_table completed
└─ Schema for uk.uk_price_paid: CREATE TABLE uk.uk_price_paid ( `price` UInt...
🧠 thinking[INFO] Text generation successful - model: claude-3-5-sonnet-latest, response_id: msg_01HxT1HKbaTT3165Wx5bDtY9
─────────────────────────────────────────────────
• ✨ SQL query generated successfully!
:) SELECT town, district, county, round(avg(price), 2) as avg_price, count() as total_sales FROM uk.uk_price_paid WHERE date >= '2021-01-01' AND date <= '2021-12-31' GROUP BY town, district, county HAVING total_sales >= 10 ORDER BY avg_price DESC LIMIT 10
```
AI는 다음 단계를 수행합니다:
1. 스키마 탐색 - 사용 가능한 데이터베이스와 테이블을 탐색합니다
2. 테이블 분석 - 관련 테이블의 구조를 살펴봅니다
3. 쿼리 생성 - 질문과 탐색된 스키마를 바탕으로 SQL을 생성합니다
`uk_price_paid` 테이블을 찾아냈고, 실행할 쿼리도 생성한 것을 확인할 수 있습니다.
해당 쿼리를 실행하면 다음과 같은 출력이 표시됩니다:
```text theme={null}
┌─town───────────┬─district───────────────┬─county──────────┬──avg_price─┬─total_sales─┐
│ ILKLEY │ HARROGATE │ NORTH YORKSHIRE │ 4310200 │ 10 │
│ LONDON │ CITY OF LONDON │ GREATER LONDON │ 4008117.32 │ 311 │
│ LONDON │ CITY OF WESTMINSTER │ GREATER LONDON │ 2847409.81 │ 3984 │
│ LONDON │ KENSINGTON AND CHELSEA │ GREATER LONDON │ 2331433.1 │ 2594 │
│ EAST MOLESEY │ RICHMOND UPON THAMES │ GREATER LONDON │ 2244845.83 │ 12 │
│ LEATHERHEAD │ ELMBRIDGE │ SURREY │ 2051836.42 │ 102 │
│ VIRGINIA WATER │ RUNNYMEDE │ SURREY │ 1914137.53 │ 169 │
│ REIGATE │ MOLE VALLEY │ SURREY │ 1715780.89 │ 18 │
│ BROADWAY │ TEWKESBURY │ GLOUCESTERSHIRE │ 1633421.05 │ 19 │
│ OXFORD │ SOUTH OXFORDSHIRE │ OXFORDSHIRE │ 1628319.07 │ 405 │
└────────────────┴────────────────────────┴─────────────────┴────────────┴─────────────┘
```
후속 질문을 하려면 매번 처음부터 질문해야 합니다.
### 그레이터 런던의 고가 부동산 찾기
이 기능은 대화 이력을 유지하지 않으므로 각 쿼리는 자체적으로 완결되어야 합니다. 후속 질문을 할 때는 이전 쿼리를 참조하지 말고 전체 맥락을 함께 제공해야 합니다.
예를 들어, 앞선 결과를 확인한 뒤 그레이터 런던의 부동산에만 집중하고 싶을 수 있습니다. "그레이터 런던은 어떤가요?"라고 묻는 대신 전체 맥락을 포함해야 합니다:
```sql theme={null}
?? Can you tell me the most expensive place to buy a house in Greater London across the years?;
```
AI는 방금 이 데이터를 살펴봤더라도 동일한 탐색 과정을 다시 거친다는 점에 유의하십시오:
```text theme={null}
• Starting AI SQL generation with schema discovery...
─────────────────────────────────────────────────
🧠 thinking[INFO] Text generation successful - model: claude-3-5-sonnet-latest, response_id: msg_012m4ayaSHTYtX98gxrDy1rz
🔧 Calling: list_databases [toolu_01...]
✓ list_databases completed
└─ Found 37 databases: - amazon - bluesky - country - covid - default - dns - en...
🔧 Calling: list_databases [toolu_01...]
🧠 thinking.✓ list_databases completed
└─ Found 37 databases: - amazon - bluesky - country - covid - default - dns - en...
🧠 thinking.[INFO] Text generation successful - model: claude-3-5-sonnet-latest, response_id: msg_01KU4SZRrJckutXUzfJ4NQtA
🔧 Calling: list_tables_in_database [toolu_01...]
└─ Args: {"database":"uk"}
🧠 thinking..✓ list_tables_in_database completed
└─ Found 9 tables in database 'uk': - uk_codes - uk_postcode_to_iso - uk_price_p...
🔧 Calling: list_tables_in_database [toolu_01...]
└─ Args: {"database":"uk"}
✓ list_tables_in_database completed
└─ Found 9 tables in database 'uk': - uk_codes - uk_postcode_to_iso - uk_price_p...
🧠 thinking[INFO] Text generation successful - model: claude-3-5-sonnet-latest, response_id: msg_01X9CnxoBpbD2xj2UzuRy2is
🔧 Calling: get_schema_for_table [toolu_01...]
└─ Args: {"database":"uk","table":"uk_price_paid"}
🧠 thinking.✓ get_schema_for_table completed
└─ Schema for uk.uk_price_paid: CREATE TABLE uk.uk_price_paid ( `price` UInt...
🔧 Calling: get_schema_for_table [toolu_01...]
└─ Args: {"database":"uk","table":"uk_price_paid"}
✓ get_schema_for_table completed
└─ Schema for uk.uk_price_paid: CREATE TABLE uk.uk_price_paid ( `price` UInt...
🧠 thinking...[INFO] Text generation successful - model: claude-3-5-sonnet-latest, response_id: msg_01QTMypS1XuhjgVpDir7N9wD
─────────────────────────────────────────────────
• ✨ SQL query generated successfully!
:) SELECT district, toYear(date) AS year, round(avg(price), 2) AS avg_price, count() AS total_sales FROM uk.uk_price_paid WHERE county = 'GREATER LONDON' GROUP BY district, year HAVING total_sales >= 10 ORDER BY avg_price DESC LIMIT 10;
```
이렇게 하면 Greater London만 구체적으로 필터링하고 결과를 연도별로 나눈, 더 목적에 맞는 쿼리가 생성됩니다.
쿼리의 출력은 아래와 같습니다:
```text theme={null}
┌─district────────────┬─year─┬───avg_price─┬─total_sales─┐
│ CITY OF LONDON │ 2019 │ 14504772.73 │ 299 │
│ CITY OF LONDON │ 2017 │ 6351366.11 │ 367 │
│ CITY OF LONDON │ 2016 │ 5596348.25 │ 243 │
│ CITY OF LONDON │ 2023 │ 5576333.72 │ 252 │
│ CITY OF LONDON │ 2018 │ 4905094.54 │ 523 │
│ CITY OF LONDON │ 2021 │ 4008117.32 │ 311 │
│ CITY OF LONDON │ 2025 │ 3954212.39 │ 56 │
│ CITY OF LONDON │ 2014 │ 3914057.39 │ 416 │
│ CITY OF LONDON │ 2022 │ 3700867.19 │ 290 │
│ CITY OF WESTMINSTER │ 2018 │ 3562457.76 │ 3346 │
└─────────────────────┴──────┴─────────────┴─────────────┘
```
City of London이 가장 비싼 지역으로 꾸준히 나타납니다! AI가 꽤 적절한 쿼리를 만들었지만, 결과가 시간순이 아니라 평균 가격순으로 정렬되어 있다는 점을 알 수 있습니다. 전년 대비 분석을 하려면 결과가 다른 방식으로 그룹화되도록 "매년 가장 비싼 지역"을 구체적으로 묻는 형태로 질문을 다듬을 수 있습니다.