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

קבוצת הקשר היא אוסף של מידע ספציפי למסד נתונים שמאפשר לכלים כמו 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"
      }
    }
  ],
  "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: טופס של הכוונה שנוצר אוטומטית באמצעות תבנית, עם פרמטרים במקום ערכי ישויות.
  • ‫parameterized_sql: תבנית שנוצרה אוטומטית של שאילתת ה-SQL שתואמת ל-intent שמכיל פרמטרים.

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

היבטי שאילתות הם קבוצה נבחרת של תנאים מייצגים בשפה טבעית עם פרדיקטים תואמים של 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: תיאור של לוגיקת החיפוש.

מגבלות

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

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

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