API reference

Entrypoints

Model inventory

Reads: getById, findByIdWithMeta, getWithCas, findMany, findOne, exists, count, page. Writes: insert, prepareInsert, upsert, replaceById, prepareReplace, replaceIfCas, patchById, incrementById, mutateById, deleteById, consumeOnce. Soft deletion: softDeleteById, restoreById, withDeleted, onlyDeleted, withoutDefaultWhere. Hydration: findDocById, findDocOne, hydrate. SQL++: queryRows, queryOne, queryPage, bucket, keyspace, from. Indexes: indexStatements, instance/static ensureIndexes. Low-level: getCollection, parse, parseProjection, serialize, serializeField.

findMany defaults to 10 rows/page 0; findOne forces limit 1. throwOnError:false converts query failures to an empty/null/false/zero result. count and exists reject includes. Key-value getById throws SDK not-found, while findOne returns null. findByIdWithMeta/getWithCas return {content,cas,expiryTime?}. A model page returns {items,hasNext,pageInfo} with limit, page, offset, and nullable nextPage/nextOffset.

Client inventory

Lifecycle: ready, shutdown, getConnection. Registry/keyspace: model, registerModel, definitions, keyspace. Collections: planCollections, ensureCollections, combined provision. GSI: planIndexes, applyIndexPlan, ensureIndexes. Search: search, planSearchIndexes, applySearchIndexPlan. Other: geo, transaction, eventing.

planCollections reports create/matching targets. provision({collections?,indexes?,waitForIndexes?}) returns collection results and index statements. Registration provisions only with an explicit provision option. keyspace(definition) renders the client bucket plus the definition target without connecting, provisioning, or requiring registration. getConnection() exposes the client-bound connection.

Transactions and scoped views

CouchsetTransaction provides model(definition) and attempt-bound query(statement, options) -> {rows}. TransactionModel provides nullable get/getById, insert(id,data), replace(document,data), replaceById(id,data), remove(document), and query. Pass the returned transaction document to replace/remove. tx.model(definition) binds and registers through its owning client on demand, but never provisions; the target resources must already exist.

ScopedModel provides chainable named scopes, inspect() (a copied composed argument object), findMany, findOne, page, exists, and count. It forwards withDeleted, onlyDeleted, and withoutDefaultWhere while retaining scope predicates.

Composition and helpers

• defineModel, defineModelPlugin, dateCodec
• withModelValidator, ModelValidationError, ModelAfterHookError
• joinField, withModelScopes, ScopedModel, withModelMethods, withDocumentMethods
• bulkMap, withModelBulk
• ModelGeo (withinBox, withinRadius), geoPoint, geoBounds, geoRadiusKm, radiusBounds
• ModelSearch (query, match, vector, withinRadius, withinBox, withinPolygon, shape), buildModelSearchIndex
• Eventing (definitions, register, define, physicalName, plan, apply, pause, remove), createEventing, createEventingWithManager, defineEventingFunction
• createCouchsetTestFixture; TimeSeriesModel (chunkId, buildChunk, appendChunk, rangeQuery, range, queryRows); intervalToMilliseconds

Modern runtime exports also include couchset, couchsetServerless, ready, ping, health, shutdown, ensureIndexes, CouchbaseConnection, startCouchbase, startCouchbaseServerless, parseDatabaseUrl, getConnectionOptions, connectionOptions, QueryBuilder, selectBuilder, buildSelectExpr, buildWhereClauseExpr, buildIndexExpr, buildSelectArrayExpr, the exported query exception classes/dictionaries, parseStringSelectExpr, escapeReservedWords, CustomQuery, Pagination, createUpdate, TimeSeriesModel, and intervalToMilliseconds.

Type-only exports cover model/read/query/include/index/TTL/connection/pagination/search/geo/plugin/hook/instrumentation/Eventing/transaction/time-series contracts; they do not exist at runtime. Helpers used internally by the client—such as its UUID, keyspace, index, and raw where builders—are not package-root exports. Lower-level public builders do not automatically apply model filters, codecs, validation, hooks, or authorization.

Key returns

• Model page: {items, hasNext, pageInfo:{limit,page,offset,nextPage,nextOffset}}
• Raw query page: {items, hasNext, params}
• CAS read: {content, cas, expiryTime?}
• Consume: {status:'consumed'|'missing'|'conflict'}
• Bulk item: {index,status:'fulfilled',value} / {index,status:'rejected',error} / {index,status:'skipped'}

SDK options/results retain Couchbase SDK types. Refer to that SDK for durability, timeout, consistency, mutation token, Search, and transaction option details.