WrenAI의 governed text-to-SQL: 에이전트에게 데이터 의미를 가르치는 계층

Text-to-SQL 에이전트가 어려운 이유는 SQL 문법보다 업무 의미에 있습니다. 매출, 활성 사용자, 완료 건수처럼 조직마다 정의가 다른 단어를 데이터베이스 스키마만으로는 충분히 설명할 수 없습니다. WrenAI 공식 README는 이 문제를 AI context layer와 governed semantic layer로 분리해 다룹니다.

스키마와 업무 정의는 다르다

테이블과 컬럼을 검색하는 것만으로는 승인된 조인, 단위, 상태값, 제외 조건을 알 수 없습니다. WrenAI는 semantic model과 instructions.md, 검증된 예시를 버전 관리 가능한 파일로 두는 방식을 제시합니다.

정보	스키마가 알려주는 것	별도 정의가 필요한 것
고객	customer_id, created_at	휴면 고객 포함 여부
매출	amount, order_id	환불·부가세 처리 기준
기간	날짜 컬럼	회계월과 달력월의 차이
관계	외래 키 후보	승인된 조인 경로

이 구분이 없으면 SQL이 실행되더라도 업무 답변은 틀릴 수 있습니다.

계획 검증을 실행 전에 둔다

공식 README는 schema-aware retrieval, MDL planning, dry-plan validation, structured errors, row limits와 value profiling을 핵심 요소로 설명합니다. 실무적으로는 에이전트가 만든 SQL을 곧바로 실행하지 않고 다음 순서를 두는 구조입니다.

1. 질문에서 지표·기간·필터를 추출합니다.
2. 의미 계층에서 승인된 모델과 정의를 찾습니다.
3. SQL 계획을 만들고 위험한 조인·범위·행 수를 검사합니다.
4. 읽기 전용 실행 후 결과와 생성 SQL을 함께 검토합니다.
5. 승인된 질문·정의·수정 사항을 다음 컨텍스트로 반영합니다.

이 구조는 모델을 더 똑똑하게 만드는 방법이라기보다, 틀린 실행이 조직 데이터에 미치는 범위를 줄이는 방법입니다.

에이전트와 BI 도구의 경계

WrenAI는 답변과 차트 생성뿐 아니라 결과를 공유 가능한 대시보드로 배포하는 흐름도 설명합니다. 그러나 대시보드가 생성됐다는 사실이 지표의 정확성을 보장하지는 않습니다. 반드시 생성 SQL, 사용한 정의, 원본 데이터 범위, 실행 시각을 함께 남겨야 합니다.

검증용 질문 세트는 다음처럼 만들 수 있습니다.

• 같은 지표를 다른 표현으로 물어도 동일한 정의를 쓰는가
• 환불과 취소를 구분하는가
• 기간을 바꾸면 필터가 의도대로 이동하는가
• 데이터가 없을 때 0과 미확인을 구분하는가
• 결과를 재실행했을 때 같은 SQL과 근거를 얻는가

적용 판단

WrenAI 같은 구조를 도입하기 전에는 조직의 핵심 지표 다섯 개부터 정의 파일로 옮기는 것이 좋습니다. 모델 호출보다 먼저 승인된 의미, 조인, 제한 조건을 문서화해야 하며, 답변 화면에는 수치만이 아니라 정의와 실행 근거가 함께 보여야 합니다. 이 글은 WrenAI를 직접 사용한 후기가 아니라 공식 README가 제시한 구조를 데이터 에이전트 설계 관점으로 해석한 글입니다.

• WrenAI 저장소
• WrenAI 공식 문서