DocumentService
Gère les collections documentaires, les recherches exactes, la pagination et la requête QueryDoc.
- PutDoc
- GetDoc
- DeleteDoc
- FindByField
- ListDoc
- QueryDoc
Documentation
Plateforme SaaS multimodèle pour documents, graphe et fichiers
RociaDB permet de structurer des données métier en documents, de relier des entités via un graphe, puis d’associer des fichiers au même contexte. Cette page pose une première base de documentation publique: concepts, intégration, SDKs, sécurité et bonnes pratiques d’usage.
gRPCJWTMulti-tenant
ModèlesDocument · Graphe · Fichier
AccèsJWT + tenant_id
SDKsPython · TypeScript · Rust
RequêtesCRUD + QueryDoc
UsageSaaS multi-tenant
OverviewVue d’ensemble
Comment la plateforme s’intègre dans un usage SaaS multi-tenant.
ModelsDocument · Graphe · FichierLes trois modèles et la manière de les combiner dans un flux métier.
APIAPI & SDKsMéthodes, pagination, requêtes documentaires et exemples clients.
ObservabilityMonitoring & tracingPrometheus, Grafana, Jaeger et logs corrélés pour exploiter la plateforme.
Vue d’ensemble
Un schéma de lecture rapide pour comprendre comment une application SaaS dialogue avec la plateforme et organise ses données.
Applications métier
Scripts & batch
SDK Python / TS / Rust
JWT + tenant_id
DocumentService
GraphService
FileService
Proto gRPC + pagination
Documents
Nœuds & arêtes
Chunks + metadata + commit
GraphService
Expose les nœuds, les arêtes et les traversées paginées, avec des IDs fournis par le client.
- PutNode
- GetNode
- AddEdge
- DeleteEdge
- NeighborsOut
- NeighborsIn
FileService
Prend en charge les fichiers chunkés, les métadonnées et la visibilité atomique via commit marker.
- Upload
- Download
- Stat
- Delete
Modèles de données
La plateforme sépare volontairement document, graphe et fichier. Leur combinaison est explicite et portée par le client.
Document
- Payload JSON brut
- tenant_id + collection + id
- ListDoc, FindByField, QueryDoc
Quand un objet doit aussi être traversé dans le graphe, le client crée également un nœud correspondant.
Graphe
- IDs fournis par le client
- AddEdge échoue si une extrémité manque
- NeighborsIn / NeighborsOut paginés
Il n’y a pas de suppression de nœud exposée dans le proto v1. Le nettoyage des arêtes reste explicite côté client.
Fichier
- Upload en streaming
- Chunks de 1 MiB
- Métadonnées: size, content_type, checksum
Un fichier n’est visible qu’après écriture du commit final. Les uploads partiels orphelins sont éligibles au GC.
Interactions gRPC
Les interactions sont exposées via des services orientés document, graphe et fichier, pensés pour des usages applicatifs et des workflows d’intégration.
Documents
Écriture, lecture, suppression et recherche dans une collection avec pagination et total_count.
PutDoc · GetDoc · DeleteDoc · ListDocGraphes
Création de nœuds et arêtes, puis traversée paginée dans les deux sens via des voisins ordonnés.
PutNode · AddEdge · NeighborsOut · NeighborsInFichiers
Upload streamé, téléchargement streamé, lecture de métadonnées et suppression logique.
Upload · Download · Stat · DeletePagination
Les listes utilisent `PageRequest(limit, cursor)` et renvoient `next_cursor` opaque.
cursor opaqueQueryDoc v1
Requête documentaire avancée
`QueryDoc` complète `ListDoc` et `FindByField` pour les cas où plusieurs filtres, un tri stable et une pagination sur résultat filtré sont nécessaires.
Filtres
V1 supporte `EQ` et `IN` uniquement, combinés en `AND`.
Tri
Tri explicite + tie-breaker stable `id asc` si absent.
Pagination
Cursor opaque à rejouer tel quel sur la page suivante.
Total count
Le serveur renvoie `total_count` avant pagination.
QueryDocRequest {
tenant_id: "tenant-a",
collection: "users",
filters: [
{
field: "organization_id",
operator: QUERY_OPERATOR_EQ,
values_json: ["\"org-1\""]
},
{
field: "status",
operator: QUERY_OPERATOR_IN,
values_json: ["\"active\"", "\"draft\""]
}
],
sort: [
{ field: "name", direction: SORT_DIRECTION_ASC }
],
page: { limit: 50, cursor: "" }
}Sécurité, environnements et exploitation
Cette section rassemble les éléments publics utiles pour exploiter la plateforme proprement dans un contexte SaaS, sans entrer dans les détails internes d’implémentation.
JWT obligatoire
Claims requis: `iss`, `sub`, `tenant_id`, `exp`, `iat`.
Issuer & JWKS
Validation contre un issuer configuré et un jeu de clés publiques JWKS avec rotation.
Audience
`aud` est vérifié si configuré côté service.
Tenant isolation
Le `tenant_id` fait partie du contrat applicatif et structure l’isolation des données.
Configuration
La plateforme distingue la configuration d’environnement, les secrets et les paramètres de sécurité.
Secrets
Les clés et secrets doivent rester hors du code applicatif et être injectés par l’environnement.
Observabilité
Logs, métriques et suivi des erreurs sont à prévoir pour exploiter la plateforme proprement.
Parcours recommandé
Déployer et intégrer sans se disperser
Pour un usage SaaS, l’important est de cadrer les environnements, l’authentification, la stratégie de modélisation et l’observabilité. Les détails d’outillage interne restent volontairement hors de cette documentation publique.
1. Créer un environnement
Isoler un tenant, choisir un environnement de travail et configurer les accès.
2. Modéliser les données
Définir ce qui relève du document, du graphe et du fichier dans votre cas métier.
3. Intégrer le client
Brancher un SDK ou un client gRPC à votre backend, à vos jobs ou à vos outils.
4. Exploiter et observer
Suivre les flux, tracer les erreurs et faire évoluer le modèle progressivement.
Monitoring, logging et tracing
La plateforme est pensée pour s’intégrer dans une chaîne d’observabilité standard: Prometheus pour les métriques, Grafana pour les dashboards, Jaeger pour le tracing distribué.
Prometheus
Les métriques sont exportées au format Prometheus via `/metrics`. Elles couvrent le volume de requêtes, la latence, les scans d’index et les flux de fichiers.
- rocia_request_total
- rocia_request_latency_ms
- rocia_index_scans_total
- rocia_stream_bytes_total
Jaeger
Le tracing distribué repose sur OpenTelemetry. Chaque requête peut porter un trace ID propagé dans les métadonnées gRPC puis corrélé avec les journaux.
- OpenTelemetry
- trace_id corrélé
- Propagation gRPC
Grafana
Grafana s’appuie naturellement sur Prometheus pour construire les dashboards SLO, suivre les p95/p99 et visualiser les incidents ou dégradations.
- Latence p50/p95/p99
- Taux de succès
- Alertes & tendances
Métriques exposées
Les métriques publiques les plus structurantes concernent le trafic, la latence, l’indexation et les flux de fichiers. Elles sont pensées pour alimenter des dashboards transverses et des alertes d’exploitation.
/metricsLogs corrélés
Les logs sont structurés en JSON afin de relier facilement une erreur, une requête, un tenant et un chemin d’exécution. Le `trace_id` permet de naviguer entre logs et traces.
- ts
- level
- request_id
- tenant_id
- service
- method
- status
- latency_ms
- trace_id
Ce que ça permet côté SaaS
Construire des tableaux de bord d’usage, suivre les SLO, identifier les régressions et investiguer plus vite sans exposer les détails d’implémentation aux clients finaux.
Prometheus + Grafana + JaegerSDKs & exemples de clients
Une base de présentation pour Python, TypeScript et Rust, alignée sur les primitives réelles du proto.
Intégration applicative
Python
pip install rociadb
client.documents.put(
tenant_id="tenant-a",
collection="users",
id="user-123",
json={"status": "active", "organization_id": "org-1"},
request_id="req-001",
)API / backend
TypeScript
npm install @rociadb/sdk
await client.graph.addEdge({
tenantId: "tenant-a",
graph: "crm",
edgeId: "edge-001",
from: "user-123",
to: "org-1",
label: "member_of",
json: { source: "sync" },
})Services critiques
Rust
cargo add rociadb
client.file_service()
.upload("tenant-a", "contracts", "ctr-42.pdf")
.content_type("application/pdf")
.checksum(checksum)
.stream(reader)
.await?;Questions fréquentes
Les points qui structurent aujourd’hui l’usage réel de la plateforme.
Comment relier un document et un nœud graphe ?
La stratégie retenue est de garder les stores séparés. Si un objet doit exister dans les deux modèles, le client crée le document et le nœud avec un ID partagé ou un lien explicite.
Est-ce que la plateforme synchronise automatiquement document et graphe ?
Non en v1. La cohérence entre les représentations est à la charge du client ou du workflow applicatif.
Peut-on requêter librement les documents avec des opérateurs riches ?
Pas encore. QueryDoc v1 couvre surtout `eq`, `in`, le tri stable et la pagination. Les opérateurs plus riches sont explicitement hors périmètre à ce stade.