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

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

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

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

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

כדי ליצור אפליקציות מבוססות-סוכנים יעילות, כלים כמו 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"
      }
    }
  ],
  "value_searches": [
    {
      "query": "SELECT $value as value, 'accounts.account_type' as columns, 'Account Type' as concept_type, 0 as distance, '{}'::text as context FROM \"accounts\" T WHERE T.\"account_type\" = $value",
      "concept_type": "Account Type",
      "description": "Exact match for account types"
    }
   ]
}

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

קובץ של קבוצת הקשרים מורכב מקבוצה של תבניות, מאפיינים וחיפושי ערכים בפורמט 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. לדוגמה, אם משתמש שואל "האם יש טיסות מנתב"ג?", יכול להיות שבמסד הנתונים שם שדה התעופה יהיה "נמל התעופה בן גוריון". בלי קישור ערכים, יכול להיות ששאילתת ה-SQL שנוצרה תסנן לפי WHERE name = 'Heathrow' ולא תחזיר תוצאות. שאילתות החיפוש של הערכים מנחות את הנציג למפות את "Heathrow" לערך הנכון במסד הנתונים, "London 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: תיאור של לוגיקת החיפוש.

מגבלות

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

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

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