- HTTP 요청
- 경로 매개변수
- 요청 본문
- 응답 본문
- 승인 범위
- QueryDataContext
- ParameterizedSecureViewParameters
- 매개변수
- GenerationOptions
- ExecutedQueryResult
- 열
- 행
- 값
- TokenUsage
자연어 사용자 쿼리에서 데이터를 쿼리합니다.
HTTP 요청
POST https://geminidataanalytics.googleapis.com/v1beta/{parent=projects/*/locations/*}:queryData
URL은 gRPC 트랜스코딩 문법을 사용합니다.
경로 매개변수
| 매개변수 | |
|---|---|
parent |
필수 항목입니다. 쿼리를 생성할 상위 리소스입니다. 형식: projects/{project}/locations/{location} |
요청 본문
요청 본문에는 다음과 같은 구조의 데이터가 포함됩니다.
| JSON 표현 |
|---|
{ "prompt": string, "context": { object ( |
| 필드 | |
|---|---|
prompt |
필수 항목입니다. 쿼리를 생성할 자연어 쿼리입니다. 예: "이번 달에 가장 많이 팔린 제품 5개는 뭐야?" |
context |
필수 항목입니다. 사용할 데이터 소스를 포함한 데이터 쿼리의 컨텍스트입니다. |
generationOptions |
(선택사항) 쿼리 생성 및 실행 동작을 제어하는 옵션입니다. |
응답 본문
생성된 쿼리와 관련 정보가 포함된 응답입니다.
성공한 경우 응답 본문은 다음과 같은 구조의 데이터를 포함합니다.
| JSON 표현 |
|---|
{ "generatedQuery": string, "intentExplanation": string, "queryResult": { object ( |
| 필드 | |
|---|---|
generatedQuery |
지정된 사용자 프롬프트에 대해 생성된 쿼리입니다. |
intentExplanation |
생성된 쿼리에 대한 자연어 설명입니다. 요청에서 options.generate_explanation이 true인 경우 채워집니다. |
queryResult |
쿼리 실행 결과입니다. 요청에서 options.generate_query_result 또는 options.generate_natural_language_answer가 true이고 실행이 성공했거나 시도된 경우 채워집니다. |
naturalLanguageAnswer |
queryResult를 기반으로 한 쿼리에 대한 자연어 답변입니다. 요청에서 options.generate_natural_language_answer가 true이고 executeSql API의 응답을 기반으로 쿼리 실행이 성공한 경우 채워집니다. |
disambiguationQuestion[] |
자연어 쿼리에서 모호성이 감지되고 options.generate_disambiguation_question이 true인 경우 이 필드에는 명확한 설명을 위한 사용자 질문이 포함됩니다. 반환된 결과는 모호한 입력을 기반으로 한 서비스의 최선의 결과를 나타냅니다. |
pipelineDebugInfo |
자세한 단계별 파이프라인 실행 정보입니다. generationOptions.generate_debug_info가 true인 경우에만 채워집니다. 디버깅 및 투명성 목적으로만 제공됩니다. 이 객체의 구조와 콘텐츠는 보장되지 않으며 언제든지 예고 없이 변경될 수 있습니다. 이 객체의 필드에 따라 프로덕션 코드나 비즈니스 로직을 작성하지 마세요. |
tokenUsage |
요청의 전체 토큰 사용량입니다. |
승인 범위
다음 OAuth 범위 중 하나가 필요합니다.
https://www.googleapis.com/auth/cloud-platformhttps://www.googleapis.com/auth/geminidataanalytics
자세한 내용은 Authentication Overview를 참조하세요.
QueryDataContext
쿼리에 사용할 데이터 소스 및 컨텍스트에 대한 참조입니다.
| JSON 표현 |
|---|
{ "datasourceReferences": { object ( |
| 필드 | |
|---|---|
datasourceReferences |
필수 항목입니다. 쿼리에 사용할 데이터 소스 참조입니다. |
parameterizedSecureViewParameters |
(선택사항) 파라미터화된 보안 뷰(PSV)의 파라미터입니다. |
ParameterizedSecureViewParameters
파라미터화된 보안 뷰(PSV)의 파라미터입니다. 이러한 매개변수는 SQL 생성 및 쿼리 실행 중에 행 수준 보안을 적용하는 데 사용됩니다.
| JSON 표현 |
|---|
{
"parameters": [
{
object ( |
| 필드 | |
|---|---|
parameters[] |
(선택사항) 파라미터화된 보안 뷰(PSV)의 이름이 지정된 파라미터 |
매개변수
파라미터화된 보안 뷰의 단일 파라미터를 나타냅니다.
| JSON 표현 |
|---|
{ "key": string, "value": string } |
| 필드 | |
|---|---|
key |
필수 항목입니다. 매개변수 키(예: |
value |
필수 항목입니다. 파라미터 값(예: |
GenerationOptions
쿼리 생성, 실행, 응답 형식을 제어하는 옵션입니다.
| JSON 표현 |
|---|
{ "generateQueryResult": boolean, "generateNaturalLanguageAnswer": boolean, "generateExplanation": boolean, "generateDisambiguationQuestion": boolean, "generateDebugInfo": boolean } |
| 필드 | |
|---|---|
generateQueryResult |
(선택사항) true인 경우 생성된 쿼리가 실행되고 결과 데이터가 응답에 반환됩니다. |
generateNaturalLanguageAnswer |
(선택사항) true인 경우 쿼리 실행 결과를 기반으로 한 자연어 답변이 생성되어 응답에 반환됩니다. |
generateExplanation |
(선택사항) true인 경우 생성된 쿼리에 대한 설명이 응답에 반환됩니다. |
generateDisambiguationQuestion |
(선택사항) true(기본값은 false)인 경우 입력 쿼리가 모호하면 서비스에서 clarifying_question을 반환할 수 있습니다. |
generateDebugInfo |
(선택사항) true(기본값은 false)인 경우 내부 디버깅 정보를 반환합니다. |
ExecutedQueryResult
쿼리 실행 결과입니다. 이 설계는 모든 방언에 공통적으로 적용됩니다.
| JSON 표현 |
|---|
{ "columns": [ { object ( |
| 필드 | |
|---|---|
columns[] |
결과 집합의 열입니다(순서대로). |
rows[] |
쿼리에서 반환된 행입니다. |
totalRowCount |
전체 결과 집합의 총 행 수입니다(알려진 경우). 이 값은 추정치 또는 정확한 수일 수 있습니다. 참고: 과도한 데이터 전송을 방지하기 위해 쿼리 실행 중에 내부 한도(예: LIMIT 1000)가 적용된 경우 이 개수는 제한되지 않은 테이블 결과 크기가 아닌 잘린 결과 크기를 반영합니다. |
partialResult |
|
queryExecutionError |
쿼리 실행이 실패한 경우의 오류 메시지입니다. |
열
결과 집합의 단일 열을 설명합니다.
| JSON 표현 |
|---|
{ "name": string, "type": string } |
| 필드 | |
|---|---|
name |
열의 이름입니다. |
type |
열의 유형입니다(예: 'VARCHAR', 'INT64', 'TIMESTAMP'). |
행
결과 집합의 단일 행을 나타냅니다.
| JSON 표현 |
|---|
{
"values": [
{
object ( |
| 필드 | |
|---|---|
values[] |
행의 값으로, 열에 위치적으로 대응합니다. |
값
행 내의 단일 값을 나타냅니다.
| JSON 표현 |
|---|
{ "value": string } |
| 필드 | |
|---|---|
value |
문자열 형식으로 표현된 셀 값입니다. 타임스탬프는 RFC3339Nano를 사용하여 형식을 지정할 수 있습니다. 이 필드는 값이 null이 아닌 경우에 사용됩니다. |
TokenUsage
요청의 전체 토큰 사용량 추적입니다.
| JSON 표현 |
|---|
{ "inputTokenCount": integer, "outputTokenCount": integer } |
| 필드 | |
|---|---|
inputTokenCount |
이 요청에 사용된 총 입력 토큰 수입니다. |
outputTokenCount |
이 요청에 사용된 총 출력 토큰 수입니다. |