Method: projects.locations.queryData

자연어 사용자 쿼리에서 데이터를 쿼리합니다.

HTTP 요청

POST https://geminidataanalytics.googleapis.com/v1beta/{parent=projects/*/locations/*}:queryData

URL은 gRPC 트랜스코딩 문법을 사용합니다.

경로 매개변수

매개변수
parent

string

필수 항목입니다. 쿼리를 생성할 상위 리소스입니다. 형식: projects/{project}/locations/{location}

요청 본문

요청 본문에는 다음과 같은 구조의 데이터가 포함됩니다.

JSON 표현
{
  "prompt": string,
  "context": {
    object (QueryDataContext)
  },
  "generationOptions": {
    object (GenerationOptions)
  }
}
필드
prompt

string

필수 항목입니다. 쿼리를 생성할 자연어 쿼리입니다. 예: "이번 달에 가장 많이 팔린 제품 5개는 뭐야?"

context

object (QueryDataContext)

필수 항목입니다. 사용할 데이터 소스를 포함한 데이터 쿼리의 컨텍스트입니다.

generationOptions

object (GenerationOptions)

(선택사항) 쿼리 생성 및 실행 동작을 제어하는 옵션입니다.

응답 본문

생성된 쿼리와 관련 정보가 포함된 응답입니다.

성공한 경우 응답 본문은 다음과 같은 구조의 데이터를 포함합니다.

JSON 표현
{
  "generatedQuery": string,
  "intentExplanation": string,
  "queryResult": {
    object (ExecutedQueryResult)
  },
  "naturalLanguageAnswer": string,
  "disambiguationQuestion": [
    string
  ],
  "pipelineDebugInfo": {
    object
  },
  "tokenUsage": {
    object (TokenUsage)
  }
}
필드
generatedQuery

string

지정된 사용자 프롬프트에 대해 생성된 쿼리입니다.

intentExplanation

string

생성된 쿼리에 대한 자연어 설명입니다. 요청에서 options.generate_explanation이 true인 경우 채워집니다.

queryResult

object (ExecutedQueryResult)

쿼리 실행 결과입니다. 요청에서 options.generate_query_result 또는 options.generate_natural_language_answer가 true이고 실행이 성공했거나 시도된 경우 채워집니다.

naturalLanguageAnswer

string

queryResult를 기반으로 한 쿼리에 대한 자연어 답변입니다. 요청에서 options.generate_natural_language_answer가 true이고 executeSql API의 응답을 기반으로 쿼리 실행이 성공한 경우 채워집니다.

disambiguationQuestion[]

string

자연어 쿼리에서 모호성이 감지되고 options.generate_disambiguation_question이 true인 경우 이 필드에는 명확한 설명을 위한 사용자 질문이 포함됩니다. 반환된 결과는 모호한 입력을 기반으로 한 서비스의 최선의 결과를 나타냅니다.

pipelineDebugInfo

object (Struct format)

자세한 단계별 파이프라인 실행 정보입니다. generationOptions.generate_debug_info가 true인 경우에만 채워집니다. 디버깅 및 투명성 목적으로만 제공됩니다. 이 객체의 구조와 콘텐츠는 보장되지 않으며 언제든지 예고 없이 변경될 수 있습니다. 이 객체의 필드에 따라 프로덕션 코드나 비즈니스 로직을 작성하지 마세요.

tokenUsage

object (TokenUsage)

요청의 전체 토큰 사용량입니다.

승인 범위

다음 OAuth 범위 중 하나가 필요합니다.

  • https://www.googleapis.com/auth/cloud-platform
  • https://www.googleapis.com/auth/geminidataanalytics

자세한 내용은 Authentication Overview를 참조하세요.

QueryDataContext

쿼리에 사용할 데이터 소스 및 컨텍스트에 대한 참조입니다.

JSON 표현
{
  "datasourceReferences": {
    object (DatasourceReferences)
  },
  "parameterizedSecureViewParameters": {
    object (ParameterizedSecureViewParameters)
  }
}
필드
datasourceReferences

object (DatasourceReferences)

필수 항목입니다. 쿼리에 사용할 데이터 소스 참조입니다.

parameterizedSecureViewParameters

object (ParameterizedSecureViewParameters)

(선택사항) 파라미터화된 보안 뷰(PSV)의 파라미터입니다.

ParameterizedSecureViewParameters

파라미터화된 보안 뷰(PSV)의 파라미터입니다. 이러한 매개변수는 SQL 생성 및 쿼리 실행 중에 행 수준 보안을 적용하는 데 사용됩니다.

JSON 표현
{
  "parameters": [
    {
      object (Parameter)
    }
  ]
}
필드
parameters[]

object (Parameter)

(선택사항) 파라미터화된 보안 뷰(PSV)의 이름이 지정된 파라미터

매개변수

파라미터화된 보안 뷰의 단일 파라미터를 나타냅니다.

JSON 표현
{
  "key": string,
  "value": string
}
필드
key

string

필수 항목입니다. 매개변수 키(예: "userId")입니다.

value

string

필수 항목입니다. 파라미터 값(예: "123")입니다.

GenerationOptions

쿼리 생성, 실행, 응답 형식을 제어하는 옵션입니다.

JSON 표현
{
  "generateQueryResult": boolean,
  "generateNaturalLanguageAnswer": boolean,
  "generateExplanation": boolean,
  "generateDisambiguationQuestion": boolean,
  "generateDebugInfo": boolean
}
필드
generateQueryResult

boolean

(선택사항) true인 경우 생성된 쿼리가 실행되고 결과 데이터가 응답에 반환됩니다.

generateNaturalLanguageAnswer

boolean

(선택사항) true인 경우 쿼리 실행 결과를 기반으로 한 자연어 답변이 생성되어 응답에 반환됩니다.

generateExplanation

boolean

(선택사항) true인 경우 생성된 쿼리에 대한 설명이 응답에 반환됩니다.

generateDisambiguationQuestion

boolean

(선택사항) true(기본값은 false)인 경우 입력 쿼리가 모호하면 서비스에서 clarifying_question을 반환할 수 있습니다.

generateDebugInfo

boolean

(선택사항) true(기본값은 false)인 경우 내부 디버깅 정보를 반환합니다.

ExecutedQueryResult

쿼리 실행 결과입니다. 이 설계는 모든 방언에 공통적으로 적용됩니다.

JSON 표현
{
  "columns": [
    {
      object (Column)
    }
  ],
  "rows": [
    {
      object (Row)
    }
  ],
  "totalRowCount": string,
  "partialResult": boolean,
  "queryExecutionError": string
}
필드
columns[]

object (Column)

결과 집합의 열입니다(순서대로).

rows[]

object (Row)

쿼리에서 반환된 행입니다.

totalRowCount

string (int64 format)

전체 결과 집합의 총 행 수입니다(알려진 경우). 이 값은 추정치 또는 정확한 수일 수 있습니다. 참고: 과도한 데이터 전송을 방지하기 위해 쿼리 실행 중에 내부 한도(예: LIMIT 1000)가 적용된 경우 이 개수는 제한되지 않은 테이블 결과 크기가 아닌 잘린 결과 크기를 반영합니다.

partialResult

boolean

queryResult에서 반환된 행이 전체 결과의 하위 집합인 경우 true로 설정합니다. 예를 들어 쿼리 실행이 행 한도에 도달하면 이러한 상황이 발생할 수 있습니다. true인 경우 queryResult에 모든 행이 포함되지 않습니다. 전체 결과를 가져오려면 QueryDataResponse의 generatedQuery를 사용하여 자체 환경에서 실행하는 것이 좋습니다.

queryExecutionError

string

쿼리 실행이 실패한 경우의 오류 메시지입니다.

열

결과 집합의 단일 열을 설명합니다.

JSON 표현
{
  "name": string,
  "type": string
}
필드
name

string

열의 이름입니다.

type

string

열의 유형입니다(예: 'VARCHAR', 'INT64', 'TIMESTAMP').

행

결과 집합의 단일 행을 나타냅니다.

JSON 표현
{
  "values": [
    {
      object (Value)
    }
  ]
}
필드
values[]

object (Value)

행의 값으로, 열에 위치적으로 대응합니다.

값

행 내의 단일 값을 나타냅니다.

JSON 표현
{
  "value": string
}
필드
value

string

문자열 형식으로 표현된 셀 값입니다. 타임스탬프는 RFC3339Nano를 사용하여 형식을 지정할 수 있습니다. 이 필드는 값이 null이 아닌 경우에 사용됩니다.

TokenUsage

요청의 전체 토큰 사용량 추적입니다.

JSON 표현
{
  "inputTokenCount": integer,
  "outputTokenCount": integer
}
필드
inputTokenCount

integer

이 요청에 사용된 총 입력 토큰 수입니다.

outputTokenCount

integer

이 요청에 사용된 총 출력 토큰 수입니다.