trustgraph/docs/tech-specs/graphql-query.he.md

GraphQL Query Technical Specification

Overview

מפרט זה מתאר את יישום ממשק שאילתות GraphQL עבור אחסון נתונים מובנים של TrustGraph ב-Apache Cassandra. בהתבסס על יכולות הנתונים המובנים המתוארות במפרט structured-data.md, מסמך זה מפרט כיצד שאילתות GraphQL יבוצעו כנגד טבלאות Cassandra המכילות אובייקטים מובנים שחולצו והועברו.

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

Goals

תמיכה דינמית בסכימה: הסתגלות אוטומטית לשינויים בסכימה בתצורה ללא אתחולים מחדש של השירות עמידה בתקני GraphQL: מתן ממשק GraphQL סטנדרטי התואם לכלי לקוחות GraphQL קיימים שאילתות Cassandra יעילות: המרת שאילתות GraphQL לשאילתות CQL יעילות של Cassandra תוך כיבוד מפתחות מחיצה ואינדקסים פתרון קשרים: תמיכה במאפייני פותרים עבור קשרים בין סוגי אובייקטים שונים בטיחות טיפוסים: הבטחת ביצוע שאילתות ובניית תגובות בצורה בטוחה טיפוסית בהתבסס על הגדרות סכימה ביצועים ניתנים להרחבה: טיפול יעיל בשאילתות מקבילות עם ניהול חיבורים מתאים ואופטימיזציה של שאילתות אינטגרציה של בקשות/תגובות: שמירה על תאימות לדפוס בקשות/תגובות המבוסס על Pulsar של TrustGraph טיפול בשגיאות: מתן דיווח מקיף על שגיאות עבור חוסר התאמה בסכימה, שגיאות שאילתות ובעיות אימות נתונים

Background

יישום אחסון הנתונים המובנים (trustgraph-flow/trustgraph/storage/objects/cassandra/) כותב אובייקטים לטבלאות Cassandra בהתבסס על הגדרות סכימה המאוחסנות במערכת התצורה של TrustGraph. טבלאות אלה משתמשות במבנה מפתח מחיצה מורכב עם אוספים ומפתחות ראשיים המוגדרים בסכימה, המאפשרות שאילתות יעילות בתוך אוספים.

מגבלות קיימות שספציפיקציה זו מתייחסת אליהן: אין ממשק שאילתות עבור הנתונים המובנים המאוחסנים ב-Cassandra חוסר יכולת לנצל את יכולות השאילתות החזקות של GraphQL עבור נתונים מובנים חוסר תמיכה במעבר על קשרים בין אובייקטים קשורים היעדר שפה סטנדרטית לגישה לנתונים מובנים

שירות שאילתות GraphQL יסגור את הפערים הללו על ידי: מתן ממשק GraphQL סטנדרטי לשאילתות של טבלאות Cassandra יצירת סכימות GraphQL באופן דינמי מתצורה של TrustGraph המרת יעילה של שאילתות GraphQL לשאילתות CQL של Cassandra תמיכה בפתרון קשרים באמצעות פותרים של שדות

Technical Design

Architecture

שירות שאילתות GraphQL ייושם כמעבד זרימה חדש של TrustGraph תוך שימוש בדפוסים מבוססים:

מיקום מודול: trustgraph-flow/trustgraph/query/objects/cassandra/

רכיבים מרכזיים:

1. מעבד שירות שאילתות GraphQL מרחיב את מחלקת FlowProcessor הבסיסית מיישם דפוס בקשה/תגובה הדומה לשירותי שאילתות קיימים מנטר את התצורה עבור עדכוני סכימה שומר על סכימת GraphQL מסונכרנת עם התצורה

2. מחולל סכימה דינמי ממיר הגדרות RowSchema של TrustGraph לטיפוסי GraphQL יוצר טיפוסי אובייקטים של GraphQL עם הגדרות שדות מתאימות מייצר טיפוס שורש Query עם פותרים מבוססי אוספים מעדכן את סכימת GraphQL כאשר התצורה משתנה

3. מבצע שאילתות מנתח שאילתות GraphQL נכנס באמצעות ספריית Strawberry מאמת שאילתות כנגד הסכימה הנוכחית מבצע שאילתות ומחזיר תגובות מובנות מטפל בשגיאות בצורה אלגנטית עם הודעות שגיאה מפורטות

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

5. פותר קשרים מיישם פותרים של שדות עבור קשרים בין אובייקטים מבצע טעינה באצווה יעילה כדי למנוע שאילתות N+1 שומר על קשרים פתורים בהקשר הבקשה תומך במעבר קשרים קדימה ואחורה

ניטור סכימת תצורה

השירות יירשם למטפל תצורה כדי לקבל עדכוני סכימה:

self.register_config_handler(self.on_schema_config)

כאשר סכימות משתנות:

1. ניתוח הגדרות סכימה חדשות מקובץ התצורה
2. יצירת סוגי GraphQL ופתרונות (resolvers) מחדש
3. עדכון הסכימה הביצועית
4. ניקוי מטמון כלשהו התלוי בסכימה

יצירת סכימת GraphQL

עבור כל RowSchema בתצורה, יוצרים:

1. סוג אובייקט GraphQL: מיפוי סוגי שדות (string → String, integer → Int, float → Float, boolean → Boolean) סימון שדות חובה כלא-nullable ב-GraphQL הוספת תיאורי שדות מהסכימה

2. שדות שאילתה ראשיים: שאילתת אוסף (לדוגמה, customers, transactions) ארגומנטים לסינון המבוססים על שדות עם אינדקס תמיכה בדפוס של "paginate" (limit, offset) אפשרויות מיון עבור שדות הניתנים למיון

3. שדות יחסים: זיהוי יחסי מפתח זר מהסכימה יצירת פתרונות (resolvers) עבור אובייקטים קשורים תמיכה הן ביחסי אובייקט בודד והן ביחסי רשימה

זרימת ביצוע שאילתות

1. קבלת בקשה: קבלת ObjectsQueryRequest מ-Pulsar חילוץ מחרוזת שאילתת GraphQL ומשתנים זיהוי משתמש והקשר של אוסף

2. אימות שאילתה: ניתוח שאילתת GraphQL באמצעות Strawberry אימות מול הסכימה הנוכחית בדיקת בחירות שדות וסוגי ארגומנטים

3. יצירת CQL: ניתוח בחירות GraphQL בניית שאילתת CQL עם סעיפי WHERE מתאימים הכללת האוסף במפתח מחיצה החלת פילטרים המבוססים על ארגומנטים של GraphQL

4. ביצוע שאילתה: ביצוע שאילתת CQL נגד Cassandra מיפוי תוצאות למבנה תגובת GraphQL פתרון כל שדות היחסים עיצוב התגובה בהתאם למפרט של GraphQL

5. העברת תגובה: יצירת ObjectsQueryResponse עם תוצאות הכללת כל שגיאות הביצוע שליחת תגובה דרך Pulsar עם מזהה מתאם

מודלים של נתונים

הערה: קיימת סכימת StructuredQueryRequest/Response קיימת ב-trustgraph-base/trustgraph/schema/services/structured_query.py. עם זאת, היא חסרה שדות קריטיים (משתמש, אוסף) ומשתמשת בסוגים לא אופטימליים. הסכימות שלהלן מייצגות את ההתפתחות המומלצת, שעליה להחליף את הסכימות הקיימות או ליצור סוגי ObjectsQueryRequest/Response חדשים.

סכימת בקשה (ObjectsQueryRequest)

from pulsar.schema import Record, String, Map, Array

class ObjectsQueryRequest(Record):
    user = String()              # Cassandra keyspace (follows pattern from TriplesQueryRequest)
    collection = String()        # Data collection identifier (required for partition key)
    query = String()             # GraphQL query string
    variables = Map(String())    # GraphQL variables (consider enhancing to support all JSON types)
    operation_name = String()    # Operation to execute for multi-operation documents

ההצדקה לשינויים מתוך בקשת StructuredQueryRequest קיימת: הוספת השדות user ו-collection כדי להתאים לדפוס של שירותי שאילתות אחרים. שדות אלה חיוניים לזיהוי ה-keyspace והקולקציה של Cassandra. המשתנים נשארים מסוג Map(String()) כרגע, אך באופן אידיאלי צריכים לתמוך בכל סוגי ה-JSON.

סכימת תגובה (ObjectsQueryResponse)

from pulsar.schema import Record, String, Array
from ..core.primitives import Error

class GraphQLError(Record):
    message = String()
    path = Array(String())       # Path to the field that caused the error
    extensions = Map(String())   # Additional error metadata

class ObjectsQueryResponse(Record):
    error = Error()              # System-level error (connection, timeout, etc.)
    data = String()              # JSON-encoded GraphQL response data
    errors = Array(GraphQLError) # GraphQL field-level errors
    extensions = Map(String())   # Query metadata (execution time, etc.)

ההצדקה לשינויים מ-StructuredQueryResponse הקיים: מבחינה בין שגיאות מערכת (error) ושגיאות GraphQL (errors) משתמשת באובייקטי GraphQLError מובנים במקום מערך מחרוזות מוסיפה שדה extensions לצורך עמידה במפרט GraphQL שומרת על הנתונים כמחרוזת JSON לצורך תאימות, למרות שטיפוסים מקוריים היו עדיפים

אופטימיזציה של שאילתות Cassandra

השירות יבצע אופטימיזציה של שאילתות Cassandra על ידי:

1. כבוד למפתחות מחיצה: תמיד לכלול אוסף בשאילתות להשתמש ביעילות במפתחות ראשיים המוגדרים בסכימה להימנע מסריקות טבלה מלאות

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

3. טעינה באצווה: לאסוף שאילתות קשר לבצע אותן באצווה כדי להפחית את מספר הפעמים לשמור תוצאות בהקשר הבקשה

4. ניהול חיבורים: לשמור על סשנים קבועים של Cassandra להשתמש בבריכת חיבורים לטפל בחיבור מחדש במקרה של כשלים

דוגמאות לשאילתות GraphQL

שאילתת אוסף פשוטה

{
  customers(status: "active") {
    customer_id
    name
    email
    registration_date
  }
}

שאילתה עם קשרים

{
  orders(order_date_gt: "2024-01-01") {
    order_id
    total_amount
    customer {
      name
      email
    }
    items {
      product_name
      quantity
      price
    }
  }
}

שאילתה מדורגת

{
  products(limit: 20, offset: 40) {
    product_id
    name
    price
    category
  }
}

תלותות יישום

Strawberry GraphQL: להגדרת סכימת GraphQL ולביצוע שאילתות Cassandra Driver: לחיבור למסד הנתונים (בשימוש כבר במודול האחסון) TrustGraph Base: עבור FlowProcessor והגדרות סכימה Configuration System: לניטור ועדכון סכימות

ממשק שורת הפקודה

השירות יספק פקודת CLI: kg-query-objects-graphql-cassandra

ארגומנטים: --cassandra-host: נקודת מגע של אשכול Cassandra --cassandra-username: שם משתמש לאימות --cassandra-password: סיסמה לאימות --config-type: סוג תצורה עבור סכימות (ברירת מחדל: "schema") ארגומנטים סטנדרטיים של FlowProcessor (תצורת Pulsar, וכו')

אינטגרציה של API

נושאים של Pulsar

נושא קלט: objects-graphql-query-request סכימה: ObjectsQueryRequest מקבל שאילתות GraphQL משירותי שער

נושא פלט: objects-graphql-query-response סכימה: ObjectsQueryResponse מחזיר תוצאות שאילתות ושגיאות

אינטגרציה של שער

השער ושער הפוך יצטרכו נקודות קצה כדי:

1. לקבל שאילתות GraphQL מלקוחות
2. להעביר לשירות השאילתות דרך Pulsar
3. להחזיר תגובות ללקוחות
4. לתמוך בשאילתות אינטרוספקציה של GraphQL

אינטגרציה של כלי סוכן

מחלקה חדשה של כלי סוכן תאפשר: יצירת שאילתות GraphQL משפה טבעית ביצוע ישיר של שאילתות GraphQL פרשנות ועיצוב תוצאות שילוב עם זרימות החלטה של סוכן

שיקולי אבטחה

הגבלת עומק שאילתה: למנוע שאילתות מקוננות עמוקות שעלולות לגרום לבעיות ביצועים ניתוח מורכבות שאילתה: להגביל את מורכבות השאילתה כדי למנוע מיצוי משאבים הרשאות ברמת השדה: תמיכה עתידית בשליטה על גישה ברמת השדה בהתבסס על תפקידי משתמש ניקוי קלט: לאמת ולנקות את כל קלט השאילתה כדי למנוע התקפות הזרקה הגבלת קצב: ליישם הגבלת קצב שאילתות למשתמש/אוסף

שיקולי ביצועים

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

אסטרטגיית בדיקה

בדיקות יחידה

יצירת סכימה מתוך הגדרות RowSchema ניתוח ותיקוף שאילתות GraphQL לוגיקת יצירת שאילתות CQL יישומים של פותרים (resolvers) של שדות

בדיקות חוזה

עמידה בחוזה הודעות Pulsar תקינות סכימת GraphQL אימות פורמט תגובה אימות מבנה שגיאות

בדיקות אינטגרציה

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

בדיקות ביצועים

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

תוכנית מעבר

אין צורך במעבר מכיוון שזו יכולת חדשה. השירות י:

1. יקרא סכימות קיימות מהתצורה
2. יתחבר לטבלאות Cassandra קיימות שנוצרו על ידי מודול האחסון
3. יתחיל לקבל שאילתות מיד עם הפריסה

ציר זמן

שבוע 1-2: יישום ליבת השירות ויצירת סכימה שבוע 3: ביצוע שאילתות ותרגום CQL שבוע 4: פתרון קשרים ואופטימיזציה שבוע 5: בדיקות וכוונון ביצועים שבוע 6: שילוב עם שער ותיעוד

שאלות פתוחות

1. אבולוציה של סכימה: כיצד השירות צריך להתמודד עם שאילתות במהלך מעברי סכימה? אפשרות: תזמון שאילתות במהלך עדכוני סכימה אפשרות: תמיכה במספר גרסאות סכימה בו זמנית

2. אסטרטגיית אחסון במטמון: האם יש לאחסן תוצאות שאילתות במטמון? לשקול: תפוגה מבוססת זמן לשקול: ביטול תוקף מבוסס אירועים

3. תמיכה בפדרציה: האם השירות צריך לתמוך בפדרציה של GraphQL לשילוב עם מקורות נתונים אחרים? יאפשר שאילתות מאוחדות על נתונים מובנים וגרפיים

4. תמיכה במנויים: האם השירות צריך לתמוך במנויים של GraphQL לעדכונים בזמן אמת? ידרוש תמיכה ב-WebSocket בשער

5. סקלרים מותאמים אישית: האם יש לתמוך בסקלרים מותאמים אישית עבור סוגי נתונים ספציפיים לתחום? דוגמאות: DateTime, UUID, שדות JSON

הפניות

מפרט טכני של נתונים מובנים: docs/tech-specs/structured-data.md תיעוד Strawberry GraphQL: https://strawberry.rocks/ מפרט GraphQL: https://spec.graphql.org/ הפניה ל-Apache Cassandra CQL: https://cassandra.apache.org/doc/stable/cassandra/cql/ תיעוד מעבד זרימת נתונים TrustGraph: תיעוד פנימי