# संरचित डेटा तकनीकी विनिर्देश

## अवलोकन

यह विनिर्देश ट्रस्टग्राफ को संरचित डेटा प्रवाह के साथ एकीकृत करने का वर्णन करता है, जिससे सिस्टम डेटा के साथ काम कर सके जिसे तालिकाओं में पंक्तियों या ऑब्जेक्ट स्टोर में ऑब्जेक्ट के रूप में दर्शाया जा सकता है। यह एकीकरण चार प्राथमिक उपयोग मामलों का समर्थन करता है:

1. **असंरचित से संरचित निष्कर्षण**: असंरचित डेटा स्रोतों को पढ़ें, ऑब्जेक्ट संरचनाओं की पहचान करें और उन्हें निकालें, और उन्हें एक सारणीबद्ध प्रारूप में संग्रहीत करें।
2. **संरचित डेटा का अंतर्ग्रहण**: डेटा को जो पहले से ही संरचित प्रारूपों में है, उसे सीधे संरचित स्टोर में निकाले गए डेटा के साथ लोड करें।
3. **प्राकृतिक भाषा प्रश्न**: प्राकृतिक भाषा के प्रश्नों को संरचित प्रश्नों में परिवर्तित करें ताकि स्टोर से मिलान करने वाले डेटा को निकाला जा सके।
4. **प्रत्यक्ष संरचित प्रश्न**: सटीक डेटा पुनर्प्राप्ति के लिए डेटा स्टोर के खिलाफ सीधे संरचित प्रश्नों को निष्पादित करें।

## लक्ष्य

**एकीकृत डेटा एक्सेस**: ट्रस्टग्राफ के भीतर संरचित और असंरचित दोनों डेटा तक पहुंचने के लिए एक एकल इंटरफ़ेस प्रदान करें।
**निर्बाध एकीकरण**: ट्रस्टग्राफ के ग्राफ-आधारित ज्ञान प्रतिनिधित्व और पारंपरिक संरचित डेटा प्रारूपों के बीच सुचारू अंतर-संचालन को सक्षम करें।
**लचीला निष्कर्षण**: विभिन्न असंरचित स्रोतों (दस्तावेज़, पाठ, आदि) से संरचित डेटा के स्वचालित निष्कर्षण का समर्थन करें।
**प्रश्न बहुमुखी प्रतिभा**: उपयोगकर्ताओं को प्राकृतिक भाषा और संरचित प्रश्न भाषाओं दोनों का उपयोग करके डेटा क्वेरी करने की अनुमति दें।
**डेटा स्थिरता**: विभिन्न डेटा प्रतिनिधित्व में डेटा अखंडता और स्थिरता बनाए रखें।
**प्रदर्शन अनुकूलन**: पैमाने पर संरचित डेटा के कुशल भंडारण और पुनर्प्राप्ति सुनिश्चित करें।
**स्कीमा लचीलापन**: विभिन्न डेटा स्रोतों को समायोजित करने के लिए स्कीमा-ऑन-राइट और स्कीमा-ऑन-रीड दोनों दृष्टिकोणों का समर्थन करें।
**पिछड़ा संगतता**: संरचित डेटा क्षमताओं को जोड़ते समय मौजूदा ट्रस्टग्राफ कार्यक्षमता को संरक्षित करें।

## पृष्ठभूमि

ट्रस्टग्राफ वर्तमान में असंरचित डेटा को संसाधित करने और विभिन्न स्रोतों से ज्ञान ग्राफ बनाने में उत्कृष्ट है। हालाँकि, कई उद्यम उपयोग मामलों में डेटा शामिल होता है जो स्वाभाविक रूप से संरचित होता है - ग्राहक रिकॉर्ड, लेनदेन लॉग, इन्वेंट्री डेटाबेस और अन्य सारणीबद्ध डेटासेट। इन संरचित डेटासेट का अक्सर व्यापक अंतर्दृष्टि प्रदान करने के लिए असंरचित सामग्री के साथ विश्लेषण करने की आवश्यकता होती है।

वर्तमान सीमाएँ शामिल हैं:
पूर्व-संरचित डेटा प्रारूपों (CSV, JSON सरणियों, डेटाबेस निर्यात) को अंतर्ग्रहण करने के लिए कोई देशी समर्थन नहीं।
दस्तावेज़ों से सारणीबद्ध डेटा निकालते समय अंतर्निहित संरचना को संरक्षित करने में असमर्थता।
संरचित डेटा पैटर्न के लिए कुशल प्रश्न तंत्र की कमी।
SQL-जैसे प्रश्नों और ट्रस्टग्राफ के ग्राफ प्रश्नों के बीच कोई पुल नहीं।

यह विनिर्देश इन कमियों को एक संरचित डेटा परत पेश करके संबोधित करता है जो ट्रस्टग्राफ की मौजूदा क्षमताओं को पूरक करता है। संरचित डेटा का मूल रूप से समर्थन करके, ट्रस्टग्राफ:
संरचित और असंरचित दोनों डेटा विश्लेषण के लिए एक एकीकृत मंच के रूप में कार्य कर सकता है।
ग्राफ संबंधों और सारणीबद्ध डेटा दोनों को कवर करने वाले हाइब्रिड प्रश्नों को सक्षम कर सकता है।
संरचित डेटा के साथ काम करने के लिए अभ्यस्त उपयोगकर्ताओं के लिए परिचित इंटरफेस प्रदान कर सकता है।
डेटा एकीकरण और व्यावसायिक बुद्धिमत्ता में नए उपयोग मामलों को अनलॉक कर सकता है।

## तकनीकी डिजाइन

### वास्तुकला

संरचित डेटा एकीकरण के लिए निम्नलिखित तकनीकी घटकों की आवश्यकता होती है:

1. **एनएलपी-टू-स्ट्रक्चर्ड-क्वेरी सेवा**
   प्राकृतिक भाषा के प्रश्नों को संरचित प्रश्नों में परिवर्तित करता है।
   कई प्रश्न भाषा लक्ष्यों का समर्थन करता है (प्रारंभ में SQL-जैसे सिंटैक्स)।
   मौजूदा ट्रस्टग्राफ एनएलपी क्षमताओं के साथ एकीकृत होता है।
   
   मॉड्यूल: trustgraph-flow/trustgraph/query/nlp_query/cassandra

2. **कॉन्फ़िगरेशन स्कीमा समर्थन** ✅ **[पूर्ण]**
   संरचित डेटा स्कीमा को संग्रहीत करने के लिए विस्तारित कॉन्फ़िगरेशन सिस्टम।
   तालिका संरचनाओं, फ़ील्ड प्रकारों और संबंधों को परिभाषित करने का समर्थन।
   स्कीमा संस्करण और माइग्रेशन क्षमताएं।

3. **ऑब्जेक्ट निष्कर्षण मॉड्यूल** ✅ **[पूर्ण]**
   बेहतर ज्ञान निष्कर्षण प्रवाह एकीकरण।
   असंरचित स्रोतों से संरचित ऑब्जेक्ट की पहचान और निष्कर्षण।
   उत्पत्ति और आत्मविश्वास स्कोर बनाए रखता है।
   एक कॉन्फ़िग हैंडलर (उदाहरण: trustgraph-flow/trustgraph/prompt/template/service.py) को कॉन्फ़िग डेटा प्राप्त करने और स्कीमा जानकारी को डिकोड करने के लिए पंजीकृत करता है।
   ऑब्जेक्ट प्राप्त करता है और उन्हें पल्सर कतार पर डिलीवरी के लिए एक्सट्रैक्टेडऑब्जेक्ट ऑब्जेक्ट में डिकोड करता है।
   ध्यान दें: `trustgraph-flow/trustgraph/extract/object/row/` पर मौजूदा कोड है। यह एक पिछला प्रयास था और इसे वर्तमान एपीआई के अनुरूप नहीं होने के कारण प्रमुख रूप से फिर से तैयार करने की आवश्यकता होगी। यदि यह उपयोगी है तो इसका उपयोग करें, यदि नहीं तो इसे खरोंच से शुरू करें।
   एक कमांड-लाइन इंटरफ़ेस की आवश्यकता है: `kg-extract-objects`

   मॉड्यूल: trustgraph-flow/trustgraph/extract/kg/objects/

4. **संरचित स्टोर लेखक मॉड्यूल** ✅ **[पूर्ण]**
   पल्सर कतारों से एक्सट्रैक्टेडऑब्जेक्ट प्रारूप में ऑब्जेक्ट प्राप्त करता है।
   Apache Cassandra को संरचित डेटा स्टोर के रूप में लक्षित करने वाला प्रारंभिक कार्यान्वयन।
   सामना किए गए स्कीमा के आधार पर गतिशील तालिका निर्माण को संभालता है।
   स्कीमा-से-कैसेंड्रा तालिका मैपिंग और डेटा परिवर्तन का प्रबंधन करता है।
   प्रदर्शन अनुकूलन के लिए बैच और स्ट्रीमिंग लेखन संचालन प्रदान करता है।
   कोई पल्सर आउटपुट नहीं - यह डेटा प्रवाह में एक टर्मिनल सेवा है।

   **स्कीमा हैंडलिंग**:
   स्कीमा संदर्भों के लिए आने वाले एक्सट्रैक्टेडऑब्जेक्ट संदेशों की निगरानी करता है।
   पहली बार जब एक नया स्कीमा सामना किया जाता है, तो स्वचालित रूप से संबंधित कैसेंड्रा तालिका बनाता है।
   ज्ञात स्कीमा के एक कैश को बनाए रखता है ताकि अनावश्यक तालिका निर्माण प्रयासों से बचा जा सके।
   इस पर विचार करना चाहिए कि स्कीमा परिभाषाएँ सीधे प्राप्त की जानी चाहिए या एक्सट्रैक्टेडऑब्जेक्ट संदेशों में स्कीमा नामों पर भरोसा किया जाना चाहिए।

   **कैसेंड्रा टेबल मैपिंग**:
   कीस्पेस का नाम एक्सट्रैक्टेडऑब्जेक्ट के मेटाडेटा से `user` फ़ील्ड से लिया गया है।
   टेबल का नाम एक्सट्रैक्टेडऑब्जेक्ट से `schema_name` फ़ील्ड से लिया गया है।
   मेटाडेटा से कलेक्शन को पार्टीशन कुंजी का हिस्सा बनाया जाता है ताकि:
     कैसेंड्रा नोड्स में डेटा का प्राकृतिक वितरण सुनिश्चित हो सके।
     एक विशिष्ट कलेक्शन के भीतर कुशल क्वेरीज़ संभव हों।
     विभिन्न डेटा आयात/स्रोत के बीच तार्किक अलगाव सुनिश्चित हो सके।
   प्राइमरी की संरचना: `PRIMARY KEY ((collection, <schema_primary_key_fields>), <clustering_keys>)`
     कलेक्शन हमेशा पार्टीशन कुंजी का पहला घटक होता है।
     स्कीमा-परिभाषित प्राइमरी की फ़ील्ड, समग्र पार्टीशन कुंजी का हिस्सा होते हैं।
     इसके लिए क्वेरीज़ में कलेक्शन को निर्दिष्ट करने की आवश्यकता होती है, जिससे प्रदर्शन पूर्वानुमेय रहता है।
   फ़ील्ड परिभाषाएँ कैसेंड्रा कॉलम में टाइप रूपांतरण के साथ मैप होती हैं:
     `string` → `text`
     `integer` → `int` या `bigint`, आकार के संकेत के आधार पर।
     `float` → `float` या `double`, परिशुद्धता की आवश्यकताओं के आधार पर।
     `boolean` → `boolean`
     `timestamp` → `timestamp`
     `enum` → `text`, एप्लिकेशन-स्तरीय सत्यापन के साथ।
   अनुक्रमित फ़ील्ड कैसेंड्रा सेकेंडरी इंडेक्स बनाते हैं (प्राइमरी कुंजी में पहले से मौजूद फ़ील्ड को छोड़कर)।
   आवश्यक फ़ील्ड एप्लिकेशन स्तर पर लागू किए जाते हैं (कैसेंड्रा NOT NULL का समर्थन नहीं करता है)।

   **ऑब्जेक्ट स्टोरेज**:
   एक्सट्रैक्टेडऑब्जेक्ट.वैल्यूज़ मैप से मान निकाले जाते हैं।
   सम्मिलन से पहले टाइप रूपांतरण और सत्यापन किया जाता है।
   गुम वैकल्पिक फ़ील्ड को कुशलतापूर्वक संभाला जाता है।
   ऑब्जेक्ट की उत्पत्ति के बारे में मेटाडेटा बनाए रखा जाता है (स्रोत दस्तावेज़, आत्मविश्वास स्कोर)।
   संदेश पुनरावृत्ति परिदृश्यों को संभालने के लिए आइडेंपोटेंट राइट का समर्थन करता है।

   **कार्यान्वयन नोट्स**:
   `trustgraph-flow/trustgraph/storage/objects/cassandra/` पर मौजूद मौजूदा कोड पुराना है और वर्तमान एपीआई के अनुरूप नहीं है।
   `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

### डेटा मॉडल:

#### स्कीमा स्टोरेज मैकेनिज्म:

स्कीमा को ट्रस्टग्राफ की कॉन्फ़िगरेशन प्रणाली में निम्नलिखित संरचना का उपयोग करके संग्रहीत किया जाता है:

**टाइप**: `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"]
}
```

यह दृष्टिकोण निम्नलिखित कार्य करने की अनुमति देता है:
कोड में बदलाव किए बिना गतिशील स्कीमा परिभाषा
आसान स्कीमा अपडेट और संस्करण
मौजूदा ट्रस्टग्राफ कॉन्फ़िगरेशन प्रबंधन के साथ सुसंगत एकीकरण
एक ही परिनियोजन में एकाधिक स्कीमा के लिए समर्थन

### एपीआई

नए एपीआई:
  ऊपर दिए गए प्रकारों के लिए पल्सर स्कीमा
  नए फ्लो में पल्सर इंटरफेस
  फ्लो को यह जानने के लिए कि कौन से
    स्कीमा प्रकार लोड करने हैं, फ्लो में स्कीमा प्रकारों को निर्दिष्ट करने का एक तरीका आवश्यक है।
  गेटवे और रिव-गेटवे में जोड़े गए एपीआई

संशोधित एपीआई:
नॉलेज एक्सट्रैक्शन एंडपॉइंट - संरचित ऑब्जेक्ट आउटपुट विकल्प जोड़ें
एजेंट एंडपॉइंट - संरचित डेटा टूल समर्थन जोड़ें

### कार्यान्वयन विवरण

मौजूदा सम्मेलनों का पालन करें - ये केवल नए प्रोसेसिंग मॉड्यूल हैं।
सब कुछ ट्रस्टग्राफ-फ्लो पैकेजों में है, सिवाय ट्रस्टग्राफ-बेस में स्कीमा आइटम के।


इस क्षमता का प्रदर्शन/पायलट करने के लिए वर्कबेंच में कुछ यूआई कार्य की आवश्यकता है।


## सुरक्षा संबंधी विचार

कोई अतिरिक्त विचार नहीं।

## प्रदर्शन संबंधी विचार

कैसेंड्रा प्रश्नों और इंडेक्स का उपयोग करने के बारे में कुछ प्रश्न हैं ताकि प्रश्न धीमे न हों।

## परीक्षण रणनीति

मौजूदा परीक्षण रणनीति का उपयोग करें, यूनिट, कॉन्ट्रैक्ट और एकीकरण परीक्षण बनाए जाएंगे।

## माइग्रेशन योजना

कोई नहीं।

## समयरेखा

निर्दिष्ट नहीं है।

## खुले प्रश्न


क्या इसे अन्य स्टोर प्रकारों के साथ काम करने के लिए बनाया जा सकता है? हम इंटरफेस का उपयोग करने का लक्ष्य रख रहे हैं जो एक स्टोर के साथ काम करने वाले मॉड्यूल को अन्य स्टोर पर लागू करने योग्य बनाते हैं।
  
  ## संदर्भ

लागू नहीं।