API 参考索引

本索引记录当前稳定的 MongoDB adapter API 与共享运行时能力。MySQL 与 PostgreSQL adapter API 会在 runtime、公开类型、示例与验证覆盖完成后再进入独立文档入口。

核心概念

文档	说明
原生 API 对比	MongoDB 原生 vs monSQLize 扩展功能对比
快速上手	常用 CRUD、分页、读缓存与 Model 入口示例
完整配置参考	`new MonSQLize(options)` 构造函数完整参数
连接管理	连接生命周期与访问器
连接池配置	多连接池配置与运行时路由：在构造函数中声明 `pools: PoolConfig[]`，通过 `pool()` / `use()` 访问
链式池/库访问	链式池/库访问 API：`pool()` / `use()` / `scopedCollection()` / `scopedModel()`
ObjectId 自动转换	MongoDB 查询和写入路径的 ObjectId 自动转换
Model 层	Model schema 校验、自定义方法、hooks、relations 与 runtime 绑定
Populate API	加载 Model relations 声明的关联文档
Relations API	定义 `hasOne` / `hasMany` / `belongsTo` 风格关系、数组键和默认字段选择
Hooks API	create、update、delete、find 流程的标准 Model 生命周期钩子
Relations 与 Populate	Model 关系定义与关联数据填充
嵌套 Populate	多层关系填充
SSH 隧道	SSH隧道 - 安全连接内网数据库
错误码参考	错误码参考 - 完整的错误码定义和处理指南
缓存系统	缓存系统（LRU + TTL）
事务管理	事务管理（自动重试、缓存锁）
写路径策略	可选的 Model-only 写入命名空间策略
Change Stream 同步	Change Stream 数据同步 - 实时备份到多个数据库
事务优化策略	事务优化策略
分布式部署	分布式部署指南（多实例缓存一致性）
生产发布与迁移	生产数据任务、CDC 同步、索引预检与切流检查
生产数据迁移同步	开发或预发布实例到生产的数据、索引和字段调整场景指南
数据任务 API 参考	单一 `DataTaskJob`、四个方法、参数、备份和恢复契约
事件系统	事件系统

查询操作（Query Operations）

文档	方法	说明
查询多个文档	`find()`	查询多个文档
查询单个文档	`findOne()`	查询单个文档
分页查询	`findPage()`	游标分页查询
统计文档数量	`count()`	统计文档数量
去重查询	`distinct()`	去重查询
监听数据变更	`watch()`	实时监听数据变更（Change Streams）

写入操作（Write Operations）

插入操作

文档	方法	说明
插入单个文档	`insertOne()`	插入单个文档
批量插入文档	`insertMany()`	批量插入文档
大批量插入	`insertBatch()`	大批量插入（分批+重试）
写入操作指南	所有插入方法	插入操作完整指南

更新操作

文档	方法	说明
更新方法总览	所有更新方法	方法选择、传统操作符和聚合管道导读
Upsert 操作指南	Upsert 操作指南	不存在就插入，存在则更新
更新单个文档	`updateOne()`	更新单个文档
批量更新文档	`updateMany()`	批量更新文档
聚合管道更新指南	聚合管道更新	字段间计算、条件赋值和管道细节
大批量更新	`updateBatch()`	大批量更新（分批+重试）
完整替换文档	`replaceOne()`	完整替换文档
查询并更新	`findOneAndUpdate()`	原子更新并返回
查询并替换	`findOneAndReplace()`	原子替换并返回

便利方法（Convenience Methods）

文档	方法	说明
Upsert 单个文档	`upsertOne()`	存在则更新，不存在则插入
递增/递减字段	`incrementOne()`	原子递增/递减字段值

删除操作

文档	方法	说明
删除单个文档	`deleteOne()` / Model 受保护删除	删除单个文档，或基于已声明关系执行 restrict 删除
批量删除文档	`deleteMany()`	批量删除文档
大批量删除	`deleteBatch()`	大批量删除（分批+重试）
查询并删除	`findOneAndDelete()`	原子删除并返回

聚合操作（Aggregation Operations）

文档	方法	说明
聚合管道查询	`aggregate()`	聚合管道查询
向量查询	Collection / Model `vectorSearch()`	MongoDB Vector Search 向量查询；Model 会应用软删除可见性
Search 索引	Collection / Model `createSearchIndex()` 等	创建、查看、更新、删除并等待 Search / Vector Search 索引
GridFS	`msq.gridfs()` / Model `gridfs()`	上传、下载和恢复 GridFS 文件

高级功能

文档	说明
链式调用 API	链式调用 API
链式调用方法详解	链式调用方法详解
查询计划分析	查询计划分析
分页书签管理	分页书签管理

工具与配置

文档	说明
工具函数	工具函数
完整配置参考	构造默认值、缓存、Redis、Model、同步、连接池、日志与校验
集合管理	集合管理
读偏好设置	读偏好设置
Count 队列控制	Count 队列控制
写路径策略	配置写操作可走 collection API，或必须经过 Model API
分布式部署配置	分布式部署配置

兼容性与测试

文档	说明
MongoDB Driver 兼容性	Driver 版本兼容性详解
findOneAnd 返回值	findOneAnd* 返回值统一说明

| ES Module 支持 | ES Module (import) 支持 |

按功能分类

CRUD 操作

Create (创建):

插入单个文档 - insertOne
批量插入文档 - insertMany
大批量插入 - insertBatch
写入操作指南 - 插入操作完整指南

Read (读取):

查询多个文档 - find
查询单个文档 - findOne
分页查询 - findPage
统计文档数量 - count
去重查询 - distinct

Update (更新):

更新方法总览 - 方法选择、传统操作符和聚合管道导读
更新单个文档 - updateOne
批量更新文档 - updateMany
完整替换文档 - replaceOne
查询并更新 - findOneAndUpdate
查询并替换 - findOneAndReplace

Delete (删除):

删除单个文档 - deleteOne
批量删除文档 - deleteMany
查询并删除 - findOneAndDelete

高级查询

聚合管道查询 - 聚合管道
向量查询 - MongoDB Vector Search 向量查询
Search 索引 - Search / Vector Search 索引生命周期
GridFS - GridFS 上传、下载与可恢复上传
查询计划分析 - 查询计划
链式调用 - 链式调用

性能与缓存

缓存系统 - 缓存系统
分页书签 - 分页优化

入口、示例与站点页面

文档	说明
文档目录索引	docs 目录索引
文档站首页	文档站首页
API 参考索引	当前 API 参考索引
安装	安装与最小连接验证
快速上手	第一次连接成功后的常用操作
示例索引	示例索引
场景指南	连接、缓存、Redis、SSH、连接池与 Model 的场景指南
能力索引	能力索引

管理、索引与表达式

文档	说明
管理 API	管理 API
数据库操作	数据库操作
创建单个索引	创建单个索引
批量创建索引	批量创建索引
删除索引	删除索引
列出索引	列出索引
GridFS	GridFS bucket、区间与可恢复上传
查询并计数	查询并计数
表达式函数	表达式函数
快速 upsert	快速 upsert

运行时与部署

文档	说明
运行时一致性与边界	运行时能力边界与一致性契约
生产发布与迁移	索引、一次性数据、CDC 与生产切流 runbook
生产数据迁移同步	一次性筛选数据和索引发布场景
支持矩阵	支持矩阵
路线图边界	路线图边界
验证说明	验证说明

ObjectId、缓存与排障

文档	说明
ObjectId 转换范围	ObjectId 转换范围
ObjectId 跨版本说明	ObjectId 跨版本说明
ObjectId 跨版本 FAQ	ObjectId 跨版本 FAQ
ObjectId 日志优化	ObjectId 日志优化
缓存 API	数据库查询缓存、多层缓存接入、缓存失效与统计
慢查询日志	慢查询日志
故障恢复示例	故障恢复示例
多连接池健康检查	多连接池健康检查
分布式部署速查	分布式部署速查
Relations 快速开始	Relations 快速开始

入门路径

新用户推荐阅读顺序:

安装 - 安装、连接并完成第一次查询
快速上手 - 完成常用 CRUD、分页、缓存和 Model 入口示例
完整配置参考 - 选择服务需要的构造参数
连接管理 - 了解连接生命周期与访问器
查询多个文档 - 学习查询细节
插入单个文档 / 批量插入文档 - 学习插入数据
更新单个文档 / 批量更新文档 - 学习更新数据
删除单个文档 / 批量删除文档 - 学习删除数据
缓存系统 - 了解缓存机制
事务管理 - 学习事务管理
分布式部署 - 多实例部署说明
生产发布与迁移 - 索引、一次性数据、CDC 与切流检查
生产数据迁移同步 - A 实例到生产的配置化发布

#API 参考索引

#核心概念

#查询操作（Query Operations）

#写入操作（Write Operations）

#插入操作

#更新操作

#便利方法（Convenience Methods）

#删除操作

#聚合操作（Aggregation Operations）

#高级功能

#工具与配置

#兼容性与测试

#按功能分类

#CRUD 操作

#高级查询

#性能与缓存

#入口、示例与站点页面

#管理、索引与表达式

#运行时与部署

#ObjectId、缓存与排障

#入门路径