tocreator/tostore
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.
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.
IAdoc/translations/fr/README.md
OriginalEnglish | 简体中文 | 日本語 | 한국어 | Español | Português (Brasil) | Русский | Deutsch | Français | Italiano | Türkçe
Navigation rapide
- Pourquoi ToStore | Fonctionnalités clés | Guide d'installation | Mode KV | Mode Tableau | Mode mémoire
- Définition du schéma | Architecture distribuée | Clés étrangères en cascade | Mobile/Ordinateur de bureau | Serveur/Agent | Algorithmes de clé primaire
- Requêtes avancées (JOIN) | Agrégation & Statistiques | Logique complexe (QueryCondition) | Requête réactive (regarder) | Requête en streaming
- KV avancé | Opérations groupées | Garantie de récupération | Récupération hybride (dense / sparse / texte) | TTL au niveau de la table | Éviction par capacité | Pagination efficace | Sonde mémoire et récupération synchrone (peek) | Cache de requêtes | Expressions atomiques | Transacciones
- Administration | Configuration de sécurité | Gestion des erreurs | Performances et diagnostics | Contribuer | Assistants IA
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 ?
- 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.
- 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.
- 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 :
- Mobile/Bureau : pour les scénarios de démarrage fréquents, il est recommandé de transmettre
schemaslors de l'initialisation. - Serveur/Agent : pour les scénarios de longue durée, il est recommandé de créer des tables de manière dynamique via
createTables.
// 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
DataTypecourants :Tapez Type de fléchette correspondant Descriptif integerintEntier standard, adapté aux identifiants, compteurs et données similaires bigIntBigInt/StringGrands entiers ; recommandé lorsque les nombres dépassent 18 chiffres pour éviter toute perte de précision doubledoubleNombre à virgule flottante, adapté aux prix, coordonnées et données similaires textStringChaîne de texte avec contraintes de longueur facultatives blobUint8ListDonnées binaires brutes booleanboolValeur booléenne datetimeDateTime/StringDate/heure ; stocké en interne sous ISO8601 arrayListType de liste ou de tableau jsonMap<String, dynamic>Objet JSON, adapté aux données structurées dynamiques vectorVectorData/List<num>Vecteurs denses pour la récupération sémantique des plus proches voisins (embeddings) sparseSparseVectorDataVecteurs neuronaux sparse pour la récupération sparse PrimaryKeyTypestratégies d'auto-génération :Stratégie Descriptif Caractéristiques nonePas de génération automatique Vous devez fournir manuellement la clé primaire lors de l'insertion sequentialIncrément séquentiel Bon pour les identifiants conviviaux, mais moins adapté aux performances distribuées timestampBasedBasé sur l'horodatage Recommandé pour les environnements distribués datePrefixedPréfixé par la date Utile lorsque la lisibilité de la date est importante pour l'entreprise shortCodeClé 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 nulleminLength/maxLength: contraintes de longueur de texteminValue/maxValue: contraintes de plage entière ou flottantedefaultValue/defaultValueType: valeurs par défaut statiques et valeurs par défaut dynamiquesunique: contrainte uniquecreateIndex: créez des index pour le filtrage, le tri ou les relations haute fréquencefieldId/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 (
schemasdéclaratifs) : Détection automatique àToStore.open(). La clé primaire cible doit êtrePrimaryKeyType.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 lefieldIdsource dansfromFieldId. - Serveur (runtime) : Appelez
updateSchema(...).promoteFieldToPrimaryKey(sourceFieldName: ..., targetPrimaryKeyName: ...).targetPrimaryKeyNameest optionnel ; omettez-le pour conserver le nom du champ source.
Choisir une méthode d'intégration
- Mobile/Ordinateur : Idéal pour passer
appSchemasdirectement dansToStore.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 baserecovering— Vérifications de sécurité et récupération après plantageoptimizing— Réglage interne du moteur et optimisation structurelleready— 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 (avecvaluedé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/orderByKeyDescTrier par key (clé primaire) orderByUpdatedAtAsc/orderByUpdatedAtDescTrier par updated_atlimit(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, utiliserhasMore/hasPrev+next()/prev();nextCursorToken/prevCursorTokenuniquement 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:truepour 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,
batchUpsertné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 :
batchUpdatemodifie 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: truepour 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 écritindexType: identifiant opaque de l'algorithme dense ; actuellementnghdistanceMetric: métrique de similarité côté index (construction et recherche) ;cosineest courant pour les embeddings sémantiques,l2pour la distance euclidienne,innerProductpour 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 moteurTextQuery.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) ouand(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êtesearchDepth:>= 1, défaut50; des valeurs plus élevées augmentent souvent le rappel et la latence ; plus proche voisin approximatif — pas un recall@K garantidistanceThreshold: plafond de distance
- Partagés
weight: poids de fusion multi-voies ; défaut1.0minScore: plancher de pertinencelimit: nombre de résultats (topK).fusionMethod(...): multi-voies par défautweightedScore; commutable versrrf
Notes sur le résultat et le scoring (QueryResult / VectorSearchResult) :
- Les enregistrements métier sont dans
data; scores et infos de canal dansretrieval.entries, alignés 1:1 avecdata. 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 atteint1.0. UtilisezminScorepour garder les hits forts et écarter les faibles. La fusion multi-voies par défautweightedScoreconserve 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. LisezrawScore/distancepour la métrique sous-jacente.entry.meta['distance']: distance ANN sur les canaux vectoriels (plus bas= plus proche).retrieval.fusionMethod:nullpour un rappel mono-canal ; multi-voies par défautweightedScore(commutable via.fusionMethod(RetrievalFusionMethod.rrf)).- Le
db.vectorSearch(...)de premier niveau renvoieList<VectorSearchResult>(primaryKey/score/rawScore/distance) pour un ANN dédié. LeminScoreoptionnel utilise le même plancher de pertinence quematchVector(peut renvoyer moins quetopK).
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.noneexige aussisourceField(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 courantglobalKvCapacityConfig: limite le KV global- Même forme que le
CapacityConfigde table, sanssourceField
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
Aggpeuvent être placés directement dans la listeselect
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 courantejoinReferencingTable(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
- 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');- Intégré dans
select(pour plusieurs métriques ou regroupements) : transmettez les objetsAggdans la listeselect.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'unMap.distinct([fields]): déduplique les résultats. Sifieldsest 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éANDorCondition(QueryCondition sub): ouvre un groupe imbriquéORor(): change le connecteur suivant enOR(la valeur par défaut estAND)
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
StreamBuilderpour 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 :
- Analyses complètes coûteuses sur des données non indexées qui changent rarement
- 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 expirationnoQueryCache(): désactiver explicitement le cache pour cette requêteclearQueryCache(): 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
limitcomme taille de page : Il est fortement recommandé de toujours spécifierlimitdans 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'
offsetdevient 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()ouprev()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
nextCursorTokenetprevCursorToken. - La requête suivante transmet le jeton via
.cursor(token)pour se positionner directement (seek). - Remarque :
cursoretoffsetsont 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 :
peekest 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, utilisezawait 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ériepeekest 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 :
Optimisé par Index - [Recommandé] :
- Méthodes sémantiques :
whereEqual,whereGreaterThan,whereLessThan,whereIn,whereBetween,whereNull,whereTrue,whereFalseetwhereStartsWith(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.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 demandegetTableSchema(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 utilisateurgetTableNames({isGlobal}): liste les noms de tables de l'inventaire de schéma global (tables utilisateur). OptionnelisGlobal:trueglobales seulement,falsenon 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/externesdropTable(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éellistSpaces(): liste tous les espaces alloués dans l'instance de base de données actuellegetSpaceInfo(useCache: true): agrégats locaux de l'espace (totalRecordCount, taille données table/index). UtilisezuseCache: falsepour réconcilier depuis les métas.deleteSpace(spaceName): supprime un espace spécifique et toutes ses données, saufdefaultet l'espace actif actuel
- Découverte d'instance
config: inspectez l'instantané final effectifDataStoreConfigpour l'instanceinstancePath: localiser précisément le répertoire de stockage physiquegetVersion()/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 tasdb.status.space()/db.status.table(tableName): inspectez les statistiques en direct et les informations de santé pour les espaces et les tablesdb.status.config(): inspecte l'instantané de configuration d'exécution actueldb.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éfautscope: contrôle la plage de sauvegardeBackupScope.database: sauvegarde l'instance entière de la base de données, y compris tous les espaces et tables globalesBackupScope.currentSpace: sauvegarde uniquement l'espace actif actuel, à l'exclusion des tables globalesBackupScope.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 sauvegardecleanupBeforeRestore: s'il faut effacer silencieusement les données actuelles associées avant la restauration ;trueest recommandé pour éviter les états logiques mixtesdeleteAfterRestore: 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 (
statusesdansDbResult/QueryResult) ou levés via des exceptions fatales (statusesdansDbException), tous les états de diagnostic reposent uniformément sur le système structuréResultStatuset partagent les mêmes codes d'état, ce qui garantit la cohérence.
- 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
DbResultouQueryResult, 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é esttrue.statuses: Une liste détaillée de tous les diagnosticsResultStatuspour 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 à analyserstatusesmanuellement.ResultType: Énumération de la catégorie d'état, pratique pour la gestion des branches et les vérifications (par exemple,isBusinessError,isDeveloperError).
- 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èveDbExceptionpour 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
onLogreçoit tous les enregistrements de journalLogRecordqui passent les filtresenableLogetlogLevelactuels.- 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 ? encodingKeyClé de chiffrement des données Définir une nouvelle valeur et relancer openOui (lent) encryptionKeyClé de sécurité ; protège encodingKeyAppeler db.rotateEncryptionKeyà l'exécutionNon (rapide) Ne codez jamais en dur les clés sensibles. Pour les lier à l’appareil, stockez
encryptionKeydans 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) :StringouUint8List. 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 deToCryptoType, tel queToCryptoType.chacha20Poly1305ouToCryptoType.aes256Gcm. La valeur par défaut estToCryptoType.chacha20Poly1305.aad(facultatif) : données supplémentaires authentifiées de typeUint8List. 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
DataStoreConfigmanuellement. 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.
- 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.
- 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
examplecomprend 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 :
- 🔗 Soumettre un PR : Pull Requests
- 📖 Documentation : Wiki
- 📢 Rapport de problèmes : GitHub Issues
- 💬 Discussion technique : GitHub Discussions