Structure the tech specs directory (#836)

Tech spec some subdirectories for different languages

docs/tech-specs/he/structured-data.he.md

@@ -0,0 +1,260 @@
+---
+layout: default
+title: "מפרט טכני של נתונים מובנים"
+parent: "Hebrew (Beta)"
+---
+
+# מפרט טכני של נתונים מובנים
+
+> **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.
+
+## סקירה כללית
+
+מפרט זה מתאר את השילוב של TrustGraph עם זרימות נתונים מובנים, המאפשר למערכת לעבוד עם נתונים שניתן לייצג אותם כשורות בטבלאות או כאובייקטים במאגרי אובייקטים. השילוב תומך בארבעה תרחישי שימוש עיקריים:
+
+1. **חילוץ מנתונים לא מובנים לנתונים מובנים**: קריאת מקורות נתונים לא מובנים, זיהוי וחילוץ מבני אובייקטים, ואחסונם בפורמט טבלאי.
+2. **טעינת נתונים מובנים**: טעינת נתונים שכבר נמצאים בפורמטים מובנים ישירות לחנות הנתונים המובנים, יחד עם נתונים מחולצים.
+3. **שאילתות בשפה טבעית**: המרת שאלות בשפה טבעית לשאילתות מובנות כדי לחלץ נתונים תואמים מהחנות.
+4. **שאילתות מובנות ישירות**: ביצוע שאילתות מובנות ישירות מול מאגר הנתונים לשליפת נתונים מדויקת.
+
+## מטרות
+
+**גישה מאוחדת לנתונים**: מתן ממשק יחיד לגישה הן לנתונים מובנים והן לנתונים לא מובנים בתוך TrustGraph.
+**שילוב חלק**: אפשור תאימות הדוקה בין ייצוג הידע מבוסס הגרף של TrustGraph לבין פורמטים מובנים מסורתיים.
+**חילוץ גמיש**: תמיכה בחילוץ אוטומטי של נתונים מובנים ממקורות לא מובנים שונים (מסמכים, טקסט וכו').
+**גמישות שאילתא**: לאפשר למשתמשים לשאול נתונים באמצעות שפה טבעית ושפות שאילתא מובנות.
+**עקביות נתונים**: שמירה על שלמות ועקביות הנתונים בייצוגי נתונים שונים.
+**אופטימיזציה של ביצועים**: הבטחת אחסון ושליפה יעילים של נתונים מובנים בקנה מידה גדול.
+**גמישות סכימה**: תמיכה בגישות "סכימה בכתיבה" ו"סכימה בקריאה" כדי להתאים למקורות נתונים מגוונים.
+**תאימות לאחור**: שמירה על פונקציונליות קיימת של TrustGraph תוך הוספת יכולות נתונים מובנים.
+
+## רקע
+
+TrustGraph מצטיינת כיום בעיבוד נתונים לא מובנים ובבניית גרפי ידע ממקורות מגוונים. עם זאת, תרחישי שימוש רבים בארגונים כוללים נתונים המובנים מטבעם - רשומות לקוחות, יומני עסקאות, מסדי נתונים של מלאי וערכות נתונים טבלאיים אחרים. ערכות נתונים מובנות אלו לעתים קרובות צריכות להיות מנותחות יחד עם תוכן לא מובנה כדי לספק תובנות מקיפות.
+
+מגבלות נוכחיות כוללות:
+חוסר תמיכה מובנית בטעינת פורמטים מובנים מראש (CSV, מערכי JSON, יצוא מסדי נתונים).
+חוסר יכולת לשמור על המבנה הטבעי בעת חילוץ נתונים טבלאיים ממסמכים.
+היעדר מנגנוני שאילתא יעילים עבור דפוסי נתונים מובנים.
+חוסר גשר בין שאילתות בסגנון SQL לשאילתות גרפיות של TrustGraph.
+
+מפרט זה מתייחס לפערים אלה על ידי הצגת שכבת נתונים מובנים המשלימה את היכולות הקיימות של TrustGraph. על ידי תמיכה בנתונים מובנים באופן טבעי, TrustGraph יכולה:
+לשמש כפלטפורמה מאוחדת לניתוח נתונים מובנים ולא מובנים.
+לאפשר שאילתות היברידיות החוצות קשרי גרף ונתונים טבלאיים.
+לספק ממשקים מוכרים למשתמשים המורגלים לעבודה עם נתונים מובנים.
+לפתוח תרחישי שימוש חדשים בשילוב נתונים ובינה עסקית.
+
+## עיצוב טכני
+
+### ארכיטקטורה
+
+השילוב של נתונים מובנים דורש את הרכיבים הטכניים הבאים:
+
+1. **שירות NLP ל-Structured-Query**
+   ממיר שאלות בשפה טבעית לשאילתות מובנות.
+   תומך במספר יעדי שפת שאילתא (בשלב הראשוני תחביר בסגנון SQL).
+   משתלב עם יכולות NLP קיימות של TrustGraph.
+   
+   מודול: trustgraph-flow/trustgraph/query/nlp_query/cassandra
+
+2. **תמיכה בסכימה לתצורה** ✅ **[הושלם]**
+   מערכת תצורה מורחבת לאחסון סכימות נתונים מובנים.
+   תמיכה בהגדרת מבני טבלאות, סוגי שדות ויחסים.
+   יכולות גרסאות סכימה ומיגרציה.
+
+3. **מודול חילוץ אובייקטים** ✅ **[הושלם]**
+   שילוב משופר של זרימת חילוץ ידע.
+   מזהה ומחלץ אובייקטים מובנים ממקורות לא מובנים.
+   שומר על מוצא וציוני אמון.
+   רושם מטפל תצורה (לדוגמה: trustgraph-flow/trustgraph/prompt/template/service.py) כדי לקבל נתוני תצורה ולפענח מידע סכימה.
+   מקבל אובייקטים ומפענח אותם לאובייקטים של ExtractedObject לצורך העברה בתורת ההודעות Pulsar.
+   הערה: קיים קוד ב-`trustgraph-flow/trustgraph/extract/object/row/`. זו הייתה ניסיון קודם וצריך לשכתב אותו באופן משמעותי מכיוון שהוא אינו תואם ל-APIs הנוכחיים. השתמש בו אם זה שימושי, התחל מאפס אם לא.
+   דורש ממשק שורת פקודה: `kg-extract-objects`
+
+   מודול: trustgraph-flow/trustgraph/extract/kg/objects/
+
+4. **מודול כתיבת אחסון מובנה** ✅ **[הושלם]**
+   מקבל אובייקטים בפורמט ExtractedObject מתורי Pulsar.
+   יישום ראשוני המכוון ל-Apache Cassandra כאחסון נתונים מובנים.
+   מטפל ביצירת טבלאות דינמית על סמך סכימות המתגלות.
+   מנהל מיפוי סכימה לטבלאות Cassandra והמרת נתונים.
+   מספק פעולות כתיבה באצווה ובסטרימינג לשיפור ביצועים.
+   אין פלטים של Pulsar - זוהי שירות סופי בזרימת הנתונים.
+
+   **טיפול בסכימה**:
+   מנטר הודעות ExtractedObject נכנסות עבור הפניות סכימה.
+   כאשר מתגלה סכימה חדשה בפעם הראשונה, יוצרת טבלה באופן אוטומטי.
+   תומך בגישות "סכימה בקריאה" ו"סכימה בכתיבה" כדי להתאים למקורות נתונים מגוונים.
+   
+פלט חוזה (יש לעקוב בדיוק אחר הפורמט הבא).
+   **מיפוי טבלאות Cassandra**:
+   מרחב הנתונים (Keyspace) נקרא על שם השדה `user` מתוך מטא-הנתונים של ExtractedObject.
+   הטבלה נקראת על שם השדה `schema_name` מתוך ExtractedObject.
+   אוסף מתוך מטא-הנתונים הופך לחלק ממפתח המחיצה (partition key) כדי להבטיח:
+     התפלגות נתונים טבעית על פני צמתים של Cassandra.
+     שאילתות יעילות בתוך אוסף ספציפי.
+     בידוד לוגי בין יבוא נתונים/מקורות שונים.
+   מבנה מפתח ראשי: `PRIMARY KEY ((collection, <schema_primary_key_fields>), <clustering_keys>)`.
+     האוסף הוא תמיד הרכיב הראשון של מפתח המחיצה.
+     שדות מפתח ראשי המוגדרים בסכימה מופיעים כחלק ממפתח המחיצה המורכב.
+     זה דורש ששאילתות יציינו את האוסף, מה שמבטיח ביצועים צפויים.
+   הגדרות שדות ממופות לעמודות של Cassandra עם המרות סוג:
+     `string` → `text`.
+     `integer` → `int` או `bigint` בהתאם לרמז לגודל.
+     `float` → `float` או `double` בהתאם לדרישות דיוק.
+     `boolean` → `boolean`.
+     `timestamp` → `timestamp`.
+     `enum` → `text` עם אימות ברמת היישום.
+   שדות עם אינדקס יוצרים אינדקסים משניים של Cassandra (למעט שדות שכבר נמצאים במפתח הראשי).
+   שדות חובה מיושמים ברמת היישום (Cassandra אינה תומכת ב-NOT NULL).
+
+   **אחסון אובייקטים**:
+   מחלץ ערכים ממפת ExtractedObject.values.
+   מבצע המרת סוג ואימות לפני הכנסה.
+   מטפל בשדות אופציונליים חסרים בצורה חלקה.
+   שומר על מטא-נתונים לגבי מקור האובייקט (מסמך מקור, ציוני אמון).
+   תומך בכתיבות אידמפוטנטיות כדי לטפל בתרחישי שידור חוזר של הודעות.
+
+   **הערות יישום**:
+   קוד קיים ב-`trustgraph-flow/trustgraph/storage/objects/cassandra/` מיושן ואינו תואם ל-APIs הנוכחיים.
+   יש להתייחס ל-`trustgraph-flow/trustgraph/storage/triples/cassandra` כדוגמה למעבד אחסון תקין.
+   יש להעריך את הקוד הקיים כדי לזהות רכיבים שניתן לעשות בהם שימוש חוזר לפני שמחליטים לבצע שינוי מבני או כתיבה מחדש.
+
+   מודול: trustgraph-flow/trustgraph/storage/objects/cassandra
+
+5. **שירות שאילתות מובנה** ✅ **[הושלם]**
+   מקבל שאילתות מובנות בפורמטים מוגדרים.
+   מבצע שאילתות על הנתונים המובנים.
+   מחזיר אובייקטים התואמים לקריטריוני השאילתה.
+   תומך בדפדוף וסינון תוצאות.
+
+   מודול: trustgraph-flow/trustgraph/query/objects/cassandra
+
+6. **אינטגרציה עם כלי סוכן**:
+   מחלקת כלי חדשה עבור מסגרות סוכן.
+   מאפשר לסוכנים לשאול נתונים מובנים.
+   מספק ממשקי שפה טבעית ושאילתות מובנות.
+   משתלב עם תהליכי קבלת החלטות קיימים של סוכנים.
+
+7. **שירות הכנסת נתונים מובנים**:
+   מקבל נתונים מובנים בפורמטים מרובים (JSON, CSV, XML).
+   מנתח ומאמת נתונים נכנסים בהתאם לסכימות מוגדרות.
+   ממיר נתונים לזרמי אובייקטים מנורמלים.
+   פולט אובייקטים לתורי הודעות מתאימים לעיבוד.
+   תומך בהעלאות אצווה ובהכנסה רציפה.
+
+   מודול: trustgraph-flow/trustgraph/decoding/structured
+
+8. **שירות הטמעת אובייקטים**:
+   מייצר הטמעות וקטוריות עבור אובייקטים מובנים.
+   מאפשר חיפוש סמנטי על פני נתונים מובנים.
+   תומך בחיפוש היברידי המשלב שאילתות מובנות עם דמיון סמנטי.
+   משתלב עם מאגרי וקטורים קיימים.
+
+   מודול: trustgraph-flow/trustgraph/embeddings/object_embeddings/qdrant
+
+### מודלים של נתונים
+
+#### מנגנון אחסון סכימות
+
+סכימות מאוחסנות במערכת התצורה של TrustGraph באמצעות המבנה הבא:
+
+**סוג**: `schema` (ערך קבוע עבור כל סכימות הנתונים המובנים).
+**מפתח**: השם/מזהה הייחודי של הסכימה (לדוגמה, `customer_records`, `transaction_log`).
+**ערך**: הגדרת סכימת JSON המכילה את המבנה.
+
+רשומה לדוגמה בתצורה:
+```
+Type: schema
+Key: customer_records
+Value: {
+  "name": "customer_records",
+  "description": "Customer information table",
+  "fields": [
+    {
+      "name": "customer_id",
+      "type": "string",
+      "primary_key": true
+    },
+    {
+      "name": "name",
+      "type": "string",
+      "required": true
+    },
+    {
+      "name": "email",
+      "type": "string",
+      "required": true
+    },
+    {
+      "name": "registration_date",
+      "type": "timestamp"
+    },
+    {
+      "name": "status",
+      "type": "string",
+      "enum": ["active", "inactive", "suspended"]
+    }
+  ],
+  "indexes": ["email", "registration_date"]
+}
+```
+
+גישה זו מאפשרת:
+הגדרה דינמית של סכימה ללא שינויים בקוד
+עדכונים וגרסאות קלים של הסכימה
+אינטגרציה עקבית עם ניהול התצורה הקיים של TrustGraph
+תמיכה במספר סכימות בתוך פריסה אחת
+
+### ממשקי API
+
+ממשקי API חדשים:
+  סכימות Pulsar עבור הסוגים שלעיל
+  ממשקי Pulsar בזרמים חדשים
+  נדרש אמצעי לציין סוגי סכימה בזרמים כך שהזרמים ידעו אילו
+    סוגי סכימה לטעון
+  ממשקי API נוספו לשער ולשער ההיפוך
+
+ממשקי API ששונו:
+נקודות קצה לחילוץ ידע - הוספת אפשרות פלט של אובייקט מובנה
+נקודות קצה של סוכנים - הוספת תמיכה בכלי נתונים מובנים
+
+### פרטי יישום
+
+בהתאם לקונבנציות קיימות - אלו מודולים חדשים לעיבוד בלבד.
+הכל נמצא בחבילות trustgraph-flow למעט פריטי סכימה
+ב-trustgraph-base.
+
+נדרשת עבודה כלשהי בממשק המשתמש ב-Workbench כדי שניתן יהיה להדגים / לבצע פיילוט
+ליכולת זו.
+
+## שיקולי אבטחה
+
+אין שיקולים נוספים.
+
+## שיקולי ביצועים
+
+ישנן שאלות בנוגע לשימוש בשאילתות ואינדקסים של Cassandra כך ששאלות
+לא יאטו את העבודה.
+
+## אסטרטגיית בדיקה
+
+יש להשתמש באסטרטגיית בדיקה קיימת, ייבנו בדיקות יחידה, חוזה ואינטגרציה.
+
+## תוכנית מעבר
+
+אין.
+
+## ציר זמן
+
+לא צוין.
+
+## שאלות פתוחות
+
+האם ניתן לגרום לזה לעבוד עם סוגי אחסון אחרים? אנו שואפים להשתמש
+  בממשקים אשר הופכים מודולים שעובדים עם אחסון אחד ליישומיים
+  לאחסון אחר.
+
+## הפניות
+
+n/a.