Skip to content
Proyectos

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-15 13:36 UTC. Last push 2026-11-05.

Cómo se miden estas cifras

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

Crecimiento de estrellas medido

in 24h
0
in 7 days
0
in 15 days
Actualización retrasada
in 1 month
Actualización retrasada

Cambios netos en períodos que se solapan, no totales diarios. Los datos no disponibles se dejan en blanco. Las estrellas indican interés, no calidad.

Acerca de

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

IA

doc/translations/es/README.md

Original

ToStore

pub package Pub Points Pub Likes Monthly Downloads

License Platform Architecture

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

Navegación rápida

¿Por qué elegir ToStore?

ToStore es un motor de datos moderno diseñado para la era de la AGI y escenarios de inteligencia perimetral. Basado en una arquitectura de nodos de autorruta (Self-Routing), otorga a los nodos alta autonomía y escalabilidad horizontal elástica, desacoplando lógicamente el rendimiento de la escala de datos: en borde y nube, el mononodo está diseñado para tablas estructuradas a escala de billones, y la recuperación vectorial / de texto disperso también apunta a 10B+.

El modelado en tiempo de ejecución y las rutas de ejecución sin bloqueo mantienen la evolución de la arquitectura siempre en línea y totalmente transparente para las operaciones del negocio: los cambios declarativos de esquema, la rotación de claves de codificación de datos y la refactorización masiva de datos se realizan sin interrupciones. Soporta Agentes y O&M automatizado con creación de tablas en tiempo de ejecución, evolución dinámica de memoria y su evolución autónoma e iteración continua—sin interrumpir el servicio.

Unifica datos estructurados relacionales, vectores densos, vectores neuronales dispersos y texto no estructurado en un solo motor, con recuperación léxica de texto, recuperación de vectores densos, recuperación neuronal dispersa y fusión de recall multi-vía integradas. Incluye capacidades de nivel empresarial: transacciones ACID, consultas relacionales complejas (JOINs, claves externas en cascada), TTL a nivel de tabla, agregaciones, así como algoritmos de clave primaria distribuida, expresiones atómicas, cifrado, aislamiento multi-espacio y recuperación automática.

A medida que la computación continúa desplazándose hacia la inteligencia perimetral, los dispositivos ya no son simplemente "pantallas de contenido", sino nodos inteligentes responsables de la generación local, la percepción del entorno, la toma de decisiones en tiempo real y la coordinación de datos. ToStore otorga al borde capacidades distribuidas para conjuntos de datos masivos y generación compleja de IA local. La profunda colaboración inteligente entre nodos de borde y nube proporciona una base de datos confiable para interacción multimodal, memoria a largo plazo, RAG y bases de conocimiento locales, recuperación híbrida, modelado espacial, colaboración autónoma en el borde y escenarios similares.

Características clave

  • 🤖 Evolución en tiempo de ejecución y O&M inteligente

    • Cambios de esquema declarativos—refactorización automática, sin versionado manual
    • Rotación de claves, migración de esquema, refactorización masiva—todo en línea, transparente al negocio
    • Especificación de estado integrada para O&M automatizado y reconocimiento de Agentes
    • Soporta evolución autónoma e iteración continua sin interrumpir el servicio
  • 🧠 Arquitectura distribuida de autorruta

    • Arquitectura de nodos de autorruta que desacopla el direccionamiento físico de la escala de datos
    • Nodos altamente autónomos colaboran para construir una topología de datos flexible
    • Escalabilidad horizontal elástica; mononodo: tablas a escala de billones, vectores 10B+
  • 🌐 Motor de datos unificado multiplataforma

    • API unificada en entornos móviles, de escritorio, web y servidor
    • Cubre datos relacionales, vectores densos / neuronales dispersos y recuperación de texto
    • Canal de datos completo desde el almacenamiento local hasta la colaboración borde-nube
  • 🔍 Consultas estructuradas y recuperación híbrida

    • Predicados complejos, JOINs, agregaciones, TTL a nivel de tabla y evicción por capacidad (FIFO / LRU)
    • Texto léxico, vectores densos y recuperación neuronal dispersa en la misma cadena de consulta
    • Ranking por fusión de recall multi-vía, con puntuaciones y diagnósticos de canal en el resultado
  • ⚡ Ejecución paralela y planificación de recursos

    • Arranque en frío constante ~35 ms, independiente de la escala de datos
    • Planificación de carga con reconocimiento de recursos; descomposición paralela multinodo
    • División temporal que mantiene las animaciones de UI fluidas incluso bajo carga pesada
  • 🔐 Offline-First y privacidad

    • Mantenga los datos en el dispositivo y utilizables sin conexión, reduciendo la dependencia de la nube y la superficie de exposición
    • Aislamiento multi-espacio con compartición global opcional—listo para multiusuario / multitenant
    • Cifrado ChaCha20-Poly1305 y AES-256-GCM integrado
    • Verificado mediante múltiples escenarios complejos de recuperación ante desastres

Instalación

[!IMPORTANT] ¿Actualizando desde v2.x? Lea la Guía de actualización de v3.x para conocer los pasos críticos de migración y los cambios importantes.

Añade tostore a tu pubspec.yaml:

dependencies:
  tostore: any # Please use the latest version

For AI Coding Assistants

Al generar código cliente de ToStore con un asistente de IA, proporcione el corpus de un solo archivo llms-full.txt: por ejemplo @llms-full.txt en el IDE, suba/pegue el archivo, o indexe su raw URL en la documentación del asistente. Incluye firmas de API, restricciones y antipatrones para alinear al modelo con la superficie pública real. Índice: llms.txt.

Inicio rápido

[!TIP] ¿Cómo elegir un modo de almacenamiento?

  1. Modo clave-valor (KV): Lo mejor para acceso a la configuración, administración de estados dispersos o almacenamiento de datos JSON. Es la forma más rápida de empezar.
  2. Modo de tabla estructurada: Lo mejor para datos comerciales centrales que necesitan consultas complejas, validación de restricciones o gobernanza de datos a gran escala. Al introducir la lógica de integridad en el motor, puede reducir significativamente los costos de desarrollo y mantenimiento de la capa de aplicaciones.
  3. Modo de memoria: Ideal para cálculo temporal, pruebas unitarias, cachés en memoria acotadas (TTL y evicción por capacidad FIFO / LRU) o administración de estado global ultrarrápida. Con consultas globales y oyentes watch, puede remodelar la interacción de la aplicación sin mantener un montón de variables globales.

Almacenamiento de valores clave (KV)

Este modo es adecuado cuando no necesita tablas estructuradas predefinidas. Es simple, práctico y está respaldado por un motor de almacenamiento de alto rendimiento. Su arquitectura de indexación eficiente mantiene el rendimiento de las consultas altamente estable y extremadamente receptivo incluso en dispositivos móviles comunes a escalas de datos muy grandes. Los datos en diferentes espacios están naturalmente aislados, mientras que también se admite el intercambio global.

// 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] ¿Necesita más funciones de clave-valor? Para operaciones avanzadas como lectura segura de tipos (getInt, getBool), incremento atómico, búsqueda por prefijo, consultas encadenadas paginadas de registros (db.kv.query()) y exploración de espacio de claves, consulte Operaciones avanzadas de clave-valor (db.kv).

Ejemplo de actualización automática de la interfaz de usuario de Flutter

En Flutter, StreamBuilder más watchValue te brinda un flujo de actualización reactiva muy conciso:

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');
  },
)

Modo de tabla estructurada

CRUD en tablas estructuradas requiere que el esquema se cree con anticipación (consulte Definición de esquema). Enfoques de integración recomendados para diferentes escenarios:

// 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']),
    );
  },
);

Modo de memoria

Para escenarios como almacenamiento en caché, cálculo temporal o cargas de trabajo que no necesitan persistencia en el disco, puede inicializar una base de datos pura en memoria a través de ToStore.memory(). En este modo, todos los datos, incluidos esquemas, índices y pares clave-valor, residen completamente en la memoria para lograr el máximo rendimiento de lectura/escritura.

El modo memoria admite varias estrategias de evicción: TTL a nivel de tabla / TTL de KV por tiempo, y Evicción por capacidad (FIFO / LRU) por cantidad o tamaño—por separado o combinadas, para que los datos calientes caduquen a tiempo o queden acotados. Ideal para cachés de sesión, pools de resultados y rutas sensibles a la memoria.

💡 También funciona como Gestión del Estado Global

No necesita un montón de variables globales ni un marco de gestión estatal pesado. Al combinar el modo de memoria con watchValue o watch(), puede lograr una actualización de la interfaz de usuario completamente automática en todos los widgets y páginas. Mantiene las poderosas capacidades de recuperación de una base de datos y al mismo tiempo le brinda una experiencia reactiva mucho más allá de las variables ordinarias, lo que lo hace ideal para el estado de inicio de sesión, la configuración en vivo o los contadores de mensajes globales.

[!CAUTION] Nota: Los datos creados en el modo de memoria pura se pierden por completo después de cerrar o reiniciar la aplicación. No lo utilice para datos comerciales principales.

// 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'});

Definición del esquema

Defina una vez y deje que el motor maneje la gobernanza automatizada de extremo a extremo para que su aplicación ya no requiera un mantenimiento de validación pesado.

Los siguientes ejemplos de dispositivos móviles, del lado del servidor y de agentes reutilizan appSchemas definido aquí.

Descripción general del esquema de tabla

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];
  • Asignaciones DataType comunes:

    Tipo Tipo de dardo correspondiente Descripción
    integer int Entero estándar, adecuado para ID, contadores y datos similares
    bigInt BigInt / String Enteros grandes; recomendado cuando los números superan los 18 dígitos para evitar pérdida de precisión
    double double Número de coma flotante, adecuado para precios, coordenadas y datos similares
    text String Cadena de texto con restricciones de longitud opcionales
    blob Uint8List Datos binarios sin procesar
    boolean bool Valor booleano
    datetime DateTime / String Fecha/hora; almacenado internamente como ISO8601
    array List Tipo de lista o matriz
    json Map<String, dynamic> Objeto JSON, adecuado para datos estructurados dinámicos
    vector VectorData / List<num> Vectores densos para recuperación semántica de vecinos cercanos (embeddings)
    sparse SparseVectorData Vectores neuronales dispersos para recuperación dispersa
  • PrimaryKeyType estrategias de generación automática:

    Estrategia Descripción Características
    none Sin generación automática Debe proporcionar manualmente la clave principal durante la inserción
    sequential Incremento secuencial Bueno para identificaciones amigables para humanos, pero menos adecuado para rendimiento distribuido
    timestampBased Basado en marca de tiempo Recomendado para entornos distribuidos
    datePrefixed Con prefijo de fecha Útil cuando la legibilidad de la fecha es importante para el negocio
    shortCode Clave primaria de código corto Compacto y adecuado para pantalla externa

Todas las claves principales se almacenan como text (String) de forma predeterminada.

Restricciones y validación automática

Puede escribir reglas de validación comunes directamente en FieldSchema, evitando la lógica duplicada en el código de la aplicación:

  • nullable: false: restricción no nula
  • minLength / maxLength: restricciones de longitud del texto
  • minValue / maxValue: restricciones de rango de números enteros o de punto flotante
  • defaultValue / defaultValueType: valores predeterminados estáticos y valores predeterminados dinámicos
  • unique: restricción única
  • createIndex: crea índices para filtrado, clasificación o relaciones de alta frecuencia
  • fieldId / tableId: ayuda a la detección de cambio de nombre para campos y tablas durante la migración

Además, unique: true crea automáticamente un índice único de un solo campo. createIndex: true y las claves externas crean automáticamente índices normales de un solo campo. Utilice indexes cuando necesite índices compuestos, índices con nombre o índices de recuperación de texto / dispersos / vectoriales.

Evolución del esquema (Schema Evolution)

El motor detecta automáticamente los cambios estructurales (alta, baja o renombrado de tablas/campos, ajustes de atributos, cambios de índices, etc.) y completa la migración de datos: no hace falta versionar la base manualmente ni escribir scripts. Los schemas declarativos evolucionan en ToStore.open(); en tiempo de ejecución también puede usar updateSchema—transparente para el negocio, sin interrumpir lecturas ni escrituras.

Promover un campo único a clave primaria

Puede promover un campo existente único y no nulo a clave primaria (renombrado opcional; con datos existentes; transparente para el negocio). No combine con setPrimaryKeyConfig.

  • Móvil (schemas declarativos): Se detecta automáticamente en ToStore.open(). La clave primaria de destino debe ser PrimaryKeyType.none (los valores vienen del campo único de origen; no se admiten otros tipos auto-generados). Si el nombre coincide, basta con el nombre; para renombrar, indique el fieldId de origen en fromFieldId.
  • Servidor (tiempo de ejecución): Llame a updateSchema(...).promoteFieldToPrimaryKey(sourceFieldName: ..., targetPrimaryKeyName: ...). targetPrimaryKeyName es opcional; omítalo para conservar el nombre del campo de origen.

Elegir un método de integración

  • Móvil/Escritorio: mejor cuando se pasa appSchemas directamente a ToStore.open(...)
  • Servidor/Agente: mejor cuando se crean esquemas dinámicamente en tiempo de ejecución a través de createTables(appSchemas)

Integración para dispositivos móviles, de escritorio y otros escenarios de inicio frecuentes

📱 Ejemplo: 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');

Seguimiento del progreso de inicio

Los cambios de esquema normales son transparentes para la lógica de negocio y no bloquean el inicio. Solo en casos excepcionales raros específicos de aplicaciones móviles que se cierran forzosamente con frecuencia (por ejemplo, una breve validación de datos y recuperación de fallas tras una salida anormal) la inicialización puede tardar un tiempo perceptible — use onStartupProgress para mostrar una pantalla de bienvenida o un indicador de progreso:

final db = await ToStore.open(
  dbPath: dbRoot,
  schemas: appSchemas,
  onStartupProgress: (progress, stage) {
    // progress: 0.0 – 1.0  |  stage: opening → recovering → optimizing → ready
    print('Progreso de inicio ${(progress * 100).toStringAsFixed(0)}% [$stage]');
    // Actualizar pantalla de bienvenida / barra de progreso
  },
);
// Base de datos completamente lista

Etapas:

  • opening — Cargando configuración, preparando el motor base
  • recovering — Comprobaciones de seguridad y recuperación tras fallo
  • optimizing — Ajuste interno del motor y optimización estructural
  • ready — Inicialización completa, listo para usar

Mantener el estado de inicio de sesión y cierre de sesión (espacio activo)

El espacio múltiple es ideal para aislar datos de usuario: un espacio por usuario, activado al iniciar sesión. Con Active Space y las opciones de cierre, puedes mantener al usuario actual durante los reinicios de la aplicación y admitir un comportamiento de cierre de sesión limpio.

  • Mantener estado de inicio de sesión: después de cambiar a un usuario a su propio espacio, marque ese espacio como activo. El próximo lanzamiento puede ingresar a ese espacio directamente al abrir la instancia predeterminada, sin un paso de "predeterminado primero, luego cambiar".
  • Cerrar sesión: Cuando el usuario cierre sesión, cierre la base de datos con keepActiveSpace: false. El próximo lanzamiento no ingresará automáticamente al espacio del usuario anterior.
// 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);

Integración del lado del servidor/agente (escenarios de larga duración)

🖥️ Ejemplo: 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),
);

Uso avanzado

ToStore proporciona un amplio conjunto de capacidades avanzadas para escenarios empresariales complejos:

Operaciones avanzadas de clave-valor (db.kv)

Para escenarios de clave-valor más complejos, se recomienda utilizar el espacio de nombres db.kv. Proporciona un conjunto completo de API con aislamiento de espacio, uso compartido global, múltiples tipos de datos, así como consultas y filtros complejos encadenados (p. ej. db.kv.query().prefix(...).orderBy...().limit(...) para paginación, ordenación, filtrado por caducidad, etc.).

  • Acceso básico (Basic Access)

    // Establecer valor (admite String, int, bool, double, Map, List, etc.)
    await db.kv.set('key', 'value', ttl: Duration(hours: 1));
    
    // Obtener valor dinámico sin procesar
    dynamic val = await db.kv.get('key');
    
    // Eliminar una sola clave
    await db.kv.remove('key');
    
  • Obtenedores con seguridad de tipos (Type-Safe Getters) Recupere datos directamente en el formato de destino sin conversión manual:

    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');
    
  • Operaciones por lotes (Bulk Operations) Procese de manera eficiente múltiples pares clave-valor en una sola operación:

    // Establecer por lotes
    await db.kv.setMany({
      'theme': 'dark',
      'language': 'es_ES',
    });
    
    // Eliminar por lotes
    await db.kv.removeKeys(['temp_1', 'temp_2']);
    
  • Contadores atómicos (Atomic Increment) Incremente o decremente valores numéricos de forma segura en escenarios de alta concurrencia:

    // Incrementar en 1 (predeterminado)
    await db.kv.setIncrement('view_count');
    // Decrementar en 5 (pasar un valor negativo)
    await db.kv.setIncrement('stock_count', amount: -5);
    
  • Consultas encadenadas de registros (db.kv.query) API encadenada similar a db.query() para consultar registros clave-valor (con value decodificado) y con paginación. A diferencia de getKeys (solo nombres de clave), esto devuelve registros completos.

    // Primera página: filtrar por prefijo, ordenar por updated_at descendente, 20 por página
    final page = await db.kv.query()
        .prefix('setting_')
        .orderByUpdatedAtDesc() // o orderByKeyAsc / orderByKeyDesc / orderByUpdatedAtAsc
        .limit(20);
    
    for (final record in page.data) {
      // record contiene: key, value, updated_at, expires_at
      print('${record['key']} = ${record['value']}');
    }
    
    // Recomendado: paginar con next() / prev() (igual que consultas de tabla, lo más sencillo)
    if (page.hasMore) {
      final page2 = await page.next();
      print('Página siguiente: ${page2.data.length}');
      if (page2.hasPrev) {
        final back = await page2.prev();
        print('Página anterior: ${back.data.length}');
      }
    }
    
    // Paginación por offset (excluyente con cursor; para páginas profundas preferir next() arriba)
    final byOffset = await db.kv.query()
        .orderByKeyAsc()
        .limit(20)
        .offset(20);
    
    // Total de registros coincidentes (sin prefix: estadística de metadatos O(1))
    final total = await db.kv.query().prefix('setting_').count();
    
    // Obtener el primer registro coincidente
    final first = await db.kv.query().prefix('setting_').orderByKeyAsc().first();
    
    // Espacio KV global
    final globalPage = await db.kv.query(isGlobal: true).limit(50);
    
    // Por defecto se filtran los caducados; para incluir no depurados aún:
    final withExpired = await db.kv.query()
        .includeExpired()
        .limit(20);
    

    Métodos encadenados habituales:

    Método Descripción
    prefix(String) Filtrar por prefijo de key
    orderByKeyAsc / orderByKeyDesc Ordenar por key (clave primaria)
    orderByUpdatedAtAsc / orderByUpdatedAtDesc Ordenar por updated_at
    limit(n) Máximo de filas por página (se recomienda especificarlo siempre)
    offset(n) Paginación por desplazamiento (borra cursor)
    cursor(token) Solo casos especiales: Token de paginación entre procesos/red
    includeExpired([true]) Incluir registros caducados aún no depurados
    count() Contar coincidencias
    first() Devolver el primer registro (no altera el limit del builder)

    Resultado QueryResult: en el uso cotidiano, paginar con hasMore / hasPrev + next() / prev(); nextCursorToken / prevCursorToken solo para transmisión entre extremos, etc. (igual que consultas de tabla).

  • Descubrimiento y gestión (Discovery & Management)

    // Solo enumerar nombres de clave (sin value); opcional prefix / limit / offset
    final keys = await db.kv.getKeys(prefix: 'setting_');
    final pageKeys = await db.kv.getKeys(
      prefix: 'setting_',
      limit: 100,
      offset: 0,
    );
    
    // Contar el total de claves en el espacio actual
    final count = await db.kv.count();
    
    // Verificar si una clave existe y no ha expirado
    final exists = await db.kv.exists('config_cache');
    
    // Sonda de memoria (sincrona, solo en caché — ver [Sonda de memoria y recuperación sincrónica (peek)](#query-peek))
    final theme = db.kv.peekGet('theme') ?? await db.kv.get('theme');
    if (db.kv.peekExists('config_cache')) { /* ... */ }
    
    // Limpiar todos los datos KV en el espacio actual
    await db.kv.clear();
    
  • Gestión del ciclo de vida (TTL) Inspeccione o actualice la configuración de expiración para claves existentes:

    // Obtener la duración restante
    Duration? ttl = await db.kv.getTtl('token');
    
    // Actualizar TTL para una clave existente (expira en 7 días)
    await db.kv.setTtl('token', Duration(days: 7));
    
  • Monitoreo reactivo (Reactive Watch)

    // Monitorear una sola clave
    db.kv.watch<int>('unread_count').listen((count) => print(count));
    
    // Monitorear una instantánea de múltiples claves
    db.kv.watchValues(['theme', 'font_size']).listen((map) => print(map));
    
  • Uso compartido global (isGlobal) Todos los métodos anteriores admiten el parámetro opcional isGlobal: true para el espacio global (compartido entre todos los espacios), false (predeterminado) para el espacio aislado actual.

Operaciones por lotes (Bulk Operations)

ToStore proporciona interfaces de procesamiento por lotes especializadas optimizadas para el rendimiento de datos a gran escala. Estas interfaces utilizan la distribución de tareas en paralelo y el fraccionamiento de tiempo para garantizar la capacidad de respuesta de la interfaz de usuario durante las operaciones de escritura intensivas.

Método Propósito principal Requisitos de datos Características
batchInsert Insertar registros por lotes Debe contener todos los campos no nulos Inserción pura, máximo rendimiento
batchUpsert Sincronización inteligente (Upsert) Debe contener todos los campos no nulos Sincronización completa, identificado por clave primaria o campo único
batchUpdate Actualizar registros por lotes Clave primaria o campo único + Campos a actualizar Actualizaciones parciales para registros existentes
  • Inserción por lotes (batchInsert)

    await db.batchInsert('users', [
      {'username': 'user1', 'email': '[email protected]'},
      {'username': 'user2', 'email': '[email protected]'},
    ]);
    
  • Sincronización inteligente por lotes (batchUpsert) Identifica automáticamente "Insertar" o "Actualizar" según la clave primaria o los campos únicos. Común para la sincronización completa de datos.

    [!IMPORTANT] Requisitos de datos: Debido a que se puede activar una inserción, batchUpsert requiere que cada registro contenga todos los campos no nulos (nullable: false).

  • Actualización por lotes de alto rendimiento (batchUpdate) Específicamente para actualizar registros existentes. Cada registro debe incluir una clave primaria o un campo único como identificador, junto con los campos que se van a modificar.

    [!TIP] Actualizaciones parciales: batchUpdate solo modifica los campos proporcionados y no requiere todos los campos no nulos, lo que lo hace ideal para actualizaciones incrementales.

    await db.batchUpdate('users', [
      {'username': 'john', 'age': 27}, // Identificar por campo único 'username' y actualizar 'age'
      {'id': '1002', 'status': 'active'}, // También puede usar la clave primaria directamente
    ]);
    

[!TIP] Puede establecer allowPartialErrors: true para asegurarse de que los fallos en registros individuales (por ejemplo, una violación de restricción única) no rechacen toda la operación por lotes.

Garantía de recuperación de escritura (Recovery Durability)

ToStore permite controlar con flexibilidad el nivel de autorreparación al retornar el resultado de la operación de escritura (finalización del await):

Nivel Garantía de recuperación en respuesta Casos de uso y características
RecoveryDurability.standard
(Recomendado por defecto)
A prueba de fallos antes de responder Protección contra bloqueos de la aplicación, excepciones no detectadas y finalizaciones de procesos por OOM. Combina un rendimiento muy alto con seguridad diaria.
RecoveryDurability.durable A prueba de cortes de energía antes de responder Persistencia física forzada antes del retorno. Garantiza recuperación autorreparable completa incluso ante cortes de energía repentinos o fallos del kernel. Ideal para transacciones financieras y auditorías críticas.
RecoveryDurability.async Rendimiento máximo (guardado asíncrono) Encola en memoria y retorna de inmediato; tras retornar la respuesta, con volúmenes de datos pequeños generalmente solo existe una ventana de pérdida extremadamente breve de unos pocos milisegundos. Ideal para registros masivos y métricas.

1. Configuración global predeterminada

Configure el nivel de recuperación predeterminado para toda la instancia en DataStoreConfig:

final db = await ToStore.open(
  config: DataStoreConfig(
    defaultRecoveryDurability: RecoveryDurability.standard, // Predeterminado: seguro contra fallos antes de responder
  ),
);

2. Anulación por operación

Todas las operaciones en tablas estructuradas, operaciones por lotes, actualizaciones/eliminaciones encadenadas y el almacenamiento Clave-Valor (KV) admiten la especificación individual mediante el parámetro opcional durability:

// 1. Operaciones en tablas estructuradas
await db.insert('orders', orderData, durability: RecoveryDurability.durable); // Pedido crítico: a prueba de cortes de energía
await db.batchInsert('logs', logList, durability: RecoveryDurability.async); // Registros masivos: asíncrono ultrarrápido

// 2. Actualizaciones y eliminaciones encadenadas
await db.update('users', {'status': 'active'})
  .where('id', '=', userId)
  .durability(RecoveryDurability.durable);

// 3. Almacenamiento Clave-Valor (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);

Vectores, texto y recuperación híbrida

La recuperación léxica de texto, de vectores densos y neuronal dispersa comparten una misma cadena de consulta (matchText / matchVector / matchSparse): combínelas con predicados estructurados en la misma cadena, o fusione varias ramas de recall. Las puntuaciones y los diagnósticos de canal se devuelven en QueryResult.retrieval, alineados 1:1 con las filas de data. Si solo necesita claves primarias y puntuaciones, prefiera .select(['id']) (o el nombre de su campo PK) para que el motor omita hidratar filas completas; de lo contrario, la recuperación híbrida materializa registros completos (incluidas incrustaciones grandes) y el rendimiento puede caer bruscamente. Para ANN dedicado sin filtros ni fusión, db.vectorSearch(...) devuelve List<VectorSearchResult> (clave primaria + puntuación) con la misma ruta de búsqueda central.

Visibilidad de búsqueda: Tras un insert/update exitoso, los índices normales, de texto y dispersos son buscables de inmediato; los índices vectoriales no se construyen en la ruta de escritura (para no afectar el rendimiento) y no son buscables al instante. Cuando necesite incluirlos en la búsqueda, ejecute await db.flush() al final del lote de negocio (conveniencia opcional); solo entonces participan en 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,
);

Mapeo canal / esquema:

Canal Tipo de campo Índice API de consulta Valor de consulta
Texto léxico DataType.text IndexType.text matchText / orMatchText TextQuery.text / terms / termsWeighted
Neuronal disperso DataType.sparse IndexType.sparse matchSparse / orMatchSparse SparseVectorData
Vector denso DataType.vector IndexType.vector matchVector / orMatchVector VectorData, etc.

Configuración de vectores densos (VectorFieldConfig, VectorIndexConfig):

  • dimensions: debe coincidir con el ancho real de la incrustación que escribe
  • indexType: identificador opaco del algoritmo denso; actualmente ngh
  • distanceMetric: métrica de similitud del lado del índice (construcción y búsqueda); cosine es habitual para incrustaciones semánticas, l2 se adapta a la distancia euclidiana e innerProduct a la búsqueda por producto escalar. Tras escribir datos, cambiarla suele requerir reconstruir el índice vectorial.

Parámetros de recuperación encadenada (cada match* / orMatch*, más limit en la cadena):

  • Texto
    • TextQuery.text: tokenizado por el motor
    • TextQuery.terms / termsWeighted: pre-tokenizado; sin segunda pasada; los términos latinos deben coincidir con el índice (normalmente minúsculas)
    • operator: or (predeterminado; ranking por unión) o and (todo término de peso positivo debe coincidir, luego se ordena)
    • No se admite coincidencia de frases
  • Disperso
    • SparseVectorData / SparseVectorData.fromMap(...): vector de consulta disperso
    • Los pesos del lado del documento conviene que caigan en (0, 1]
  • Vector
    • field / vector: campo de destino y vector de consulta
    • searchDepth: >= 1, predeterminado 50; valores mayores suelen subir el recall y la latencia; vecino más cercano aproximado — no es un recall@K garantizado
    • distanceThreshold: techo de distancia
  • Compartidos
    • weight: peso de fusión multi-vía; predeterminado 1.0
    • minScore: umbral inferior de relevancia
    • limit: número de resultados (topK)
    • .fusionMethod(...): multi-vía predeterminado weightedScore; conmutable a rrf

Notas de resultado y puntuación (QueryResult / VectorSearchResult):

  • Los registros de negocio están en data; puntuaciones e info de canal en retrieval.entries, alineadas 1:1 con data. Si solo necesita claves primarias y puntuaciones, prefiera .select(['id']).
  • score (puntuación de relevancia normalizada, 0.0 ~ 1.0): relevancia unificada para texto, disperso y vector (mayor = más relevante). La coincidencia exacta de vector alcanza 1.0. Use minScore para conservar aciertos fuertes y descartar débiles. La fusión multi-vía predeterminada weightedScore conserva un acierto fuerte de un solo canal; texto y disperso permanecen en [0.0, 1.0).
  • rawScore: métrica física no normalizada — coseno / producto escalar / L2 / impacto de texto. Use rawScore / distance cuando necesite la métrica subyacente.
  • entry.meta['distance']: distancia ANN en canales vectoriales (menor = más cercano).
  • retrieval.fusionMethod: null en recall de un solo canal; multi-vía predeterminado weightedScore (conmutable con .fusionMethod(RetrievalFusionMethod.rrf)).
  • El db.vectorSearch(...) de nivel superior devuelve List<VectorSearchResult> (primaryKey / score / rawScore / distance) para ANN dedicado. El minScore opcional usa el mismo umbral de relevancia que matchVector (puede devolver menos de topK).

Puntuación de relevancia (score) y línea base de umbrales (canal único y multi-vía weightedScore; no para rrf). Para embeddings típicos (dimensiones ≥ 128); en dimensiones menores los vecinos débiles pueden puntuar alto — suba minScore o use rawScore si hace falta:

Puntuación de relevancia (score) Significado base y escenarios típicos
>= 0.85 Misma entidad (verificación facial, biometría, deduplicación exacta)
>= 0.70 Coincidencia semántica de alta confianza (hechos centrales, Q&A precisa)
>= 0.40 Relevancia semántica básica (RAG general, anti-alucinación en bases de conocimiento)
>= 0.30 Recall inicial amplio (descubrimiento difuso, pool pre-rerank)
< 0.30 Asociación débil o ruido de fondo

Configure el minScore del canal según necesite descartar aciertos de baja relevancia.

TTL a nivel de tabla (vencimiento automático basado en tiempo)

Para registros, telemetría, eventos y otros datos que deberían caducar con el tiempo, puede definir TTL a nivel de tabla a través de ttlConfig. El motor limpiará automáticamente los registros caducados en segundo plano:

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, // Conservar 7 días
    // Obligatorio en tablas nuevas / al activar TTL por primera vez:
    // 1) DataType.datetime  2) nullable: false
    // 3) DefaultValueType.currentTimestamp
    sourceField: 'created_at',
  ),
);

Evicción por capacidad (FIFO / LRU)

Limita cuántos registros conserva una tabla por cantidad y/o tamaño aproximado. Independiente del TTL—pueden combinarse. El excedente se elimina automáticamente en segundo plano.

// FIFO (predeterminado): expulsar los más antiguos por clave primaria.
// No establezca sourceField (salvo PrimaryKeyType.none).
capacityConfig: CapacityConfig(
  maxEntries: 10000,
  // maxBytes: 50 * 1024 * 1024, // límite de tamaño opcional
  policy: CapacityEvictionPolicy.fifo,
),

// LRU: sourceField obligatorio (datetime, non-null, currentTimestamp).
// Actualícelo cuando el registro deba contar como usado recientemente.
capacityConfig: CapacityConfig(
  maxEntries: 10000,
  policy: CapacityEvictionPolicy.lru,
  sourceField: 'last_active_at',
),
  • Configure al menos uno de maxEntries / maxBytes.
  • FIFO + PrimaryKeyType.none también requiere sourceField (mismas reglas datetime).

También puede activar, cambiar o desactivar la evicción por capacidad en una tabla existente en tiempo de ejecución (sin reabrir la base):

// Activar / actualizar
await db.updateSchema('recent_events').setCapacityConfig(
  CapacityConfig(
    maxEntries: 10000,
    policy: CapacityEvictionPolicy.lru,
    sourceField: 'last_active_at',
  ),
);

// Desactivar (conserva las filas; deja de borrar por capacidad)
await db.updateSchema('recent_events').disableCapacity();

La capacidad KV se configura al abrir la base con DataStoreConfig (no en cada kv.set):

  • kvCapacityConfig: límite de claves del espacio actual
  • globalKvCapacityConfig: límite de KV global
  • Misma forma que el CapacityConfig de tabla, pero sin sourceField
final db = await ToStore.open(
  dbPath: '...',
  config: DataStoreConfig(
    kvCapacityConfig: CapacityConfig(
      maxEntries: 5000,
      policy: CapacityEvictionPolicy.lru,
    ),
    globalKvCapacityConfig: CapacityConfig(
      maxEntries: 2000,
      policy: CapacityEvictionPolicy.fifo,
    ),
  ),
);

Almacenamiento inteligente (Upsert)

ToStore decide si actualizar o insertar en función de la clave primaria o el campo único incluido en data. where no se admite aquí; el objetivo del conflicto se determina por los propios datos.

// Por clave primaria
final result = await db.upsert('users', {
  'id': 1,
  'username': 'john',
  'email': '[email protected]',
});

// Por clave única (el registro debe contener todos los campos que participan en una restricción única más los campos obligatorios)
await db.upsert('users', {
  'username': 'john',
  'email': '[email protected]',
  'age': 26,
});

// Batch upsert (admite modo atómico o modo de éxito parcial)
// allowPartialErrors: true significa que algunas filas pueden fallar mientras que otras aún tienen éxito
final batchResult = await db.batchUpsert('users', [
  {'username': 'a', 'email': '[email protected]'},
  {'username': 'b', 'email': '[email protected]'},
], allowPartialErrors: true);

Consultas avanzadas

ToStore proporciona una API de consulta declarativa encadenable con manejo de campos flexible y relaciones complejas entre tablas múltiples.

1. Selección de campo (select)

El método select especifica qué campos se devuelven. Si no lo llama, todos los campos se devuelven de forma predeterminada.

  • Aliases: admite la sintaxis field as alias (no distingue entre mayúsculas y minúsculas) para cambiar el nombre de las claves en el conjunto de resultados.
  • Campos calificados para tabla: en combinaciones de varias tablas, table.field evita conflictos de nombres
  • Mezcla de agregación: los objetos Agg se pueden colocar directamente dentro de la lista select
final results = await db.query('orders')
    .select([
      'orders.id',
      'users.name as customer_name',
      'orders.amount',
      Agg.count('id', alias: 'total_items')
    ])
    .join('users', 'orders.user_id', '=', 'users.id')
    .where('orders.amount', '>', 1000)
    .limit(20);

2. Se une (join)

Admite join estándar (unión interna), leftJoin y rightJoin.

3. Uniones inteligentes basadas en claves externas (recomendado)

Si foreignKeys está definido correctamente en TableSchema, no es necesario escribir a mano las condiciones de unión. El motor puede resolver relaciones de referencia y generar automáticamente la ruta JOIN óptima.

  • joinReferencedTable(tableName): se une automáticamente a la tabla principal a la que hace referencia la tabla actual
  • joinReferencingTable(tableName): une automáticamente tablas secundarias que hacen referencia a la tabla actual
// 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);

Agregación, agrupación y estadísticas (Agg y GroupBy)

1. Agregación (Agg fábrica)

Las funciones agregadas calculan estadísticas sobre un conjunto de datos. Con el parámetro alias, puede personalizar los nombres de los campos de resultados.

Método Propósito Ejemplo
Agg.count(field) Contar registros no nulos Agg.count('id', alias: 'total')
Agg.sum(field) Valores de suma Agg.sum('amount', alias: 'total_price')
Agg.avg(field) Valor medio Agg.avg('score', alias: 'average_score')
Agg.max(field) Valor máximo Agg.max('age')
Agg.min(field) Valor mínimo Agg.min('price')

[!TIP] Dos estilos de agregación comunes

  1. Métodos de acceso directo (recomendados para métricas individuales): llame directamente a la cadena y obtenga el valor calculado inmediatamente. num? totalAge = await db.query('users').sum('age');
  2. Incrustado en select (para múltiples métricas o agrupaciones): pase objetos Agg a la lista select. final stats = await db.query('orders').select(['status', Agg.sum('amount')]).groupBy(['status']);

2. Agrupación y filtrado (groupBy / having)

Utilice groupBy para categorizar registros, luego having para filtrar resultados agregados, similar al comportamiento 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étodos de consulta auxiliar

  • exists() (alto rendimiento): comprueba si algún registro coincide. A diferencia de count() > 0, produce un cortocircuito tan pronto como se encuentra una coincidencia, lo cual es excelente para conjuntos de datos muy grandes.
  • count(): devuelve eficientemente el número de registros coincidentes.
  • first(): un método conveniente equivalente a limit(1) y que devuelve la primera fila directamente como Map.
  • distinct([fields]): deduplica resultados. Si se proporciona fields, la unicidad se calcula en función de esos campos.
// 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. Lógica compleja con QueryCondition

QueryCondition es la herramienta principal de ToStore para la lógica anidada y la construcción de consultas entre paréntesis. Cuando las simples llamadas where encadenadas no son suficientes para expresiones como (A AND B) OR (C AND D), esta es la herramienta a utilizar.

  • condition(QueryCondition sub): abre un grupo anidado AND
  • orCondition(QueryCondition sub): abre un grupo anidado OR
  • or(): cambia el siguiente conector a OR (el valor predeterminado es AND)
Ejemplo 1: Condiciones O mixtas

SQL equivalente: 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);
Ejemplo 2: Fragmentos de condición reutilizables

Puede definir fragmentos de lógica empresarial reutilizables una vez y combinarlos en diferentes consultas:

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. Consulta de transmisión

Adecuado para conjuntos de datos muy grandes cuando no desea cargar todo en la memoria a la vez. Los resultados se pueden procesar a medida que se leen.

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

6. Consulta reactiva

El método watch() le permite monitorear los resultados de la consulta en tiempo real. Devuelve un Stream y vuelve a ejecutar automáticamente la consulta cada vez que los datos coincidentes cambian en la tabla de destino.

  • Antirrebote automático: el antirrebote inteligente integrado evita ráfagas redundantes de consultas
  • Sincronización de UI: funciona naturalmente con Flutter StreamBuilder para listas de actualización en vivo
// 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();
  },
)

Almacenamiento en caché de resultados de consultas manuales (opcional)

[!IMPORTANT] ToStore ya incluye internamente un eficiente caché LRU inteligente de múltiples niveles. No se recomienda la administración de caché manual de rutina. Considérelo solo en casos especiales:

  1. Análisis completos costosos de datos no indexados que rara vez cambian
  2. Requisitos persistentes de latencia ultrabaja incluso para consultas no activas
  • useQueryCache([Duration? expiry]): habilita el caché y opcionalmente establece una caducidad
  • noQueryCache(): deshabilita explícitamente el caché para esta consulta
  • clearQueryCache(): invalida manualmente el caché para este patrón de consulta
final results = await db.query('heavy_table')
    .where('non_indexed_field', '=', 'value')
    .useQueryCache(const Duration(minutes: 10)); // Manual acceleration for a heavy query only

Consulta y paginación eficiente

[!TIP] Especifique siempre limit como tamaño de página: Se recomienda encarecidamente especificar siempre limit en sus consultas. Si se omite, el motor limita por defecto a 1000 registros para evitar consultar demasiados datos a la vez.

ToStore ofrece soporte de paginación de doble modo. Para el desplazamiento de listas o la carga infinita, se recomienda encarecidamente utilizar la paginación por cursor integrada y sin fisuras; para saltar a páginas específicas, la paginación básica es suficiente:

1. Paginación básica (Modo Offset)

Adecuado para escenarios donde el volumen de datos es pequeño (por ejemplo, menos de 10k) o cuando necesita saltar a una página específica con precisión.

final result = await db.query('users')
    .orderByDesc('created_at')
    .offset(40) // Omitir las primeras 40 filas
    .limit(20); // Tomar 20 filas

[!TIP] Cuando offset se vuelve muy grande, la base de datos debe escanear y descartar una gran cantidad de registros, y el rendimiento se degrada linealmente. Para una paginación profunda o conjuntos de datos más grandes, se recomienda utilizar el Modo Cursor.

2. Paginación por cursor (Modo Cursor - Recomendado)

Ideal para conjuntos de datos masivos y desplazamiento infinito. Al registrar la posición inicial del flujo de datos de la página actual, se posiciona directamente en esa ubicación durante la paginación (seek), evitando escanear y descartar datos históricos, y manteniendo constante la velocidad de la paginación profunda.

  • Gestión automática: Establezca un límite para el tamaño de la página y simplemente llame a next() o prev() para las páginas siguientes para obtener un rendimiento de paginación excelente de forma sencilla y rápida.
  • Desplazamiento del punto de partida: Admite la combinación con .offset(N) en la consulta inicial para ubicar la ventana de inicio, después de lo cual al llamar a next() directamente se obtienen las páginas siguientes.
// 1. Iniciar consulta inicial
final page1 = await db.query('users')
    .orderByDesc('id')
    .limit(20);

// 2. Obtener la siguiente página
if (page1.hasMore) {
  final page2 = await page1.next(); 
  print('Cantidad de elementos en la siguiente página: ${page2.data.length}');
  
  // 3. Obtener la página anterior
  if (page2.hasPrev) {
    final prevPage = await page2.prev();
    print('Datos de la página anterior: ${prevPage.data}');
  }
}
Escenario avanzado: Paginación por tokens sin estado (Token-based Cursor)

Para la paginación cotidiana en la app, prefiera next() / prev() arriba. Use tokens de cursor solo en APIs cliente-servidor o al serializar el estado de paginación entre procesos/redes:

  • La consulta inicial devuelve las cadenas nextCursorToken y prevCursorToken.
  • La consulta siguiente pasa el token a través de .cursor(token) para posicionarse (seek).
  • Nota: cursor y offset son mutuamente excluyentes; establecer uno borra el otro.
// Consulta inicial (por ejemplo, en el lado del servidor API)
final page1 = await db.query('users')
    .orderByDesc('id')
    .limit(20);

final String? nextToken = page1.nextCursorToken; // Serializar y devolver este token al cliente

// Cuando el cliente solicita la siguiente página con el token:
if (nextToken != null) {
  final page2 = await db.query('users')
      .orderByDesc('id')
      .limit(20)
      .cursor(nextToken); // Pasar el token para posicionarse y leer con precisión
}
Característica Modo Offset Modo Cursor
Rendimiento de la consulta Se degrada a medida que aumentan las páginas Velocidad constante para paginación profunda
Ideal para Conjuntos de datos pequeños, saltos de página exactos Conjuntos de datos masivos, desplazamiento infinito
Consistencia bajo cambios Los cambios en los datos pueden causar saltos o duplicados de filas Evita duplicaciones y omisiones causadas por cambios en los datos

Sonda de memoria y recuperación sincrónica (peek)

Para escenarios con requisitos extremos de rendimiento y latencia, ToStore ofrece la serie peek de recuperación sincrónica puramente en memoria, absorbiendo lecturas calientes en ráfaga directamente en el proceso: dispositivos edge pueden sostener millones de lecturas por segundo; servidores con hardware más potente pueden alcanzar decenas de millones por máquina (consulte Benchmarks).

[!NOTE] Solo caché en memoria: peek es un bypass puro en memoria sin programación. En caso de fallo de caché devuelve vacío/null de inmediato; el motor no realiza E/S de archivos sincrónica (evitando bloquear el bucle de eventos bajo alta concurrencia). Para resultados persistentes completos, use await query() en la aplicación.

Métodos peek

Método Tipo de retorno Descripción
peekFirst() Map<String, dynamic>? Registro único; devuelve null si no hay caché
peek() QueryResult<T> QueryResult con lista data y metadatos de paginación (hasMore, cursores, etc.); datos solo con acierto de caché
peekExists() bool Comprueba sincrónicamente si existe un registro coincidente en caché
peekCount() int Cuenta sincrónicamente registros coincidentes en caché
result.peekNext() QueryResult<T> Página siguiente sincrónica cuando el resultado paginado está en caché
result.peekPrev() QueryResult<T> Página anterior sincrónica cuando el resultado paginado está en caché

Mejor práctica: sonda de memoria primero (Peek-Through)

// Registro único: sonda de memoria primero, consulta asíncrona estándar si falla
final q = db.query('users').where('id', '=', userId);
final user = q.peekFirst() ?? await q.first();

// Consulta paginada con sonda
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(); // acierto de caché: cambio de página sincrónico
  if (next.data.isEmpty) await page.next();
}

Sonda KV (db.kv)

Método Equivalente async Descripción
peekGet(key) get(key) Sondeo puntual en memoria; claves expiradas → null
peekExists(key) exists(key) Verificación de existencia en memoria
db.kv.query().peek() await db.kv.query() Sondeo paginado (prefijo / orden / limit)
db.kv.query().peekFirst() await db.kv.query().first() Sondeo del primer registro
// Punto: sondea primero, async si falla
final theme = db.kv.peekGet('theme', isGlobal: true) ?? await db.kv.get('theme', isGlobal: true);

// Sonda KV paginada
var page = db.kv.query().prefix('setting_').limit(20).peek();
if (page.data.isEmpty) page = await db.kv.query().prefix('setting_').limit(20);

[!TIP] Recomendación: Las consultas asíncronas estándar (await query()) usan programación de eventos para estabilidad a largo plazo y equidad multitarea; 100k+ QPS es suficiente para la mayoría de cargas. La serie peek está diseñada para absorber picos extremos de lectura caliente a millones/decenas de millones de QPS por máquina.

Claves externas y cascada

Las claves externas garantizan la integridad referencial y le permiten configurar actualizaciones y eliminaciones en cascada. Las relaciones se validan al escribir y actualizar. Si las políticas en cascada están habilitadas, los datos relacionados se actualizan automáticamente, lo que reduce el trabajo de coherencia en el código de la aplicación.

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
        ),
    ],
  ),
]);

Operadores de consulta

Todas las condiciones where(field, operator, value) admiten los siguientes operadores (no distingue entre mayúsculas y minúsculas):

Operador Descripción Ejemplo / Rendimiento
= Igual where('status', '=', 'val') — [Recomendado] Búsqueda por índice (Seek)
!=, <> No es igual where('role', '!=', 'val') — [Precaución] Escaneo completo de tabla
> , >=, <, <= Comparación de rango where('age', '>', 18) — [Recomendado] Escaneo por índice
IN Incluido en where('id', 'IN', [...]) — [Recomendado] Búsqueda por índice (Seek)
NOT IN No incluido en where('status', 'NOT IN', [...]) — [Precaución] Escaneo completo de tabla
BETWEEN Rango where('age', 'BETWEEN', [18, 65]) — [Recomendado] Escaneo por índice
LIKE Coincidencia de patrón (% = cualquier carácter, _ = un solo carácter) where('name', 'LIKE', 'John%') — [Precaución] Ver nota abajo
NOT LIKE Patrón no coincidente where('email', 'NOT LIKE', '...') — [Precaución] Escaneo completo de tabla
IS Es null where('deleted_at', 'IS', null) — [Recomendado] Búsqueda por índice (Seek)
IS NOT No es null where('email', 'IS NOT', null) — [Precaución] Escaneo completo de tabla

Métodos de consulta semántica (recomendados)

Recomendado para evitar cadenas de operadores escritas a mano y para obtener una mejor asistencia IDE.

1. Comparación

Se utiliza para comparaciones directas numéricas o de cadenas.

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. Colección y gama

Se utiliza para probar si un campo se encuentra dentro de un conjunto o rango.

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. Verificación nula

Se utiliza para probar si un campo tiene un valor.

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. Coincidencia de patrones

Admite búsqueda con comodines de estilo SQL (% coincide con cualquier número de caracteres, _ coincide con un solo carácter).

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] Guía de Rendimiento de Consultas (Índice vs Escaneo Completo)

En escenarios de datos a gran escala (millones de filas o más), siga estos principios para evitar retrasos en el hilo principal y tiempos de espera de consulta:

  1. Optimizado por índice - [Recomendado]:

    • Métodos semánticos: whereEqual, whereGreaterThan, whereLessThan, whereIn, whereBetween, whereNull, whereTrue, whereFalse y whereStartsWith (coincidencia de prefijo).
    • Operadores: =, >, <, >=, <=, IN, BETWEEN, IS null, LIKE 'prefix%'.
    • Explicación: Estas operaciones logran un posicionamiento ultrarrápido a través de índices. Para whereStartsWith / LIKE 'abc%', el índice aún puede realizar un escaneo de rango de prefijo.
  2. Riesgos de escaneo completo - [Precaución]:

    • Coincidencia difusa: whereContains (LIKE '%val%'), whereEndsWith (LIKE '%val'), whereContainsAny.
    • Consultas de negación: whereNotEqual (!=, <>), whereNotIn (NOT IN), whereNotNull (IS NOT null/whereNotEmpty).
    • Patrón no coincidente: NOT LIKE.
    • Explicación: Las operaciones anteriores generalmente requieren recorrer toda el área de almacenamiento de datos incluso si se ha creado un índice. Si bien el impacto es mínimo en dispositivos móviles o conjuntos de datos pequeños, en escenarios de análisis de datos distribuidos o de tamaño ultra grande, deben usarse con precaución, combinadas con otras condiciones de índice (por ejemplo, filtrar por ID o rango de tiempo) y la cláusula limit.

Arquitectura distribuida

// 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);
}

Ejemplos de clave primaria

ToStore proporciona múltiples algoritmos de clave primaria distribuidos para diferentes escenarios comerciales:

  • Clave primaria secuencial (PrimaryKeyType.sequential): 238978991
  • Clave principal basada en marca de tiempo (PrimaryKeyType.timestampBased): 1306866018836946
  • Clave principal con prefijo de fecha (PrimaryKeyType.datePrefixed): 20250530182215887631
  • Clave principal de código corto (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 */]
  ),
]);

Expresiones atómicas

El sistema de expresión proporciona actualizaciones de campos atómicos con seguridad de tipos. Todos los cálculos se ejecutan de forma atómica en la capa de la base de datos, evitando conflictos concurrentes:

// 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);

Expresiones condicionales (por ejemplo, diferenciar actualización versus inserción en un upsert): use Expr.isUpdate() / Expr.isInsert() junto con Expr.ifElse o Expr.when para que la expresión se evalúe solo al actualizar o solo al insertar.

// 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()),
});

Transacciones

Las transacciones garantizan la atomicidad en múltiples operaciones: o todo tiene éxito o todo se revierte, preservando la coherencia de los datos.

Características de la transacción

  • múltiples operaciones, todas exitosas o todas revertidas
  • el trabajo inacabado se recupera automáticamente después de fallas
  • las operaciones exitosas persisten de manera segura
// 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('Transacción confirmada con éxito');
} else {
  print('Transacción revertida debido a:');
  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);

Administración y mantenimiento

Las siguientes API cubren la administración, el diagnóstico y el mantenimiento de bases de datos para el desarrollo de complementos, paneles de administración y escenarios operativos:

  • Gestión de mesa
    • createTable(schema): crea una única tabla manualmente; útil para la carga de módulos o la creación de tablas de tiempo de ejecución bajo demanda
    • getTableSchema(tableName): recupera la información del esquema definido; útil para la validación automatizada o la generación de modelos de UI
    • getTableNames({isGlobal}): lista nombres de tablas del inventario de schema global (tablas de usuario). Opcional isGlobal: true solo globales, false solo no globales, omitir = ambas. Los schemas no globales se comparten entre espacios; solo los datos se aíslan.
    • getTableInfo(tableName): estadísticas en tiempo de ejecución (totalRecordCount, totalTableDataSizeBytes, totalIndexDataSizeBytes, indexCount, creación, si es global)
    • clear(tableName): borre todos los datos de la tabla mientras conserva de forma segura el esquema, los índices y las restricciones de claves internas/externas.
    • dropTable(tableName): destruir completamente una tabla y su esquema; no reversible
  • Gestión del espacio
    • currentSpaceName: obtiene el espacio activo actual en tiempo real
    • listSpaces(): enumera todos los espacios asignados en la instancia de base de datos actual
    • getSpaceInfo(useCache: true): agregados locales del espacio (totalRecordCount, tamaño de datos de tabla/índice). Use useCache: false para reconciliar desde meta.
    • deleteSpace(spaceName): elimina un espacio específico y todos sus datos, excepto default y el espacio activo actual
  • Descubrimiento de instancia
    • config: inspecciona la instantánea DataStoreConfig final efectiva de la instancia.
    • instancePath: localiza el directorio de almacenamiento físico con precisión
    • getVersion() / setVersion(version): control de versiones definido por el negocio para decisiones de migración a nivel de aplicación (no la versión del motor)
  • Mantenimiento
    • flush(mode: FlushMode.full): fuerza las escrituras pendientes al almacenamiento. Modos: recovery (más rápido; registro de recuperación solo a búferes del SO; sobrevive a fallos de la app, no a cortes de energía), recoveryDurable (registro de recuperación a almacenamiento estable; busca sobrevivir a cortes de energía), full (predeterminado; registro de recuperación + datos de tabla e índices a almacenamiento estable).
    • deleteDatabase(): elimina todos los archivos físicos y metadatos de la instancia actual; utilizar con cuidado
  • Diagnóstico
    • db.status.memory(): inspecciona las tasas de aciertos de la caché, el uso de la página de índice y la asignación general del montón
    • db.status.space() / db.status.table(tableName): inspeccionar estadísticas en vivo e información de salud para espacios y tablas
    • db.status.config(): inspecciona la instantánea de configuración del tiempo de ejecución actual
    • db.status.migration(taskId): realiza un seguimiento del progreso de la migración asincrónica en tiempo real

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());

Copia de seguridad y restauración

Especialmente útil para la importación/exportación local de un solo usuario, grandes migraciones de datos fuera de línea y reversión del sistema después de una falla:

  • Copia de seguridad (backup)
    • compress: si se habilita la compresión; recomendado y habilitado por defecto
    • scope: controla el rango de respaldo
      • BackupScope.database: realiza una copia de seguridad de instancia de base de datos completa, incluidos todos los espacios y tablas globales
      • BackupScope.currentSpace: realiza una copia de seguridad solo del espacio activo actual, excluyendo las tablas globales
      • BackupScope.currentSpaceWithGlobal: realiza una copia de seguridad del espacio actual más sus tablas globales relacionadas, ideal para migración de un solo inquilino o de un solo usuario.
  • Restaurar (restore)
    • backupPath: ruta física al paquete de respaldo
    • cleanupBeforeRestore: si se deben borrar silenciosamente los datos actuales relacionados antes de la restauración; Se recomienda true para evitar estados lógicos mixtos.
    • deleteAfterRestore: elimina automáticamente el archivo fuente de la copia de seguridad después de una restauración exitosa
// 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,
);

Códigos de estado y manejo de errores

Hay dos canales para la retroalimentación de errores y excepciones en ToStore:

[!NOTE] Base de diagnóstico unificada: Ya sea que se devuelvan a través del modelo de resultado de respuesta (statuses en DbResult/QueryResult) o se lancen a través de excepciones fatales (statuses en DbException), todos los estados de diagnóstico se basan uniformemente en el sistema estructurado ResultStatus y comparten los mesmos códigos de estado, lo que garantiza la coherencia.

  1. Modelo de resultado de respuesta (Result-based Response) Para operaciones cotidianas como inserción, actualización, eliminación, consulta, transacciones y modificaciones del esquema de tabla en tiempo de ejecución. Estas operaciones no lanzarán excepciones cuando ocurran violaciones de restricciones, fallos de validación o argumentos no válidos. En su lugar, ToStore envuelve los resultados usando DbResult o QueryResult, registrando toda la información de diagnóstico en la lista de estados. Esto garantiza que los errores ordinarios de lógica empresarial no interrumpan la base de datos.
  • hasErrors: Indica si hay errores en la operación actual. En operaciones por lotes o transacciones, si hay al menos un error, esta propiedad es true.
  • statuses: Una lista detallada de todos los diagnósticos ResultStatus de la operación. Admite una coincidencia de orden 1:1, lo cual es muy útil para operaciones por lotes.
  • firstPrimaryKey: Lee la clave primaria generada físicamente de forma directa durante una única operación de inserción/escritura sin necesidad de analizar statuses manualmente.
  • ResultType: Enumeración para la categoría de estado, conveniente para el manejo de bifurcaciones y comprobaciones (por ejemplo, isBusinessError, isDeveloperError).
  1. Lanzamiento de excepciones (Exception-based Throwing) Para errores fatales causados por descuidos del desarrollador o fallos de diseño (por ejemplo, fallo en la verificación del esquema durante ToStore.open, incompatibilidad de la versión del motor, corrupción fatal en la migración de datos, etc.). En estos casos, ToStore lanza DbException para detener la ejecución, instando al desarrollador a rectificarla.

[!WARNING] Pautas de desarrollo: Los errores comerciales ordinarios no deben lanzar excepciones; deben devolverse en el modelo de resultado de respuesta para evitar interrumpir el tiempo de ejecución de la aplicación.


Ejemplos de errores y excepciones

1. Manejo de respuesta para una sola escritura

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

if (result.hasErrors) {
  // Obtener el primer tipo de error y descripción
  print('Operation failed: [\${result.firstType.codeKey}] \${result.message}');
} else {
  print('Escritura exitosa, la clave primaria es: \${result.firstPrimaryKey}');
}

2. Diagnóstico detallado en escritura por lotes

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

if (batchResult.hasErrors) {
  print('Operación por lotes fallida parcialmente: exitosos \${batchResult.successCount}, fallidos \${batchResult.failedCount}');
  
  for (final status in batchResult.statuses) {
    final int idx = status.index;
    
    if (status is ConstraintStatus) {
      print('Index [\$idx] Violación de restricción! Tabla! Tabla: \${status.tableName}, campos: \${status.fields}');
    } else if (status is InvalidArgumentStatus) {
      print('Index [\$idx] Error de argumento! Parámetro! Parameter: \${status.parameterName}, valor pasado: \${status.passedValue}');
    } else if (status.type != ResultType.success) {
      print('Index [\$idx] Ocurrió un error: [\${status.codeKey}] \${status.message}');
    }
  }
}

3. Error fatal y captura de excepción de inicialización (DbException)

try {
  // Initialize database with schemas that might have validation issues
  final db = await ToStore.open(schemas: appSchemas);
} on DbException catch (e) {
  print('❌ Excepción fatal de base de datos! Mensaje de error: \n\${e.message}');
  
  // Iterate through the detailed status list in the exception
  for (final status in e.statuses) {
    if (status is SchemaValidationStatus) {
      print('Fallo en la validación del esquema! Tabla! Tabla: \${status.tableName}, campo: \${status.field}, configuración no válida: \${status.wrongValue}');
    } else {
      print('Información de diagnóstico: [\${status.codeKey}] \${status.message}');
    }
  }
}

Para obtener la lista completa de tipos de errores, códigos de estado hoja, formatos de serialización JSON y asignaciones de campos, consulte la especificación completa: Especificación de diagnóstico automático y resolución de estado de ToStore ResultStatus.

Registrar devolución de llamada y diagnóstico de base de datos

ToStore puede enrutar los registros del ciclo de vida de la base de datos a la capa empresarial a través de ToStore.setLogConfig(...).

  • La devolución de llamada onLog recibe todos los registros de registro LogRecord que pasan los filtros actuales enableLog y logLevel.
    • LogLevel.error: Ocurrió un error local, no afecta el funcionamiento normal.
    • LogLevel.critical: Error global a nivel de desastre (como disco lleno, memoria insuficiente, falla grave de migración, etc.) que requiere intervención manual. Se recomienda activar notificaciones de alarma en este nivel.
  • Llame a ToStore.setLogConfig(...) antes de la inicialización para que también se capturen los registros generados durante la inicialización y la dinámica migración.
  // Configurar parámetros de registro o devolución de llamada
  ToStore.setLogConfig(
    enableLog: true,
    logLevel: debugMode ? LogLevel.debug : LogLevel.warn,
    logLabel: 'my_app_db', // Título gris claro en la parte superior del registro para distinguir aplicaciones o instancias de bases de datos,
    onLog: (log) {
      // En producción, se puede reportar warn/error/critical al backend o plataforma de registro
      // log.level corresponde al nivel de registro (LogLevel.debug, info, warn, error, critical)
      // log.message corresponde al texto del registro procesado
      // log.status corresponde al estado de diagnóstico ResultStatus subyacente (contiene code y 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();

Configuración de seguridad

[!WARNING] Administración de claves

Clave Función Cómo cambiar ¿Reescritura completa de datos?
encodingKey Clave de cifrado de datos Establecer nuevo valor y volver a open Sí (lento)
encryptionKey Clave de seguridad; protege encodingKey Llamar db.rotateEncryptionKey en tiempo de ejecución No (rápido)

Nunca codifique claves sensibles. Para vincularlas al dispositivo, guarde encryptionKey en el Keychain / Keystore / enclave seguro del SO y páselo al motor.

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,
  ),
);

Cambiar encodingKey: establezca el nuevo valor en EncryptionConfig y vuelva a open. El motor detecta el cambio y migra los datos automáticamente en segundo plano, sin intervención de la aplicación.

Rotar encryptionKey (rotación periódica por seguridad/cumplimiento): sin reescritura de datos; se ejecuta en línea.

// 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) {
  // Manejar error (oldKey incorrecto, migración de encodingKey en curso, etc.)
  return;
}
// Éxito: configuración en memoria actualizada; pase el encryptionKey más reciente en el próximo ToStore.open

Cifrado de nivel de valor (ToCrypto)

El cifrado de base de datos completa protege todos los datos de tablas e índices, pero puede afectar el rendimiento general. Si solo necesita proteger algunos valores confidenciales, utilice ToCrypto en su lugar. Está desacoplado de la base de datos, no requiere ninguna instancia db y permite que su aplicación codifique/decodifique valores antes de escribir o después de leer. La salida es Base64, que encaja naturalmente en columnas JSON o TEXTO.

  • key (obligatorio): String o Uint8List. Si no son 32 bytes, se utiliza SHA-256 para derivar una clave de 32 bytes.
  • type (opcional): tipo de cifrado de ToCryptoType, como ToCryptoType.chacha20Poly1305 o ToCryptoType.aes256Gcm. El valor predeterminado es ToCryptoType.chacha20Poly1305.
  • aad (opcional): datos adicionales autenticados de tipo Uint8List. Si se proporcionan durante la codificación, también se deben proporcionar exactamente los mismos bytes durante la decodificación.
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);

Configuración avanzada explicada (DataStoreConfig)

[!TIP] Inteligencia de configuración cero ToStore detecta automáticamente la plataforma, las características de rendimiento, la memoria disponible y el comportamiento de E/S para optimizar parámetros como la simultaneidad, el tamaño del fragmento y el presupuesto de caché. En el 99% de los escenarios empresariales comunes, no es necesario ajustar DataStoreConfig manualmente. Los valores predeterminados ya proporcionan un rendimiento excelente para la plataforma actual.

Parámetro Predeterminado Propósito y recomendación
yieldDurationMs 8ms Recomendación principal. El intervalo de tiempo utilizado cuando las tareas largas dan resultados. 8ms se alinea bien con el renderizado de 120 fps/60 fps y ayuda a mantener la interfaz de usuario fluida durante consultas o migraciones grandes.
maxQueryOffset 10000 Protección de consultas. Cuando offset supera este umbral, se genera un error. Esto evita E/S patológicas debido a una paginación con desplazamiento profundo.
defaultQueryLimit 1000 Guarda de recursos. Se aplica cuando una consulta no especifica limit, lo que evita la carga accidental de conjuntos de resultados masivos y posibles problemas de OOM.
cacheMemoryBudgetMB (automático) Gestión de memoria detallada. Presupuesto total de memoria caché. El motor lo utiliza para impulsar la recuperación de LRU automáticamente.
enableJournal verdadero Autorreparación de accidentes. Cuando está habilitado, el motor puede recuperarse automáticamente después de accidentes o cortes de energía.
defaultRecoveryDurability standard Garantía de recuperación en respuesta. Define el nivel de autorreparación antes de que las operaciones de escritura retornen el resultado:
• standard (Predeterminado): A prueba de fallos antes de responder. Protege contra bloqueos de app, excepciones no detectadas y terminación OOM.
• durable: A prueba de cortes de energía antes de responder. Persistencia física forzada antes del retorno; recuperación completa ante cortes de energía.
• async: Rendimiento máximo. Retorna inmediatamente y guarda en segundo plano; tras responder, en datos pequeños suele existir una ventana de solo unos pocos milisegundos.
persistRecoveryOnCommit verdadero Sólida garantía de durabilidad. Cuando es cierto, las transacciones confirmadas se sincronizan con el almacenamiento físico. Cuando es falso, el vaciado se realiza de forma asíncrona en segundo plano para mejorar la velocidad, con un pequeño riesgo de perder una pequeña cantidad de datos en caso de fallos extremos.
ttlCleanupIntervalMs 300000 Encuesta TTL global. El intervalo en segundo plano para escanear datos caducados cuando el motor no está inactivo. Los valores más bajos eliminan los datos caducados antes pero cuestan más gastos generales.
kvCapacityConfig null Capacidad KV del espacio. Límite FIFO/LRU para claves del espacio; no configure sourceField. Véase Evicción por capacidad.
globalKvCapacityConfig null Capacidad KV global. Misma forma que kvCapacityConfig.
maxConcurrency (automático) Control de simultaneidad de cálculo. Establece el recuento máximo de trabajadores paralelos para tareas intensivas como el cálculo de vectores y el cifrado/descifrado. Generalmente es mejor mantenerlo automático.
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, // A prueba de fallos antes de responder
  ),
);

Rendimiento y experiencia

Puntos de referencia

Destacados del suite 100K y validación edge a escala de mil millones (3 rondas, 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

Gráficos completos y todas las operaciones: Benchmarks.

ToStore Basic Performance Demo

  • Demostración de rendimiento básico (basic-demo.mp4): es posible que la vista previa del GIF no muestre todo. Abra el vídeo para ver la demostración completa. Incluso en dispositivos móviles comunes, el inicio, la paginación y la recuperación permanecen estables y fluidos incluso cuando el conjunto de datos supera los 100 millones de registros.

ToStore Disaster Recovery Stress Test

  • Prueba de estrés de recuperación ante desastres (disaster-recovery.mp4): durante las escrituras de alta frecuencia, el proceso se interrumpe intencionalmente una y otra vez para simular fallas y cortes de energía. ToStore puede recuperarse rápidamente.

Consejos de experiencia

  • 📱 Proyecto de ejemplo: el directorio example incluye una aplicación Flutter completa
  • 🚀 Compilaciones de producción: empaquetar y probar en modo de lanzamiento; el rendimiento de la versión va mucho más allá del modo de depuración
  • ✅ Pruebas estándar: las capacidades principales están cubiertas por pruebas estandarizadas

Si ToStore te ayuda, danos un ⭐️, ¡es una de las mejores formas de apoyar el proyecto. Muchas gracias!

🤝 Contribuir

ToStore es un motor de datos moderno en continua evolución, y agradecemos mucho las contribuciones de la comunidad. Ya sea corrigiendo errores, mejorando la documentación, refinando la arquitectura o proponiendo nuevas ideas, puedes participar a través de PR: