Driver Nosql

Source: packages/spec/src/data/driver-nosql.zod.ts

TypeScript Usage

import { AggregationPipelineSchema, AggregationStageSchema, ConsistencyLevelSchema, DocumentSchemaValidationSchema, NoSQLDataTypeMappingSchema, NoSQLDatabaseTypeSchema, NoSQLDriverConfigSchema, NoSQLIndexSchema, NoSQLIndexTypeSchema, NoSQLOperationTypeSchema, NoSQLQueryOptionsSchema, NoSQLTransactionOptionsSchema, ReplicationConfigSchema, ShardingConfigSchema } from '@objectstack/spec/data';
import type { AggregationPipeline, AggregationStage, ConsistencyLevel, DocumentSchemaValidation, NoSQLDataTypeMapping, NoSQLDatabaseType, NoSQLDriverConfig, NoSQLIndex, NoSQLIndexType, NoSQLOperationType, NoSQLQueryOptions, NoSQLTransactionOptions, ReplicationConfig, ShardingConfig } from '@objectstack/spec/data';

// Validate data
const result = AggregationPipelineSchema.parse(data);

AggregationPipeline

Properties

Property	Type	Required	Description
collection	`string`	✅	Collection/table name
stages	`{ operator: string; options: Record<string, any> }[]`	✅	Aggregation pipeline stages
options	`{ consistency?: Enum<'all' \| 'quorum' \| 'one' \| 'local_quorum' \| 'each_quorum' \| 'eventual'>; readFromSecondary?: boolean; projection?: Record<string, 0 \| 1>; timeout?: integer; … }`	optional	Query options

Nested Shape: `AggregationPipeline.stages[number]`

Property	Type	Required	Description
operator	`string`	✅	Aggregation operator (e.g., $match, $group, $sort)
options	`Record<string, any>`	✅	Stage-specific options

Nested Shape: `AggregationPipeline.options`

Property	Type	Required	Description
consistency	`Enum<'all' \| 'quorum' \| 'one' \| 'local_quorum' \| 'each_quorum' \| 'eventual'>`	optional	Consistency level override
readFromSecondary	`boolean`	optional	Allow reading from secondary replicas
projection	`Record<string, 0 \| 1>`	optional	Field projection
timeout	`integer`	optional	Query timeout (ms)
useCursor	`boolean`	optional	Use cursor instead of loading all results
batchSize	`integer`	optional	Cursor batch size
profile	`boolean`	optional	Enable query profiling
hint	`string`	optional	Index hint for query optimization

AggregationStage

Properties

Property	Type	Required	Description
operator	`string`	✅	Aggregation operator (e.g., $match, $group, $sort)
options	`Record<string, any>`	✅	Stage-specific options

ConsistencyLevel

Allowed Values

all
quorum
one
local_quorum
each_quorum
eventual

DocumentSchemaValidation

Properties

Property	Type	Required	Description
enabled	`boolean`	optional (default: `false`)	Enable schema validation
validationLevel	`Enum<'strict' \| 'moderate' \| 'off'>`	optional	Validation strictness
validationAction	`Enum<'error' \| 'warn'>`	optional	Action on validation failure
jsonSchema	`Record<string, any>`	optional	JSON Schema for validation

NoSQLDataTypeMapping

Properties

Property	Type	Required	Description
text	`string`	✅	NoSQL type for text fields
number	`string`	✅	NoSQL type for number fields
boolean	`string`	✅	NoSQL type for boolean fields
date	`string`	✅	NoSQL type for date fields
datetime	`string`	✅	NoSQL type for datetime fields
json	`string`	optional	NoSQL type for JSON/object fields
uuid	`string`	optional	NoSQL type for UUID fields
binary	`string`	optional	NoSQL type for binary fields
array	`string`	optional	NoSQL type for array fields
objectId	`string`	optional	NoSQL type for ObjectID fields (MongoDB)
geopoint	`string`	optional	NoSQL type for geospatial point fields

NoSQLDatabaseType

Allowed Values

mongodb
couchdb
dynamodb
cassandra
redis
elasticsearch
neo4j
orientdb

NoSQLDriverConfig

Properties

Property	Type	Required	Description
name	`string`	✅	Driver instance name
type	`'nosql'`	✅	Driver type must be "nosql"
capabilities	`{ queryDateGranularity?: Record<string, boolean>; autonumber?: boolean; batchSchemaSync?: boolean }`	✅	Driver capability flags
connectionString	`string`	optional	Database connection string (driver-specific format)
poolConfig	`{ min: number; max: number; idleTimeoutMillis: number; connectionTimeoutMillis: number }`	optional	Connection pool configuration
databaseType	`Enum<'mongodb' \| 'couchdb' \| 'dynamodb' \| 'cassandra' \| 'redis' \| 'elasticsearch' \| 'neo4j' \| 'orientdb'>`	✅	Specific NoSQL database type
dataTypeMapping	`{ text: string; number: string; boolean: string; date: string; … }`	✅	NoSQL data type mapping configuration
consistency	`Enum<'all' \| 'quorum' \| 'one' \| 'local_quorum' \| 'each_quorum' \| 'eventual'>`	optional	Consistency level for operations
replication	`{ enabled: boolean; replicaSetName?: string; replicas?: integer; readPreference?: Enum<'primary' \| 'primaryPreferred' \| 'secondary' \| 'secondaryPreferred' \| 'nearest'>; … }`	optional	Replication configuration
sharding	`{ enabled: boolean; shardKey?: string; shardingStrategy?: Enum<'hash' \| 'range' \| 'zone'>; numShards?: integer }`	optional	Sharding configuration
schemaValidation	`{ enabled: boolean; validationLevel?: Enum<'strict' \| 'moderate' \| 'off'>; validationAction?: Enum<'error' \| 'warn'>; jsonSchema?: Record<string, any> }`	optional	Document schema validation
region	`string`	optional	AWS region (for managed NoSQL services)
accessKeyId	`string`	optional	AWS access key ID
secretAccessKey	`string`	optional	AWS secret access key
ttlField	`string`	optional	Field name for TTL (auto-deletion)
maxDocumentSize	`integer`	optional	Maximum document size in bytes
collectionPrefix	`string`	optional	Prefix for collection/table names

Nested Shape: `NoSQLDriverConfig.capabilities`

Property	Type	Required	Description
queryDateGranularity	`Record<string, boolean>`	optional	Per-granularity native date bucketing (day/week/month/quarter/year). Missing keys fall back to in-memory bucketing.
autonumber	`boolean`	optional	Driver natively generates persistent autonumber/sequence values
batchSchemaSync	`boolean`	optional	Supports batched schema sync to reduce schema DDL round-trips (absence = false)
create	`never`	optional	[REMOVED] `DriverCapabilities.create` was removed in @objectstack/spec 17.0.0 (ADR-0049 enforce-or-remove) — no code in any repository ever read it, so its value never changed which code path ran. CRUD is not optional for a driver: `create`/`find`/`findOne`/`update`/`delete` are REQUIRED `IDataDriver` methods and the engine calls them unconditionally. Delete the key.
read	`never`	optional	[REMOVED] `DriverCapabilities.read` was removed in @objectstack/spec 17.0.0 (ADR-0049 enforce-or-remove) — no code in any repository ever read it, so its value never changed which code path ran. CRUD is not optional for a driver: reads go through the REQUIRED `find`/`findOne`/`count` methods, called unconditionally. Delete the key.
update	`never`	optional	[REMOVED] `DriverCapabilities.update` was removed in @objectstack/spec 17.0.0 (ADR-0049 enforce-or-remove) — no code in any repository ever read it, so its value never changed which code path ran. CRUD is not optional for a driver: `update`/`upsert` are REQUIRED `IDataDriver` methods, called unconditionally. Delete the key.
delete	`never`	optional	[REMOVED] `DriverCapabilities.delete` was removed in @objectstack/spec 17.0.0 (ADR-0049 enforce-or-remove) — no code in any repository ever read it, so its value never changed which code path ran. CRUD is not optional for a driver: `delete` is a REQUIRED `IDataDriver` method, called unconditionally. Delete the key.
bulkCreate	`never`	optional	[REMOVED] `DriverCapabilities.bulkCreate` was removed in @objectstack/spec 17.0.0 (ADR-0049 enforce-or-remove) — no code in any repository ever read it, so its value never changed which code path ran. The bulk methods (`bulkCreate`/`bulkUpdate`/`bulkDelete`) are REQUIRED `IDataDriver` methods and the engine calls them directly; wire-level batch capability is advertised by REST discovery from the live composition (#3298), never from this record. Delete the key.
bulkUpdate	`never`	optional	[REMOVED] `DriverCapabilities.bulkUpdate` was removed in @objectstack/spec 17.0.0 (ADR-0049 enforce-or-remove) — no code in any repository ever read it, so its value never changed which code path ran. The bulk methods are REQUIRED `IDataDriver` methods and the engine calls them directly; wire-level batch capability is advertised by REST discovery from the live composition (#3298), never from this record. Delete the key.
bulkDelete	`never`	optional	[REMOVED] `DriverCapabilities.bulkDelete` was removed in @objectstack/spec 17.0.0 (ADR-0049 enforce-or-remove) — no code in any repository ever read it, so its value never changed which code path ran. The bulk methods are REQUIRED `IDataDriver` methods and the engine calls them directly; wire-level batch capability is advertised by REST discovery from the live composition (#3298), never from this record. Delete the key.
transactions	`never`	optional	[REMOVED] `DriverCapabilities.transactions` was removed in @objectstack/spec 17.0.0 (ADR-0049 enforce-or-remove) — no code in any repository ever read it, so its value never changed which code path ran. Transaction use is gated on METHOD PRESENCE — `driver.beginTransaction` (`engine.transaction()`, ADR-0034 ambient transactions): a driver without the method gets the non-transactional fallback, whatever this bit claimed. Discovery's `transactionalBatch` capability is likewise derived from `engine.transaction` plus the mounted batch route, never from this bit. Delete the key.
savepoints	`never`	optional	[REMOVED] `DriverCapabilities.savepoints` was removed in @objectstack/spec 17.0.0 (ADR-0049 enforce-or-remove) — no code in any repository ever read it, so its value never changed which code path ran. No savepoint code path exists in the engine — a capability bit for a feature the platform does not call is a false affordance, not documentation. Delete the key.
isolationLevels	`never`	optional	[REMOVED] `DriverCapabilities.isolationLevels` was removed in @objectstack/spec 17.0.0 (ADR-0049 enforce-or-remove) — no code in any repository ever read it, so its value never changed which code path ran. Isolation is requested per transaction via `beginTransaction({ isolationLevel })`; no planner ever consulted this list to decide anything. Delete the key.
queryFilters	`never`	optional	[REMOVED] `DriverCapabilities.queryFilters` was removed in @objectstack/spec 17.0.0 (ADR-0049 enforce-or-remove) — no code in any repository ever read it, so its value never changed which code path ran. `find()` receives the full QueryAST (`where`/`orderBy`/`limit`/`offset`) and MUST execute all of it — the "ObjectQL will filter in memory" fallback this bit's description promised was never built. Delete the key.
querySorting	`never`	optional	[REMOVED] `DriverCapabilities.querySorting` was removed in @objectstack/spec 17.0.0 (ADR-0049 enforce-or-remove) — no code in any repository ever read it, so its value never changed which code path ran. `find()` receives the full QueryAST and MUST execute all of it — the "ObjectQL will sort in memory" fallback this bit's description promised was never built. Delete the key.
queryPagination	`never`	optional	[REMOVED] `DriverCapabilities.queryPagination` was removed in @objectstack/spec 17.0.0 (ADR-0049 enforce-or-remove) — no code in any repository ever read it, so its value never changed which code path ran. `find()` receives the full QueryAST and MUST execute all of it — the "ObjectQL will paginate in memory" fallback this bit's description promised was never built. Delete the key.
queryAggregations	`never`	optional	[REMOVED] `DriverCapabilities.queryAggregations` was removed in @objectstack/spec 17.0.0 (ADR-0049 enforce-or-remove) — no code in any repository ever read it, so its value never changed which code path ran. Aggregate pushdown is decided by `typeof driver.aggregate === 'function'` plus `queryDateGranularity` (engine aggregate dispatch) — never by this bit. Delete the key.
queryWindowFunctions	`never`	optional	[REMOVED] `DriverCapabilities.queryWindowFunctions` was removed in @objectstack/spec 17.0.0 (ADR-0049 enforce-or-remove) — no code in any repository ever read it, so its value never changed which code path ran. ObjectQL never plans window functions through a driver, so there was nothing for the bit to switch on. Delete the key.
querySubqueries	`never`	optional	[REMOVED] `DriverCapabilities.querySubqueries` was removed in @objectstack/spec 17.0.0 (ADR-0049 enforce-or-remove) — no code in any repository ever read it, so its value never changed which code path ran. ObjectQL never plans subqueries through a driver, so there was nothing for the bit to switch on. Delete the key.
queryCTE	`never`	optional	[REMOVED] `DriverCapabilities.queryCTE` was removed in @objectstack/spec 17.0.0 (ADR-0049 enforce-or-remove) — no code in any repository ever read it, so its value never changed which code path ran. ObjectQL never plans Common Table Expressions through a driver, so there was nothing for the bit to switch on. Delete the key.
joins	`never`	optional	[REMOVED] `DriverCapabilities.joins` was removed in @objectstack/spec 17.0.0 (ADR-0049 enforce-or-remove) — no code in any repository ever read it, so its value never changed which code path ran. Related data is resolved by the engine (lookup expansion over `find()`), not by driver-side JOIN planning — no code consulted the bit. Delete the key.
fullTextSearch	`never`	optional	[REMOVED] `DriverCapabilities.fullTextSearch` was removed in @objectstack/spec 17.0.0 (ADR-0049 enforce-or-remove) — no code in any repository ever read it, so its value never changed which code path ran. `$search` is compiled by the engine into an `$or` of `$contains` predicates over the searchable fields (ADR-0061) and removed from the AST before the driver sees it — no driver-side full-text path exists. Delete the key.
jsonQuery	`never`	optional	[REMOVED] `DriverCapabilities.jsonQuery` was removed in @objectstack/spec 17.0.0 (ADR-0049 enforce-or-remove) — no code in any repository ever read it, so its value never changed which code path ran. No engine path ever branched on driver-side JSON querying. Delete the key.
geospatialQuery	`never`	optional	[REMOVED] `DriverCapabilities.geospatialQuery` was removed in @objectstack/spec 17.0.0 (ADR-0049 enforce-or-remove) — no code in any repository ever read it, so its value never changed which code path ran. No geospatial query path exists in the platform — declaring the bit advertised a capability nothing delivers. Delete the key.
streaming	`never`	optional	[REMOVED] `DriverCapabilities.streaming` was removed in @objectstack/spec 17.0.0 (ADR-0049 enforce-or-remove) — no code in any repository ever read it, and `findStream`, the only read this bit could describe, was itself removed in 17.0.0: nothing ever called it, and two of its three implementations materialised the entire result set before yielding. The bit carried the same defect one level up (`SqlDriver` implemented `findStream` yet declared `streaming: false`; `InMemoryDriver` declared `true` over a full-table read) — which is what zero readers makes inevitable. Page large reads through `find()` with `limit`/`offset`. Delete the key.
jsonFields	`never`	optional	[REMOVED] `DriverCapabilities.jsonFields` was removed in @objectstack/spec 17.0.0 (ADR-0049 enforce-or-remove) — no code in any repository ever read it, so its value never changed which code path ran. Field-type handling is negotiated per object at `syncSchema` time by the driver itself (e.g. `SqlDriver`'s per-object JSON/date column tracking); no engine path consulted the bit. Delete the key.
arrayFields	`never`	optional	[REMOVED] `DriverCapabilities.arrayFields` was removed in @objectstack/spec 17.0.0 (ADR-0049 enforce-or-remove) — no code in any repository ever read it, so its value never changed which code path ran. Field-type handling is negotiated per object at `syncSchema` time by the driver itself; no engine path consulted the bit. Delete the key.
vectorSearch	`never`	optional	[REMOVED] `DriverCapabilities.vectorSearch` was removed in @objectstack/spec 17.0.0 (ADR-0049 enforce-or-remove) — no code in any repository ever read it, so its value never changed which code path ran. No vector read path routes through `IDataDriver`. When one exists it should arrive WITH its caller and its capability bit together (the honest order under enforce-or-remove), not as a dangling boolean. Delete the key.
schemaSync	`never`	optional	[REMOVED] `DriverCapabilities.schemaSync` was removed in @objectstack/spec 17.0.0 (ADR-0049 enforce-or-remove) — no code in any repository ever read it, so its value never changed which code path ran. Schema sync is gated on METHOD PRESENCE — `typeof driver.syncSchema === 'function'` (engine and ObjectQL plugin init). Delete the key.
migrations	`never`	optional	[REMOVED] `DriverCapabilities.migrations` was removed in @objectstack/spec 17.0.0 (ADR-0049 enforce-or-remove) — no code in any repository ever read it, so its value never changed which code path ran. No migration engine ever consulted it. Delete the key.
indexes	`never`	optional	[REMOVED] `DriverCapabilities.indexes` was removed in @objectstack/spec 17.0.0 (ADR-0049 enforce-or-remove) — no code in any repository ever read it, so its value never changed which code path ran. Declared indexes are materialised by the driver itself during schema sync (`SqlDriver.syncDeclaredIndexes`); no engine path consulted the bit. Delete the key.
connectionPooling	`never`	optional	[REMOVED] `DriverCapabilities.connectionPooling` was removed in @objectstack/spec 17.0.0 (ADR-0049 enforce-or-remove) — no code in any repository ever read it, so its value never changed which code path ran. Pooling is configured via `poolConfig` and owned by the driver; `getPoolStats` is duck-typed where monitoring wants it. Nothing consulted the bit. Delete the key.
preparedStatements	`never`	optional	[REMOVED] `DriverCapabilities.preparedStatements` was removed in @objectstack/spec 17.0.0 (ADR-0049 enforce-or-remove) — no code in any repository ever read it, so its value never changed which code path ran. Parameterised execution is an implementation detail of the driver (`execute(command, parameters)`); nothing consulted the bit. Delete the key.
queryCache	`never`	optional	[REMOVED] `DriverCapabilities.queryCache` was removed in @objectstack/spec 17.0.0 (ADR-0049 enforce-or-remove) — no code in any repository ever read it, so its value never changed which code path ran. No query-cache layer keyed off it exists; `DriverOptions.skipCache` is a per-call hint to the driver, not a switch on this bit. Delete the key.

Nested Shape: `NoSQLDriverConfig.poolConfig`

Property	Type	Required	Description
min	`number`	optional (default: `2`)	Minimum number of connections in pool
max	`number`	optional (default: `10`)	Maximum number of connections in pool
idleTimeoutMillis	`number`	optional (default: `30000`)	Time in ms before idle connection is closed
connectionTimeoutMillis	`number`	optional (default: `5000`)	Time in ms to wait for available connection

Nested Shape: `NoSQLDriverConfig.dataTypeMapping`

Property	Type	Required	Description
text	`string`	✅	NoSQL type for text fields
number	`string`	✅	NoSQL type for number fields
boolean	`string`	✅	NoSQL type for boolean fields
date	`string`	✅	NoSQL type for date fields
datetime	`string`	✅	NoSQL type for datetime fields
json	`string`	optional	NoSQL type for JSON/object fields
uuid	`string`	optional	NoSQL type for UUID fields
binary	`string`	optional	NoSQL type for binary fields
array	`string`	optional	NoSQL type for array fields
objectId	`string`	optional	NoSQL type for ObjectID fields (MongoDB)
geopoint	`string`	optional	NoSQL type for geospatial point fields

Nested Shape: `NoSQLDriverConfig.replication`

Property	Type	Required	Description
enabled	`boolean`	optional (default: `false`)	Enable replication
replicaSetName	`string`	optional	Replica set name
replicas	`integer`	optional	Number of replicas
readPreference	`Enum<'primary' \| 'primaryPreferred' \| 'secondary' \| 'secondaryPreferred' \| 'nearest'>`	optional	Read preference for replica set
writeConcern	`Enum<'majority' \| 'acknowledged' \| 'unacknowledged'>`	optional	Write concern level

Nested Shape: `NoSQLDriverConfig.sharding`

Property	Type	Required	Description
enabled	`boolean`	optional (default: `false`)	Enable sharding
shardKey	`string`	optional	Field to use as shard key
shardingStrategy	`Enum<'hash' \| 'range' \| 'zone'>`	optional	Sharding strategy
numShards	`integer`	optional	Number of shards

Nested Shape: `NoSQLDriverConfig.schemaValidation`

Property	Type	Required	Description
enabled	`boolean`	optional (default: `false`)	Enable schema validation
validationLevel	`Enum<'strict' \| 'moderate' \| 'off'>`	optional	Validation strictness
validationAction	`Enum<'error' \| 'warn'>`	optional	Action on validation failure
jsonSchema	`Record<string, any>`	optional	JSON Schema for validation

NoSQLIndex

Properties

Property	Type	Required	Description
name	`string`	✅	Index name
type	`Enum<'single' \| 'compound' \| 'unique' \| 'text' \| 'geospatial' \| 'hashed' \| 'ttl' \| 'sparse'>`	✅	Index type
fields	`{ field: string; order?: Enum<'asc' \| 'desc' \| 'text' \| '2dsphere'> }[]`	✅	Fields to index
unique	`boolean`	optional (default: `false`)	Enforce uniqueness over exactly the listed `fields`. Boolean on purpose — no ADR-0120 scope vocabulary here: this is the raw driver-descriptor layer, below tenancy. The 'organization'/'global' boundary is stated on the authorable surfaces (FieldSchema.unique, IndexSchema.unique) and resolved into physical key columns before a descriptor like this is built, so an organization key part, when there is one, is already a listed field
sparse	`boolean`	optional (default: `false`)	Sparse index
expireAfterSeconds	`integer`	optional	TTL in seconds
partialFilterExpression	`Record<string, any>`	optional	Partial index filter
background	`boolean`	optional (default: `false`)	Create index in background

Nested Shape: `NoSQLIndex.fields[number]`

Property	Type	Required	Description
field	`string`	✅	Field name
order	`Enum<'asc' \| 'desc' \| 'text' \| '2dsphere'>`	optional	Index order or type

NoSQLIndexType

Allowed Values

single
compound
unique
text
geospatial
hashed
ttl
sparse

NoSQLOperationType

Allowed Values

find
findOne
insert
update
delete
aggregate
mapReduce
count
distinct
createIndex
dropIndex

NoSQLQueryOptions

Properties

Property	Type	Required	Description
consistency	`Enum<'all' \| 'quorum' \| 'one' \| 'local_quorum' \| 'each_quorum' \| 'eventual'>`	optional	Consistency level override
readFromSecondary	`boolean`	optional	Allow reading from secondary replicas
projection	`Record<string, 0 \| 1>`	optional	Field projection
timeout	`integer`	optional	Query timeout (ms)
useCursor	`boolean`	optional	Use cursor instead of loading all results
batchSize	`integer`	optional	Cursor batch size
profile	`boolean`	optional	Enable query profiling
hint	`string`	optional	Index hint for query optimization

NoSQLTransactionOptions

Properties

Property	Type	Required	Description
readConcern	`Enum<'local' \| 'majority' \| 'linearizable' \| 'snapshot'>`	optional	Read concern level
writeConcern	`Enum<'majority' \| 'acknowledged' \| 'unacknowledged'>`	optional	Write concern level
readPreference	`Enum<'primary' \| 'primaryPreferred' \| 'secondary' \| 'secondaryPreferred' \| 'nearest'>`	optional	Read preference
maxCommitTimeMS	`integer`	optional	Transaction commit timeout (ms)

ReplicationConfig

Properties

Property	Type	Required	Description
enabled	`boolean`	optional (default: `false`)	Enable replication
replicaSetName	`string`	optional	Replica set name
replicas	`integer`	optional	Number of replicas
readPreference	`Enum<'primary' \| 'primaryPreferred' \| 'secondary' \| 'secondaryPreferred' \| 'nearest'>`	optional	Read preference for replica set
writeConcern	`Enum<'majority' \| 'acknowledged' \| 'unacknowledged'>`	optional	Write concern level

ShardingConfig

Properties

Property	Type	Required	Description
enabled	`boolean`	optional (default: `false`)	Enable sharding
shardKey	`string`	optional	Field to use as shard key
shardingStrategy	`Enum<'hash' \| 'range' \| 'zone'>`	optional	Sharding strategy
numShards	`integer`	optional	Number of shards

Driver Nosql

On this page