# GraphQL क्वेरी तकनीकी विनिर्देश

## अवलोकन

यह विनिर्देश अपाचे कैसेंड्रा में ट्रस्टग्राफ के संरचित डेटा भंडारण के लिए एक GraphQL क्वेरी इंटरफ़ेस के कार्यान्वयन का वर्णन करता है। संरचित-डेटा.md विनिर्देश में उल्लिखित संरचित डेटा क्षमताओं पर निर्माण करते हुए, यह दस्तावेज़ बताता है कि निकाले गए और संसाधित संरचित ऑब्जेक्ट युक्त कैसेंड्रा तालिकाओं के खिलाफ GraphQL क्वेरी कैसे निष्पादित की जाएंगी।

GraphQL क्वेरी सेवा कैसेंड्रा में संग्रहीत संरचित डेटा के लिए एक लचीला, टाइप-सुरक्षित इंटरफ़ेस प्रदान करेगी। यह स्कीमा परिवर्तनों के लिए गतिशील रूप से अनुकूल होगा, ऑब्जेक्ट के बीच संबंधों सहित जटिल प्रश्नों का समर्थन करेगा, और ट्रस्टग्राफ के मौजूदा संदेश-आधारित वास्तुकला के साथ सहजता से एकीकृत होगा।

## लक्ष्य

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

## पृष्ठभूमि

संरचित डेटा भंडारण कार्यान्वयन (trustgraph-flow/trustgraph/storage/objects/cassandra/) ट्रस्टग्राफ के कॉन्फ़िगरेशन सिस्टम में संग्रहीत स्कीमा परिभाषाओं के आधार पर कैसेंड्रा तालिकाओं में ऑब्जेक्ट लिखता है। ये तालिकाएँ एक समग्र विभाजन कुंजी संरचना का उपयोग करती हैं जिसमें संग्रह और स्कीमा-परिभाषित प्राथमिक कुंजियाँ होती हैं, जो संग्रह के भीतर कुशल प्रश्नों को सक्षम करती हैं।

वर्तमान सीमाएँ जिन्हें इस विनिर्देश द्वारा संबोधित किया गया है:
कैसेंड्रा में संग्रहीत संरचित डेटा के लिए कोई क्वेरी इंटरफ़ेस नहीं।
संरचित डेटा के लिए GraphQL की शक्तिशाली क्वेरी क्षमताओं का लाभ उठाने में असमर्थता।
संबंधित ऑब्जेक्ट के बीच संबंध ट्रैवर्सल के लिए कोई समर्थन नहीं।
संरचित डेटा एक्सेस के लिए एक मानकीकृत क्वेरी भाषा का अभाव।

GraphQL क्वेरी सेवा इन कमियों को भरकर:
कैसेंड्रा तालिकाओं के लिए एक मानक GraphQL इंटरफ़ेस प्रदान करना।
ट्रस्टग्राफ कॉन्फ़िगरेशन से गतिशील रूप से GraphQL स्कीमा उत्पन्न करना।
कुशलतापूर्वक GraphQL क्वेरी को कैसेंड्रा CQL में अनुवाद करना।
फ़ील्ड रिज़ॉल्वर के माध्यम से संबंध संकल्प का समर्थन करना।

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

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

GraphQL क्वेरी सेवा को एक नए ट्रस्टग्राफ फ्लो प्रोसेसर के रूप में लागू किया जाएगा जो स्थापित पैटर्न का पालन करता है:

**मॉड्यूल स्थान**: `trustgraph-flow/trustgraph/query/objects/cassandra/`

**मुख्य घटक**:

1. **GraphQL क्वेरी सेवा प्रोसेसर**
   बेस FlowProcessor क्लास का विस्तार करता है।
   मौजूदा क्वेरी सेवाओं के समान अनुरोध/प्रतिक्रिया पैटर्न को लागू करता है।
   स्कीमा अपडेट के लिए कॉन्फ़िगरेशन की निगरानी करता है।
   कॉन्फ़िगरेशन के साथ GraphQL स्कीमा को सिंक्रनाइज़ रखता है।

2. **गतिशील स्कीमा जनरेटर**
   ट्रस्टग्राफ RowSchema परिभाषाओं को GraphQL प्रकारों में परिवर्तित करता है।
   उचित फ़ील्ड परिभाषाओं के साथ GraphQL ऑब्जेक्ट प्रकार बनाता है।
   संग्रह-आधारित रिज़ॉल्वर के साथ रूट क्वेरी प्रकार उत्पन्न करता है।
   जब कॉन्फ़िगरेशन बदलता है तो GraphQL स्कीमा को अपडेट करता है।

3. **क्वेरी निष्पादक**
   Strawberry लाइब्रेरी का उपयोग करके आने वाली GraphQL क्वेरी को पार्स करता है।
   वर्तमान स्कीमा के विरुद्ध क्वेरी को मान्य करता है।
   क्वेरी निष्पादित करता है और संरचित प्रतिक्रियाएँ लौटाता है।
   विस्तृत त्रुटि संदेशों के साथ त्रुटियों को कुशलतापूर्वक संभालता है।

4. **कैसेंड्रा क्वेरी अनुवादक**
   GraphQL चयन को CQL क्वेरी में परिवर्तित करता है।
   उपलब्ध अनुक्रमणिकाओं और विभाजन कुंजियों के आधार पर क्वेरी को अनुकूलित करता है।
   फ़िल्टरिंग, पेजिंग और सॉर्टिंग को संभालता है।
   कनेक्शन पूलिंग और सत्र जीवनचक्र का प्रबंधन करता है।

5. **संबंध रिज़ॉल्वर**
   ऑब्जेक्ट संबंधों के लिए फ़ील्ड रिज़ॉल्वर को लागू करता है।
   N+1 क्वेरी से बचने के लिए कुशल बैच लोडिंग करता है।
   अनुरोध संदर्भ के भीतर हल किए गए संबंधों को कैश करता है।
   आगे और पीछे दोनों संबंध ट्रैवर्सल का समर्थन करता है।

### कॉन्फ़िगरेशन स्कीमा निगरानी

सेवा स्कीमा अपडेट प्राप्त करने के लिए एक कॉन्फ़िगरेशन हैंडलर को पंजीकृत करेगी:

```python
self.register_config_handler(self.on_schema_config)
```

जब स्कीमा बदलते हैं:
1. कॉन्फ़िगरेशन से नए स्कीमा परिभाषाओं को पार्स करें।
2. GraphQL प्रकारों और रिज़ॉल्वरों को फिर से उत्पन्न करें।
3. निष्पादन योग्य स्कीमा को अपडेट करें।
4. किसी भी स्कीमा-निर्भर कैश को साफ़ करें।

### GraphQL स्कीमा पीढ़ी

कॉन्फ़िगरेशन में प्रत्येक RowSchema के लिए, निम्नलिखित उत्पन्न करें:

1. **GraphQL ऑब्जेक्ट टाइप**:
   फ़ील्ड प्रकारों को मैप करें (string → String, integer → Int, float → Float, boolean → Boolean)।
   आवश्यक फ़ील्ड को GraphQL में गैर-शून्य के रूप में चिह्नित करें।
   स्कीमा से फ़ील्ड विवरण जोड़ें।

2. **रूट क्वेरी फ़ील्ड**:
   संग्रह क्वेरी (जैसे, `customers`, `transactions`)।
   अनुक्रमित फ़ील्ड के आधार पर फ़िल्टरिंग तर्क।
   पेजिंग समर्थन (सीमा, ऑफ़सेट)।
   सॉर्ट करने योग्य फ़ील्ड के लिए सॉर्टिंग विकल्प।

3. **रिलेशनशिप फ़ील्ड**:
   स्कीमा से विदेशी कुंजी संबंधों की पहचान करें।
   संबंधित ऑब्जेक्ट के लिए फ़ील्ड रिज़ॉल्वर बनाएं।
   एकल ऑब्जेक्ट और सूची दोनों संबंधों का समर्थन करें।

### क्वेरी निष्पादन प्रवाह

1. **अनुरोध स्वागत**:
   Pulsar से ObjectsQueryRequest प्राप्त करें।
   GraphQL क्वेरी स्ट्रिंग और चर निकालें।
   उपयोगकर्ता और संग्रह संदर्भ की पहचान करें।

2. **क्वेरी सत्यापन**:
   Strawberry का उपयोग करके GraphQL क्वेरी को पार्स करें।
   वर्तमान स्कीमा के विरुद्ध मान्य करें।
   फ़ील्ड चयन और तर्क प्रकारों की जांच करें।

3. **CQL पीढ़ी**:
   GraphQL चयन का विश्लेषण करें।
   उचित WHERE खंडों के साथ CQL क्वेरी बनाएं।
   विभाजन कुंजी में संग्रह शामिल करें।
   GraphQL तर्कों के आधार पर फ़िल्टर लागू करें।

4. **क्वेरी निष्पादन**:
   Cassandra के खिलाफ CQL क्वेरी निष्पादित करें।
   परिणामों को GraphQL प्रतिक्रिया संरचना में मैप करें।
   किसी भी रिलेशनशिप फ़ील्ड को हल करें।
   GraphQL विनिर्देश के अनुसार प्रतिक्रिया को प्रारूपित करें।

5. **प्रतिक्रिया वितरण**:
   परिणामों के साथ ObjectsQueryResponse बनाएं।
   किसी भी निष्पादन त्रुटि को शामिल करें।
   सहसंबंध आईडी के साथ Pulsar के माध्यम से प्रतिक्रिया भेजें।

### डेटा मॉडल

> **ध्यान दें**: `trustgraph-base/trustgraph/schema/services/structured_query.py` में एक मौजूदा StructuredQueryRequest/Response स्कीमा मौजूद है। हालाँकि, इसमें महत्वपूर्ण फ़ील्ड (उपयोगकर्ता, संग्रह) की कमी है और यह उप-इष्टतम प्रकारों का उपयोग करता है। नीचे दिए गए स्कीमा अनुशंसित विकास का प्रतिनिधित्व करते हैं, जिसे या तो मौजूदा स्कीमा को बदलने के लिए या नए 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` फ़ील्ड जोड़े गए।
ये फ़ील्ड कैसेंड्रा की स्पेस और कलेक्शन की पहचान करने के लिए आवश्यक हैं।
वेरिएबल अभी भी 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 ऑब्जेक्ट का उपयोग करता है।
GraphQL विनिर्देश के अनुपालन के लिए `extensions` फ़ील्ड जोड़ता है।
अनुकूलता के लिए डेटा को JSON स्ट्रिंग के रूप में रखता है, हालांकि मूल प्रकार बेहतर होंगे।

### कैसेंड्रा क्वेरी अनुकूलन

सेवा कैसेंड्रा क्वेरी को इस प्रकार अनुकूलित करेगी:

1. **पार्टिशन कुंजियों का सम्मान करना:**
   हमेशा क्वेरी में संग्रह शामिल करें।
   स्कीमा-परिभाषित प्राथमिक कुंजियों का कुशलतापूर्वक उपयोग करें।
   पूर्ण तालिका स्कैन से बचें।

2. **सूचकांकों का उपयोग करना:**
   फ़िल्टरिंग के लिए द्वितीयक सूचकांकों का उपयोग करें।
   जब संभव हो, तो कई फ़िल्टरों को मिलाएं।
   चेतावनी दें जब क्वेरी अक्षम हो सकती हैं।

3. **बैच लोडिंग:**
   संबंध क्वेरी एकत्र करें।
   राउंड ट्रिप को कम करने के लिए बैचों में निष्पादित करें।
   अनुरोध संदर्भ के भीतर परिणामों को कैश करें।

4. **कनेक्शन प्रबंधन:**
   लगातार कैसेंड्रा सत्र बनाए रखें।
   कनेक्शन पूलिंग का उपयोग करें।
   विफलताओं पर पुनः कनेक्शन को संभालें।

### उदाहरण 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)**: ग्राफक्यूएल स्कीमा परिभाषा और क्वेरी निष्पादन के लिए
**कैसेंड्रा ड्राइवर (Cassandra Driver)**: डेटाबेस कनेक्टिविटी के लिए (भंडारण मॉड्यूल में पहले से उपयोग किया गया)
**ट्रस्टग्राफ बेस (TrustGraph Base)**: फ्लोप्रोसेसर और स्कीमा परिभाषाओं के लिए
**कॉन्फ़िगरेशन सिस्टम (Configuration System)**: स्कीमा निगरानी और अपडेट के लिए

### कमांड-लाइन इंटरफ़ेस

सेवा एक CLI कमांड प्रदान करेगी: `kg-query-objects-graphql-cassandra`

तर्क:
`--cassandra-host`: कैसेंड्रा क्लस्टर संपर्क बिंदु
`--cassandra-username`: प्रमाणीकरण उपयोगकर्ता नाम
`--cassandra-password`: प्रमाणीकरण पासवर्ड
`--config-type`: स्कीमा के लिए कॉन्फ़िगरेशन प्रकार (डिफ़ॉल्ट: "स्कीमा")
मानक फ्लोप्रोसेसर तर्क (पल्सर कॉन्फ़िगरेशन, आदि)

## एपीआई एकीकरण

### पल्सर विषय (Pulsar Topics)

**इनपुट टॉपिक (Input Topic)**: `objects-graphql-query-request`
स्कीमा: ऑब्जेक्ट्सक्वेरीरिक्वेस्ट (ObjectsQueryRequest)
गेटवे सेवाओं से ग्राफक्यूएल क्वेरी प्राप्त करता है

**आउटपुट टॉपिक (Output Topic)**: `objects-graphql-query-response`
स्कीमा: ऑब्जेक्ट्सक्वेरीरिस्पांस (ObjectsQueryResponse)
क्वेरी परिणाम और त्रुटियां लौटाता है

### गेटवे एकीकरण

गेटवे और रिवर्स-गेटवे को निम्नलिखित के लिए एंडपॉइंट की आवश्यकता होगी:
1. क्लाइंट से ग्राफक्यूएल क्वेरी स्वीकार करें
2. पल्सर के माध्यम से क्वेरी सेवा को आगे बढ़ाएं
3. क्लाइंट को प्रतिक्रियाएं लौटाएं
4. ग्राफक्यूएल इंट्रॉस्पेक्शन क्वेरी का समर्थन करें

### एजेंट टूल एकीकरण

एक नया एजेंट टूल क्लास निम्नलिखित को सक्षम करेगा:
प्राकृतिक भाषा से ग्राफक्यूएल क्वेरी पीढ़ी
प्रत्यक्ष ग्राफक्यूएल क्वेरी निष्पादन
परिणाम व्याख्या और स्वरूपण
एजेंट निर्णय प्रवाह के साथ एकीकरण

## सुरक्षा विचार

**क्वेरी गहराई सीमित करना (Query Depth Limiting)**: गहराई से नेस्टेड क्वेरी को रोकें जो प्रदर्शन समस्याओं का कारण बन सकती हैं
**क्वेरी जटिलता विश्लेषण (Query Complexity Analysis)**: संसाधन समाप्त होने से रोकने के लिए क्वेरी जटिलता को सीमित करें
**फ़ील्ड-लेवल अनुमतियाँ (Field-Level Permissions)**: उपयोगकर्ता भूमिकाओं के आधार पर फ़ील्ड-लेवल एक्सेस नियंत्रण के लिए भविष्य का समर्थन
**इनपुट सैनिटाइजेशन (Input Sanitization)**: इंजेक्शन हमलों को रोकने के लिए सभी क्वेरी इनपुट को मान्य और सैनिटाइज करें
**दर सीमित करना (Rate Limiting)**: प्रति उपयोगकर्ता/संग्रहण क्वेरी दर सीमित करना लागू करें

## प्रदर्शन विचार

**क्वेरी योजना (Query Planning)**: सीक्यूएल पीढ़ी को अनुकूलित करने के लिए निष्पादन से पहले क्वेरी का विश्लेषण करें
**परिणाम कैशिंग (Result Caching)**: फ़ील्ड रिज़ॉल्वर स्तर पर बार-बार एक्सेस किए जाने वाले डेटा को कैश करने पर विचार करें
**कनेक्शन पूलिंग (Connection Pooling)**: कैसेंड्रा के लिए कुशल कनेक्शन पूल बनाए रखें
**बैच ऑपरेशन (Batch Operations)**: जब भी संभव हो, कई क्वेरी को संयोजित करें ताकि विलंबता कम हो सके
**निगरानी (Monitoring)**: अनुकूलन के लिए क्वेरी प्रदर्शन मेट्रिक्स को ट्रैक करें

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

### यूनिट परीक्षण
रोस्कीमा परिभाषाओं से स्कीमा पीढ़ी
ग्राफक्यूएल क्वेरी पार्सिंग और सत्यापन
सीक्यूएल क्वेरी पीढ़ी तर्क
फ़ील्ड रिज़ॉल्वर कार्यान्वयन

### अनुबंध परीक्षण
पल्सर संदेश अनुबंध अनुपालन
ग्राफक्यूएल स्कीमा वैधता
प्रतिक्रिया प्रारूप सत्यापन
त्रुटि संरचना सत्यापन

### एकीकरण परीक्षण
परीक्षण कैसेंड्रा उदाहरण के खिलाफ एंड-टू-एंड क्वेरी निष्पादन
स्कीमा अपडेट हैंडलिंग
संबंध संकल्प
पेजिंग और फ़िल्टरिंग
त्रुटि परिदृश्य

### प्रदर्शन परीक्षण
लोड के तहत क्वेरी थ्रूपुट
विभिन्न क्वेरी जटिलताओं के लिए प्रतिक्रिया समय
बड़े परिणाम सेट के साथ मेमोरी उपयोग
कनेक्शन पूल दक्षता

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

इस नई क्षमता के रूप में माइग्रेशन की आवश्यकता नहीं है। सेवा निम्नलिखित करेगी:
1. कॉन्फ़िगरेशन से मौजूदा स्कीमा पढ़ें
2. स्टोरेज मॉड्यूल द्वारा बनाए गए मौजूदा कैसेंड्रा तालिकाओं से कनेक्ट करें
3. तैनाती पर तुरंत क्वेरी स्वीकार करना शुरू करें

## समयरेखा

सप्ताह 1-2: कोर सेवा कार्यान्वयन और स्कीमा पीढ़ी
सप्ताह 3: क्वेरी निष्पादन और सीक्यूएल अनुवाद
सप्ताह 4: संबंध संकल्प और अनुकूलन
सप्ताह 5: परीक्षण और प्रदर्शन ट्यूनिंग
सप्ताह 6: गेटवे एकीकरण और प्रलेखन

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

1. **स्कीमा विकास (Schema Evolution)**: सेवा स्कीमा संक्रमण के दौरान क्वेरी को कैसे संभालती है?
   विकल्प: स्कीमा अपडेट के दौरान क्वेरी को कतार में लगाएं
   विकल्प: एक साथ कई स्कीमा संस्करणों का समर्थन करें

2. **कैशिंग रणनीति (Caching Strategy)**: क्या क्वेरी परिणामों को कैश किया जाना चाहिए?
   विचार करें: समय-आधारित समाप्ति
   विचार करें: घटना-आधारित अमान्यकरण

3. **संघटन समर्थन (Federation Support)**: क्या सेवा अन्य डेटा स्रोतों के साथ संयोजन के लिए ग्राफक्यूएल संघटन का समर्थन करना चाहिए?
   यह संरचित और ग्राफ डेटा में एकीकृत क्वेरी को सक्षम करेगा

4. **सदस्यता समर्थन (Subscription Support)**: क्या सेवा वास्तविक समय अपडेट के लिए ग्राफक्यूएल सदस्यता का समर्थन करना चाहिए?
   

5. **कस्टम स्केलर:** क्या डोमेन-विशिष्ट डेटा प्रकारों के लिए कस्टम स्केलर प्रकारों का समर्थन किया जाना चाहिए?
   उदाहरण: DateTime, UUID, JSON फ़ील्ड

## संदर्भ

स्ट्रक्चर्ड डेटा तकनीकी विनिर्देश: `docs/tech-specs/structured-data.md`
स्ट्रॉबेरी GraphQL दस्तावेज़: https://strawberry.rocks/
GraphQL विनिर्देश: https://spec.graphql.org/
अपाचे कैसेंड्रा CQL संदर्भ: https://cassandra.apache.org/doc/stable/cassandra/cql/
ट्रस्टग्राफ फ्लो प्रोसेसर दस्तावेज़: आंतरिक दस्तावेज़