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

<<<<<<< HEAD
# Vipimo vya Kiufundi vya Umasilisho wa GraphQL

## Muhtasari

Maelekezo haya yanaelezea utekelezaji wa kiolesura cha uwasilisho wa GraphQL kwa kuhifadhi data iliyopangwa ya TrustGraph katika Apache Cassandra. Kujenga juu ya uwezo wa data iliyopangwa uliyoainishwa katika maelekezo ya structured-data.md, hati hii inaeleza jinsi maswali ya GraphQL yanavyotekelezwa dhidi ya meza za Cassandra zinazokuza vitu vilivyochukuliwa na vilivyomingwa.

Huduma ya uwasilisho wa GraphQL itatoa kiolesura kinachobadilika na kinacholingana na aina kwa kuuliza data iliyopangwa iliyohifadhiwa katika Cassandra. Itabadilika moja kwa moja kwa mabadiliko ya mpango, inasaidia maswali tata ikiwa ni pamoja na uhusiano kati ya vitu, na itounganisha kikamilifu na usanifu uliopo wa TrustGraph unaotegemea ujumbe.

## Lengo

**Usaidizi wa Mpango Unaobadilika**: Kujifunga kiotomatiki kwa mabadiliko ya mpango bila kuacha huduma
**Uzingatiaji wa Viwango vya GraphQL**: Kutoa kiolesura cha kawaida cha GraphQL kinacholingana na zana na wateja wa GraphQL iliyopo
**Maswali ya Ufanisi ya Cassandra**: Kubadilisha maswali ya GraphQL kuwa maswali ya ufanisi ya Cassandra CQL kwa kuheshimu funguo za sehemu na fahirisi
**Suluhisho la Uhusiano**: Kusaidia suluhu za GraphQL kwa uhusiano kati ya aina tofauti za vitu
**Usalama wa Aina**: Kuhakikisha utekelezaji wa aina-salama wa maswali na utengenezaji wa majibu kulingana na maelezo ya mpango
**Utendaji Unaoweza Kukidhi Mahitaji**: Kushughulikia maswali mengi kwa ufanisi kwa kutumia udhibiti wa muunganisho na uboreshaji wa maswali
**Ujumuishaji wa Ombi/Jibu**: Kuhifadhi utangamano na mtindo wa ombi/jibu wa TrustGraph unaotegemea Pulsar
**Usimamizi wa Makosa**: Kutoa ripoti kamili ya makosa kwa kutofautiana kwa mpango, makosa ya maswali, na masuala ya uthibitisho wa data

## Asili

Utekelezaji wa uhifadhi wa data iliyopangwa (trustgraph-flow/trustgraph/storage/objects/cassandra/) huandika vitu kwenye meza za Cassandra kulingana na maelezo ya mpango yaliyohifadhiwa katika mfumo wa usanidi wa TrustGraph. Meza hizi hutumia muundo wa funguo ya sehemu iliyounganishwa na funguo za msingi zilizobainishwa na mpango, na kuwezesha maswali ya ufanisi ndani ya makusanyo.

Marekebisho ya sasa ambayo maelekezo haya yanaashiria:
Hakuna kiolesura cha kuuliza kwa data iliyopangwa iliyohifadhiwa katika Cassandra
Uwasilishaji usio wa uwezo wa uwezo wa maswali ya GraphQL kwa data iliyopangwa
Usaidizi usio na uhusiano kati ya vitu vinavyohusiana
Ukosefu wa lugha ya kawaida ya kuuliza kwa upataji wa data iliyopangwa

Huduma ya uwasilisho wa GraphQL itafunga pengo hizi kwa:
Kutoa kiolesura cha kawaida cha GraphQL kwa kuuliza meza za Cassandra
Kujenga schemas za GraphQL kwa moja kwa moja kutoka usanidi wa TrustGraph
Kubadilisha maswali ya GraphQL kwa ufanisi kwa CQL ya Cassandra
Kusaidia suluhisho la uhusiano kupitia suluhu za uwanja

## Ubunifu wa Kiufundi

### Usanifu

Huduma ya uwasilisho wa GraphQL itatekelezwa kama mchakato mpya wa TrustGraph kufuatia mbinu zilizopo:
=======
# Vipimo vya Kiufundi vya Ulinganisho wa GraphQL

## Muhtasari

Maelezo haya yanaeleza utekelezaji wa kiolesura cha ulinganisho wa GraphQL kwa kuhifadhi data iliyopangwa ya TrustGraph katika Apache Cassandra. Kujenga juu ya uwezo wa data iliyopangwa uliotajwa katika maelezo ya structured-data.md, hati hii inaeleza jinsi ulinganisho wa GraphQL utakavyotekelezwa dhidi ya meza za Cassandra zinazozingatia vitu vilivyochukuliwa na kuingizwa.

Huduma ya ulinganisho wa GraphQL itatoa kiolesura kinachobadilika na kinacholingana na aina kwa ulinganisho wa data iliyopangwa iliyohifadhiwa katika Cassandra. Itabadilika moja kwa moja kulingana na mabadiliko ya muundo, itaidhinisha ulinganisho tata ikiwa ni pamoja na uhusiano kati ya vitu, na itounganisha kikamilifu na usanifu uliopo wa TrustGraph unaotegemea ujumbe.

## Lengo

**Usaidizi wa Muundo Unaobadilika**: Kujifunga kiotomatiki na mabadiliko ya muundo katika usanidi bila kuacha huduma
**Uzingatiaji wa Viwango vya GraphQL**: Kutoa kiolesura cha kawaida cha GraphQL kinacholingana na zana na wateja wa GraphQL iliyopo
**Ulinganisho wa Ufanisi wa Cassandra**: Kubadilisha ulinganisho wa GraphQL kuwa ulinganisho wa CQL wa Cassandra unaofaa kwa kuheshimu funguo za sehemu na fahirisi
**Suluhisho la Uhusiano**: Kusaidia suluhu za GraphQL kwa uhusiano kati ya aina tofauti za vitu
**Usalama wa Aina**: Kuhakikisha utekelezaji wa ulinganisho salama wa aina na uzalishaji wa majibu kulingana na ufafanuzi wa muundo
**Utendaji Unaoweza Kukidhi Mahitaji**: Kushughulikia ulinganisho wa wakati mmoja kwa ufanisi kwa kutumia udhibiti wa muunganisho na uboreshaji wa ulinganisho
**Ujumuishaji wa Ombi/Jibu**: Kuhifadhi utangamano na mtindo wa ombi/jibu wa TrustGraph unaotegemea Pulsar
**Usimamizi wa Makosa**: Kutoa ripoti kamili ya makosa kwa kutofautiana kwa muundo, makosa ya ulinganisho, na masuala ya uthibitisho wa data

## Asili

Utekelezaji wa uhifadhi wa data iliyopangwa (trustgraph-flow/trustgraph/storage/objects/cassandra/) huandika vitu kwenye meza za Cassandra kulingana na ufafanuzi wa muundo uliohifadhiwa katika mfumo wa usanidi wa TrustGraph. Meza hizi hutumia muundo wa funguo ya sehemu iliyounganishwa na funguo za msingi zilizobainishwa na muundo, na kuwezesha ulinganisho wa ufanisi ndani ya mikusanyiko.

Marekebisho ya sasa ambayo maelezo haya yanaashiria:
Hakuna kiolesura cha ulinganisho kwa data iliyopangwa iliyohifadhiwa katika Cassandra
Uwezekano wa kutumia uwezo wa ulinganisho wa GraphQL kwa data iliyopangwa
Usaidizi usio na uhusiano wa ueleuzi kati ya vitu vinavyohusiana
Ukosefu wa lugha ya kawaida ya ulinganisho kwa ufikiaji wa data iliyopangwa

Huduma ya ulinganisho wa GraphQL itafunga pengo hizi kwa:
Kutoa kiolesura cha kawaida cha GraphQL kwa ulinganisho wa meza za Cassandra
Kujenga schemas za GraphQL moja kwa moja kutoka kwa usanidi wa TrustGraph
Kubadilisha ulinganisho wa GraphQL kwa CQL ya Cassandra kwa ufanisi
Kusaidia suluhisho la uhusiano kupitia suluhu za uwanja

## Muundo wa Kiufundi

### Usanifu

Huduma ya ulinganisho wa GraphQL itatekelezwa kama mchakato mpya wa TrustGraph kufuatia mbinu zilizopo:
>>>>>>> 82edf2d (New md files from RunPod)

**Eneo la Moduli**: `trustgraph-flow/trustgraph/query/objects/cassandra/`

**Vipengele Muhimu**:

<<<<<<< HEAD
1. **Mchakato wa Huduma ya Uwasilisho wa GraphQL**
   Huendelea na darasa la msingi la FlowProcessor
   Inatekeleza mtindo wa ombi/jibu sawa na huduma zingine za kuuliza
   Inafuatilia usanidi kwa sasisho za mpango
   Inahifadhi mpango wa GraphQL inayosawazishwa na usanidi

2. **Mjenzi wa Mpango wa Njia Moja Moja**
   Inabadilisha maelezo ya TrustGraph RowSchema kuwa aina za GraphQL
   Inaunda aina za vitu vya GraphQL na maelezo ya uwanja sahihi
   Inazalisha aina ya mizizi ya Ombi na suluhu za msingi za makusanyo
   Inasasisha mpango wa GraphQL wakati usanidi unabadilika

3. **Mtekelezaji wa Maswali**
   Inachambua maswali ya GraphQL yanayoingia kwa kutumia maktaba ya Strawberry
   Inathibitisha maswali dhidi ya mpango wa sasa
   Inatekeleza maswali na inarudisha majibu yaliyopangwa
   Inashughulikia makosa kwa utulivu na ujumbe wa makosa wa kina

4. **Mhubiri wa Maswali ya Cassandra**
   Inabadilisha uteuzi wa GraphQL kuwa maswali ya CQL
   Inaboresha maswali kulingana na fahirisi na funguo za sehemu zinazopatikana
   Inashughulikia kuchujwa, upangishaji, na utaratibu
   Inadhibiti udhibiti wa muunganisho na maisha ya kikao

5. **Suluhu ya Uhusiano**
   Inatekeleza suluhu za uwanja kwa uhusiano wa vitu
   Inafanya upakiaji wa kundi ili kuepuka maswali ya N+1
   Inahifadhi suluhu za uhusiano ndani ya muktadha wa ombi
   Inasaidia utambuzi wa uhusiano wa mbele na nyuma

### Ufuatiliaji wa Mpango wa Usanidi

Huduma itasajili mshukiwa wa usanidi ili kupokea sasisho za mpango:
=======
1. **Mchakato wa Huduma ya Ulinganisho wa GraphQL**
   Huendelea na darasa la msingi la FlowProcessor
   Huendesha mtindo wa ombi/jibu sawa na huduma zingine za ulinganisho
   Huangalia usanidi kwa sasisho za muundo
   Huendeleza schema ya GraphQL ili kuendana na usanidi

2. **Mzalishaji wa Muundo wa Njia Moja Moja**
   Hubadilisha ufafanuzi wa TrustGraph RowSchema kuwa aina za GraphQL
   Huunda aina za vitu vya GraphQL na ufafanuzi sahihi wa uwanja
   Huunda aina ya Query ya mizizi na suluhu za msingi za mkusanyiko
   Huendeleza schema ya GraphQL wakati usanidi unabadilika

3. **Mtekelezaji wa Ulinganisho**
   Huainisha ulinganisho wa GraphQL unaoingia kwa kutumia maktaba ya Strawberry
   Huainisha ulinganisho dhidi ya schema ya sasa
   Huendesha ulinganisho na hurudisha majibu yaliyopangwa
   Hushughulikia makosa kwa njia nzuri na ujumbe wa makosa wa kina

4. **Mhubiri wa Ulinganisho wa Cassandra**
   Hubadilisha uteuzi wa GraphQL kuwa ulinganisho wa CQL
   Huongeza ulinganisho kulingana na fahirisi na funguo za sehemu zinazopatikana
   Hushughulikia uchujaji, upangishaji, na utaratibu
   Hushughulikia udhibiti wa muunganisho na mzunguko wa kikao

5. **Suluhu ya Uhusiano**
   Huendesha suluhu za uwanja kwa uhusiano wa vitu
   Hufanya upakiaji wa kundi ili kuepuka masuala ya N+1
   Huweka suluhu za uhusiano ndani ya muktadha wa ombi
   Inasaidia ueleuzi wa uhusiano wa mbele na nyuma

### Ufuatiliaji wa Muundo wa Usanidi

Huduma itajisajili kwa mshughuliki wa usanidi ili kupokea sasisho za muundo:
>>>>>>> 82edf2d (New md files from RunPod)

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

Wakati schemas hubadilika:
1. Changanua maelezo mapya ya schema kutoka kwa usanidi
<<<<<<< HEAD
2. Tengeneza upya aina za GraphQL na suluhu
=======
2. Tengeneza upya aina na suluhu za GraphQL
>>>>>>> 82edf2d (New md files from RunPod)
3. Sasisha schema inayotumika
4. Ondoa kumbukumbu zozote zinazotegemea schema

### Uzalishaji wa Schema ya GraphQL

Kwa kila RowSchema katika usanidi, tengeneza:

1. **Aina ya Kitu cha GraphQL**:
   Linganisha aina za sehemu (string → String, integer → Int, float → Float, boolean → Boolean)
   Weka sehemu ambazo zinahitajika kama zisizo na thamani null katika GraphQL
   Ongeza maelezo ya sehemu kutoka kwa schema

2. **Sehemu za Uchunguzi Mkuu**:
   Uchunguzi wa mkusanyiko (e.g., `customers`, `transactions`)
<<<<<<< HEAD
   Vigezo vya kuchujwa kulingana na sehemu zilizo na fahirisi
   Usaidizi wa ukurasa (limit, offset)
=======
   Majadiliano ya kuchujwa kulingana na sehemu zilizo na index
   Usaidizi wa upangaji (limit, offset)
>>>>>>> 82edf2d (New md files from RunPod)
   Chaguo za kupanga kwa sehemu ambazo zinaweza kupangwa

3. **Sehemu za Uhusiano**:
   Tambua uhusiano wa ufunguo wa kigeni kutoka kwa schema
   Unda suluhu za sehemu kwa vitu vinavyohusiana
<<<<<<< HEAD
   Usaidizi wa uhusiano wa kitu kimoja na orodha
=======
   Saidia uhusiano wa kitu kimoja na orodha
>>>>>>> 82edf2d (New md files from RunPod)

### Mtiririko wa Utendaji wa Uchunguzi

1. **Mapokezi ya Ombi**:
   Pokea `ObjectsQueryRequest` kutoka Pulsar.
   Toa mfuatano wa GraphQL na vigezo.
   Tambua muktadha wa mtumiaji na mkusanyiko.

2. **Uthibitisho wa Ombi**:
   Changanua mfuatano wa GraphQL kwa kutumia Strawberry.
   Thibitisha dhidi ya mpango (schema) unaoendelea.
   Angalia uteuzi wa sehemu na aina za hoja (argument).

3. **Uundaji wa Ombi la CQL**:
<<<<<<< HEAD
   Jadili uteuzi wa GraphQL.
   Unda ombi la CQL na vipengele sahihi vya `WHERE`.
=======
   Changanua uteuzi wa GraphQL.
   Unda ombi la CQL na vigezo sahihi vya `WHERE`.
>>>>>>> 82edf2d (New md files from RunPod)
   Jumuisha mkusanyiko katika ufunguo wa sehemu (partition key).
   Tumia vichujio kulingana na hoja za GraphQL.

4. **Utendaji wa Ombi**:
   Tekeleza ombi la CQL dhidi ya Cassandra.
   Linganisha matokeo na muundo wa jibu la GraphQL.
   Tatua sehemu zozote za uhusiano.
   Tengeneza jibu kulingana na vipimo vya GraphQL.

5. **Utoaji wa Jibu**:
   Unda `ObjectsQueryResponse` na matokeo.
   Jumuisha makosa yoyote ya utekelezaji.
   Tuma jibu kupitia Pulsar na kitambulisho cha uhusiano (correlation ID).

### Mifano ya Data

<<<<<<< HEAD
> **Kumbuka**: Mpango (schema) uliopo wa `StructuredQueryRequest/Response` unafanya kazi katika `trustgraph-base/trustgraph/schema/services/structured_query.py`. Hata hivyo, hauna vipengele muhimu (mtumiaji, mkusanyiko) na hutumia aina ambazo sio bora. Mifano iliyo hapa chini inaonyesha maendeleo yanayopendekezwa, ambayo inaweza kuchukua nafasi ya mifano iliyopo au kuundwa kama aina mpya za `ObjectsQueryRequest/Response`.
=======
> **Kumbuka**: Mpango (schema) uliopo wa `StructuredQueryRequest/Response` unafanya kazi katika `trustgraph-base/trustgraph/schema/services/structured_query.py`. Hata hivyo, hauna sehemu muhimu (mtumiaji, mkusanyiko) na hutumia aina ambazo sio bora. Mifano iliyo hapa chini inaonyesha maendeleo yanayopendekezwa, ambayo inaweza kuchukua nafasi ya mifano iliyopo au kuundwa kama aina mpya za `ObjectsQueryRequest/Response`.
>>>>>>> 82edf2d (New md files from RunPod)

#### Mpango wa Ombi (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
**Mazingatio ya mabadiliko kutoka kwa Ombi la Ulinganisho Lililopo:**
Imeongezwa sehemu `user` na `collection` ili kuendana na mtindo wa huduma zingine za utafutaji.
Sehemu hizi ni muhimu kwa kutambua eneo la kuhifadhi data (keyspace) na mkusanyiko (collection) katika Cassandra.
=======
**Mazingatio ya mabadiliko kutoka kwa Ombi la Ulipimaji Uliohifadhiwa (StructuredQueryRequest):**
Imeongezwa sehemu `user` na `collection` ili kuendana na mtindo wa huduma zingine za ulipimaji.
Sehemu hizi ni muhimu kwa kutambua eneo la kuhifadhi (keyspace) na mkusanyiko (collection) wa Cassandra.
>>>>>>> 82edf2d (New md files from RunPod)
Vigezo vinaendelea kuwa Map(String()) kwa sasa, lakini inapaswa kusaidia aina zote za JSON.

#### Muundo wa Majibu (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.)
```

**Mazingatio ya mabadiliko kutoka kwa Jibu la Uliopo la StructuredQueryResponse:**
Hutofautisha kati ya makosa ya mfumo (`error`) na makosa ya GraphQL (`errors`)
Hutumia vitu vilivyopangwa vya GraphQLError badala ya safu ya maandishi
Huongeza sehemu `extensions` ili kufuata vipimo vya GraphQL
<<<<<<< HEAD
Huhifadhi data kama mnyororo wa JSON ili kuendana, ingawa aina asilia zingekuwa bora
=======
Huendeleza data kama mnyororo wa JSON kwa utangamano, ingawa aina asilia zingekuwa bora
>>>>>>> 82edf2d (New md files from RunPod)

### Uboreshaji wa Umasilisho wa Cassandra

Huduma itaboresha masilisho ya Cassandra kwa:

<<<<<<< HEAD
1. **Kufuata Vipengele vya Partition:**
   Daima jumuisha mkusanyiko katika masilisho
   Tumia funguo kuu zilizotolewa na mpango kwa ufanisi
   Epuka uchanganuzi kamili wa jedwali

2. **Kutumia Faharasa:**
   Tumia faharasa za sekondari kwa kuchujwa
   Unganisha vichujio vingi wakati inafaa
   Toa onyo wakati masilisho yanaweza kuwa yasiyo na ufanisi

3. **Upakiaji wa Kundi:**
=======
1. **Kutii Mifungo ya Sehemu**:
   Daima jumuisha mkusanyiko katika masilisho
   Tumia funguo kuu zilizotolewa na muundo kwa ufanisi
   Epuka uchanganuzi kamili wa jedwali

2. **Kutumia Faharasa**:
   Tumia faharasa za sekondari kwa kuchujua
   Unganisha vichujio vingi wakati inafaa
   Toa onyo wakati masilisho yanaweza kuwa yasiyo na ufanisi

3. **Upakiaji wa Kundi**:
>>>>>>> 82edf2d (New md files from RunPod)
   Kusanya masilisho ya uhusiano
   Tekeleza kwa makundi ili kupunguza safari za kurudi na kuja
   Hifadhi matokeo ndani ya muktadha wa ombi

<<<<<<< HEAD
4. **Usimamizi wa Muunganisho:**
=======
4. **Usimamizi wa Muunganisho**:
>>>>>>> 82edf2d (New md files from RunPod)
   Dumishe vipindi vya Cassandra vinavyoendelea
   Tumia mabwalo ya muunganisho
   Shughulikia muunganisho upya katika hali ya kushindwa

### Mifano ya Masilisho ya GraphQL

#### Masilisho ya Mkusaniko Rahisi
```graphql
{
  customers(status: "active") {
    customer_id
    name
    email
    registration_date
  }
}
```

#### Swali na Mahusiano
```graphql
{
  orders(order_date_gt: "2024-01-01") {
    order_id
    total_amount
    customer {
      name
      email
    }
    items {
      product_name
      quantity
      price
    }
  }
}
```

#### Swali lililogawanywa katika kurasa.
```graphql
{
  products(limit: 20, offset: 40) {
    product_id
    name
    price
    category
  }
}
```

<<<<<<< HEAD
### Utendaji (Implementation)

**Strawberry GraphQL**: Kwa uainishaji wa schema ya GraphQL na utekelezaji wa swali.
**Cassandra Driver**: Kwa muunganisho wa hifadhidata (tayari inatumika katika moduli ya uhifadhi).
**TrustGraph Base**: Kwa FlowProcessor na uainishaji wa schema.
=======
### Utendaji (Dependencies)

**Strawberry GraphQL**: Kwa ufafanuzi wa schema ya GraphQL na utekelezaji wa swali.
**Cassandra Driver**: Kwa muunganisho wa hifadhidata (tayari inatumika katika moduli ya uhifadhi).
**TrustGraph Base**: Kwa FlowProcessor na ufafanuzi wa schema.
>>>>>>> 82edf2d (New md files from RunPod)
**Mfumo wa Usanidi**: Kwa ufuatiliaji na sasisho za schema.

### Kiolesura cha Amri (Command-Line Interface)

Huduma itatoa amri ya CLI: `kg-query-objects-graphql-cassandra`

Majadilisho:
`--cassandra-host`: Alama ya kuwasiliana na kundi la Cassandra.
`--cassandra-username`: Jina la mtumiaji la uthibitishaji.
`--cassandra-password`: Nenosiri la uthibitishaji.
<<<<<<< HEAD
`--config-type`: Aina ya usanidi kwa schema (ya kawaida: "schema").
=======
`--config-type`: Aina ya usanidi kwa schema (kiwango: "schema").
>>>>>>> 82edf2d (New md files from RunPod)
Majadilisho ya kawaida ya FlowProcessor (usanidi wa Pulsar, n.k.).

## Uunganisho wa API

### Mada za Pulsar

**Mada ya Ingizo**: `objects-graphql-query-request`
Schema: ObjectsQueryRequest
Inapokea maswali ya GraphQL kutoka kwa huduma za lango.

**Mada ya Toa**: `objects-graphql-query-response`
Schema: ObjectsQueryResponse
Inarudisha matokeo ya swali na makosa.

### Uunganisho wa Lango

Lango na lango la kinyume (reverse-gateway) itahitaji sehemu za:
1. Kukubali maswali ya GraphQL kutoka kwa wateja.
2. Kusambaza kwa huduma ya swali kupitia Pulsar.
3. Kurudisha majibu kwa wateja.
4. Kusaidia maswali ya utafiti wa GraphQL.

### Uunganisho wa Zana ya Wakala

<<<<<<< HEAD
Darasa mpya la zana ya wakala itaruhusu:
=======
Darasa jipya la zana ya wakala itaruhusu:
>>>>>>> 82edf2d (New md files from RunPod)
Uundaji wa swali la GraphQL kutoka kwa lugha ya asili.
Utendaji wa moja kwa moja wa swali la GraphQL.
Tafsiri na umbizo wa matokeo.
Uunganisho na mtiririko wa maamuzi wa wakala.

## Masuala ya Usalama

**Kipengele cha Kuzuia Kina cha Swali**: Kuzuia maswali yenye kina kikubwa ambacho kinaweza kusababisha matatizo ya utendaji.
**Uchambuzi wa Ufumbuzi wa Swali**: Kupunguza ufumbuzi wa swali ili kuzuia matumizi yasiyofaa ya rasilimali.
**Ruhusa za Kawaida**: Usaidizi wa baadaye kwa udhibiti wa ufikiaji wa kawaida kulingana na majukumu ya mtumiaji.
**Usanifu wa Ingizo**: Kuhakikisha na kusafisha pembejeo zote za swali ili kuzuia mashambulizi ya kuingiza.
**Kipengele cha Kupunguza Kasi**: Kuweka kikomo cha kasi ya swali kwa kila mtumiaji/mkusanyiko.

## Masuala ya Utendaji

<<<<<<< HEAD
**Upangaji wa Swali**: Kuchambua maswali kabla ya utekelezaji ili kuongeza ufanisi wa uundaji wa CQL.
**Kuhifadhi Matokeo**: Kuzingatia kuhifadhi data inayopatikana mara kwa mara katika kiwango cha kielekezi cha matokeo.
**Usimamizi wa Muunganisho**: Kudumisha mizingi bora ya muunganisho kwa Cassandra.
=======
**Upangaji wa Swali**: Kuchambua maswali kabla ya utekelezaji ili kuongeza ufanisi wa utengenezaji wa CQL.
**Kuhifadhi Matokeo**: Kuzingatia kuhifadhi data inayopatikana mara kwa mara katika kiwango cha suluhu.
**Usimamizi wa Muunganisho**: Kudumisha mikoa bora ya muunganisho kwa Cassandra.
>>>>>>> 82edf2d (New md files from RunPod)
**Operesheni za Kikundi**: Kuchanganya maswali mengi wakati inafaa ili kupunguza latensi.
**Ufuatiliaji**: Kufuatilia vipimo vya utendaji wa swali kwa ajili ya uboreshaji.

## Mkakati wa Majaribio

<<<<<<< HEAD
### Majaribio ya Vitengo
Uzalishaji wa schema kutoka kwenye maelezo ya RowSchema
Uchunguzi na uthibitisho wa swali la GraphQL
Mantiki ya uzalishaji wa swali la CQL
Utendaji wa suluhu za sehemu

### Majaribio ya Mkataba
Uzingatiaji wa mkataba wa ujumbe wa Pulsar
Uthibitisho wa uhalali wa schema ya GraphQL
Uthibitisho wa muundo wa jibu
Uthibitisho wa muundo wa hitilafu

### Majaribio ya Uunganishaji
Utendaji wa swali kamili dhidi ya mfano wa Cassandra wa majaribio
Usimamizi wa sasisho za schema
Suluhisho la uhusiano
Urekebishaji na utafutaji
Hali za hitilafu

### Majaribio ya Utendaji
=======
### Majaribsu ya Vitengo
Uzalishaji wa schema kutoka kwa maelezo ya RowSchema
Uchunguzi na uthibitishaji wa swali la GraphQL
Mantiki ya uzalishaji wa swali la CQL
Utendaji wa suluhu za sehemu

### Majaribsu ya Mkataba
Uzingatiaji wa mkataba wa ujumbe wa Pulsar
Uthibitisho wa utiifu wa schema ya GraphQL
Uthibitisho wa muundo wa jibu
Uthibitisho wa muundo wa hitilafu

### Majaribsu ya Uunganishaji
Utendaji wa swali kamili dhidi ya mfano wa Cassandra wa majaribio
Usimamizi wa sasisho za schema
Suluhisho la uhusiano
Urekebishaji na utaratibu
Hali za hitilafu

### Majaribsu ya Utendaji
>>>>>>> 82edf2d (New md files from RunPod)
Ufanisi wa swali chini ya mzigo
Muda wa jibu kwa utata wa swali mbalimbali
Matumizi ya kumbukumbu na matokeo makubwa
Ufanisi wa kikundi cha muunganisho

## Mpango wa Uhamishaji

<<<<<<< HEAD
Uhamishaji hauhitajiki kwani hii ni uwezo mpya. Huduma itafanya:
1. Kusoma schema zilizopo kutoka kwenye usanidi
2. Kuunganisha na meza zilizopo za Cassandra zilizoundwa na moduli ya uhifadhi
3. Kuanza kukubali maswali mara tu inaposanikishwa

## Muda
=======
Hakuna uhamishaji unaohitajika kwani hii ni uwezo mpya. Huduma itafanya:
1. Kusoma schema zilizopo kutoka kwa usanidi
2. Kuunganisha na meza zilizopo za Cassandra zilizoundwa na moduli ya uhifadhi
3. Kuanza kukubali maswali mara tu baada ya kuwekwa

## Ratiba
>>>>>>> 82edf2d (New md files from RunPod)

Wiki 1-2: Utendaji wa msingi wa huduma na uzalishaji wa schema
Wiki 3: Utendaji wa swali na tafsiri ya CQL
Wiki 4: Suluhisho la uhusiano na uboreshaji
Wiki 5: Majaribio na uboreshaji wa utendaji
Wiki 6: Uunganisho wa lango na maandishi

## Maswali ya Wazi

<<<<<<< HEAD
1. **Maendeleo ya Schema**: Huduma inapaswa kushughulikia maswali vipi wakati wa mabadiliko ya schema?
=======
1. **Maendeleo ya Schema**: Huduma inapaswa kushughulikia maswali wakati wa mabadiliko ya schema?
>>>>>>> 82edf2d (New md files from RunPod)
   Chaguo: Kuweka maswali kwenye folyo wakati wa sasisho za schema
   Chaguo: Kusaidia matoleo mengi ya schema kwa wakati mmoja

2. **Mkakati wa Uhifadhi**: Je, matokeo ya swali yanapaswa kuhifadhiwa?
   Zingatia: Muda wa kumalizika
   Zingatia: Ubatilishaji kulingana na tukio

3. **Usaidizi wa Shirikisho**: Je, huduma inapaswa kusaidia shirikisho la GraphQL ili kuunganisha na vyanzo vingine vya data?
   Itaruhusu maswali ya umoja katika data iliyopangwa na ya grafu

4. **Usaidizi wa Ujiandikishaji**: Je, huduma inapaswa kusaidia uandikishaji wa GraphQL kwa sasisho za wakati halisi?
   Itahitaji usaidizi wa WebSocket katika lango

5. **Scalar Maalum**: Je, aina za scalar maalum zinapaswa kuungwa mkono kwa aina za data maalum za kikoa?
   Mifano: DateTime, UUID, nafasi za JSON

## Marejeleo

Maelezo ya Kimataifa ya Data Iliyopangwa: `docs/tech-specs/structured-data.md`
<<<<<<< HEAD
Nyaraka za Strawberry GraphQL: https://strawberry.rocks/
Maelezo ya GraphQL: https://spec.graphql.org/
Marejeleo ya Apache Cassandra CQL: https://cassandra.apache.org/doc/stable/cassandra/cql/
Nyaraka za Msimamizi wa Mtiririko wa TrustGraph: Nyaraka za ndani
=======
Nyaraka za GraphQL Strawberry: https://strawberry.rocks/
Maelezo ya GraphQL: https://spec.graphql.org/
Marejeleo ya Apache Cassandra CQL: https://cassandra.apache.org/doc/stable/cassandra/cql/
Nyaraka za Mfumo wa Mchakato wa TrustGraph: Nyaraka za ndani
>>>>>>> 82edf2d (New md files from RunPod)