[TIL] 내일배움캠프 124일차_[OpenAI] query2doc

👀Today I Learn

• SQL은 데이터베이스를 다루는 데 있어 필수적인 언어이지만, 복잡한 SQL 쿼리를 이해하는 건 생각보다 쉽지 않음
• 특히, 다음과 같은 상황에서 더 어려움
  • 누가 작성했는지 모를 레거시 SQL을 마주했을 때
  • 데이터 분석가, 기획자, 개발자가 함께 협업할 때
  • SQL을 공부하면서 각 쿼리가 무슨 일을 하는지 이해하고 싶을 때
• 이럴 때 유용하게 쓸 수 있는 도구가 바로 query2doc

query2doc란?

• query2doc은 SQL 쿼리를 사람이 이해할 수 있는 자연어 문장으로 설명해주는 오픈소스 도구
• LLM(대형 언어 모델, 예: GPT)을 활용하여 SQL 쿼리를 분석하고, 그 의미를 간단한 설명 문장으로 변환

• 예를 들어,

    SELECT name FROM users WHERE age > 30;
  

  • 라는 쿼리를 입력하면 : “Retrieve the names of users who are older than 30.”와 같은 설명이 출력
• SQL 문법에 익숙하지 않거나, 쿼리의 의미를 빠르게 파악하고 싶은 사람에게 매우 유용

query2doc의 작동 방식

1. SQL 쿼리 입력

   • 사용자가 자연어로 설명받고 싶은 SQL 쿼리를 입력

2. SQL 파싱 및 전처리

   • 쿼리의 구조를 파악하기 위해 파서(parser)를 사용하여 각 구성 요소를 추출
   • 예: SELECT, FROM, WHERE, JOIN 등

3. 프롬프트 구성

   • 파싱된 SQL을 바탕으로 GPT 모델에게 전달할 수 있는 적절한 프롬프트(prompt)를 생성

4. GPT 모델 호출

   • OpenAI의 GPT 등 사전 학습된 LLM에 쿼리를 전달해 자연어 설명을 생성

5. 자연어 결과 반환

   • 사람이 읽기 쉬운 형태의 쿼리 설명이 출력

설치 및 사용 방법

1. 설치

git clone https://github.com/egorov-artyom/query2doc.git
cd query2doc
pip install -r requirements.txt

2. 환경 변수 설정

• query2doc은 OpenAI의 GPT API를 사용하므로 API Key가 필요

    export OPENAI_API_KEY=your_openai_api_key
  

• 또는 .env 파일에 다음과 같이 작성

  OPENAI_API_KEY=your_openai_api_key
  

3. 실행

python query2doc.py --query "SELECT name FROM users WHERE age > 30;"

• 또는 CLI에서 직접 실행

poetry run query2doc --query "SELECT * FROM orders WHERE price > 1000;"

예제 테스트

간단한 SELECT

SELECT id, name FROM customers;

• 답변 : “Retrieve the id and name fields from the customers table.”

JOIN과 GROUP BY 포함 쿼리

SELECT u.name, COUNT(p.id) 
FROM users u 
JOIN posts p ON u.id = p.user_id 
GROUP BY u.name;

• 답변 : “Retrieve the number of posts written by each user.”

조건문과 HAVING 사용

SELECT department, AVG(salary) as avg_salary
FROM employees
GROUP BY department
HAVING AVG(salary) > 5000;

• 답변 : “Retrieve departments where the average salary of employees is greater than 5000.”

query2doc의 장점 및 주의할 점

장점

기능	설명
빠른 이해	복잡한 쿼리를 단 몇 초 만에 설명
협업 친화	SQL을 모르는 기획자나 PM도 쿼리 내용을 이해 가능
문서화 용이	SQL 문서화 작업 자동화
학습 도구	SQL을 처음 배우는 사람에게도 설명서처럼 활용 가능

주의할 점

• 기본적으로 영어로 출력됨
  • 한국어 설명이 필요하다면 프롬프트를 커스터마이징하거나, 출력 결과를 번역 API와 연동해야 함
• LLM의 특성상 정확도가 100%는 아님
  • 특히 복잡한 하위 쿼리나 윈도우 함수가 포함된 쿼리는 해석이 부정확할 수 있으니 사람이 반드시 검토해야 함
• OpenAI API 사용량에 따라 요금이 발생할 수 있음

query2doc 커스터마이징 팁

• query2doc은 Python 코드 기반으로 동작하기 때문에, 아래와 같이 확장할 수 있음

  • 한국어 설명 기능 추가: prompt를 수정하여 "Please describe the following SQL query in Korean:"처럼 명시
  • 다양한 LLM 모델 연동: GPT 외에도 Cohere, Claude, Mistral 등 다양한 모델 사용 가능
  • 웹 인터페이스 추가: Streamlit 등으로 UI 구성 시 팀원들과 공유 용이

💡Today I Thought

오늘의 체크리스트

• 알고리즘 코드카타 2문제
• SQL 코드카타 1문제
• 발표 자료 준비
• TIL 작성

회고

 이제 내일 최종 발표..! 시간 너무 빠르다 진짜.. 공부 열심히 해서 언능 취업해서 맛난것도 먹구, 울애긔들 맛있는 거, 좋은 거 다 사줘야지🥺