MongoDB

非官方测试版翻译

本页面由 PageTurner AI 翻译（测试版）。未经项目官方认可。发现错误？报告问题 →

MongoDB 支持

TypeORM 提供基础的 MongoDB 支持（要求 Node.js 驱动为 v7 或更高版本）。

TypeORM 的大部分功能专用于关系型数据库，本页面涵盖所有 MongoDB 专属功能。

安装

npm install mongodb

数据源选项

appName - 创建此 MongoClient 实例的应用程序名称。MongoDB 会在每次建立连接时将此值打印到服务器日志中，同时也会记录在慢查询日志和分析集合中。
authMechanism - 设置 MongoDB 用于连接认证的认证机制。
authSource - 指定与用户凭证关联的数据库名称。
autoEncryption - 可选启用使用中自动加密功能。
checkServerIdentity - 验证证书 cert 是否颁发给 hostname。
compressors - 启用网络压缩的压缩器数组或逗号分隔字符串，用于此客户端与 mongod/mongos 实例之间的通信。
connectTimeoutMS - 连接超时前的尝试时间（毫秒）。默认值：30000。
database - 数据库名称。
directConnection - 允许驱动程序强制使用单节点拓扑类型（连接字符串仅包含单个主机时）。
driver - 驱动程序对象。默认为 require("mongodb")。
family - IP 地址族。
forceServerObjectId - 强制服务器分配 _id 值而非驱动程序分配。默认值：false。
host - 数据库主机地址。
hostReplicaSet - 数据库主机副本集。
ignoreUndefined - 指定 BSON 序列化器是否忽略 undefined 字段。默认值：false。
localThresholdMS - 从多个合适 MongoDB 实例中选择时的延迟窗口大小（毫秒）。
maxStalenessSeconds - 指定从节点在客户端停止将其用于读操作前允许的最大陈旧秒数。最小值为 90 秒。
minPoolSize - 连接池的最小连接数。
monitorCommands - 为此客户端启用命令监控。
noDelay - TCP 连接无延迟。
password - 数据库密码。
pkFactory - 用于生成自定义 _id 的主键工厂对象。
poolSize - 连接池的最大连接数。映射到 MongoDB 驱动的 maxPoolSize 选项。
port - 数据库主机端口。MongoDB 默认端口为 27017。
promoteBuffers - 是否将 Binary BSON 值提升为 Node.js 原生 Buffer。默认值：false。
promoteLongs - 当 Long 值在 53 位精度范围内时是否提升为 number 类型。默认值：true。
promoteValues - 尽可能将 BSON 值提升为原生类型，设为 false 则仅接收包装类型。默认值：true。
proxyHost - 配置用于创建 TCP 连接的 Socks5 代理主机。
proxyPassword - 当代理需要用户名/密码认证时，配置 Socks5 代理密码。
proxyPort - 配置用于创建 TCP 连接的 Socks5 代理端口。
proxyUsername - 当代理需要用户名/密码认证时，配置 Socks5 代理用户名。
raw - 是否将文档结果作为原始 BSON 缓冲区返回。默认值：false。
readConcern - 为集合指定读关注级别。
readPreference - 优先使用的读偏好设置：
- ReadPreference.PRIMARY
- ReadPreference.PRIMARY_PREFERRED
- ReadPreference.SECONDARY
- ReadPreference.SECONDARY_PREFERRED
- ReadPreference.NEAREST
readPreferenceTags - 以逗号分隔的键值对（冒号分隔）形式指定标签文档。
replicaSet - 指定副本集名称（当 mongod 是副本集成员时）。
retryWrites - 启用可重试写入。
serializeFunctions - 是否序列化任意对象中的函数。默认值：false。
socketTimeoutMS - 套接字操作超时前的尝试时间（毫秒）。默认值：360000。
tls - 启用或禁用连接的 TLS/SSL。默认值：false。
tlsAllowInvalidCertificates - 绕过 mongod/mongos 实例提供的证书验证。默认值：false。
tlsCAFile - 指定包含证书颁发机构根证书链的本地 .pem 文件路径。
tlsCertificateKeyFile - 指定包含客户端 TLS/SSL 证书和密钥的本地 .pem 文件路径。
tlsCertificateKeyFilePassword - 指定解密 tlsCertificateKeyFile 的密码。
url - 执行连接操作的 URL。请注意，其他数据源选项会覆盖 URL 中设置的参数。
username - 数据库用户名。
writeConcern - MongoDB 写入关注级别，描述写操作请求 MongoDB 返回的确认级别。

可通过 extra 对象添加额外选项，这些选项将直接传递给客户端库。更多信息请参阅 mongodb 文档中的连接选项。

定义实体与列

定义实体和列的方式与关系型数据库几乎相同，主要区别在于必须使用 @ObjectIdColumn 替代 @PrimaryColumn 或 @PrimaryGeneratedColumn。

简单实体示例：

import { ObjectId } from "mongodb"
import { Entity, ObjectIdColumn, Column } from "typeorm"

@Entity()
export class User {
    @ObjectIdColumn()
    _id: ObjectId

    @Column()
    firstName: string

    @Column()
    lastName: string
}

应用启动方式如下：

import { DataSource } from "typeorm"

const myDataSource = new DataSource({
    type: "mongodb",
    host: "localhost",
    port: 27017,
    database: "test",
})

定义子文档（嵌入式文档）

由于 MongoDB 支持对象嵌套（即文档内嵌文档），在 TypeORM 中也可实现同样功能：

import { ObjectId } from "mongodb"
import { Entity, ObjectIdColumn, Column } from "typeorm"

export class Profile {
    @Column()
    about: string

    @Column()
    education: string

    @Column()
    career: string
}

import { ObjectId } from "mongodb"
import { Entity, ObjectIdColumn, Column } from "typeorm"

export class Photo {
    @Column()
    url: string

    @Column()
    description: string

    @Column()
    size: number

    constructor(url: string, description: string, size: number) {
        this.url = url
        this.description = description
        this.size = size
    }
}

import { Entity, ObjectId, ObjectIdColumn, Column } from "typeorm"

@Entity()
export class User {
    @ObjectIdColumn()
    id: ObjectId

    @Column()
    firstName: string

    @Column()
    lastName: string

    @Column((type) => Profile)
    profile: Profile

    @Column((type) => Photo)
    photos: Photo[]
}

保存此实体后：

const user = new User()
user.firstName = "Timber"
user.lastName = "Saw"
user.profile = new Profile()
user.profile.about = "About Trees and Me"
user.profile.education = "Tree School"
user.profile.career = "Lumberjack"
user.photos = [
    new Photo("me-and-trees.jpg", "Me and Trees", 100),
    new Photo("me-and-chakram.jpg", "Me and Chakram", 200),
]

await myDataSource.manager.save(user)

数据库中将存储以下文档：

{
    "firstName": "Timber",
    "lastName": "Saw",
    "profile": {
        "about": "About Trees and Me",
        "education": "Tree School",
        "career": "Lumberjack"
    },
    "photos": [
        {
            "url": "me-and-trees.jpg",
            "description": "Me and Trees",
            "size": 100
        },
        {
            "url": "me-and-chakram.jpg",
            "description": "Me and Chakram",
            "size": 200
        }
    ]
}

使用 `MongoEntityManager` 与 `MongoRepository`

除特定于关系型数据库的方法（如 query 和 transaction）外，您可使用 EntityManager 中的大多数方法，例如：

const timber = await myDataSource.manager.findOneBy(User, {
    firstName: "Timber",
    lastName: "Saw",
})

针对 MongoDB 还提供了扩展自 EntityManager 的独立 MongoEntityManager。

const timber = await myDataSource.manager.findOneBy(User, {
    firstName: "Timber",
    lastName: "Saw",
})

就像独立的 MongoEntityManager 一样，也存在一个扩展自 Repository 的 MongoRepository：

const timber = await myDataSource.getMongoRepository(User).findOneBy({
    firstName: "Timber",
    lastName: "Saw",
})

在 find() 中使用高级选项：

等于：

const timber = await myDataSource.getMongoRepository(User).find({
    where: {
        firstName: { $eq: "Timber" },
    },
})

小于：

const timber = await myDataSource.getMongoRepository(User).find({
    where: {
        age: { $lt: 60 },
    },
})

包含：

const timber = await myDataSource.getMongoRepository(User).find({
    where: {
        firstName: { $in: ["Timber", "Zhang"] },
    },
})

排除：

const timber = await myDataSource.getMongoRepository(User).find({
    where: {
        firstName: { $not: { $in: ["Timber", "Zhang"] } },
    },
})

或：

const timber = await myDataSource.getMongoRepository(User).find({
    where: {
        $or: [{ firstName: "Timber" }, { firstName: "Zhang" }],
    },
})

查询子文档

const users = await myDataSource.getMongoRepository(User).find({
    where: {
        "profile.education": { $eq: "Tree School" },
    },
})

查询子文档数组

// Query users with photos of size less than 500
const users = await myDataSource.getMongoRepository(User).find({
    where: {
        "photos.size": { $lt: 500 },
    },
})

MongoEntityManager 和 MongoRepository 均包含大量 MongoDB 专属实用方法：

`createCursor`

为查询创建游标，用于遍历 MongoDB 返回的结果集。

`createEntityCursor`

为查询创建游标（返回经过修改的版本），将每个结果转换为实体模型。

`aggregate`

对集合执行聚合管道操作。

`bulkWrite`

执行批量写入操作（非流式 API）。

`count`

统计数据库中匹配查询条件的文档数量。

`countDocuments`

统计数据库中匹配查询条件的文档数量。

`createCollectionIndex`

在数据库集合上创建索引。

`createCollectionIndexes`

在集合中创建多个索引。索引规范定义见 createIndexes。

`deleteMany`

删除 MongoDB 中的多个文档。

`deleteOne`

删除 MongoDB 中的单个文档。

`distinct`

distinct 命令返回集合中指定键的所有不重复值列表。

`dropCollectionIndex`

从当前集合中删除指定索引。

`dropCollectionIndexes`

删除集合中的所有索引。

`findOneAndDelete`

以原子操作方式查找并删除文档，该操作期间需要持有写入锁。

`findOneAndReplace`

以原子操作方式查找并替换文档，该操作期间需要持有写入锁。

`findOneAndUpdate`

以原子操作方式查找并更新文档，该操作期间需要持有写入锁。

`geoHaystackSearch`

使用集合的地理草堆索引执行地理空间搜索。

`geoNear`

执行 geoNear 命令在集合中搜索项目。

`group`

对整个集合执行分组命令。

`collectionIndexes`

获取集合的所有索引信息。

`collectionIndexExists`

检查集合上是否存在指定索引。

`collectionIndexInformation`

获取当前集合的索引信息。

`initializeOrderedBulkOp`

初始化有序批量写入操作：操作将按添加顺序串行执行，每种操作类型变化时会创建新操作。

`initializeUnorderedBulkOp`

初始化无序批量写入操作：所有操作将被缓冲为插入/更新/删除命令，以乱序方式执行。

`insertMany`

向 MongoDB 中插入多个文档组成的数组。

`insertOne`

向 MongoDB 中插入单个文档。

`isCapped`

判断当前集合是否为固定大小集合（capped collection）。

`listCollectionIndexes`

获取集合所有索引的详细信息列表。

`parallelCollectionScan`

返回多个并行游标以支持全集合并行读取，返回结果不保证顺序。

`reIndex`

重建集合所有索引（警告：reIndex 是阻塞操作，索引将在前台重建，大集合操作缓慢）。

`rename`

重命名现有集合。

`replaceOne`

替换 MongoDB 中的单个文档。

`updateMany`

根据筛选条件更新集合中的多个文档。

`updateOne`

根据筛选条件更新集合中的单个文档。

MongoDB 支持​

安装​

数据源选项​

定义实体与列​

定义子文档（嵌入式文档）​

使用 MongoEntityManager 与 MongoRepository​

createCursor​

createEntityCursor​

aggregate​

bulkWrite​

count​

countDocuments​

createCollectionIndex​

createCollectionIndexes​

deleteMany​

deleteOne​

distinct​

dropCollectionIndex​

dropCollectionIndexes​

findOneAndDelete​

findOneAndReplace​

findOneAndUpdate​

geoHaystackSearch​

geoNear​

group​

collectionIndexes​

collectionIndexExists​

collectionIndexInformation​

initializeOrderedBulkOp​

initializeUnorderedBulkOp​

insertMany​

insertOne​

isCapped​

listCollectionIndexes​

parallelCollectionScan​

reIndex​

rename​

replaceOne​

updateMany​

updateOne​