add more docs

Signed-off-by: Jenkins, Kenneth Alexander <kjenkins60@gatech.edu>

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

@@ -0,0 +1,383 @@
+# 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
+   שומר על קשרים פתורים בהקשר הבקשה
+   תומך במעבר קשרים קדימה ואחורה
+
+### ניטור סכימת תצורה
+
+השירות יירשם למטפל תצורה כדי לקבל עדכוני סכימה:
+
+```python
+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)
+
+```python
+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)
+
+```python
+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
+
+#### שאילתת אוסף פשוטה
+```graphql
+{
+  customers(status: "active") {
+    customer_id
+    name
+    email
+    registration_date
+  }
+}
+```
+
+#### שאילתה עם קשרים
+```graphql
+{
+  orders(order_date_gt: "2024-01-01") {
+    order_id
+    total_amount
+    customer {
+      name
+      email
+    }
+    items {
+      product_name
+      quantity
+      price
+    }
+  }
+}
+```
+
+#### שאילתה מדורגת
+```graphql
+{
+  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: תיעוד פנימי