סקירה כללית של קבוצות הקשרים

קבוצת הקשר היא אוסף של מידע ספציפי למסד נתונים שמאפשר לכלים כמו QueryData ליצור שאילתות ברמת דיוק גבוהה. ערכות הקשר יכולות לכלול תבניות, היבטים וחיפושים של ערכים שעוזרים ל-QueryData להבין את סכימת מסד הנתונים ואת הלוגיקה העסקית של האפליקציות.

אלה מסדי הנתונים הנתמכים:

  • ‫AlloyDB ל-PostgreSQL
  • Cloud SQL ל-MySQL
  • Cloud SQL ל-PostgreSQL
  • Spanner
  • ‫Firestore עם תאימות ל-MongoDB

מהן קבוצות הקשרים

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

אתם מגדירים את ההקשר בקבצים שמכילים אובייקטים בפורמט JSON לכל סוג הקשר. אתם יכולים ליצור את קובצי ההקשר האלה בעזרת סוכן הנדסת ההקשר. אחרי זה מעלים את קובץ ההקשר לקבוצת הקשרים שיוצרים במסוף Google Cloud. התהליך הזה מאפשר לכלים כמו QueryData ללמוד את הסכימה הספציפית של מסד הנתונים ואת הלוגיקה העסקית של האפליקציה.

קובץ ההקשר נראה כך:

קובץ ההקשר של הנציג נראה כך:

{
  "templates": [
    {
      "nl_query": "Count prague loan accounts",
      "sql": "SELECT COUNT(T1.account_id) FROM bird_dev_financial.account AS T1 INNER JOIN bird_dev_financial.loan AS T2 ON T1.account_id = T2.account_id INNER JOIN bird_dev_financial.district AS T3 ON T1.district_id = T3.district_id WHERE T3.\"A3\" = 'Prague'",
      "intent": "How many accounts associated with loans are located in the Prague region?",
      "manifest": "How many accounts associated with loans are located in a given city?",
      "parameterized": {
        "parameterized_intent": "How many accounts associated with loans are located in $1",
        "parameterized_sql": "SELECT COUNT(T1.account_id) FROM bird_dev_financial.account AS T1 INNER JOIN bird_dev_financial.loan AS T2 ON T1.account_id = T2.account_id INNER JOIN bird_dev_financial.district AS T3 ON T1.district_id = T3.district_id WHERE T3.\"A3\" = $1"
      }
    }
  ],
  "facets": [
    {
      "sql_snippet": "employee.\"A11\" BETWEEN 6000 AND 10000",
      "intent": "Average salary between 6000 and 10000",
      "manifest": "Average salary between a given number and a given number",
      "parameterized": {
         "parameterized_intent": "Average salary between $1 and $2",
         "parameterized_sql_snippet": "employee.\"A11\" BETWEEN $1 AND $2"
      }
    }
  ]
}

פורמט קובץ קבוצת הקשרים

קובץ של הגדרות הקשר מורכב מקבוצה שנבחרה בקפידה של תבניות, היבטים וחיפושי ערכים בפורמט JSON, שמנחים כלים כמו QueryData בתרגום שאלות בשפה טבעית לשאילתות למסד נתונים ספציפי. הגדרת ההקשר מבטיחה יצירת SQL ברמת דיוק גבוהה לתבניות שאילתה נפוצות.

כדי להבטיח דיוק מרבי, חשוב לוודא שקבוצת ההקשרים מדויקת ומקיפה את כל השאילתות הצפויות באפליקציה.

אפשר ליצור קבוצות הקשר באזורים us-central1,‏ us-east1,‏ europe-west4 ו-asia-southeast1.

תבניות של שאילתות

תבניות של שאילתות הן קבוצה של שאלות מייצגות בשפה טבעית עם שאילתות SQL תואמות. הם כוללים גם הסברים שמספקים נימוק דקלרטיבי ליצירת SQL משפה טבעית.

אובייקט של תבנית שאילתה נראה כך:

{
  "templates": [
    {
      "nl_query": "Count prague loan accounts",
      "sql": "SELECT COUNT(T1.account_id) FROM bird_dev_financial.account AS T1 INNER JOIN bird_dev_financial.loan AS T2 ON T1.account_id = T2.account_id INNER JOIN bird_dev_financial.district AS T3 ON T1.district_id = T3.district_id WHERE T3.\"A3\" = 'Prague'",
      "intent": "How many accounts associated with loans are located in the Prague region?",
      "manifest": "How many accounts associated with loans are located in a given city?",
      "parameterized": {
        "parameterized_intent": "How many accounts associated with loans are located in $1",
        "parameterized_sql": "SELECT COUNT(T1.account_id) FROM bird_dev_financial.account AS T1 INNER JOIN bird_dev_financial.loan AS T2 ON T1.account_id = T2.account_id INNER JOIN bird_dev_financial.district AS T3 ON T1.district_id = T3.district_id WHERE T3.\"A3\" = $1"
      }
    }
  ],
  ...
}

הרכיבים העיקריים של אובייקט ה-JSON של תבנית השאילתה הם:

  • ‫nl_query: דוגמה לשאילתה בשפה טבעית שכלים כמו QueryData מטפלים בה.
  • ‫sql: שאילתת ה-SQL של השאילתה בשפה טבעית.
  • ‫intent: המטרה או הייעוד של שאילתת השפה הטבעית. אם לא מגדירים את הערך הזה, ברירת המחדל היא השאילתה בשפה טבעית.
  • ‫manifest: צורה כללית של הכוונה שנוצרת אוטומטית.
  • parameterized_intent: תבנית שנוצרת אוטומטית של ה-intent, שבה ערכי הישויות מוחלפים בפרמטרים.
  • ‫parameterized_sql: טופס של שאילתת SQL שנוצר אוטומטית על סמך תבנית, שמתאים לכוונת המשתמש עם הפרמטרים.

היבטים של שאילתות

היבטי שאילתות הם קבוצה נבחרת של תנאים מייצגים בשפה טבעית עם פרדיקטים תואמים של SQL. ההיבטים מנהלים את הסינון ואת התנאים, וכך מאפשרים לתבניות של שאילתות לבצע חיפושים לפי היבטים.

אובייקט של היבט שאילתה נראה כך:

{
...
"facets": [
    {
      "sql_snippet": "employee.\"A11\" BETWEEN 6000 AND 10000",
      "intent": "Average salary between 6000 and 10000",
      "manifest": "Average salary between a given number and a given number",
      "parameterized": {
         "parameterized_intent": "Average salary between $1 and $2",
         "parameterized_sql_snippet": "employee.\"A11\" BETWEEN $1 AND $2"
      }
    }
  ]
}

הרכיבים העיקריים של אובייקט ה-JSON של המאפיין הם:

  • ‫sql_snippet: קטע קוד ב-SQL. כדי למנוע אי-בהירות, צריך להוסיף לשמות העמודות את שמות הטבלאות (לדוגמה, table_name.column_name).
  • ‫intent: הסבר על הפרדיקט של ה-SQL.
  • ‫manifest: צורה כללית של הכוונה שנוצרת אוטומטית.
  • parameterized_intent: תבנית שנוצרת אוטומטית של ה-intent, שבה ערכי הישויות מוחלפים בפרמטרים.
  • ‫parameterized_sql_snippet: טופס של sql_snippet שנוצר אוטומטית על סמך תבנית, שתואם לכוונת המשתמש עם הפרמטרים.

שאילתות חיפוש של ערכים

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

ממשק QueryData API משתמש בקישור ערכים כדי להמיר שפה טבעית ל-SQL בצורה מדויקת יותר. באמצעות שאילתות חיפוש של ערכים, ה-API יכול לתקן שגיאות כתיב ולפתור סוגי ערכים על סמך ערכים במסד הנתונים, וכך לשפר את דיוק ההמרות.

קישור ערכים משפר את הדיוק של ההמרה משפה טבעית ל-SQL. לדוגמה, אם משתמש שואל "יש טיסות מנמל התעופה הית'רו?", יכול להיות שבמסד הנתונים יישמר שם שדה התעופה כ-"London Heathrow". בלי קישור ערכים, יכול להיות ששאילתת ה-SQL שנוצרה תסנן לפי WHERE name = 'Heathrow' ולא תחזיר תוצאות. שאילתות חיפוש של ערכים עוזרות לסוכן למפות את "נתב"ג" לערך הנכון במסד הנתונים, "נמל התעופה בן גוריון", ולמיקום שלו בסכימה (airports.name), כדי לוודא ששאילתת ה-SQL שנוצרת מדויקת.

דוגמה לשאילתת חיפוש של ערך:

{
  ...
  "value_searches": [
    {
      "query": "SELECT $value as value, 'airports.iata' as columns, 'Airport IATA Code' as concept_type, 0 as distance, '{}'::text as context FROM \"airports\" T WHERE T.\"iata\" = $value",
      "concept_type": "Airport IATA Code",
      "description": "Exact match (Standard SQL) for 3-letter airport codes"
    },
    {
      "query": "WITH TrigramMetrics AS ( SELECT T.\"name\" AS original_value, (T.\"name\" <-> $value::text) AS normalized_dist FROM \"airports\" T WHERE T.\"name\" % $value::text ) SELECT original_value AS value, 'airports.name' AS columns, 'Airport Name' AS concept_type, normalized_dist AS distance, '{}'::text AS context FROM TrigramMetrics",
      "concept_type": "Airport Name",
      "description": "Fuzzy match using standard trigram for partial airport names"
    },
    {
      "query": "WITH SemanticMetrics AS ( SELECT T.\"city\" AS original_value, ( (google_ml.embedding('gemini-embedding-001', $value)::vector <=> google_ml.embedding('gemini-embedding-001', T.\"city\")::vector) / 2.0 ) AS normalized_dist FROM \"airports\" T WHERE T.\"city\" IS NOT NULL ) SELECT original_value AS value, 'airports.city' AS columns, 'Airport City' AS concept_type, normalized_dist AS distance, '{}'::text AS context FROM SemanticMetrics",
      "concept_type": "Airport City",
      "description": "Semantic search on string values for airport city names"
    }
  ]
}

הרכיבים העיקריים של אובייקט ה-JSON של חיפוש הערכים הם:

  • ‫query: הצהרת SQL עם פרמטרים שמגדירה את הלוגיקה להתאמת ביטוי ערך לערכים שמאוחסנים במסד נתונים. בדרך כלל, קבוצת התוצאות מציגה את הערך התואם, את מיקום הסכימה, את סוג המושג ומדד מרחק מנורמל (בין 0 ל-1).
  • ‫concept_type: תווית סמנטית שמוקצית לערך – לדוגמה, district או loan_status. התווית הזו עוזרת לקשר בין הערכים, ובסופו של דבר עוזרת לכלים כמו QueryData API להבין את התפקיד של ביטוי הערך בסכימה. הוא גם עוזר ליצור הצהרת SQL שמטרגטת את הקונספט של הערך, וגם את הטבלה והעמודה שבהן מופיע ביטוי הערך.
  • ‫description: תיאור של לוגיקת החיפוש.

מגבלות

יש כמה מגבלות לגבי קבוצות של הקשרים:

  • אין תמיכה ב-Cloud SQL ל-SQL Server.
  • קבוצות הקשר למסדי נתונים תומכות רק בתבניות, בהיבטים ובחיפושי ערכים.
  • הקשרים של מסדי נתונים משמשים רק את נקודת הקצה QueryData ב-Conversational Analytics API.

המאמרים הבאים