튜토리얼 에이전트 – 01 Qurify로 데이터베이스와 대화 시작하기

Qurify 튜토리얼 모드가 0.4.4 업데이트로 새롭게 추가되었습니다. ✎ 0.4.4 릴리즈 노트 바로가기

데이터베이스와의 대화가 낯선 사용자부터, Qurify의 유용한 기능들을 샅샅이 알아보고 싶은 사용자들을 위해 '큐리파이 배우기' 모드를 도입했습니다. Qurify를 처음 접한 사용자들은 튜토리얼 에이전트와 함께 언제든지 Qurify의 기능을 차근차근 익힐 수 있습니다.
또한 Qurify 튜토리얼 에이전트는 SQL 학습 흐름을 제공합니다. SQL의 기본 조작법부터 그룹별 집계, 조인 등을 통한 효과적인 데이터 검색 방법까지 튜토리얼을 통해 익힐 수 있습니다. 따라서 SQL을 모르는 사용자라도 튜토리얼 에이전트와 함께 데이터를 분석하며 SQL에 익숙해지는 시간을 가질 수 있습니다.

Qurify는 언제든지 사용자가 큐리파이 배우기를 시작할 수 있도록 지원합니다. 예제 질문이나 입력 창을 통해 Qurify와 바로 대화를 시작할 수 있지만, 튜토리얼 에이전트를 실행하면 Qurify가 제공하는 데이터베이스 대화에 필요한 기능들을 모두 사용해볼 수 있습니다.

대화 화면의 좌측 상단에서도 언제든지 대화-큐리파이 배우기 전환이 가능합니다.
대화 도중 Qurify를 깊이 있게 알아보기 위해 튜토리얼을 시작하고 싶거나, 반대로 튜토리얼 도중에 Qurify와 자유롭게 대화하고 싶은 사용자들은 모드를 전환하여 원하는 기능을 이용할 수 있습니다.
또한 Qurify는 사용자의 튜토리얼 진행 상황을 저장합니다. 즉 튜토리얼을 중단하고 대화를 시작하여도, 후에 튜토리얼을 중단한 부분부터 이어서 다시 진행할 수 있습니다.

이제 본격적으로 튜토리얼 에이전트와 함께 Qurify가 제공하는 기능을 직접 사용해보며 데이터베이스와 대화하는 법을 익혀 보도록 하겠습니다.

튜토리얼은 총 14단계로 이루어져 있습니다. 이 여정 동안 우리는 튜토리얼 에이전트와 함께 Qurify와 대화하는 법부터 데이터베이스로부터 정보를 얻어내고 이를 분석하는 법까지 익히게 됩니다.

'큐리파이 배우기 시작' 버튼을 눌러 튜토리얼 에이전트를 실행해보겠습니다.
(대화 창의 ⬆️ 버튼을 눌러 실행할 수도 있습니다.)

1. 큐리파이 배우기 시작 - 테이블 목록 확인하기

튜토리얼은 Qurify 대화 과정에서 실제로 사용하는 환경에서 진행하게 됩니다.
튜토리얼 과정에서의 Qurify 대화 화면은 총 3가지의 요소로 구분할 수 있습니다.

튜토리얼 에이전트는 다음 항목들로 이루어진 답변을 사용자에게 제공합니다.

1. 사용자가 수행해야 할 미션 제공

2. 미션을 완료할 수 있는 힌트 제공

3. 현재 단계 및 진행 방법 안내

4. 처음으로 돌아가기 & 다음 단계로 이동 & 힌트 실행

튜토리얼 에이전트의 답변에 포함되어 있는 힌트는 튜토리얼의 현재 단계를 완료하기 위한 해결책과도 같습니다. 대화 하단의 힌트 실행 버튼을 누르거나 직접 chat input에 입력 및 전송하면, 힌트를 직접 실행하여 그 결과를 살펴 보고 튜토리얼의 다음 단계로 이동할 수 있습니다.
'데이터베이스의 테이블 목록 확인하기' 태스크를 완료하기 위해, 힌트 실행 버튼을 통해 Qurify가 제안한 힌트를 직접 실행해보도록 하겠습니다.

get_table_info를 사용하여 데이터베이스에 있는 모든 테이블 목록 보여줘

Qurify가 데이터베이스의 전체 테이블 목록을 가져오는 데 성공했습니다. Qurify MCP Server가 get_table_info를 실행하여 사용자의 요청을 처리한 것입니다.
튜토리얼의 첫 단계를 성공적으로 마쳤으니 다음 단계로 이동 버튼을 눌러 이후 단계를 진행하도록 하겠습니다.

(MCP에 대해 더 알아보고 싶다면 이전 게시물을 참고하세요.)

2. 주요 테이블의 컬럼 확인하기

'다음 단계로 이동' 프롬프트와 함께 다음 단계의 튜토리얼을 진행하게 되었습니다.
대화 화면 상단, 또는 도구 실행 결과의 tutorial_tracker를 참고하면 현재 단계와 실행해야 할 태스크를 언제든지 확인 가능합니다. 플레이스 홀더는 AI를 통해 자동으로 생성되어, 사용자가 해당 단계에서 어떤 태스크를 수행해야 하는지 안내합니다.

2단계는 특정 테이블의 컬럼 목록을 확인하는 것을 목표로 합니다.
이번에는 프롬프트를 직접 입력 및 전송함으로써 목표를 달성해보도록 하겠습니다.

get_table_columns를 이용하여 orders 테이블의 모든 컬럼 정보를 보여줘

1단계와 달리 Qurify MCP Server가 이번에는 get_table_columns를 사용하여 orders 테이블의 모든 컬럼 정보를 가져왔습니다. 사이드 바의 Tables 목록에서 orders 테이블과 이에 속한 컬럼들을 보면, get_table_columns가 올바른 컬럼 정보를 추출했다는 점을 알 수 있습니다.

또한 답변 하단에 배치된 버튼을 이용하는 대신 직접 프롬프트를 입력하여도 튜토리얼을 정상적으로 진행하는 모습을 보입니다. 프롬프트를 직접 입력하는 방법으로 프롬프트를 진행하다 보면, 튜토리얼의 의도에 벗어나는 프롬프트를 입력하여 해당 단계의 목표를 완수하지 못할 수 있습니다. 미션을 이해하기 힘들거나 튜토리얼의 이전 단계부터 차근차근 다시 진행하고 싶다면, 언제든지 처음으로 돌아가기 버튼을 눌러 튜토리얼의 첫 단계부터 다시 시작할 수 있습니다.

(이후 모든 단계는 답변 하단의 힌트 실행 버튼을 이용하여 진행하겠습니다.)

3. 전체 테이블 관계도 확인

테이블 목록, 칼럼 목록을 확인하는 방법을 알았으니 이번에는 테이블 간의 관계를 알아보겠습니다.

find_join_path를 이용하여 모든 테이블의 조인 관계를 보여줘

Qurify MCP Server가 find_join_path를 실행하여 테이블 간의 모든 조인 관계를 성공적으로 탐색했습니다.
해당 조인 관계가 실존하는지 검증하기 위해, Qurify의 답변 중 5, 6번(products<—>categories, products<—>suppliers) 관계를 ERD에서 직접 찾아보겠습니다.
(ERD 보기 기능은 사이드 바 - Schema - 관계도 버튼을 통해 활성화할 수 있습니다.)

products 테이블과 categories 테이블, suppliers 테이블이 조인 관계에 있음을 ERD에서도 확인 가능합니다.
이로써 find_join_path를 이용하면 테이블 간의 조인 관계를 ERD 없이도 쉽게 찾을 수 있다는 점을 알 수 있었습니다.

4. 특정 테이블 중심 관계 확인

이번에는 모든 테이블이 아닌 특정한 하나의 테이블을 중심으로 다른 테이블과의 관계를 찾아보겠습니다.

find_join_path를 이용하여 orders 테이블과 직접 연결된 테이블 알려줘

3단계와 똑같이 Qurify MCP Server가 find_join_path를 실행했지만, 이번에는 orders 테이블과 직접 연결된 테이블만 탐색했습니다. 어떤 원리로 각자 다른 결과를 낳았을까요?
도구 실행 결과에서 확인할 수 있는 '도구 호출 시 전달된 인자'를 통해 힌트를 얻을 수 있습니다.

좌측은 모든 테이블을 중심으로, 우측은 orders 테이블을 중심으로 다른 테이블과의 관계를 탐색한 결과입니다.
도구 호출 시 전달된 인자 중 table_a를 살펴 보면, 좌측은 아무 값도 전달하지 않았으나 우측은 orders를 전달하였습니다. 즉 table_a 인자가 아무 값도 전달하지 않으면 모든 테이블의 조인 관계를, 특정한 테이블명을 전달하면 해당 테이블의 조인 관계를 찾는 것입니다.

도구 호출 및 실행 결과의 메커니즘이 궁금하다면, 이처럼 도구 호출 시 전달된 인자를 살펴봄으로써 실행 과정과 원리를 유추할 수 있습니다.

5. 테이블의 샘플 데이터 확인하기

지금까지 데이터베이스와 테이블의 구조를 살펴보았습니다. 이제는 테이블의 내부에 존재하는 데이터를 본격적으로 활용할 시간입니다.
데이터를 직접적으로 활용하기에 앞서, 테이블에 어떤 데이터가 존재하는지 알면 더욱 원활한 질의 과정을 경험할 수 있습니다. 5단계에서는 이를 실현할 수 있는 '샘플 데이터 확인'을 미션으로 제시합니다.

orders 테이블에서 데이터 3개만 보여줘

이번에는 DBHub가 execute_sql을 호출하여 orders 테이블로부터 샘플 데이터 3개를 추출했습니다. execute_sql 호출 시 전달된 인자를 보면, 다음과 같은 SQL 쿼리가 전달됐음을 확인 가능합니다.

SELECT * FROM orders LIMIT 3;

이를 통해 orders 테이블에서 3개의 데이터를 보여 달라는 사용자의 프롬프트를 잘 이해하고 실행했음을 알 수 있습니다.
또한 Qurify는 테이블 형식의 응답을 CSV로 추출하는 기능을 지원합니다. 만약 실행 결과를 다른 응용 프로그램에 이용하거나 외부와 공유하고 싶다면, CSV 다운로드 기능을 이용할 수 있습니다.

6. 특정 컬럼만 선택 조회하기

테이블 내 데이터를 조회할 때, 모든 컬럼을 대상으로 쿼리를 진행한다면 결과가 너무 방대해지거나 알고 싶은 정보를 찾기 어려울 수 있습니다. 이러한 문제를 해결하기 위해 특정 컬럼만 골라서 조회하는 방법을 알아보겠습니다.

orders 테이블에서 customer_id와 freight 컬럼만 5개 보여줘

5단계와 같이 DBHub가 execute_sql을 실행했으나, 이번에는 2개의 컬럼과 5개의 데이터를 조회했다는 점이 다릅니다.
우리는 앞서 '도구 호출 인자'를 통해 이러한 변화의 원인을 유추할 수 있다는 점을 알아보았습니다. 특정 컬럼만 조회하라는 사용자의 요청에 맞추어 전달한 SQL 구문은 다음과 같습니다.

SELECT customer_id, freight FROM orders LIMIT 5

5단계의 SQL 쿼리와 비교하면, SELECT와 LIMIT의 범위가 달라졌음을 알 수 있습니다.
이처럼 Qurify는 사용자의 자연어 질문으로부터 요구 사항을 이해하고, 이를 만족시킬 수 있도록 적절한 인자 전달을 통해 질의를 수행합니다.

7. 문자열 기반 단일 조건 필터링

특정 컬럼에 이어, 이번에는 특정 조건에 해당하는 데이터만을 조회해보겠습니다.
데이터 검색 과정에서 적용할 수 있는 조건의 종류는 다양합니다. '1998년 이전의 주문 일자', '운송 비용이 50000 이상인 주문', '김씨 또는 이씨인 주문자'와 같은 조건을 탐색 과정에 적용할 수 있습니다.
이 중에서도 customer_id가 특정 문자열과 일치해야 한다는 조건을 추가하여 데이터를 검색해보겠습니다.

generate_sql_query를 이용해서 orders 테이블에서 customer_id이(가) 'VINET'인 데이터 5개만 보여줘

도구 실행 결과의 일부를 살펴 보면, Qurify MCP Server가 generate_sql_query를 통해 생성한 SQL문을 DBHub의 execute_sql이 인자로 사용하고 있습니다. 해당 SQL 쿼리는 다음과 같습니다.

SELECT 
  * 
FROM 
  orders 
WHERE 
  customer_id = 'VINET' 
LIMIT 
  5

앞서 살펴보았던 SQL문과 달리, 이번에는 WHERE customer_id = 'VINET'이라는 조건문이 추가되었습니다. 그 결과로 execute_sql의 실행 결과에는 모두 customer_id가 VINET인 데이터만 표시되고 있습니다.
지금까지 진행했던 튜토리얼 단계들과는 달리, 7단계에서는 여러 가지 도구를 사용하여 질의를 수행하였습니다. 이처럼 Qurify는 각자의 고유한 기능을 가진 MCP 서버들이 모여 사용자의 태스크를 완수하기 위해 긴밀한 협업 과정을 거칩니다.

(MCP에 대한 자세한 내용은 이전 포스트에서 확인할 수 있습니다.)

8. 숫자 기반 조건 필터링

7단계와 유사하지만, 이번에는 문자열 대신 숫자를 기준으로 하는 조건을 추가해보도록 하겠습니다. 숫자 기반 조건은 'x보다 큰 수', 'y보다 작은 수', 혹은 'z와 같은 수'와 같은 방식으로 작성할 수 있습니다.

generate_sql_query를 이용해서 orders 테이블에서 freight이(가) 50000보다 작은 데이터 5개만 찾아줘

7단계와 마찬가지로 Qurify MCP Server가 generate_sql_query를 이용하여 SQL 쿼리를 생성하고, 이는 DBHub의 execute_sql 호출 시 인자로 전달됩니다. 해당 SQL 쿼리는 다음과 같습니다.

SELECT
  order_id,
  freight
FROM
  orders
WHERE
  freight < 50000
LIMIT
  5

이번에는 freight < 50000이라는 조건이 포함되어 있습니다. 사용자의 입력으로부터 사용자가 요구하는 조건문을 알아내어 SQL 쿼리 생성과 실행에 반영한 것입니다. 그 결과로 freight이 50000보다 작은 데이터 5개를 성공적으로 확인할 수 있었습니다.
이처럼 Qurify는 자연어 입력을 분석하여 테이블과 컬럼, 필요한 조건 등을 알아내고 이를 질의 과정에 반영하여 사용자의 요구사항을 만족시킬 수 있는 응답을 제공합니다. 즉 데이터베이스를 다루는 법을 몰라도 Qurify를 사용한다면 자연어만으로 충분히 원하는 데이터를 탐색하고 분석할 수 있습니다.

마치며

지금까지 튜토리얼의 처음부터 8단계까지 순서대로 진행하며 Qurify에서 사용할 수 있는 기본적인 기능부터 도구 호출 인자와 같은 유용한 추가 기능까지 알아보았습니다.
다음 포스트에서는 9단계부터 끝까지 튜토리얼을 이어서 진행하며, 아직 알아보지 못한 Qurify의 기능을 소개하도록 하겠습니다.