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

---
layout: default
title: "GraphQL Query Technical Specification"
parent: "Hebrew (Beta)"
---

# GraphQL Query Technical Specification

> **Beta Translation:** This document was translated via Machine Learning and as such may not be 100% accurate. All non-English languages are currently classified as Beta.

## Overview

<<<<<<< HEAD
מפרט זה מתאר את יישום ממשק שאילתות GraphQL עבור אחסון נתונים מובנים של TrustGraph ב-Apache Cassandra. בהתבסס על יכולות הנתונים המובנים המתוארות במפרט structured-data.md, מסמך זה מפרט כיצד שאילתות GraphQL יבוצעו כנגד טבלאות Cassandra המכילות אובייקטים מובנים שחולצו והועברו.
=======
מפרט זה מתאר את יישום ממשק שאילתות GraphQL עבור אחסון נתונים מובנים של TrustGraph ב-Apache Cassandra. בהתבסס על יכולות הנתונים המובנים המתוארות במפרט structured-data.md, מסמך זה מפרט כיצד שאילתות GraphQL יבוצעו כנגד טבלאות Cassandra המכילות אובייקטים מובנים שחולצו ויועברו.
>>>>>>> 82edf2d (New md files from RunPod)

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

## Goals

**תמיכה דינמית בסכימה**: הסתגלות אוטומטית לשינויים בסכימה בתצורה ללא אתחולים מחדש של השירות
<<<<<<< HEAD
**עמידה בתקני GraphQL**: מתן ממשק GraphQL סטנדרטי התואם לכלי לקוחות GraphQL קיימים
**שאילתות Cassandra יעילות**: המרת שאילתות GraphQL לשאילתות CQL יעילות של Cassandra תוך כיבוד מפתחות מחיצה ואינדקסים
**פתרון קשרים**: תמיכה במאפייני פותרים עבור קשרים בין סוגי אובייקטים שונים
**בטיחות טיפוסים**: הבטחת ביצוע שאילתות ובניית תגובות בצורה בטוחה טיפוסית בהתבסס על הגדרות סכימה
**ביצועים ניתנים להרחבה**: טיפול יעיל בשאילתות מקבילות עם ניהול חיבורים מתאים ואופטימיזציה של שאילתות
=======
**עמידה בתקני GraphQL**: מתן ממשק GraphQL סטנדרטי התואם לכלי ולקוחות GraphQL קיימים
**שאילתות Cassandra יעילות**: המרת שאילתות GraphQL לשאילתות CQL יעילות של Cassandra תוך כיבוד מפתחות מחיצה ואינדקסים
**פתרון קשרים**: תמיכה בפתרוני שדות עבור קשרים בין סוגי אובייקטים שונים
**בטיחות טיפוסים**: הבטחת ביצוע שאילתות ובניית תגובות בצורה בטוחה טיפוסית בהתבסס על הגדרות סכימה
**ביצועים ניתנים להרחבה**: טיפול יעיל בשאילתות מקבילות עם ניהול בריכת חיבורים ואופטימיזציה של שאילתות
>>>>>>> 82edf2d (New md files from RunPod)
**אינטגרציה של בקשות/תגובות**: שמירה על תאימות לדפוס בקשות/תגובות המבוסס על Pulsar של TrustGraph
**טיפול בשגיאות**: מתן דיווח מקיף על שגיאות עבור חוסר התאמה בסכימה, שגיאות שאילתות ובעיות אימות נתונים

## Background

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

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

מגבלות נוכחיות שמתפרט זה מטפל בהן:
>>>>>>> 82edf2d (New md files from RunPod)
אין ממשק שאילתות עבור הנתונים המובנים המאוחסנים ב-Cassandra
חוסר יכולת לנצל את יכולות השאילתות החזקות של GraphQL עבור נתונים מובנים
חוסר תמיכה במעבר על קשרים בין אובייקטים קשורים
היעדר שפה סטנדרטית לגישה לנתונים מובנים

שירות שאילתות GraphQL יסגור את הפערים הללו על ידי:
מתן ממשק GraphQL סטנדרטי לשאילתות של טבלאות Cassandra
יצירת סכימות GraphQL באופן דינמי מתצורה של TrustGraph
המרת יעילה של שאילתות GraphQL לשאילתות CQL של Cassandra
<<<<<<< HEAD
תמיכה בפתרון קשרים באמצעות פותרים של שדות
=======
תמיכה בפתרון קשרים באמצעות פתרוני שדות
>>>>>>> 82edf2d (New md files from RunPod)

## Technical Design

### Architecture

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

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

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

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

<<<<<<< HEAD
2. **מחולל סכימה דינמי**
   ממיר הגדרות RowSchema של TrustGraph לטיפוסי GraphQL
   יוצר טיפוסי אובייקטים של GraphQL עם הגדרות שדות מתאימות
   מייצר טיפוס שורש Query עם פותרים מבוססי אוספים
=======
2. **מחולל סכימה דינמית**
   ממיר הגדרות RowSchema של TrustGraph לסוגי GraphQL
   יוצר סוגי אובייקטים של GraphQL עם הגדרות שדות מתאימות
   מייצר סוג שאילתא ראשי עם פותרים מבוססי אוספים
>>>>>>> 82edf2d (New md files from RunPod)
   מעדכן את סכימת GraphQL כאשר התצורה משתנה

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

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

5. **פותר קשרים**
   מיישם פותרים של שדות עבור קשרים בין אובייקטים
=======
   מנהל ניהול בריכת חיבורים ומחזור חיים של סשן

5. **פתרון קשרים**
   מיישם פתרוני שדות עבור קשרים בין אובייקטים
>>>>>>> 82edf2d (New md files from RunPod)
   מבצע טעינה באצווה יעילה כדי למנוע שאילתות 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 עם מזהה מתאם

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

<<<<<<< HEAD
> **הערה**: קיימת סכימת StructuredQueryRequest/Response קיימת ב-`trustgraph-base/trustgraph/schema/services/structured_query.py`. עם זאת, היא חסרה שדות קריטיים (משתמש, אוסף) ומשתמשת בסוגים לא אופטימליים. הסכימות שלהלן מייצגות את ההתפתחות המומלצת, שעליה להחליף את הסכימות הקיימות או ליצור סוגי ObjectsQueryRequest/Response חדשים.
=======
> **הערה**: קיימת סכימת StructuredQueryRequest/Response קיימת ב-`trustgraph-base/trustgraph/schema/services/structured_query.py`. עם זאת, היא חסרה שדות קריטיים (משתמש, אוסף) ומשתמשת בסוגים לא אופטימליים. הסכימות שלהלן מייצגות את ההתפתחות המומלצת, שעשויה להחליף את הסכימות הקיימות או ליצור סוגי ObjectsQueryRequest/Response חדשים.
>>>>>>> 82edf2d (New md files from RunPod)

#### סכימת בקשה (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
```

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

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

#### סכימת התגובה (ObjectsQueryResponse)
>>>>>>> 82edf2d (New md files from RunPod)

```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. **טעינה באצווה:**
   לאסוף שאילתות קשר
<<<<<<< HEAD
   לבצע אותן באצווה כדי להפחית את מספר הפעמים
=======
   לבצע אותן באצווה כדי להפחית מעברים
>>>>>>> 82edf2d (New md files from RunPod)
   לשמור תוצאות בהקשר הבקשה

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 והגדרות סכימה
<<<<<<< HEAD
**Configuration System**: לניטור ועדכון סכימות
=======
**Configuration System**: עבור ניטור ועדכון סכימות
>>>>>>> 82edf2d (New md files from RunPod)

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

השירות יספק פקודת 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
טיפול בעדכוני סכימה
פתרון קשרים
דפוסים של דף אחרי דף וסינון
<<<<<<< HEAD
תרחישי שגיאות
=======
תרחישי שגיאה
>>>>>>> 82edf2d (New md files from RunPod)

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

## תוכנית מעבר

<<<<<<< HEAD
אין צורך במעבר מכיוון שזו יכולת חדשה. השירות י:
1. יקרא סכימות קיימות מהתצורה
=======
אין צורך במעבר מכיוון שזו יכולת חדשה. השירות יעשה את הפעולות הבאות:
1. יקרא סכימות קיימות מהגדרות
>>>>>>> 82edf2d (New md files from RunPod)
2. יתחבר לטבלאות Cassandra קיימות שנוצרו על ידי מודול האחסון
3. יתחיל לקבל שאילתות מיד עם הפריסה

## ציר זמן

שבוע 1-2: יישום ליבת השירות ויצירת סכימה
שבוע 3: ביצוע שאילתות ותרגום CQL
שבוע 4: פתרון קשרים ואופטימיזציה
<<<<<<< HEAD
שבוע 5: בדיקות וכוונון ביצועים
=======
שבוע 5: בדיקות וכיוונון ביצועים
>>>>>>> 82edf2d (New md files from RunPod)
שבוע 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/
<<<<<<< HEAD
תיעוד מעבד זרימת נתונים TrustGraph: תיעוד פנימי
=======
תיעוד מעבד זרימה של TrustGraph: תיעוד פנימי
>>>>>>> 82edf2d (New md files from RunPod)