Skip to content
Projets

tocreator/tostore has 67 GitHub stars and 11 forks. GitHot measured 0 stars in 24 hours and 0 in 7 days. Last checked 2026-11-19 17:44 UTC. Last push 2026-11-17.

Comment ces chiffres sont mesurés

What you can do

  • Declarative schema changes—automatic refactoring, no manual versioning
  • Key rotation, schema migration, massive refactoring—all online, business-transparent
  • Built-in status spec for automated O&M and Agent recognition
  • Supports autonomous evolution and continuous iteration without interrupting service

Progression mesurée des étoiles

in 24h
0
in 7 days
0
in 15 days
Historique en cours
in 1 month
Historique en cours

Variations nettes sur des périodes qui se chevauchent, pas des totaux quotidiens. Les mesures absentes restent vides. Les étoiles indiquent l’intérêt, pas la qualité.

À propos

Data engine: AI vector & SQL/NoSQL database. Key-value/KV, embeddings, BM25 full-text, hybrid & semantic search for RAG/LLM. Local storage, TTL/LRU cache, offline encrypted.

IA

doc/translations/fr/README.md

Original

ToStore

pub package Pub Points Pub Likes Monthly Downloads

License Platform Architecture

English | 简体中文 | 日本語 | 한국어 | Español | Português (Brasil) | Русский | Deutsch | Français | Italiano | Türkçe

Navigation rapide

Pourquoi choisir ToStore ?

ToStore est un moteur de données moderne conçu pour l'ère de l'AGI et les scénarios d'intelligence en périphérie. Basé sur une architecture de nœuds auto-routés (Self-Routing), il confère aux nœuds une grande autonomie et une extensibilité horizontale élastique, découplant logiquement les performances de l'échelle des données — en périphérie comme dans le cloud, le mono-nœud vise les tables structurées à l'échelle du billion (10¹²), et la récupération vectorielle / texte sparse vise aussi 10B+.

Le modelage d'exécution et les chemins d'exécution non bloquants maintiennent l'évolution de l'architecture toujours en ligne et totalement transparente pour les opérations métier — les changements déclaratifs de schéma, la rotation des clés de codage des données et le refactoring massif de données s'effectuent sans interruption. Il prend en charge les Agents et l'exploitation automatisée avec création de tables à l'exécution, évolution dynamique de la mémoire, ainsi que leur évolution autonome et leur itération continue — sans interrompre le service.

Il unifie les données structurées relationnelles, les vecteurs denses, les vecteurs neuronaux sparse et le texte non structuré dans un seul moteur, avec récupération lexicale de texte, récupération de vecteurs denses, récupération neuronale sparse et fusion de rappel multi-voies intégrées. Les capacités de niveau entreprise incluent les transactions ACID, les requêtes relationnelles complexes (JOINs, clés étrangères en cascade), le TTL au niveau table, les agrégations, ainsi que les algorithmes de clé primaire distribuée, les expressions atomiques, le chiffrement, l'isolation multi-espace et la récupération automatique.

Alors que l'informatique continue de se déplacer vers l'intelligence en périphérie, les appareils ne sont plus de simples « affichages de contenu », mais des nœuds intelligents responsables de la génération locale, de la perception de l'environnement, de la prise de décision en temps réel et de la coordination des données. ToStore offre à la périphérie des capacités distribuées pour des ensembles de données massifs et une génération locale complexe d'IA. La collaboration intelligente approfondie entre les nœuds périphériques et cloud fournit une base de données fiable pour l'interaction multimodale, la mémoire à long terme, le RAG et les bases de connaissances locales, la récupération hybride, la modélisation spatiale, la collaboration autonome en périphérie et des scénarios similaires.

Principales fonctionnalités

  • 🤖 Évolution d'exécution et exploitation intelligente

    • Changements de schéma déclaratifs — refactoring automatique, sans versionnage manuel
    • Rotation des clés, migration de schéma, refactoring massif — tout en ligne, transparent pour le métier
    • Spécification d'état intégrée pour l'exploitation automatisée et la reconnaissance d'Agents
    • Prend en charge l'évolution autonome et l'itération continue sans interruption de service
  • 🧠 Architecture distribuée auto-routée

    • Architecture de nœuds auto-routés découplant l'adressage physique de l'échelle des données
    • Nœuds hautement autonomes collaborant pour construire une topologie de données flexible
    • Extensibilité horizontale élastique ; mono-nœud : tables à l'échelle du billion, vecteurs 10B+
  • 🌐 Moteur de données multiplateforme unifié

    • API unifiée dans les environnements mobiles, de bureau, Web et serveur
    • Couvre les données relationnelles, les vecteurs denses / neuronaux sparse et la récupération de texte
    • Pipeline de données complet du stockage local à la collaboration périphérie-cloud
  • 🔍 Requêtes structurées et récupération hybride

    • Prédicats complexes, JOINs, agrégations, TTL au niveau de la table et éviction par capacité (FIFO / LRU)
    • Texte lexical, vecteurs denses et récupération neuronale sparse sur la même chaîne de requête
    • Classement par fusion de rappel multi-voies, avec scores et diagnostics de canal dans le résultat
  • ⚡ Exécution parallèle et planification des ressources

    • Démarrage à froid constant ~35 ms, indépendant de l'échelle des données
    • Planification de charge tenant compte des ressources ; décomposition parallèle multi-nœuds
    • Découpage temporel maintenant les animations d'interface fluides même sous forte charge
  • 🔐 Offline-First et confidentialité

    • Conservez les données sur l'appareil et utilisables hors ligne, réduisant la dépendance au cloud et la surface d'exposition
    • Isolation multi-espace avec partage global optionnel — prêt pour multi-utilisateurs / multi-locataires
    • Chiffrement ChaCha20-Poly1305 et AES-256-GCM intégré
    • Vérifié par de multiples scénarios complexes de reprise après sinistre

Installation

[!IMPORTANT] Mise à niveau depuis la v2.x ? Veuillez lire le Guide de mise à niveau vers la v3.x pour connaître les étapes de migration critiques et les modifications majeures.

Ajoutez tostore à votre pubspec.yaml :

dependencies:
  tostore: any # Please use the latest version

For AI Coding Assistants

Pour générer du code client ToStore avec un assistant IA, fournissez-lui le corpus mono-fichier llms-full.txt — par exemple @llms-full.txt dans l'IDE, téléversez/collez le fichier, ou indexez son raw URL dans la documentation de l'assistant. Il contient les signatures d'API, contraintes et anti-modèles pour aligner le modèle sur la surface publique réelle. Index : llms.txt.

Démarrage rapide

[!TIP] Comment choisir un mode de stockage ?

  1. Key-Value Mode (KV) : Idéal pour l'accès à la configuration, la gestion des états dispersés ou le stockage de données JSON. C'est le moyen le plus rapide de démarrer.
  2. Mode table structurée : Idéal pour les données métier de base qui nécessitent des requêtes complexes, une validation de contraintes ou une gouvernance des données à grande échelle. En intégrant la logique d’intégrité dans le moteur, vous pouvez réduire considérablement les coûts de développement et de maintenance de la couche applicative.
  3. Mode mémoire : idéal pour les calculs temporaires, les tests unitaires, les caches mémoire bornés (TTL et éviction par capacité FIFO / LRU) ou la gestion globale ultra-rapide de l'état. Avec les requêtes globales et les écouteurs watch, vous pouvez remodeler l'interaction des applications sans conserver une pile de variables globales.

Stockage de valeurs-clés (KV)

Ce mode convient lorsque vous n'avez pas besoin de tableaux structurés prédéfinis. C'est simple, pratique et soutenu par un moteur de stockage hautes performances. Son architecture d'indexation efficace maintient les performances des requêtes très stables et extrêmement réactives, même sur les appareils mobiles ordinaires à très grande échelle de données. Les données dans différents espaces sont naturellement isolées, tandis que le partage mondial est également pris en charge.

// Initialize the database
final db = await ToStore.open();

// Set key-value pairs (supports String, int, bool, double, Map, List, Json, and more)
await db.setValue('user_profile', {
  'name': 'John',
  'age': 25,
});

// Switch space - isolate data for different users
await db.switchSpace(spaceName: 'user_123');

// Set a globally shared variable (isGlobal: true enables cross-space sharing, such as login state)
await db.setValue('current_user', 'John', isGlobal: true);

// Automatic expiration cleanup (TTL)
// Supports either a relative lifetime (ttl) or an absolute expiration time (expiresAt)
await db.setValue('temp_config', 'value', ttl: Duration(hours: 2));
await db.setValue('session_token', 'abc', expiresAt: DateTime(2026, 2, 31));

// Read data
final profile = await db.getValue('user_profile'); // Map<String, dynamic>

// Listen for real-time value changes (useful for refreshing local UI without extra state frameworks)
db.watchValue('current_user', isGlobal: true).listen((value) {
  print('Logged-in user changed to: $value');
});

// Listen to multiple keys at once
db.watchValues(['current_user', 'login_status']).listen((map) {
  print('Multiple config values were updated: $map');
});

// Remove data
await db.removeValue('current_user');

[!TIP] Besoin de plus de fonctionnalités clé-valeur ? Pour les opérations avancées telles que la lecture sécurisée des types (getInt, getBool), l'incrémentation atomique, la recherche par préfixe, les requêtes chaînées paginées d'enregistrements (db.kv.query()) et l'exploration de l'espace de clés, veuillez consulter Opérations clé-valeur avancées (db.kv).

Exemple d'actualisation automatique de l'interface utilisateur Flutter

Dans Flutter, StreamBuilder plus watchValue vous offre un flux de rafraîchissement réactif très concis :

StreamBuilder(
  // When listening to a global variable, remember to set isGlobal: true
  stream: db.watchValue('current_user', isGlobal: true),
  builder: (context, snapshot) {
    // snapshot.data is the latest value of 'current_user' in KV storage
    final user = snapshot.data ?? 'Not logged in';
    return Text('Current user: $user');
  },
)

Mode tableau structuré

CRUD sur les tables structurées nécessite que le schéma soit créé à l'avance (voir Définition du schéma). Approches d'intégration recommandées pour différents scénarios :

// 1. Initialize the database
final db = await ToStore.open();

// 2. Insert data (prepare some base records)
final result = await db.insert('users', {
  'username': 'John',
  'email': '[email protected]',
  'age': 25,
});

// Unified operation result model: DbResult
// It is recommended to check hasErrors
if (!result.hasErrors) {
  print('Insert succeeded, generated primary key ID: ${result.firstPrimaryKey}');
} else {
  print('Insert failed: ${result.message}');
}

// Chained query (see [Query Operators](#query-operators); supports =, !=, >, <, LIKE, IN, and more)
final users = await db.query('users')
    .where('age', '>', 20)
    .where('username', 'like', '%John%')
    .orderByDesc('age')
    .limit(20);

// Update and delete
await db.update('users', {'age': 26}).where('username', '=', 'John');
await db.delete('users').where('username', '=', 'John');

// Real-time listening (see [Reactive Query](#reactive-query) for more details)
db.query('users').where('age', '>', 18).watch().listen((users) {
  print('Users matching the condition have changed: $users');
});

// Pair with Flutter StreamBuilder for automatic local UI refresh
StreamBuilder(
  stream: db.query('users').where('age', '>', 18).watch(),
  builder: (context, snapshot) {
    final users = snapshot.data ?? [];
    return ListView.builder(
      itemCount: users.length,
      itemBuilder: (context, index) => Text(users[index]['username']),
    );
  },
);

Mode mémoire

Pour des scénarios tels que la mise en cache, le calcul temporaire ou les charges de travail qui ne nécessitent pas de persistance sur le disque, vous pouvez initialiser une base de données en mémoire pure via ToStore.memory(). Dans ce mode, toutes les données, y compris les schémas, les index et les paires clé-valeur, résident entièrement en mémoire pour des performances de lecture/écriture maximales.

Le mode mémoire prend en charge plusieurs stratégies d'éviction : TTL au niveau de la table / TTL KV basés sur le temps, et Éviction par capacité (FIFO / LRU) par nombre ou taille—seules ou combinées, pour faire expirer les données chaudes à l'heure ou les maintenir bornées. Idéal pour les caches de session, les pools de résultats et les chemins sensibles à la mémoire.

💡 Fonctionne également comme gestion globale de l'état

Vous n'avez pas besoin d'une pile de variables globales ou d'un cadre de gestion d'état lourd. En combinant le mode mémoire avec watchValue ou watch(), vous pouvez obtenir une actualisation entièrement automatique de l'interface utilisateur sur les widgets et les pages. Il conserve les puissantes capacités de récupération d'une base de données tout en vous offrant une expérience réactive bien au-delà des variables ordinaires, ce qui le rend idéal pour l'état de connexion, la configuration en direct ou les compteurs de messages globaux.

[!CAUTION] Remarque : Les données créées en mode mémoire pure sont complètement perdues après la fermeture ou le redémarrage de l'application. Ne l'utilisez pas pour les données commerciales de base.

// Pure in-memory DB — TTL and/or FIFO/LRU capacity eviction as needed
final memDb = await ToStore.memory(
  config: DataStoreConfig(
    kvCapacityConfig: CapacityConfig(
      maxEntries: 5000,
      policy: CapacityEvictionPolicy.lru,
    ),
  ),
);

// Set a global state value (for example: unread message count)
await memDb.setValue('unread_count', 5, isGlobal: true);

// Listen from anywhere in the UI without passing parameters around
memDb.watchValue<int>('unread_count', isGlobal: true).listen((count) {
  print('UI automatically sensed the message count change: $count');
});

// All CRUD, KV access, and vector search run at in-memory speed
await memDb.insert('active_users', {'name': 'Marley', 'status': 'online'});

Définition du schéma

Définissez une seule fois et laissez le moteur gérer une gouvernance automatisée de bout en bout afin que votre application ne subisse plus de maintenance de validation lourde.

Les exemples suivants de mobile, côté serveur et agent réutilisent tous appSchemas défini ici.

Présentation du schéma de table

const userSchema = TableSchema(
  name: 'users', // Table name, required
  tableId: 'users', // Unique identifier of the table, optional
  primaryKeyConfig: PrimaryKeyConfig(
    name: 'id', // Primary key field name, defaults to id
    type: PrimaryKeyType.sequential, // Primary key auto-generation strategy
    sequentialConfig: SequentialIdConfig(
      initialValue: 1000, // Initial value for sequential IDs
      increment: 1, // Step size
      useRandomIncrement: false, // Whether to use random step sizes
    ),
  ),
  fields: [
    FieldSchema(
      name: 'username', // Field name, required
      type: DataType.text, // Field data type, required
      nullable: false, // Whether null is allowed
      minLength: 3, // Minimum length
      maxLength: 32, // Maximum length
      unique: true, // Whether it must be unique
      fieldId: 'username', // Stable field identifier, optional, used to detect field renames
      comment: 'Login name', // Optional comment
    ),
    FieldSchema(
      name: 'status',
      type: DataType.integer,
      minValue: 0, // Minimum numeric value
      maxValue: 150, // Maximum numeric value
      defaultValue: 0, // Static default value
      createIndex: true, // Shortcut for creating an index
    ),
    FieldSchema(
      name: 'created_at',
      type: DataType.datetime,
      nullable: false,
      defaultValueType: DefaultValueType.currentTimestamp, // Automatically fill with current time
      createIndex: true,
    ),
  ],
  indexes: const [
    IndexSchema(
      indexName: 'idx_users_status_created_at', // Optional index name
      fields: ['status', 'created_at'], // Composite index fields
      unique: false, // Whether it is a unique index
      type: IndexType.btree, // Index type: btree/vector
    ),
  ],
  foreignKeys: const [], // Optional foreign-key constraints; see "Foreign Keys & Cascading"
  isGlobal: false, // Whether this is a global table; true means it can be shared across spaces
  ttlConfig: null, // Optional table-level TTL; see "Table-level TTL"
  capacityConfig: null, // Optional capacity eviction; see "Capacity Eviction"
);

const appSchemas = [userSchema];
  • Mappages DataType courants :

    Tapez Type de fléchette correspondant Descriptif
    integer int Entier standard, adapté aux identifiants, compteurs et données similaires
    bigInt BigInt / String Grands entiers ; recommandé lorsque les nombres dépassent 18 chiffres pour éviter toute perte de précision
    double double Nombre à virgule flottante, adapté aux prix, coordonnées et données similaires
    text String Chaîne de texte avec contraintes de longueur facultatives
    blob Uint8List Données binaires brutes
    boolean bool Valeur booléenne
    datetime DateTime / String Date/heure ; stocké en interne sous ISO8601
    array List Type de liste ou de tableau
    json Map<String, dynamic> Objet JSON, adapté aux données structurées dynamiques
    vector VectorData / List<num> Vecteurs denses pour la récupération sémantique des plus proches voisins (embeddings)
    sparse SparseVectorData Vecteurs neuronaux sparse pour la récupération sparse
  • PrimaryKeyType stratégies d'auto-génération :

    Stratégie Descriptif Caractéristiques
    none Pas de génération automatique Vous devez fournir manuellement la clé primaire lors de l'insertion
    sequential Incrément séquentiel Bon pour les identifiants conviviaux, mais moins adapté aux performances distribuées
    timestampBased Basé sur l'horodatage Recommandé pour les environnements distribués
    datePrefixed Préfixé par la date Utile lorsque la lisibilité de la date est importante pour l'entreprise
    shortCode Clé primaire de code court Compact et adapté à un affichage externe

Toutes les clés primaires sont stockées sous text (String) par défaut.

Contraintes et validation automatique

Vous pouvez écrire des règles de validation communes directement dans FieldSchema, évitant ainsi la duplication de logique dans le code de l'application :

  • nullable: false : contrainte non nulle
  • minLength / maxLength : contraintes de longueur de texte
  • minValue / maxValue : contraintes de plage entière ou flottante
  • defaultValue / defaultValueType : valeurs par défaut statiques et valeurs par défaut dynamiques
  • unique : contrainte unique
  • createIndex : créez des index pour le filtrage, le tri ou les relations haute fréquence
  • fieldId / tableId : aide à la détection du renommage des champs et des tables lors de la migration

De plus, unique: true crée automatiquement un index unique à champ unique. createIndex: true et les clés étrangères créent automatiquement des index normaux à champ unique. Utilisez indexes lorsque vous avez besoin d'index composites, d'index nommés ou d'index de récupération texte / sparse / vectoriels.

Évolution du schéma (Schema Evolution)

Le moteur détecte automatiquement les changements structurels (ajout, suppression ou renommage de tables/champs, ajustements d'attributs, changements d'index, etc.) et réalise la migration des données — sans versionnage manuel ni scripts. Les schemas déclaratifs évoluent à ToStore.open() ; à l'exécution, utilisez aussi updateSchema — transparent pour le métier, lectures et écritures sans interruption.

Promouvoir un champ unique en clé primaire

Vous pouvez promouvoir un champ existant unique et non null en clé primaire (renommage optionnel ; avec données existantes ; transparent pour le métier). Ne combinez pas avec setPrimaryKeyConfig.

  • Mobile (schemas déclaratifs) : Détection automatique à ToStore.open(). La clé primaire cible doit être PrimaryKeyType.none (valeurs issues du champ unique source ; les autres types auto-générés ne sont pas pris en charge). Si les noms correspondent, le nom suffit ; pour renommer, renseignez le fieldId source dans fromFieldId.
  • Serveur (runtime) : Appelez updateSchema(...).promoteFieldToPrimaryKey(sourceFieldName: ..., targetPrimaryKeyName: ...). targetPrimaryKeyName est optionnel ; omettez-le pour conserver le nom du champ source.

Choisir une méthode d'intégration

  • Mobile/Ordinateur : Idéal pour passer appSchemas directement dans ToStore.open(...)
  • Serveur/Agent : Idéal lors de la création dynamique de schémas au moment de l'exécution via createTables(appSchemas)

Intégration pour les mobiles, les ordinateurs de bureau et d'autres scénarios de démarrage fréquents

📱 Exemple : mobile_quickstart.dart

import 'package:path/path.dart' as p;
import 'package:path_provider/path_provider.dart';

// On Android/iOS, resolve the app's writable directory first, then pass dbPath explicitly
final docDir = await getApplicationDocumentsDirectory();
final dbRoot = p.join(docDir.path, 'common');

// Reuse the appSchemas defined above
final db = await ToStore.open(
  dbPath: dbRoot,
  schemas: appSchemas,
);

// Multi-space architecture - isolate data for different users
await db.switchSpace(spaceName: 'user_123');

Suivi de la progression du démarrage

Les changements de schéma normaux sont transparents pour la logique métier et ne bloquent pas le démarrage. Ce n'est que dans de rares cas exceptionnels spécifiques aux applications mobiles fréquemment fermées de force (par exemple, une brève validation des données et une récupération après plantage après une sortie anormale) que l'initialisation peut prendre un temps perceptible — utilisez onStartupProgress pour afficher un écran d'accueil ou un indicateur de progression :

final db = await ToStore.open(
  dbPath: dbRoot,
  schemas: appSchemas,
  onStartupProgress: (progress, stage) {
    // progress: 0.0 – 1.0  |  stage: opening → recovering → optimizing → ready
    print('Progression du démarrage ${(progress * 100).toStringAsFixed(0)}% [$stage]');
    // Mettre à jour l'écran d'accueil / la barre de progression
  },
);
// Base de données entièrement prête

Étapes :

  • opening — Chargement de la configuration, préparation du moteur de base
  • recovering — Vérifications de sécurité et récupération après plantage
  • optimizing — Réglage interne du moteur et optimisation structurelle
  • ready — Initialisation terminée, prêt à l'emploi

Conserver l'état de connexion et de déconnexion (espace actif)

Le multi-espace est idéal pour isoler les données utilisateur : un espace par utilisateur, activé la connexion. Avec Active Space et les options de fermeture, vous pouvez conserver l'utilisateur actuel lors des redémarrages de l'application et prendre en charge un comportement de déconnexion propre.

  • Conserver l'état de connexion : après avoir basculé un utilisateur vers son propre espace, marquez cet espace comme actif. Le prochain lancement peut entrer dans cet espace directement lors de l'ouverture de l'instance par défaut, sans étape « par défaut d'abord, puis changer ».
  • Déconnexion : Lorsque l'utilisateur se déconnecte, fermez la base de données avec keepActiveSpace: false. Le prochain lancement n'entrera pas automatiquement dans l'espace de l'utilisateur précédent.
// After login: switch to the user's space and mark it active
await db.switchSpace(spaceName: 'user_$userId', keepActive: true);

// Optional: strictly stay in default when needed (for example, login screen only)
// final db = await ToStore.open(..., applyActiveSpaceOnDefault: false);

// On logout: close and clear the active space so the next launch starts from default
await db.close(keepActiveSpace: false);

Intégration côté serveur/agent (scénarios de longue durée)

🖥️ Exemple : server_quickstart.dart

final db = await ToStore.open();

// Create table structures while the process is running
await db.createTables(appSchemas);

// Online schema updates
final result = await db.updateSchema('users')
  .renameTable('users_new')                // Rename table
  .modifyField(
    'username',
    minLength: 5,
    maxLength: 20,
    unique: true
  )                                        // Modify field attributes
  .renameField('old_name', 'new_name')     // Rename field
  .removeField('deprecated_field')         // Remove field
  .addField('created_at', type: DataType.datetime)  // Add field
  .removeIndex(fields: ['age'])            // Remove index
  .setPrimaryKeyConfig(                    // Change auto-generated PK strategy; avoid when the table already has data
    const PrimaryKeyConfig(type: PrimaryKeyType.shortCode)
  );
// Promote a unique field to PK (see promote-primary-key section; do not chain with the above):
// await db.updateSchema('users').promoteFieldToPrimaryKey(
//   sourceFieldName: 'user_id',
//   targetPrimaryKeyName: 'uid', // optional; omit to keep the source field name
// );

// Monitor migration progress
final taskId = result.taskId;
if (taskId != null) {
  // Inspect migration metadata
  print('Estimated duration: ${result.estimateDuration?.inMilliseconds} ms');
  print('Migration write mode: ${result.writeMode}'); // e.g. MigrationWriteMode.indexOnly

  final status = await db.queryMigrationTaskStatus(taskId);
  print('Migration progress: ${status?.progressPercentage}%');
}


// Optional performance tuning for pure server workloads
// yieldDurationMs controls how often long-running work yields time slices.
// The default is tuned to 8ms to keep frontend UI animations smooth.
// In environments without UI, 50ms is recommended for higher throughput.
final dbServer = await ToStore.open(
  config: DataStoreConfig(yieldDurationMs: 50),
);

Utilisation avancée

ToStore fournit un riche ensemble de fonctionnalités avancées pour des scénarios commerciaux complexes :

Opérations avancées Clé-Valeur (db.kv)

Pour des scénarios Clé-Valeur plus complexes, il est recommandé d'utiliser l'espace de noms db.kv. Il fournit un ensemble complet d'API avec isolation d'espace, partage global, plusieurs types de données, ainsi que des requêtes et filtres complexes chaînés (par ex. db.kv.query().prefix(...).orderBy...().limit(...) pour la pagination, le tri, le filtrage d'expiration, etc.).

  • Accès de base (Basic Access)

    // Définir une valeur (prend en charge String, int, bool, double, Map, List, etc.)
    await db.kv.set('key', 'value', ttl: Duration(hours: 1));
    
    // Obtenir la valeur dynamique brute
    dynamic val = await db.kv.get('key');
    
    // Supprimer une seule clé
    await db.kv.remove('key');
    
  • Getters sécurisés (Type-Safe Getters) Récupérez des données directement au format cible sans conversion manuelle :

    String? name = await db.kv.getString('user_name');
    int? age = await db.kv.getInt('user_age');
    bool? isVip = await db.kv.getBool('is_vip');
    Map<String, dynamic>? profile = await db.kv.getMap('profile');
    List<String>? tags = await db.kv.getList<String>('tags');
    
  • Opérations groupées (Bulk Operations) Traitez efficacement plusieurs paires clé-valeur en une seule opération :

    // Définition groupée
    await db.kv.setMany({
      'theme': 'dark',
      'language': 'fr_FR',
    });
    
    // Suppression groupée
    await db.kv.removeKeys(['temp_1', 'temp_2']);
    
  • Compteurs atomiques (Atomic Increment) Incrémentez ou décrémentez en toute sécurité les valeurs numériques dans des scénarios à haute concurrence :

    // Incrémenter de 1 (par défaut)
    await db.kv.setIncrement('view_count');
    // Décrémenter de 5 (passer une valeur négative)
    await db.kv.setIncrement('stock_count', amount: -5);
    
  • Requêtes chaînées d'enregistrements (db.kv.query) API chaînée similaire à db.query() pour interroger des enregistrements clé-valeur (avec value décodé) et prendre en charge la pagination. Contrairement à getKeys (noms de clés uniquement), cela renvoie des enregistrements complets.

    // Première page : filtrer par préfixe, trier par updated_at décroissant, 20 par page
    final page = await db.kv.query()
        .prefix('setting_')
        .orderByUpdatedAtDesc() // ou orderByKeyAsc / orderByKeyDesc / orderByUpdatedAtAsc
        .limit(20);
    
    for (final record in page.data) {
      // record contient : key, value, updated_at, expires_at
      print('${record['key']} = ${record['value']}');
    }
    
    // Recommandé : paginer avec next() / prev() (comme les requêtes de table, le plus simple)
    if (page.hasMore) {
      final page2 = await page.next();
      print('Page suivante : ${page2.data.length}');
      if (page2.hasPrev) {
        final back = await page2.prev();
        print('Page précédente : ${back.data.length}');
      }
    }
    
    // Pagination par offset (exclut cursor ; pour le deep paging préférer next() ci-dessus)
    final byOffset = await db.kv.query()
        .orderByKeyAsc()
        .limit(20)
        .offset(20);
    
    // Nombre total d'enregistrements correspondants (sans prefix : stats métadonnées O(1))
    final total = await db.kv.query().prefix('setting_').count();
    
    // Récupérer le premier enregistrement correspondant
    final first = await db.kv.query().prefix('setting_').orderByKeyAsc().first();
    
    // Espace KV global
    final globalPage = await db.kv.query(isGlobal: true).limit(50);
    
    // Par défaut les expirés sont filtrés ; pour inclure ceux non encore nettoyés :
    final withExpired = await db.kv.query()
        .includeExpired()
        .limit(20);
    

    Méthodes chaînées courantes :

    Méthode Description
    prefix(String) Filtrer par préfixe de key
    orderByKeyAsc / orderByKeyDesc Trier par key (clé primaire)
    orderByUpdatedAtAsc / orderByUpdatedAtDesc Trier par updated_at
    limit(n) Nombre max d'éléments par page (à spécifier explicitement de préférence)
    offset(n) Pagination par décalage (efface cursor)
    cursor(token) Cas spéciaux uniquement : jeton de pagination inter-processus/réseau
    includeExpired([true]) Inclure les enregistrements expirés non encore nettoyés
    count() Compter les correspondances
    first() Renvoyer le premier enregistrement (n'altère pas le limit du builder)

    Résultat QueryResult : pour la pagination courante, utiliser hasMore / hasPrev + next() / prev() ; nextCursorToken / prevCursorToken uniquement pour le transfert cross-end, etc. (comme les requêtes de table).

  • Découverte & Gestion (Discovery & Management)

    // Énumérer uniquement les noms de clés (sans value) ; prefix / limit / offset optionnels
    final keys = await db.kv.getKeys(prefix: 'setting_');
    final pageKeys = await db.kv.getKeys(
      prefix: 'setting_',
      limit: 100,
      offset: 0,
    );
    
    // Compter le nombre total de clés dans l'espace actuel
    final count = await db.kv.count();
    
    // Vérifier si une clé existe et n'a pas expiré
    final exists = await db.kv.exists('config_cache');
    
    // Sonde mémoire (synchrone, cache uniquement — voir [Sonde mémoire et récupération synchrone (peek)](#query-peek))
    final theme = db.kv.peekGet('theme') ?? await db.kv.get('theme');
    if (db.kv.peekExists('config_cache')) { /* ... */ }
    
    // Effacer toutes les données KV dans l'espace actuel
    await db.kv.clear();
    
  • Gestion du cycle de vie (TTL) Inspectez ou mettez à jour les paramètres d'expiration pour les clés existantes :

    // Obtenir la durée restante
    Duration? ttl = await db.kv.getTtl('token');
    
    // Mettre à jour le TTL pour une clé existante (expire dans 7 jours)
    await db.kv.setTtl('token', Duration(days: 7));
    
  • Surveillance réactive (Reactive Watch)

    // Surveiller une seule clé
    db.kv.watch<int>('unread_count').listen((count) => print(count));
    
    // Surveiller un instantané de plusieurs clés
    db.kv.watchValues(['theme', 'font_size']).listen((map) => print(map));
    
  • Partage global (isGlobal) Toutes les méthodes ci-dessus prennent en charge le paramètre optionnel isGlobal : true pour l'espace global (partagé entre tous les espaces), false (par défaut) pour l'espace isolé actuel.

Opérations groupées (Bulk Operations)

ToStore fournit des interfaces de traitement groupé spécialisées optimisées pour un débit de données à grande échelle. Ces interfaces utilisent la distribution de tâches en parallèle et le découpage temporel pour garantir la réactivité de l'interface utilisateur lors d'opérations d'écriture intensives.

Méthode Objectif principal Exigences en matière de données Caractéristiques
batchInsert Insérer des enregistrements par lot Doit contenir tous les champs non nullables Insertion pure, performance maximale
batchUpsert Synchronisation intelligente (Upsert) Doit contenir tous les champs non nullables Synchronisation complète, identifié par clé primaire ou champ unique
batchUpdate Mettre à jour des enregistrements par lot Clé primaire ou champ unique + Champs à mettre à jour Mises à jour partielles pour les enregistrements existants
  • Insertion groupée (batchInsert)

    await db.batchInsert('users', [
      {'username': 'user1', 'email': '[email protected]'},
      {'username': 'user2', 'email': '[email protected]'},
    ]);
    
  • Synchronisation groupée intelligente (batchUpsert) Identifie automatiquement "Insérer" ou "Mettre à jour" en fonction de la clé primaire ou des champs uniques. Courant pour la synchronisation complète des données.

    [!IMPORTANT] Exigences de données : Comme une insertion peut être déclenchée, batchUpsert nécessite que chaque enregistrement contienne tous les champs non nullables (nullable: false).

  • Mise à jour groupée haute performance (batchUpdate) Spécifiquement pour la mise à jour des enregistrements existants. Chaque enregistrement doit inclure une clé primaire ou un champ unique comme identifiant, ainsi que les champs à modifier.

    [!TIP] Mises à jour partielles : batchUpdate modifie uniquement les champs fournis et ne nécessite pas tous les champs non nullables, lo qui le rend idéal pour les mises à jour incrémentielles.

    await db.batchUpdate('users', [
      {'username': 'john', 'age': 27}, // Identifier par champ unique 'username' et mettre à jour 'age'
      {'id': '1002', 'status': 'active'}, // Peut également utiliser la clé primaire directement
    ]);
    

[!TIP] Vous pouvez définir allowPartialErrors: true pour vous assurer que les échecs d'enregistrements individuels (par exemple, une violation de contrainte unique) ne rejettent pas l'intégralité de l'opération groupée.

Garantie de récupération à l'écriture (Recovery Durability)

ToStore permet de contrôler avec souplesse le niveau d'auto-réparation au moment où l'opération d'écriture renvoie son résultat (fin de l'await) :

Niveau Garantie de récupération à la réponse Cas d'utilisation et caractéristiques
RecoveryDurability.standard
(Recommandation par défaut)
Résistant aux crashs avant réponse Protection contre les plantages de l'application, les exceptions non interceptées et les arrêts par OOM du système. Équilibre un débit très élevé et la sécurité métier quotidienne.
RecoveryDurability.durable Résistant aux coupures de courant avant réponse Écriture physique forcée sur le stockage avant le retour. Garantit une auto-réparation complète même en cas de coupure de courant soudaine ou de panique noyau. Idéal pour les transactions financières et audits critiques.
RecoveryDurability.async Débit maximal (sauvegarde asynchrone) Mis en file d'attente en mémoire et retourne immédiatement ; après le retour, pour de petits volumes de données, il n'existe généralement qu'une fenêtre de perte extrêmement courte de quelques millisecondes. Idéal pour les journaux massifs et métriques.

1. Configuration globale par défaut

Configurez le niveau de récupération par défaut au niveau de l'instance dans DataStoreConfig :

final db = await ToStore.open(
  config: DataStoreConfig(
    defaultRecoveryDurability: RecoveryDurability.standard, // Par défaut : résistant aux crashs avant réponse
  ),
);

2. Remplacement par opération

Toutes les écritures dans des tables structurées, les opérations groupées, les mises à jour/suppressions chaînées et le stockage Clé-Valeur (KV) prennent en charge une spécification individuelle via le paramètre optionnel durability :

// 1. Opérations sur tables structurées
await db.insert('orders', orderData, durability: RecoveryDurability.durable); // Commande critique : résistant aux coupures
await db.batchInsert('logs', logList, durability: RecoveryDurability.async); // Journaux massifs : asynchrone ultrarapide

// 2. Mises à jour et suppressions chaînées
await db.update('users', {'status': 'active'})
  .where('id', '=', userId)
  .durability(RecoveryDurability.durable);

// 3. Stockage Clé-Valeur (KV)
await db.setValue('token', tokenVal, durability: RecoveryDurability.standard);
await db.kv.set('session_id', 'xyz', durability: RecoveryDurability.async);
await db.kv.setMany(settingsMap, durability: RecoveryDurability.durable);

Vecteurs, texte et récupération hybride

La récupération lexicale de texte, de vecteurs denses et neuronale sparse partagent une même chaîne de requête (matchText / matchVector / matchSparse) : combinez-les avec des prédicats structurés sur la même chaîne, ou fusionnez plusieurs branches de rappel. Les scores et diagnostics de canal sont renvoyés dans QueryResult.retrieval, alignés 1:1 avec les lignes de data. Si vous n'avez besoin que des clés primaires et des scores, préférez .select(['id']) (ou le nom de votre champ PK) pour que le moteur évite d'hydrater les lignes complètes — sinon la récupération hybride matérialise les enregistrements entiers (y compris de gros embeddings) et le débit peut chuter fortement. Pour un ANN dédié sans filtres ni fusion, db.vectorSearch(...) renvoie List<VectorSearchResult> (clé primaire + score) avec le même chemin de recherche central.

Visibilité de recherche : Après un insert/update réussi, les index ordinaires, texte et sparse sont immédiatement interrogeables ; les index vectoriels ne sont pas construits sur le chemin d'écriture (pour ne pas nuire au débit) et ne sont pas immédiatement recherchables. Quand vous devez les inclure dans la recherche, appelez await db.flush() après votre lot métier (commodité optionnelle) ; ce n'est qu'alors qu'ils participent à matchVector / vectorSearch.

await db.createTables([
  const TableSchema(
    name: 'documents',
    primaryKeyConfig: PrimaryKeyConfig(
      name: 'id',
      type: PrimaryKeyType.timestampBased,
    ),
    fields: [
      FieldSchema(name: 'content', type: DataType.text, nullable: false),
      FieldSchema(
        name: 'category',
        type: DataType.text,
        nullable: false,
        createIndex: true,
      ),
      FieldSchema(
        name: 'features',
        type: DataType.sparse, // Neural sparse vector
        nullable: false,
      ),
      FieldSchema(
        name: 'embedding',
        type: DataType.vector, // Dense vector
        nullable: false,
        vectorConfig: VectorFieldConfig(
          dimensions: 128, // Written and queried vectors must match this width
        ),
      ),
    ],
    indexes: [
      IndexSchema(fields: ['content'], type: IndexType.text), // Lexical text index
      IndexSchema(fields: ['features'], type: IndexType.sparse), // Neural sparse index
      IndexSchema(
        fields: ['embedding'],
        type: IndexType.vector, // Dense vector index
        vectorConfig: VectorIndexConfig(
          indexType: VectorIndexType.ngh, // NGH: ToStore built-in dense index
          distanceMetric: VectorDistanceMetric.cosine,
        ),
      ),
    ],
  ),
]);

final queryVector =
    VectorData.fromList(List.generate(128, (i) => i * 0.01));
final querySparse = SparseVectorData.fromMap({12: 0.8, 45: 0.6, 90: 0.3});

// 1) Lexical text retrieval (engine tokenizes TextQuery.text;
//    or use pre-tokenized TextQuery.terms / termsWeighted)
final textHits = await db
    .query('documents')
    .select(['id'])
    .matchText('content', TextQuery.text('distributed kernel storage'))
    .limit(5);

// 2) Neural sparse retrieval
final sparseHits = await db
    .query('documents')
    .select(['id'])
    .matchSparse('features', querySparse, minScore: 0.30)
    .limit(5);

// 3) Dense vector ANN (default searchDepth = 50)
final result = await db
    .query('documents')
    .select(['id'])
    .matchVector('embedding', queryVector, minScore: 0.40)
    .limit(5);

for (var i = 0; i < result.data.length; i++) {
  final record = result.data[i];
  final entry = result.retrieval?.entries[i];
  print('pk=${record['id']}, score=${entry?.score}, '
      'rawScore=${entry?.rawScore}, distance=${entry?.meta?['distance']}');
}

// 4) Structured filter + vector (AND)
final filtered = await db
    .query('documents')
    .whereEqual('category', 'tech')
    .matchVector('embedding', queryVector, minScore: 0.40)
    .limit(5);

// 5) Multi-way fusion: text + sparse + vector (default weightedScore)
final fused = await db
    .query('documents')
    .matchText('content', TextQuery.text('distributed storage'), weight: 0.4)
    .matchSparse('features', querySparse, weight: 0.3, minScore: 0.20)
    .matchVector('embedding', queryVector, weight: 0.6, minScore: 0.40)
    .limit(10);
print('fusion=${fused.retrieval?.fusionMethod}'); // weightedScore

// Opt into rank-only fusion (relative scores — not absolute relevance bands)
final fusedRrf = await db
    .query('documents')
    .matchText('content', TextQuery.text('distributed storage'), weight: 0.4)
    .matchVector('embedding', queryVector, weight: 0.6, minScore: 0.40)
    .fusionMethod(RetrievalFusionMethod.rrf)
    .limit(10);
print('fusion=${fusedRrf.retrieval?.fusionMethod}'); // rrf

// Dedicated ANN (PK + score only; no query chain / fusion)
final ann = await db.vectorSearch(
  'documents',
  fieldName: 'embedding',
  queryVector: queryVector,
  topK: 5,
  minScore: 0.40,
);

Correspondance canal / schéma :

Canal Type de champ Index API de requête Valeur de requête
Texte lexical DataType.text IndexType.text matchText / orMatchText TextQuery.text / terms / termsWeighted
Neuronal sparse DataType.sparse IndexType.sparse matchSparse / orMatchSparse SparseVectorData
Vecteur dense DataType.vector IndexType.vector matchVector / orMatchVector VectorData, etc.

Configuration des vecteurs denses (VectorFieldConfig, VectorIndexConfig) :

  • dimensions : doit correspondre à la largeur réelle de l'embedding écrit
  • indexType : identifiant opaque de l'algorithme dense ; actuellement ngh
  • distanceMetric : métrique de similarité côté index (construction et recherche) ; cosine est courant pour les embeddings sémantiques, l2 pour la distance euclidienne, innerProduct pour le produit scalaire. Après écriture de données, la modifier exige en général de reconstruire l'index vectoriel.

Paramètres de récupération chaînée (chaque match* / orMatch*, plus limit sur la chaîne) :

  • Texte
    • TextQuery.text : tokenisé par le moteur
    • TextQuery.terms / termsWeighted : pré-tokenisé ; pas de second passage ; les termes latins doivent correspondre au côté index (généralement en minuscules)
    • operator : or (par défaut ; classement par union) ou and (chaque terme de poids positif doit matcher, puis classement)
    • La correspondance de phrases n'est pas prise en charge
  • Sparse
    • SparseVectorData / SparseVectorData.fromMap(...) : vecteur de requête sparse
    • Les poids côté document devraient de préférence tomber dans (0, 1]
  • Vecteur
    • field / vector : champ cible et vecteur de requête
    • searchDepth : >= 1, défaut 50 ; des valeurs plus élevées augmentent souvent le rappel et la latence ; plus proche voisin approximatif — pas un recall@K garanti
    • distanceThreshold : plafond de distance
  • Partagés
    • weight : poids de fusion multi-voies ; défaut 1.0
    • minScore : plancher de pertinence
    • limit : nombre de résultats (topK)
    • .fusionMethod(...) : multi-voies par défaut weightedScore ; commutable vers rrf

Notes sur le résultat et le scoring (QueryResult / VectorSearchResult) :

  • Les enregistrements métier sont dans data ; scores et infos de canal dans retrieval.entries, alignés 1:1 avec data. Préférez .select(['id']) si vous n'avez besoin que des clés primaires et des scores.
  • score (score de pertinence normalisé, 0.0 ~ 1.0) : pertinence unifiée texte / sparse / vecteur (plus haut = plus pertinent). L'auto-match exact de vecteur atteint 1.0. Utilisez minScore pour garder les hits forts et écarter les faibles. La fusion multi-voies par défaut weightedScore conserve un hit fort mono-canal ; texte et sparse restent dans [0.0, 1.0).
  • rawScore : métrique physique non normalisée — cosinus / produit scalaire / L2 / impact texte. Lisez rawScore / distance pour la métrique sous-jacente.
  • entry.meta['distance'] : distance ANN sur les canaux vectoriels (plus bas = plus proche).
  • retrieval.fusionMethod : null pour un rappel mono-canal ; multi-voies par défaut weightedScore (commutable via .fusionMethod(RetrievalFusionMethod.rrf)).
  • Le db.vectorSearch(...) de premier niveau renvoie List<VectorSearchResult> (primaryKey / score / rawScore / distance) pour un ANN dédié. Le minScore optionnel utilise le même plancher de pertinence que matchVector (peut renvoyer moins que topK).

Score de pertinence (score) et ligne de base des seuils (mono-canal et multi-voies weightedScore ; pas pour rrf). Pour des embeddings typiques (dimensions ≥ 128) ; à plus basse dimension, les voisins faibles peuvent scorer haut — augmentez minScore ou utilisez rawScore si besoin :

Score de pertinence (score) Signification de base et scénarios typiques
>= 0.85 Même entité (vérification faciale, biométrie, déduplication exacte)
>= 0.70 Correspondance sémantique haute confiance (faits centraux, Q&A précise)
>= 0.40 Pertinence sémantique de base (RAG général, anti-hallucination des bases de connaissances)
>= 0.30 Premier rappel large (découverte floue, pool pré-rerank)
< 0.30 Association faible ou bruit de fond

Configurez le minScore du canal selon le besoin pour écarter les hits de faible pertinence.

TTL au niveau de la table (expiration automatique basée sur le temps)

Pour les journaux, la télémétrie, les événements et autres données qui devraient expirer avec le temps, vous pouvez définir la durée de vie au niveau de la table via ttlConfig. Le moteur nettoiera automatiquement les enregistrements expirés en arrière-plan :

const TableSchema(
  name: 'event_logs',
  fields: [
    FieldSchema(
      name: 'created_at',
      type: DataType.datetime,
      nullable: false,
      createIndex: true,
      defaultValueType: DefaultValueType.currentTimestamp,
    ),
  ],
  ttlConfig: TableTtlConfig(
    ttlMs: 7 * 24 * 60 * 60 * 1000, // Conserver 7 jours
    // Obligatoire pour les nouvelles tables / premier activation du TTL :
    // 1) DataType.datetime  2) nullable: false
    // 3) DefaultValueType.currentTimestamp
    sourceField: 'created_at',
  ),
);

Éviction par capacité (FIFO / LRU)

Limite le nombre d’enregistrements conservés par une table selon le compte et/ou la taille approximative. Indépendant du TTL—les deux peuvent être activés ensemble. L’excédent est nettoyé automatiquement en arrière-plan.

// FIFO (par défaut) : évincer les plus anciens par clé primaire.
// Ne pas définir sourceField (sauf PrimaryKeyType.none).
capacityConfig: CapacityConfig(
  maxEntries: 10000,
  // maxBytes: 50 * 1024 * 1024, // limite de taille optionnelle
  policy: CapacityEvictionPolicy.fifo,
),

// LRU : sourceField obligatoire (datetime, non-null, currentTimestamp).
// Mettez à jour ce champ quand l’enregistrement doit compter comme récent.
capacityConfig: CapacityConfig(
  maxEntries: 10000,
  policy: CapacityEvictionPolicy.lru,
  sourceField: 'last_active_at',
),
  • Définir au moins l’un de maxEntries / maxBytes.
  • FIFO + PrimaryKeyType.none exige aussi sourceField (mêmes règles datetime).

Vous pouvez aussi activer, modifier ou désactiver l’éviction par capacité sur une table existante à l’exécution (sans rouvrir la base) :

// Activer / mettre à jour
await db.updateSchema('recent_events').setCapacityConfig(
  CapacityConfig(
    maxEntries: 10000,
    policy: CapacityEvictionPolicy.lru,
    sourceField: 'last_active_at',
  ),
);

// Désactiver (conserve les lignes ; arrête les suppressions par capacité)
await db.updateSchema('recent_events').disableCapacity();

La capacité KV se configure à l’ouverture via DataStoreConfig (pas à chaque kv.set) :

  • kvCapacityConfig : limite les clés de l’espace courant
  • globalKvCapacityConfig : limite le KV global
  • Même forme que le CapacityConfig de table, sans sourceField
final db = await ToStore.open(
  dbPath: '...',
  config: DataStoreConfig(
    kvCapacityConfig: CapacityConfig(
      maxEntries: 5000,
      policy: CapacityEvictionPolicy.lru,
    ),
    globalKvCapacityConfig: CapacityConfig(
      maxEntries: 2000,
      policy: CapacityEvictionPolicy.fifo,
    ),
  ),
);

Stockage intelligent (Upsert)

ToStore décide s'il faut mettre à jour ou insérer en fonction de la clé primaire ou du champ unique inclus dans data. where n'est pas pris en charge ici ; la cible du conflit est déterminée par les données elles-mêmes.

// Par clé primaire
final result = await db.upsert('users', {
  'id': 1,
  'username': 'john',
  'email': '[email protected]',
});

// Par clé unique (l'enregistrement doit contenir tous les champs participant à une contrainte unique plus les champs obligatoires)
await db.upsert('users', {
  'username': 'john',
  'email': '[email protected]',
  'age': 26,
});

// Batch upsert (prend en charge le mode atomique ou le mode succès partiel)
// allowPartialErrors: true signifie que certaines lignes peuvent échouer alors que d'autres réussissent encore
final batchResult = await db.batchUpsert('users', [
  {'username': 'a', 'email': '[email protected]'},
  {'username': 'b', 'email': '[email protected]'},
], allowPartialErrors: true);

Requêtes avancées

ToStore fournit une API de requête déclarative chaînable avec une gestion flexible des champs et des relations multi-tables complexes.

1. Sélection de champ (select)

La méthode select spécifie quels champs sont renvoyés. Si vous ne l'appelez pas, tous les champs sont renvoyés par défaut.

  • Alias : prend en charge la syntaxe field as alias (insensible à la casse) pour renommer les clés dans le jeu de résultats
  • Champs qualifiés de table : dans les jointures multi-tables, table.field évite les conflits de noms
  • Mélange d'agrégation : les objets Agg peuvent être placés directement dans la liste select
final results = await db.query('orders')
    .select([
      'orders.id',
      'users.name as customer_name',
      'orders.amount',
      Agg.count('id', alias: 'total_items')
    ])
    .join('users', 'orders.user_id', '=', 'users.id')
    .where('orders.amount', '>', 1000)
    .limit(20);

2. Rejoint (join)

Prend en charge les normes join (jointure interne), leftJoin et rightJoin.

3. Jointures intelligentes basées sur des clés étrangères (recommandé)

Si foreignKeys est défini correctement dans TableSchema, vous n'avez pas besoin d'écrire manuellement les conditions de jointure. Le moteur peut résoudre les relations de référence et générer automatiquement le chemin JOIN optimal.

  • joinReferencedTable(tableName) : rejoint automatiquement la table parent référencée par la table courante
  • joinReferencingTable(tableName) : rejoint automatiquement les tables enfants qui font référence à la table actuelle
// Assume posts defines a foreign key to users
final posts = await db.query('posts')
    .joinReferencedTable('users') // Automatically resolves to ON posts.user_id = users.id
    .select(['posts.title', 'users.username'])
    .limit(20);

Agrégation, regroupement et statistiques (Agg & GroupBy)

1. Agrégation (Agg usine)

Les fonctions d'agrégation calculent des statistiques sur un ensemble de données. Avec le paramètre alias, vous pouvez personnaliser les noms des champs de résultat.

Méthode Objectif Exemple
Agg.count(field) Compter les enregistrements non nuls Agg.count('id', alias: 'total')
Agg.sum(field) Valeurs de somme Agg.sum('amount', alias: 'total_price')
Agg.avg(field) Valeur moyenne Agg.avg('score', alias: 'average_score')
Agg.max(field) Valeur maximale Agg.max('age')
Agg.min(field) Valeur minimale Agg.min('price')

[!TIP] Deux styles d'agrégation courants

  1. Méthodes de raccourci (recommandées pour les métriques uniques) : appelez directement sur la chaîne et récupérez immédiatement la valeur calculée. num? totalAge = await db.query('users').sum('age');
  2. Intégré dans select (pour plusieurs métriques ou regroupements) : transmettez les objets Agg dans la liste select. final stats = await db.query('orders').select(['status', Agg.sum('amount')]).groupBy(['status']);

2. Regroupement et filtrage (groupBy / having)

Utilisez groupBy pour catégoriser les enregistrements, puis having pour filtrer les résultats agrégés, similaire au comportement HAVING de SQL.

final stats = await db.query('orders')
    .select([
      'status',
      Agg.sum('amount', alias: 'sum_amount'),
      Agg.count('id', alias: 'order_count')
    ])
    .groupBy(['status'])
    // having accepts a QueryCondition used to filter aggregated results
    .having(QueryCondition().where(Agg.sum('amount'), '>', 5000))
    .limit(10);

3. Méthodes de requête d'assistance

  • exists() (haute performance) : vérifie si un enregistrement correspond. Contrairement à count() > 0, il court-circuite dès qu'une correspondance est trouvée, ce qui est excellent pour les très grands ensembles de données.
  • count() : renvoie efficacement le nombre d'enregistrements correspondants.
  • first() : une méthode pratique équivalente à limit(1) et renvoyant directement la première ligne sous la forme d'un Map.
  • distinct([fields]) : déduplique les résultats. Si fields est fourni, l'unicité est calculée en fonction de ces champs.
// Efficient existence check
if (await db.query('users').whereEqual('email', '[email protected]').exists()) {
  print('Email is already registered');
}

// Get a deduplicated city list
final cities = await db.query('users').distinct(['city']);

4. Logique complexe avec QueryCondition

QueryCondition est l'outil principal de ToStore pour la logique imbriquée et la construction de requêtes entre parenthèses. Lorsque de simples appels where enchaînés ne suffisent pas pour des expressions comme (A AND B) OR (C AND D), c'est l'outil à utiliser.

  • condition(QueryCondition sub) : ouvre un groupe imbriqué AND
  • orCondition(QueryCondition sub) : ouvre un groupe imbriqué OR
  • or() : change le connecteur suivant en OR (la valeur par défaut est AND)
Exemple 1 : Conditions OU mixtes

SQL équivalent : WHERE is_active = true AND (role = 'admin' OR fans >= 1000)

final subGroup = QueryCondition()
    .whereEqual('role', 'admin')
    .or()
    .whereGreaterThanOrEqualTo('fans', 1000);

final results = await db.query('users')
    .whereEqual('is_active', true)
    .condition(subGroup);
Exemple 2 : Fragments de condition réutilisables

Vous pouvez définir des fragments de logique métier réutilisables une seule fois et les combiner dans différentes requêtes :

final hotUser = QueryCondition().whereGreaterThan('fans', 5000);
final recentLogin = QueryCondition().whereGreaterThan('last_login', '2024-01-01');

final targetUsers = await db.query('users')
    .condition(hotUser)
    .condition(recentLogin);

5. Requête en streaming

Convient aux très grands ensembles de données lorsque vous ne souhaitez pas tout charger en mémoire en même temps. Les résultats peuvent être traités au fur et à mesure de leur lecture.

db.streamQuery('users').listen((data) {
  print('Processing one record: $data');
});

6. Requête réactive

La méthode watch() vous permet de surveiller les résultats des requêtes en temps réel. Il renvoie un Stream et réexécute automatiquement la requête chaque fois que les données correspondantes changent dans la table cible.

  • Anti-rebond automatique : l'anti-rebond intelligent intégré évite les rafales de requêtes redondantes
  • Synchronisation de l'interface utilisateur : fonctionne naturellement avec Flutter StreamBuilder pour les listes de mise à jour en direct
// Simple listener
db.query('users').whereEqual('is_online', true).watch().listen((users) {
  print('Online user count changed: ${users.length}');
});

// Flutter StreamBuilder integration example
// Local UI refreshes automatically when data changes
StreamBuilder<List<Map<String, dynamic>>>(
  stream: db.query('messages').orderByDesc('id').limit(50).watch(),
  builder: (context, snapshot) {
    if (snapshot.hasData) {
      return ListView.builder(
        itemCount: snapshot.data!.length,
        itemBuilder: (context, index) => MessageTile(snapshot.data![index]),
      );
    }
    return CircularProgressIndicator();
  },
)

Mise en cache manuelle des résultats de requête (facultatif)

[!IMPORTANT] ToStore inclut déjà un cache LRU intelligent à plusieurs niveaux efficace en interne. La gestion manuelle du cache de routine n'est pas recommandée. Considérez-la uniquement dans des cas particuliers :

  1. Analyses complètes coûteuses sur des données non indexées qui changent rarement
  2. Exigences persistantes de latence ultra-faible, même pour les requêtes non brûlantes
  • useQueryCache([Duration? expiry]) : active le cache et définit éventuellement une expiration
  • noQueryCache() : désactiver explicitement le cache pour cette requête
  • clearQueryCache() : invalider manuellement le cache pour ce modèle de requête
final results = await db.query('heavy_table')
    .where('non_indexed_field', '=', 'value')
    .useQueryCache(const Duration(minutes: 10)); // Manual acceleration for a heavy query only

Requête et pagination efficace

[!TIP] Spécifiez toujours limit comme taille de page : Il est fortement recommandé de toujours spécifier limit dans vos requêtes. S'il est omis, le moteur limitera par défaut à 1 000 enregistrements pour éviter de charger trop de données à la fois.

ToStore prend en charge la pagination en mode double. Pour le défilement infini ou le chargement de listes, nous recommandons fortement l'utilisation de la pagination par curseur fluide intégrée ; pour sauter directement à des pages spécifiques, la pagination offset de base suffit :

1. Pagination de base (Mode Offset)

Adapté aux scénarios où le volume de données est faible (par exemple, inférieur à 10k) ou lorsque vous devez sauter précisément à une page spécifique.

final result = await db.query('users')
    .orderByDesc('created_at')
    .offset(40) // Ignorer les 40 premières lignes
    .limit(20); // Récupérer 20 lignes

[!TIP] Lorsque l'offset devient très grand, la base de données doit analyser et ignorer une grande quantité d'enregistrements, ce qui entraîne une baisse linéaire des performances. Pour une pagination profonde ou des ensembles de données plus volumineux, il est recommandé d'utiliser le Mode Curseur.

2. Pagination par curseur (Mode Curseur - Recommandé)

Idéal pour les ensembles de données volumineux et le défilement infini. En enregistrant la position de départ du flux de données de la page actuelle, le moteur se positionne directement à cet emplacement lors de la pagination (seek), évitant ainsi d'analyser et d'ignorer les données historiques, maintenant ainsi une vitesse constante pour la pagination profonde.

  • Gestion automatique : Définissez une limite de taille de page et appelez simplement next() ou prev() pour les pages suivantes afin d'obtenir des performances de pagination optimales en toute simplicité.
  • Décalage du point de départ : Permet de combiner .offset(N) lors de la requête initiale pour localiser la fenêtre de départ, après quoi l'appel à next() récupère directement les pages suivantes.
// 1. Lancer la requête initiale
final page1 = await db.query('users')
    .orderByDesc('id')
    .limit(20);

// 2. Récupérer la page suivante
if (page1.hasMore) {
  final page2 = await page1.next(); 
  print('Nombre d'éléments sur la page suivante : \${page2.data.length}');
  
  // 3. Récupérer la page précédente
  if (page2.hasPrev) {
    final prevPage = await page2.prev();
    print('Données de la page précédente : \${prevPage.data}');
  }
}
Scénario avancé : Pagination par jeton sans état (Token-based Cursor)

Pour la pagination courante dans l'app, préférez next() / prev() ci-dessus. Utilisez les jetons de curseur uniquement pour les API client-serveur ou lors de la sérialisation de l'état de pagination entre processus/réseaux :

  • La requête initiale renvoie les chaînes de jetons nextCursorToken et prevCursorToken.
  • La requête suivante transmet le jeton via .cursor(token) pour se positionner directement (seek).
  • Remarque : cursor et offset sont mutuellement exclusifs ; en définir un efface l'autre.
// Requête initiale (par exemple, côté serveur API)
final page1 = await db.query('users')
    .orderByDesc('id')
    .limit(20);

final String? nextToken = page1.nextCursorToken; // Sérialiser et renvoyer ce jeton au client

// Lorsque le client demande la page suivante avec le jeton :
if (nextToken != null) {
  final page2 = await db.query('users')
      .orderByDesc('id')
      .limit(20)
      .cursor(nextToken); // Transmettre le jeton pour se positionner et lire précisément
}
Fonctionnalité Mode Offset Mode Curseur
Performance de la requête Se dégrade à mesure que les pages augmentent Vitesse constante pour la pagination profonde
Idéal pour Ensembles de données plus petits, sauts de page exacts Ensembles de données volumineux, défilement infini
Cohérence lors des modifications Les modifications de données peuvent entraîner des doublons ou des sauts de lignes Évite les doublons et les omissions causés par les modifications de données

Sonde mémoire et récupération synchrone (peek)

Pour les scénarios aux exigences extrêmes de débit et de latence, ToStore fournit la série peek de récupération synchrone purement en mémoire, absorbant les lectures chaudes en rafale directement dans le processus : les appareils edge peuvent supporter des millions de lectures par seconde ; les serveurs avec un matériel plus puissant peuvent atteindre des dizaines de millions par machine (voir Benchmarks).

[!NOTE] Cache mémoire uniquement : peek est un contournement mémoire pur sans planification. En cas d'échec de cache, retour immédiat vide/null ; le moteur n'effectue pas d'E/S fichier synchrone (évitant le blocage de la boucle d'événements sous forte concurrence). Pour des résultats persistants complets, utilisez await query() dans l'application.

Méthodes peek

Méthode Type de retour Description
peekFirst() Map<String, dynamic>? Enregistrement unique ; null en cas d'échec de cache
peek() QueryResult<T> QueryResult avec liste data et métadonnées de pagination (hasMore, curseurs, etc.) ; données uniquement en cas de succès de cache
peekExists() bool Vérifie de façon synchrone l'existence d'un enregistrement correspondant en cache
peekCount() int Compte de façon synchrone les enregistrements correspondants en cache
result.peekNext() QueryResult<T> Page suivante synchrone lorsque le résultat paginé est en cache
result.peekPrev() QueryResult<T> Page précédente synchrone lorsque le résultat paginé est en cache

Bonne pratique : sonde mémoire d'abord (Peek-Through)

// Enregistrement unique : sonde mémoire d'abord, requête asynchrone standard si échec
final q = db.query('users').where('id', '=', userId);
final user = q.peekFirst() ?? await q.first();

// Requête paginée avec sonde
final listQ = db.query('users').orderByDesc('id').limit(20);
var page = listQ.peek();
if (page.data.isEmpty) page = await listQ;

if (page.hasMore) {
  final next = page.peekNext(); // succès de cache : pagination synchrone
  if (next.data.isEmpty) await page.next();
}

Sonde KV (db.kv)

Méthode Équivalent async Description
peekGet(key) get(key) Sonde ponctuelle en mémoire ; clés expirées → null
peekExists(key) exists(key) Vérification d'existence en mémoire
db.kv.query().peek() await db.kv.query() Sonde paginée (préfixe / tri / limit)
db.kv.query().peekFirst() await db.kv.query().first() Sonde du premier enregistrement
// Point : sonde d'abord, async en repli si échec
final theme = db.kv.peekGet('theme', isGlobal: true) ?? await db.kv.get('theme', isGlobal: true);

// Sonde KV paginée
var page = db.kv.query().prefix('setting_').limit(20).peek();
if (page.data.isEmpty) page = await db.kv.query().prefix('setting_').limit(20);

[!TIP] Recommandation : Les requêtes asynchrones standard (await query()) utilisent la planification d'événements pour la stabilité à long terme et l'équité multitâche ; 100k+ QPS suffisent pour la plupart des charges. La série peek est conçue pour absorber des pics extrêmes de lecture chaude à des millions/dizaines de millions de QPS par machine.

Clés étrangères et cascade

Les clés étrangères garantissent l'intégrité référentielle et vous permettent de configurer des mises à jour et des suppressions en cascade. Les relations sont validées lors de l'écriture et de la mise à jour. Si les politiques en cascade sont activées, les données associées sont mises à jour automatiquement, réduisant ainsi le travail de cohérence dans le code de l'application.

await db.createTables([
  const TableSchema(
    name: 'users',
    primaryKeyConfig: PrimaryKeyConfig(name: 'id'),
    fields: [
      FieldSchema(name: 'username', type: DataType.text, nullable: false),
    ],
  ),
  TableSchema(
    name: 'posts',
    primaryKeyConfig: const PrimaryKeyConfig(name: 'id'),
    fields: [
      const FieldSchema(name: 'title', type: DataType.text, nullable: false),
      const FieldSchema(name: 'user_id', type: DataType.integer, nullable: false),
      const FieldSchema(name: 'content', type: DataType.text),
    ],
    foreignKeys: [
        ForeignKeySchema(
          name: 'fk_posts_user',
          fields: ['user_id'],              // Field in the current table
          referencedTable: 'users',         // Referenced table
          referencedFields: ['id'],         // Referenced field
          onDelete: ForeignKeyCascadeAction.cascade,  // Delete posts automatically when the user is deleted
          onUpdate: ForeignKeyCascadeAction.cascade,  // Cascade updates
        ),
    ],
  ),
]);

Opérateurs de requête

Toutes les conditions where(field, operator, value) prennent en charge les opérateurs suivants (insensibles à la casse) :

Opérateur Description Exemple / Performance
= Égal where('status', '=', 'val') — [Recommandé] Recherche par index (Seek)
!=, <> Pas égal where('role', '!=', 'val') — [Attention] Analyse complète de la table
> , >=, <, <= Comparaison where('age', '>', 18) — [Recommandé] Analyse par index
IN Dans la liste where('id', 'IN', [...]) — [Recommandé] Recherche par index (Seek)
NOT IN Pas dans la liste where('status', 'NOT IN', [...]) — [Attention] Analyse complète de la table
BETWEEN Plage where('age', 'BETWEEN', [18, 65]) — [Recommandé] Analyse par index
LIKE Correspondance de modèle (% = n'importe quel caractère, _ = un seul caractère) where('name', 'LIKE', 'John%') — [Attention] Voir la note ci-dessous
NOT LIKE Inadéquation des motifs where('email', 'NOT LIKE', '...') — [Attention] Analyse complète de la table
IS Est-ce que null where('deleted_at', 'IS', null) — [Recommandé] Recherche par index (Seek)
IS NOT N'est-ce pas null where('email', 'IS NOT', null) — [Attention] Analyse complète de la table

Méthodes de requête sémantique (recommandées)

Recommandé pour éviter les chaînes d'opérateurs écrites à la main et pour obtenir une meilleure assistance IDE.

1. Comparaison

Utilisé pour les comparaisons directes de valeurs numériques ou de chaînes.

db.query('users').whereEqual('username', 'John');           // Equal
db.query('users').whereNotEqual('role', 'guest');          // Not equal
db.query('users').whereGreaterThan('age', 18);             // Greater than
db.query('users').whereGreaterThanOrEqualTo('score', 60);  // Greater than or equal
db.query('users').whereLessThan('price', 100);             // Less than
db.query('users').whereLessThanOrEqualTo('quantity', 10);  // Less than or equal
db.query('users').whereTrue('is_active');                  // Is true
db.query('users').whereFalse('is_banned');                 // Is false

2. Collection & Gamme

Utilisé pour tester si un champ se situe dans un ensemble ou une plage.

db.query('users').whereIn('id', ['id1', 'id2']);                 // In list
db.query('users').whereNotIn('status', ['banned', 'pending']);   // Not in list
db.query('users').whereBetween('age', 18, 65);                   // In range (inclusive)

3. Vérification nulle

Utilisé pour tester si un champ a une valeur.

db.query('users').whereNull('deleted_at');    // Is null
db.query('users').whereNotNull('email');      // Is not null
db.query('users').whereEmpty('nickname');     // Is null or empty string
db.query('users').whereNotEmpty('bio');       // Is not null and not empty

4. Correspondance de motifs

Prend en charge la recherche par caractère générique de style SQL (% correspond à n'importe quel nombre de caractères, _ correspond à un seul caractère).

db.query('users').whereLike('name', 'John%');                        // SQL-style pattern match
db.query('users').whereContains('bio', 'flutter');                   // Contains match (LIKE '%value%')
db.query('users').whereStartsWith('name', 'Admin');                  // Prefix match (LIKE 'value%')
db.query('users').whereEndsWith('email', '.com');                    // Suffix match (LIKE '%value')
db.query('users').whereContainsAny('tags', ['dart', 'flutter']);     // Fuzzy match against any item in the list
// Equivalent to: .where('age', '>', 18).where('name', 'like', '%John%')
final users = await db.query('users')
    .whereGreaterThan('age', 18)
    .whereLike('username', '%John%')
    .orderByDesc('age')
    .limit(20);

[!CAUTION] Guide de Performance des Requêtes (Index vs Analyse Complète)

Dans les scénarios de données à grande échelle (millions de lignes ou plus), veuillez suivre ces principes pour éviter les ralentissements du thread principal et les délais d'attente de requête :

  1. Optimisé par Index - [Recommandé] :

    • Méthodes sémantiques : whereEqual, whereGreaterThan, whereLessThan, whereIn, whereBetween, whereNull, whereTrue, whereFalse et whereStartsWith (correspondance de préfixe).
    • Opérateurs : =, >, <, >=, <=, IN, BETWEEN, IS null, LIKE 'prefix%'.
    • Explication : Ces opérations permettent un positionnement ultra-rapide via les index. Pour whereStartsWith / LIKE 'abc%', l'index peut toujours effectuer une analyse de plage de préfixes.
  2. Risques d'Analyse Complète - [Attention] :

    • Correspondance floue : whereContains (LIKE '%val%'), whereEndsWith (LIKE '%val'), whereContainsAny.
    • Requêtes de négation : whereNotEqual (!=, <>), whereNotIn (NOT IN), whereNotNull (IS NOT null/whereNotEmpty).
    • Inadéquation des motifs : NOT LIKE.
    • Explication : Les opérations ci-dessus nécessitent généralement de parcourir toute la zone de stockage de données, même si un index est créé. Bien que l'impact soit minimal sur les appareils mobiles ou les petits ensembles de données, dans les scénarios d'analyse de données distribuées ou de taille ultra-grande, elles doivent être utilisées avec prudence, combinées avec d'autres conditions d'index (par exemple, réduire les données par ID ou plage horaire) et la clause limit.

Architecture distribuée

// Configure distributed nodes
final db = await ToStore.open(
  config: DataStoreConfig(
    distributedNodeConfig: const DistributedNodeConfig(
      enableDistributed: true,            // Enable distributed mode
      clusterId: 1,                       // Cluster ID
      centralServerUrl: 'https://127.0.0.1:8080',
      accessToken: 'b7628a4f9b4d269b98649129'
    )
  )
);

// Batch insert
await db.batchInsert('vector_data', [
  {'vector_name': 'face_2365', 'timestamp': DateTime.now()},
  {'vector_name': 'face_2366', 'timestamp': DateTime.now()},
  // ... efficient one-shot insertion of vector records
]);

// Stream and process large datasets
await for (final record in db.streamQuery('vector_data')
  .where('vector_name', '=', 'face_2366')
  .where('timestamp', '>=', DateTime.now().subtract(Duration(days: 30)))
  .stream) {
  // Process each result incrementally to avoid loading everything at once
  print(record);
}

Exemples de clés primaires

ToStore fournit plusieurs algorithmes de clé primaire distribués pour différents scénarios commerciaux :

  • Clé primaire séquentielle (PrimaryKeyType.sequential) : 238978991
  • Clé primaire basée sur l'horodatage (PrimaryKeyType.timestampBased) : 1306866018836946
  • Clé primaire avec préfixe de date (PrimaryKeyType.datePrefixed) : 20250530182215887631
  • Clé primaire de code court (PrimaryKeyType.shortCode) : 9eXrF0qeXZ
// Sequential primary key configuration example
await db.createTables([
  const TableSchema(
    name: 'users',
    primaryKeyConfig: PrimaryKeyConfig(
      type: PrimaryKeyType.sequential,
      sequentialConfig: SequentialIdConfig(
        initialValue: 10000,      // Starting value
        increment: 50,            // Step size
        useRandomIncrement: true, // Random step size to hide business volume
      ),
    ),
    fields: [/* field definitions */]
  ),
]);

Expressions atomiques

Le système d'expression fournit des mises à jour de champs atomiques de type sécurisé. Tous les calculs sont exécutés de manière atomique au niveau de la couche de base de données, évitant ainsi les conflits simultanés :

// Simple increment: balance = balance + 100
await db.update('accounts', {
  'balance': Expr.field('balance') + Expr.value(100),
}).where('id', '=', accountId);

// Complex calculation: total = price * quantity + tax
await db.update('orders', {
  'total': Expr.field('price') * Expr.field('quantity') + Expr.field('tax'),
}).where('id', '=', orderId);

// Multi-layer parentheses: finalPrice = ((price * quantity) + tax) * (1 - discount)
await db.update('orders', {
  'finalPrice': ((Expr.field('price') * Expr.field('quantity')) + Expr.field('tax')) *
                 (Expr.value(1) - Expr.field('discount')),
}).where('id', '=', orderId);

// Use functions: price = min(price, maxPrice)
await db.update('products', {
  'price': Expr.min(Expr.field('price'), Expr.field('maxPrice')),
}).where('id', '=', productId);

// Timestamp: updatedAt = now()
await db.update('users', {
  'updatedAt': Expr.now(),
}).where('id', '=', userId);

Expressions conditionnelles (par exemple, différencier mise à jour et insertion dans un upsert) : utilisez Expr.isUpdate() / Expr.isInsert() avec Expr.ifElse ou Expr.when afin que l'expression soit évaluée uniquement lors de la mise à jour ou uniquement lors de l'insertion.

// Upsert: increment on update, set to 1 on insert
// The insert branch can use a plain literal; expressions are only evaluated on the update path
await db.upsert('counters', {
  'key': 'visits',
  'count': Expr.ifElse(
    Expr.isUpdate(),
    Expr.field('count') + Expr.value(1),
    1,
  ),
});

// Use Expr.when (single branch, otherwise null)
await db.upsert('orders', {
  'id': orderId,
  'updatedAt': Expr.when(Expr.isUpdate(), Expr.now(), otherwise: Expr.now()),
});

Transactions

Les transactions garantissent l'atomicité entre plusieurs opérations : soit tout réussit, soit tout est annulé, préservant ainsi la cohérence des données.

Caractéristiques des transactions

  • plusieurs opérations, soit toutes réussissent, soit toutes reviennent en arrière
  • le travail inachevé est automatiquement récupéré après un crash
  • les opérations réussies sont conservées en toute sécurité
// Basic transaction - atomically commit multiple operations
final txResult = await db.transaction(() async {
  // Insert a user
  await db.insert('users', {
    'username': 'john',
    'email': '[email protected]',
    'fans': 100,
  });

  // Atomic update using an expression
  await db.update('users', {
    'fans': Expr.field('fans') + Expr.value(50),
  }).where('username', '=', 'john');

  // If any operation fails, all changes are rolled back automatically
});

if (!txResult.hasErrors) {
  print('Transaction validée avec succès');
} else {
  print('Transaction annulée en raison de :');
  for (final status in txResult.statuses) {
    if (status.type != ResultType.success) {
      print(' - [$status.codeKey}] $status.message}');
    }
  }
}

// Automatic rollback on error
final txResult2 = await db.transaction(() async {
  await db.insert('users', {
    'username': 'jane',
    'email': '[email protected]',
  });
  throw Exception('Business logic error'); // Trigger rollback
}, rollbackOnError: true);

Administration et maintenance

Les API suivantes couvrent l'administration, les diagnostics et la maintenance des bases de données pour le développement de type plugin, les panneaux d'administration et les scénarios opérationnels :

  • Gestion des tables
    • createTable(schema) : créer une seule table manuellement ; utile pour le chargement de modules ou la création de tables d'exécution à la demande
    • getTableSchema(tableName) : récupérer les informations du schéma défini ; utile pour la validation automatisée ou la génération de modèles d'interface utilisateur
    • getTableNames({isGlobal}) : liste les noms de tables de l'inventaire de schéma global (tables utilisateur). Optionnel isGlobal : true globales seulement, false non globales seulement, omis = les deux. Les schémas non globaux sont partagés entre espaces ; seules les données sont isolées.
    • getTableInfo(tableName) : statistiques d'exécution (totalRecordCount, totalTableDataSizeBytes, totalIndexDataSizeBytes, indexCount, création, global ou non)
    • clear(tableName) : effacez toutes les données de la table tout en conservant en toute sécurité le schéma, les index et les contraintes de clés internes/externes
    • dropTable(tableName) : détruire complètement une table et son schéma ; non réversible
  • Gestion de l'espace
    • currentSpaceName : obtenez l'espace actif actuel en temps réel
    • listSpaces() : liste tous les espaces alloués dans l'instance de base de données actuelle
    • getSpaceInfo(useCache: true) : agrégats locaux de l'espace (totalRecordCount, taille données table/index). Utilisez useCache: false pour réconcilier depuis les métas.
    • deleteSpace(spaceName) : supprime un espace spécifique et toutes ses données, sauf default et l'espace actif actuel
  • Découverte d'instance
    • config : inspectez l'instantané final effectif DataStoreConfig pour l'instance
    • instancePath : localiser précisément le répertoire de stockage physique
    • getVersion() / setVersion(version) : contrôle de version défini par l'entreprise pour les décisions de migration au niveau de l'application (pas la version du moteur)
  • Entretien
    • flush(mode: FlushMode.full) : force l'écriture des données en attente vers le stockage. Modes : recovery (le plus rapide ; journal de récupération uniquement vers les tampons OS ; survit à un crash de l'app, pas à une coupure de courant), recoveryDurable (journal de récupération vers un stockage stable ; vise à survivre aux coupures de courant), full (par défaut ; journal de récupération + données de table et d'index vers un stockage stable).
    • deleteDatabase() : supprime tous les fichiers physiques et métadonnées de l'instance actuelle ; utiliser avec précaution
  • Diagnostics
    • db.status.memory() : inspectez les taux de réussite du cache, l'utilisation des pages d'index et l'allocation globale du tas
    • db.status.space() / db.status.table(tableName) : inspectez les statistiques en direct et les informations de santé pour les espaces et les tables
    • db.status.config() : inspecte l'instantané de configuration d'exécution actuel
    • db.status.migration(taskId) : suivez la progression de la migration asynchrone en temps réel

final spaces = await db.listSpaces();
final tableNames = await db.getTableNames();
final spaceInfo = await db.getSpaceInfo(useCache: false);
final tableSchema = await db.getTableSchema('users');
final tableInfo = await db.getTableInfo('users');

print('spaces: $spaces');
print('tables: $tableNames');
print(spaceInfo.toJson());
print(tableSchema?.toJson());
print(tableInfo?.toJson());

await db.flush();

final memoryInfo = await db.status.memory();
final configInfo = await db.status.config();
print(memoryInfo.toJson());
print(configInfo.toJson());

Sauvegarde et restauration

Particulièrement utile pour l'importation/exportation locale par un seul utilisateur, la migration de données hors ligne volumineuses et la restauration du système après une panne :

  • Sauvegarde (backup)
    • compress : s'il faut activer la compression ; recommandé et activé par défaut
    • scope : contrôle la plage de sauvegarde
      • BackupScope.database : sauvegarde l'instance entière de la base de données, y compris tous les espaces et tables globales
      • BackupScope.currentSpace : sauvegarde uniquement l'espace actif actuel, à l'exclusion des tables globales
      • BackupScope.currentSpaceWithGlobal : sauvegarde l'espace actuel ainsi que ses tables globales associées, idéal pour la migration à locataire unique ou à utilisateur unique
  • Restaurer (restore)
    • backupPath : chemin physique vers le package de sauvegarde
    • cleanupBeforeRestore : s'il faut effacer silencieusement les données actuelles associées avant la restauration ; true est recommandé pour éviter les états logiques mixtes
    • deleteAfterRestore : supprime automatiquement le fichier source de sauvegarde après une restauration réussie
// Example: export the full data package for the current user
final backupPath = await db.backup(
  compress: true,
  scope: BackupScope.currentSpaceWithGlobal,
);

// Example: restore from a backup package and clean up the source file automatically
final restored = await db.restore(
  backupPath,
  cleanupBeforeRestore: true,
  deleteAfterRestore: true,
);

Codes d'état et gestion des erreurs

Il existe deux canaux pour le retour d'informations sur les erreurs et les exceptions dans ToStore :

[!NOTE] Base de diagnostic unifiée : Qu'ils soient renvoyés via le modèle de résultat de réponse (statuses dans DbResult/QueryResult) ou levés via des exceptions fatales (statuses dans DbException), tous les états de diagnostic reposent uniformément sur le système structuré ResultStatus et partagent les mêmes codes d'état, ce qui garantit la cohérence.

  1. Modèle de résultat de réponse (Result-based Response) Pour les opérations quotidiennes telles que l'insertion, la mise à jour, la suppression, la requête, les transactions et les modifications de schéma de table en cours d'exécution. Ces opérations ne lèveront pas d'exceptions lors de violations de contraintes, de défaillances de validation ou d'arguments non valides. Au lieu de cela, ToStore enveloppe les résultats à l'aide de DbResult ou QueryResult, en enregistrant toutes les informations de diagnostic dans la liste d'états. Cela garantit que les erreurs de logique métier ordinaires n'interrompent pas la base de données.
  • hasErrors : Indique s'il y a des erreurs dans l'opération en cours. Dans les opérations par lots ou les transactions, si au moins une erreur est présente, cette propriété est true.
  • statuses : Une liste détaillée de tous les diagnostics ResultStatus pour l'opération. Il prend en charge une correspondance d'ordre 1:1, ce qui est très utile pour les opérations par lots.
  • firstPrimaryKey : Lit directement la clé primaire physiquement générée lors d'une seule operação d'insertion/écriture sans avoir à analyser statuses manuellement.
  • ResultType : Énumération de la catégorie d'état, pratique pour la gestion des branches et les vérifications (par exemple, isBusinessError, isDeveloperError).
  1. Levée d'exceptions (Exception-based Throwing) Pour les erreurs fatales causées par un oubli du développeur ou des défauts de conception (par exemple, échec de la vérification du schéma lors de ToStore.open, incompatibilité de version du moteur, corruption fatale de la migration des données, etc.). Dans ces cas, ToStore lève DbException pour arrêter l'exécution, invitant le développeur à la corriger.

[!WARNING] Directives de développement : Les erreurs commerciales ordinaires ne doivent pas lever d'exceptions ; elles doivent être renvoyées dans le modèle de résultat de réponse pour éviter de perturber l'exécution de l'application.


Exemples d'erreurs et d'exceptions

1. Gestion des réponses pour une écriture unique

final result = await db.insert('users', {
  'username': 'john',
  'email': '[email protected]',
});

if (result.hasErrors) {
  // Obtenir le premier type d'erreur et sa description
  print('Operation failed: [\${result.firstType.codeKey}] \${result.message}');
} else {
  print('Écriture réussie, la clé primaire est : \${result.firstPrimaryKey}');
}

2. Diagnostic détaillé pour les écritures par lots

final batchResult = await db.batchInsert('users', [
  {'username': 'alice', 'email': '[email protected]'},
  {'username': 'bob', 'email': 'invalid-email-format'}, // Validation fails
]);

if (batchResult.hasErrors) {
  print('L'opération par lots a partiellement échoué : réussis \${batchResult.successCount}, échoués \${batchResult.failedCount}');
  
  for (final status in batchResult.statuses) {
    final int idx = status.index;
    
    if (status is ConstraintStatus) {
      print('Index [\$idx] Violation de contrainte! Table! Table: \${status.tableName}, champs: \${status.fields}');
    } else if (status is InvalidArgumentStatus) {
      print('Index [\$idx] Erreur d'argument! Paramètre! Parameter: \${status.parameterName}, valeur passée: \${status.passedValue}');
    } else if (status.type != ResultType.success) {
      print('Index [\$idx] Une erreur s'est produite: [\${status.codeKey}] \${status.message}');
    }
  }
}

3. Erreur fatale et capture de l'exception d'initialisation (DbException)

try {
  // Initialize database with schemas that might have validation issues
  final db = await ToStore.open(schemas: appSchemas);
} on DbException catch (e) {
  print('❌ Exception fatale de la base de données ! Message d'erreur : \n\${e.message}');
  
  // Iterate through the detailed status list in the exception
  for (final status in e.statuses) {
    if (status is SchemaValidationStatus) {
      print('Échec de la validation du schéma ! Table! Table: \${status.tableName}, champ: \${status.field}, configuration invalide: \${status.wrongValue}');
    } else {
      print('Informations de diagnostic: [\${status.codeKey}] \${status.message}');
    }
  }
}

Pour la liste complète des types d'erreurs, des codes d'état feuilles, des formats de sérialisation JSON et des mappages de champs, veuillez vous référer à la spécification complète : Spécification de diagnostic automatique et de résolution de statut ToStore ResultStatus.

Rappel du journal et diagnostics de la base de données

ToStore peut acheminer les journaux du cycle de vie de la base de données vers la couche métier via ToStore.setLogConfig(...).

  • Le rappel onLog reçoit tous les enregistrements de journal LogRecord qui passent les filtres enableLog et logLevel actuels.
    • LogLevel.error: Une erreur locale s'est produite, n'affecte pas le fonctionnement normal.
    • LogLevel.critical: Erreur globale de niveau catastrophe (telle que disque plein, mémoire insuffisante, échec de migration critique, etc.) nécessitant une intervention manuelle. Il est recommandé de déclencher des notifications d'alarme à ce niveau.
  • Appelez ToStore.setLogConfig(...) avant l'initialisation afin que les journaux générés lors de l'initialisation et de la migration automatique soient également capturés.
  // Configurer les paramètres de journalisation ou le rappel
  ToStore.setLogConfig(
    enableLog: true,
    logLevel: debugMode ? LogLevel.debug : LogLevel.warn,
    logLabel: 'my_app_db', // Titre gris clair en haut du journal pour distinguer les applications ou les instances de base de données,
    onLog: (log) {
      // En production, warn/error/critical peuvent être signalés au backend ou à la plateforme de journalisation
      // log.level correspond au niveau de journalisation (LogLevel.debug, info, warn, error, critical)
      // log.message correspond au texte du journal traité
      // log.status correspond à l'état de diagnostic ResultStatus sous-jacent (contient code et codeKey)
      if (!debugMode && (log.level == LogLevel.warn || log.level == LogLevel.error || log.level == LogLevel.critical)) {
        developer.log(log.message, name: 'my_app_db', time: log.timestamp);
      }
    },
  );

  final db = await ToStore.open();

Configuration de la sécurité

[!WARNING] Gestion des clés

Clé Rôle Comment changer Réécriture complète des données ?
encodingKey Clé de chiffrement des données Définir une nouvelle valeur et relancer open Oui (lent)
encryptionKey Clé de sécurité ; protège encodingKey Appeler db.rotateEncryptionKey à l'exécution Non (rapide)

Ne codez jamais en dur les clés sensibles. Pour les lier à l’appareil, stockez encryptionKey dans le Keychain / Keystore / enclave sécurisée du système, puis passez-la au moteur.

final db = await ToStore.open(
  config: DataStoreConfig(
    encryptionConfig: EncryptionConfig(
      // Supported: none, xorObfuscation, chacha20Poly1305, aes256Gcm
      encryptionType: EncryptionType.chacha20Poly1305,

      // Data encryption key: encrypts table/index/log data; changing it triggers a background rewrite
      encodingKey: 'Your-Encoding-Key...',

      // Security key: protects encodingKey; rotate online via db.rotateEncryptionKey
      encryptionKey: 'Your-Secure-Encryption-Key...',

      // standard: critical table data, B-tree indexes, and log payloads
      // full: encrypts the entire engine files
      encryptionScope: EncryptionScope.standard,
    ),
    // Enable crash recovery logging (Write-Ahead Logging), enabled by default
    enableJournal: true,
    // Whether transactions force data to disk on commit; set false to reduce sync overhead
    persistRecoveryOnCommit: true,
  ),
);

Changer encodingKey : définissez la nouvelle valeur dans EncryptionConfig et relancez open. Le moteur détecte le changement et migre les données automatiquement en arrière-plan, sans intervention applicative.

Rotation de encryptionKey (rotation périodique sécurité/conformité) : pas de réécriture des données ; exécutable en ligne.

// If encryptionKey was never set explicitly, oldKey can be omitted
final result = await db.rotateEncryptionKey(newKey: 'new-secure-key');
// Or: await db.rotateEncryptionKey(oldKey: 'old-key', newKey: 'new-key');
if (result.hasErrors) {
  // Gérer l'échec (oldKey incorrect, migration encodingKey en cours, etc.)
  return;
}
// Succès : config en mémoire mise à jour ; passez le dernier encryptionKey au prochain ToStore.open

Chiffrement au niveau de la valeur (ToCrypto)

Le chiffrement complet de la base de données sécurise toutes les données des tables et des index, mais peut affecter les performances globales. Si vous n'avez besoin de protéger que quelques valeurs sensibles, utilisez plutôt ToCrypto. Il est découplé de la base de données, ne nécessite aucune instance db et permet à votre application d'encoder/décoder les valeurs avant l'écriture ou après la lecture. La sortie est Base64, qui s'intègre naturellement dans les colonnes JSON ou TEXT.

  • key (obligatoire) : String ou Uint8List. S'il ne s'agit pas de 32 octets, SHA-256 est utilisé pour dériver une clé de 32 octets.
  • type (facultatif) : type de cryptage de ToCryptoType, tel que ToCryptoType.chacha20Poly1305 ou ToCryptoType.aes256Gcm. La valeur par défaut est ToCryptoType.chacha20Poly1305.
  • aad (facultatif) : données supplémentaires authentifiées de type Uint8List. S’ils sont fournis lors du codage, les mêmes octets doivent également être fournis lors du décodage.
const key = 'my-secret-key';
// Encode: plaintext -> Base64 ciphertext (can be stored in DB or JSON)
final cipher = ToCrypto.encode('sensitive data', key: key);
// Decode when reading
final plain = ToCrypto.decode(cipher, key: key);

// Optional: bind contextual data with aad (must match during decode)
final aad = Uint8List.fromList(utf8.encode('users:id_number'));
final cipher2 = ToCrypto.encode('secret', key: key, aad: aad);
final plain2 = ToCrypto.decode(cipher2, key: key, aad: aad);

Configuration avancée expliquée (DataStoreConfig)

[!TIP] Intelligence zéro configuration ToStore détecte automatiquement la plate-forme, les caractéristiques de performances, la mémoire disponible et le comportement des E/S pour optimiser des paramètres tels que la concurrence, la taille des partitions et le budget du cache. Dans 99 % des scénarios commerciaux courants, vous n'avez pas besoin d'affiner DataStoreConfig manuellement. Les valeurs par défaut offrent déjà d'excellentes performances pour la plateforme actuelle.

Paramètre Par défaut Objectif et recommandation
yieldDurationMs 8 ms Recommandation principale. La tranche de temps utilisée lorsque les tâches longues aboutissent. 8ms s'aligne bien avec le rendu 120 ips/60 ips et permet de maintenir l'interface utilisateur fluide lors de requêtes ou de migrations volumineuses.
maxQueryOffset 10 000 Protection des requêtes. Lorsque offset dépasse ce seuil, une erreur est générée. Cela empêche les E/S pathologiques d’une pagination à décalage profond.
defaultQueryLimit 1000 Garde-corps de ressources. Appliqué lorsqu'une requête ne spécifie pas limit, empêchant le chargement accidentel d'ensembles de résultats massifs et les problèmes potentiels de MOO.
cacheMemoryBudgetMB (auto) Gestion fine de la mémoire. Budget total de mémoire cache. Le moteur l'utilise pour piloter automatiquement la récupération LRU.
enableJournal vrai Auto-réparation en cas de crash. Lorsqu'il est activé, le moteur peut récupérer automatiquement après un crash ou une panne de courant.
defaultRecoveryDurability standard Garantie de récupération à la réponse. Définit le niveau d'auto-réparation avant que les opérations d'écriture ne renvoient de résultat :
• standard (Par défaut) : Résistant aux crashs avant réponse. Protégé contre les crashs d'application, exceptions non interceptées et arrêts OOM.
• durable : Résistant aux coupures de courant avant réponse. Forcé sur le stockage physique avant retour ; auto-réparation complète garantie même en cas de coupure soudaine.
• async : Débit maximal. Répond immédiatement et enregistre en arrière-plan ; après la réponse, pour de petits volumes, fenêtre de perte de quelques millisecondes seulement.
persistRecoveryOnCommit vrai Forte garantie de durabilité. Lorsqu'elles sont vraies, les transactions validées sont synchronisées avec le stockage physique. Lorsqu'il est faux, le vidage est effectué de manière asynchrone en arrière-plan pour une meilleure vitesse, avec un faible risque de perte d'une infime quantité de données en cas de crash extrême.
ttlCleanupIntervalMs 300 000 Interrogation TTL globale. L'intervalle d'arrière-plan pour l'analyse des données expirées lorsque le moteur n'est pas inactif. Des valeurs inférieures suppriment les données expirées plus tôt, mais coûtent plus cher.
kvCapacityConfig null Capacité KV d'espace. Limite FIFO/LRU pour les clés d'espace ; ne pas définir sourceField. Voir Éviction par capacité.
globalKvCapacityConfig null Capacité KV globale. Même forme que kvCapacityConfig.
maxConcurrency (auto) Contrôle de la concurrence de calcul. Définit le nombre maximal de travailleurs parallèles pour les tâches intensives telles que le calcul vectoriel et le chiffrement/déchiffrement. Il est généralement préférable de le garder automatique.
final db = await ToStore.open(
  config: DataStoreConfig(
    yieldDurationMs: 8, // Excellent for frontend UI smoothness; for servers, 50ms is often better
    defaultQueryLimit: 50, // Force a maximum result-set size
    enableJournal: true, // Ensure crash self-healing
    defaultRecoveryDurability: RecoveryDurability.standard, // Résistant aux crashs avant réponse
  ),
);

Performances et expérience

Repères

Points forts du suite 100K et validation edge à l'échelle du milliard (3 tours, standard durability, 2026-10-08) :

Metric Result
Cold start ~35 ms (stable vs data scale)
PK Read (Hot Cache) 4.5M ops/s
Batch Insert 588K ops/s
Pagination (Hot Cache) 579K ops/s
ANN @ depth 1 (~91%) 36K ops/s

Graphiques complets et toutes les opérations : Benchmarks.

ToStore Basic Performance Demo

  • Démo des performances de base (basic-demo.mp4) : l'aperçu GIF peut ne pas tout afficher. Veuillez ouvrir la vidéo pour la démonstration complète. Même sur les appareils mobiles ordinaires, le démarrage, la pagination et la récupération restent stables et fluides même lorsque l'ensemble de données dépasse 100 millions d'enregistrements.

ToStore Disaster Recovery Stress Test

  • Test de stress de reprise après sinistre (disaster-recovery.mp4) : lors des écritures à haute fréquence, le processus est intentionnellement interrompu encore et encore pour simuler des crashs et des pannes de courant. ToStore est capable de récupérer rapidement.

Conseils d'expérience

  • 📱 Exemple de projet : le répertoire example comprend une application Flutter complète
  • 🚀 Builds de production : packager et tester en mode release ; les performances de la version sont bien au-delà du mode débogage
  • ✅ Tests standard : les capacités de base sont couvertes par des tests standardisés

Si ToStore vous aide, donnez-nous un ⭐️, c'est l'une des meilleures façons de soutenir le projet. Merci beaucoup !

🤝 Contribuer

ToStore est un moteur de données moderne en évolution continue, et nous accueillons chaleureusement les contributions de la communauté. Qu'il s'agisse de corriger des bugs, d'améliorer la documentation, de perfectionner l'architecture ou de proposer de nouvelles idées, vous pouvez participer via PR :