Method: projects.locations.queryData

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

HTTP 요청

POST https://geminidataanalytics.googleapis.com/v1alpha/{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
  ]
}
필드
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인 경우 이 필드에는 명확한 설명을 요청하는 사용자 질문이 포함됩니다. 반환된 값은 모호한 입력을 기반으로 서비스가 최선을 다한 결과를 나타냅니다.

승인 범위

다음 OAuth 범위가 필요합니다.

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

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

QueryDataContext

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

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

object (DatasourceReferences)

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

object (ParameterizedSecureViewParameters)

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

ParameterizedSecureViewParameters

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

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

object (Parameter)

선택사항입니다. 파라미터화된 보안 뷰의 이름이 지정된 파라미터입니다.

매개변수

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

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

string

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

string

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

GenerationOptions

질문 생성, 실행, 응답 형식을 제어하는 옵션

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

boolean

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

boolean

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

boolean

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

boolean

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

ExecutedQueryResult

쿼리 실행 결과입니다. 디자인은 모든 방언에 일반적입니다.

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

object (Column)

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

object (Row)

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

string (int64 format)

전체 결과 집합의 총 행 수입니다(알려진 경우). 추정치 또는 정확한 수치일 수 있습니다.
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이 아닌 경우 이 필드가 사용됩니다.