QueryData를 사용하면 대화형 언어를 사용하여 Spanner 데이터베이스의 속성 그래프 데이터와 상호작용하고 데이터 에이전트를 빌드할 수 있습니다. QueryData는 속성 그래프의 스키마를 기반으로 자연어 질문에서 Graph Query Language(GQL) 쿼리를 생성합니다. 사용 사례의 정확성을 높이기 위해 도메인별 비즈니스 로직과 사용자가 하는 질문을 포착하는 쿼리 템플릿, 쿼리 패싯, 값 검색의 모음인 컨텍스트 세트를 제공할 수도 있습니다. 컨텍스트 세트에 대한 자세한 내용은 컨텍스트 세트 개요를 참조하세요.
QueryData를 사용해야 하는 경우
Spanner Graph용 QueryData는 다음과 같은 애플리케이션에 적합합니다.
- 그래프 데이터 기반 대화형 어시스턴트: 지원 또는 애널리틱스 어시스턴트가 QueryData를 통해 멀티홉 GQL 쿼리를 생성하고 실행하여 '계정 7에서 송금된 금액이 60일 이내에 반환되었나요?'라는 질문에 답변합니다.
- 사기, 위험, 규정 준수를 위한 조사 부조종사: 분석가는 후속 질문을 통해 소유권 및 이전 네트워크를 탐색하고, 컨텍스트 세트는 모든 답변에서 고위험 이전과 같은 용어를 일관되게 유지합니다.
- 지식 그래프 추론 에이전트: ADK 또는 MCP 클라이언트로 빌드된 에이전트는 QueryData를 도구로 호출하여 그래프에 저장된 관계(예: 중개인을 통해 관리하는 계정)를 기반으로 추론을 수행합니다.
핵심 개념
대화형 질문을 GQL 쿼리로 안정적으로 변환하기 위해 QueryData는 다음과 같은 핵심 개념을 사용합니다.
QueryData 및 대화형 분석 API
대화형 분석 API의 QueryData 엔드포인트는 Spanner 데이터베이스의 속성 그래프에 대해 프로그래매틱 자연어-GQL(NL2GQL) 쿼리 생성을 지원하는 에이전트형 도구입니다. 대화형 애플리케이션 또는 멀티 에이전트 워크플로 내에서 QueryData 엔드포인트는 각 요청의 graph_ids 필드에 나열하는 속성 그래프의 스키마 해석 및 쿼리 합성을 처리합니다. 에이전트 하네스(예: Antigravity, 에이전트 개발 키트(ADK), LangChain)는 대화 기록, 사용자 상태, 도구 조정을 관리하여 사용자의 입력을 맥락화한 후 자연어 요청을 QueryData 엔드포인트로 전송합니다.
컨텍스트 세트
컨텍스트 세트는 데이터베이스와 관련된 데이터베이스별 지식, 선별된 쿼리 패턴, 비즈니스 규칙의 모음입니다. QueryData는 일반적인 LLM 지식이나 원시 속성 그래프 스키마에만 의존하는 대신 컨텍스트 세트를 사용하여 그래프 모델의 미묘한 차이와 조직별 용어(예: 은행 금융 그래프에서 비즈니스에서 고위험 송금으로 간주하는 항목)를 이해합니다. 이 가이드의 예시에서는 FinGraph 속성 그래프 스키마와 샘플 데이터 세트를 사용합니다. FinGraph 스키마를 만들고 샘플 데이터를 삽입하려면 Spanner Graph 설정 및 쿼리를 참조하세요.
컨텍스트 세트에는 세 가지 기본 구성요소가 포함됩니다.
- 쿼리 템플릿: 대표적인 자연어 질문과 이에 대응하는 사전 검증된 GQL 쿼리의 선별된 쌍입니다. 템플릿은 특정 비즈니스 의도가 GQL 문에 매핑되는 방식을 정의하는 표준 예시를 제공합니다(예: 'Dana의 계정에서 이체를 받은 계정은 무엇인가요?'가
Owns및Transfers에지를 순회하는GRAPH FinGraph MATCH쿼리에 매핑되는 방식). - 쿼리 패싯: 재사용 가능한 GQL 절(예: 그래프 패턴, 필터 조건, 기간, 금액 기준, 비즈니스 조건(예: 차단된 계정))입니다. 패싯을 사용하면 QueryData가 모든 조합에 대해 별도의 템플릿을 사용하지 않고도 여러 필터링 기준을 쿼리에 동적으로 결합할 수 있습니다.
- 값 검색:
GRAPH_TABLE에 대한SELECT문으로 작성된 시맨틱 및 문자열 일치 쿼리로, 사용자의 질문에 있는 값 문구를 노드 및 에지 속성에 저장된 정확한 값에 그라운딩합니다. 값 검색은 완전 일치, 문자열 유사성 또는 시맨틱 벡터 임베딩을 사용하여 모호성을 해결하는 데 도움이 됩니다(예: 'rainy day'를 계정 닉네임Rainy Day Fund에 매핑하거나 'Czech Republic'을 저장된 값Czech_Republic에 매핑).
QueryData 작동 방식
에이전트 또는 애플리케이션이 자연어 요청(예: 에이전트가 대화 기록 또는 사용자 상태로 맥락을 파악한 사용자의 질문)을 보내면 QueryData는 다음 단계를 수행합니다.
- 값 확인: QueryData는 Spanner 데이터베이스에 대해 값 검색 쿼리를 실행하여 프롬프트의 값 구문(예: 사람 이름, 계정 닉네임, 국가)을 특정 노드 및 에지 속성 값에 매핑합니다.
- 의도 일치 및 모호성 해소: QueryData는 컨텍스트화된 요청을 컨텍스트 집합에 정의한 선별된 쿼리 템플릿 및 패싯과 일치시킵니다. 요청이 불완전하거나 모호한 경우 QueryData는 에이전트 또는 애플리케이션이 사용자에게 명확한 설명을 요청할 수 있도록 모호성 해소 질문을 반환할 수 있습니다.
- 쿼리 합성: QueryData는
graph_ids에 나열된 속성 그래프의 스키마, 일치하는 템플릿 구조, 적용된 패싯, 확인된 값을 사용하여 완전한 GQL 쿼리를 합성합니다. - 쿼리 실행: 생성된 GQL 쿼리가 Spanner 데이터베이스에 대해 실행되어 결과를 반환합니다.
컨텍스트 세트 작성 및 관리
컨텍스트 세트를 작성하고 관리하려면 다음 단계를 따르세요.
- 작성자 컨텍스트: 속성 그래프의 쿼리 템플릿, 패싯, 값 검색을 정의합니다. 자세한 내용은 컨텍스트 세트 개요를 참조하세요. 컨텍스트 엔지니어링 에이전트를 사용하여 컨텍스트 생성을 자동화할 수도 있습니다.
- Google Cloud 콘솔에서 관리: Spanner Studio에서 컨텍스트 세트를 만들고 관리하여 쿼리 생성에 사용할 수 있도록 합니다.
- 애플리케이션과 통합:
graph_ids에 나열된 대상 속성 그래프를 사용하여 직접 REST API 호출을 통해 애플리케이션 또는 AI 에이전트를 QueryData에 연결합니다.
다음 단계
- Spanner Graph의 컨텍스트 세트 알아보기
- Spanner Graph의 QueryData를 테스트하는 방법 알아보기
- 튜토리얼에 따라 QueryData를 애플리케이션과 통합합니다.