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
  ],
  "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

צריך להגדיר את הערך כ-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.

TokenUsage

מעקב אחרי השימוש הכולל בטוקנים לבקשה.

ייצוג ב-JSON
{
  "inputTokenCount": integer,
  "outputTokenCount": integer
}
שדות
inputTokenCount

integer

המספר הכולל של טוקנים של קלט שנעשה בהם שימוש בבקשה הזו.

outputTokenCount

integer

המספר הכולל של טוקני הפלט שנעשה בהם שימוש בבקשה הזו.