Method: projects.locations.queryData

שאילתות נתונים משאילתת משתמש בשפה טבעית.

בקשת HTTP


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

כתובות ה-URL כתובות בתחביר של gRPC Transcoding.

פרמטרים של נתיב

פרמטרים
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

אם זוהתה דו-משמעות בשאילתת השפה הטבעית והאפשרות generate_disambiguation_question הייתה true, השדה הזה מכיל שאלה למשתמש להבהרה. התוצאה שמוחזרת מייצגת את המאמץ הכי טוב של השירות על סמך הקלט הלא חד-משמעי.

היקפי הרשאות

נדרש היקף ההרשאות הבא של OAuth:

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

ניתן למצוא מידע נוסף כאן: Authentication Overview.

QueryDataContext

הפניות למקורות נתונים והקשר לשימוש בשאילתה.

ייצוג ב-JSON 
{
  "datasourceReferences": {
    object (DatasourceReferences)
  }
}
שדות
datasourceReferences

object (DatasourceReferences)

חובה. הפניות למקור הנתונים שבהן יש להשתמש בשאילתה.

GenerationOptions

אפשרויות לשליטה ביצירת השאילתה, בהרצה שלה ובפורמט התשובה.

ייצוג ב-JSON 
{
  "generateQueryResult": boolean,
  "generateNaturalLanguageAnswer": boolean,
  "generateExplanation": boolean,
  "generateDisambiguationQuestion": boolean
}
שדות
generateQueryResult

boolean

זה שינוי אופציונלי. אם הערך הוא true, השאילתה שנוצרה תופעל ונתוני התוצאה יוחזרו בתגובה.
generateNaturalLanguageAnswer

boolean

זה שינוי אופציונלי. אם הערך הוא true, תיווצר תשובה בשפה טבעית על סמך תוצאת הביצוע של השאילתה, והיא תוחזר בתגובה.
generateExplanation

boolean

זה שינוי אופציונלי. אם הערך הוא true, הסבר על השאילתה שנוצרה יוחזר בתגובה.
generateDisambiguationQuestion

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)

המספר הכולל של השורות במערך התוצאות המלא, אם ידוע. יכול להיות שזה יהיה אומדן או ספירה מדויקת.
partialResult

boolean

הערך מוגדר כ-true אם השורות שמוחזרות בפונקציה queryResult הן קבוצת משנה של התוצאה המלאה. לדוגמה, מצב כזה יכול לקרות אם ביצוע השאילתה מגיע למגבלת שורות. אם הערך הוא True, ה-queryResult לא מכיל את כל השורות. כדי לאחזר את התוצאה המלאה, כדאי להשתמש בפונקציה generatedQuery ב-QueryDataResponse ולהפעיל אותה בסביבה שלכם.
queryExecutionError

string

הודעת השגיאה אם ביצוע השאילתה נכשל.

עמודה

מתאר עמודה אחת בערכת התוצאות.

ייצוג ב-JSON 
{
  "name": string,
  "type": string
}
שדות
name

string

שם העמודה.
type

string

סוג העמודה (למשל, ‫"VARCHAR",‏ "INT64",‏ "TIMESTAMP").

Row

מייצג שורה אחת בערכת התוצאות.

ייצוג ב-JSON 
{
  "values": [
    {
      object (Value)
    }
  ]
}
שדות
values[]

object (Value)

הערכים בשורה, בהתאם למיקום שלהם בעמודות.

ערך

מייצג ערך יחיד בשורה.

ייצוג ב-JSON 
{
  "value": string
}
שדות
value

string

הערך של התא, שמיוצג בפורמט מחרוזת. אפשר לעצב את חותמות הזמן, למשל באמצעות RFC3339Nano. השדה הזה נמצא בשימוש אם הערך הוא לא null.