仓库 API

[仓库 API](#仓库 API)
- [Repository API](#Repository API)
  - 额外选项
- [TreeRepository API](#TreeRepository API)
- [MongoRepository API](#MongoRepository API)

`Repository` API

manager - 由此仓库使用的 EntityManager。

const manager = repository.manager

metadata - 由此仓库管理的实体的 EntityMetadata。了解更多关于实体元数据中的事务。

const metadata = repository.metadata

queryRunner - EntityManager 使用的查询运行器。仅在 EntityManager 的事务实例中使用。

const queryRunner = repository.queryRunner

target - 由此仓库管理的目标实体类。仅在 EntityManager 的事务实例中使用。

const target = repository.target

createQueryBuilder - 创建用于构建 SQL 查询的查询构建器。了解更多关于查询构建器。

const users = await repository
    .createQueryBuilder("user")
    .where("user.name = :name", { name: "John" })
    .getMany()

hasId - 检查给定实体的主列属性是否已定义。

if (repository.hasId(user)) {
    // ... 做些事情
}

getId - 获取给定实体的主列属性值。如果实体具有复合主键，则返回值将是一个具有主列名称和值的对象。

const userId = repository.getId(user) // userId === 1

create - 创建 User 的新实例。可选地接受一个对象字面量，其中包含将写入新创建的用户对象的用户属性。

const user = repository.create() // 相当于 const user = new User();
const user = repository.create({
    id: 1,
    firstName: "Timber",
    lastName: "Saw",
}) // 相当于 const user = new User(); user.firstName = "Timber"; user.lastName = "Saw";

merge - 将多个实体合并为单个实体。

const user = new User()
repository.merge(user, { firstName: "Timber" }, { lastName: "Saw" }) // 相当于 user.firstName = "Timber"; user.lastName = "Saw";

preload - 从给定的普通 JavaScript 对象创建一个新实体。如果实体已存在于数据库中，则会加载它（以及与之相关的所有内容），用给定对象的新值替换所有值，并返回新实体。新实体实际上是从数据库加载的实体，其中的所有属性都替换为新对象的属性。注意，给定的实体对象必须具有实体 id / 主键才能找到实体。如果找不到具有给定 id 的实体，则返回 undefined。

const partialUser = {
    id: 1,
    firstName: "Rizzrak",
    profile: {
        id: 1,
    },
}
const user = await repository.preload(partialUser)
// user 将包含来自 partialUser 的所有缺失数据，与 partialUser 属性值相同：
// { id: 1, firstName: "Rizzrak", lastName: "Saw", profile: { id: 1, ... } }

save - 保存给定的实体或实体数组。如果实体已存在于数据库中，则进行更新。如果实体在数据库中不存在，则进行插入。它将所有给定的实体保存在单个事务中（对于实体而言，管理器不是事务性的）。还支持部分更新，因为所有未定义的属性将被跳过。返回保存的实体/实体数组。

await repository.save(user)
await repository.save([category1, category2, category3])

remove - 删除给定的实体或实体数组。它将所有给定的实体在单个事务中删除（对于实体而言，管理器不是事务性的）。返回删除的实体/实体数组。

await repository.remove(user)
await repository.remove([category1, category2, category3])

insert - 插入新实体或实体数组。

await repository.insert({
    firstName: "Timber",
    lastName: "Timber",
})

await repository.insert([
    {
        firstName: "Foo",
        lastName: "Bar",
    },
    {
        firstName: "Rizz",
        lastName: "Rak",
    },
])

update - 根据给定的更新选项或实体 ID 部分更新实体。

await repository.update({ age: 18 }, { category: "ADULT" })
// 执行 UPDATE user SET category = ADULT WHERE age = 18

await repository.update(1, { firstName: "Rizzrak" })
// 执行 UPDATE user SET firstName = Rizzrak WHERE id = 1

upsert - 插入新实体或实体数组，除非它们已经存在，否则将更新它们。支持 AuroraDataApi、Cockroach、Mysql、Postgres 和 Sqlite 数据库驱动程序。

await repository.upsert(
    [
        { externalId: "abc123", firstName: "Rizzrak" },
        { externalId: "bca321", firstName: "Karzzir" },
    ],
    ["externalId"],
)
/** 执行
 *  INSERT INTO user
 *  VALUES
 *      (externalId = abc123, firstName = Rizzrak),
 *      (externalId = cba321, firstName = Karzzir),
 *  ON CONFLICT (externalId) DO UPDATE SET firstName = EXCLUDED.firstName
 **/

await repository.upsert(
    [
        { externalId: "abc123", firstName: "Rizzrak" },
        { externalId: "bca321", firstName: "Karzzir" },
    ],
    {
        conflictPaths: ["externalId"],
        skipUpdateIfNoValuesChanged: true, // 支持 postgres，如果更新不会改变行值，则跳过更新
        upsertType: "upsert", // "on-conflict-do-update" | "on-duplicate-key-update" | "upsert" - 可选择提供 UpsertType，"upsert" 目前只支持 CockroachDB
    },
)
/** 执行
 *  INSERT INTO user
 *  VALUES
 *      (externalId = abc123, firstName = Rizzrak),
 *      (externalId = cba321, firstName = Karzzir),
 *  ON CONFLICT (externalId) DO UPDATE
 *  SET firstName = EXCLUDED.firstName
 *  WHERE user.firstName IS DISTINCT FROM EXCLUDED.firstName
 **/

await repository.upsert(
    [
        { externalId: "abc123", firstName: "Rizzrak", dateAdded: "2020-01-01" },
        { externalId: "bca321", firstName: "Karzzir", dateAdded: "2022-01-01" },
    ],
    {
        conflictPaths: ["externalId"],
        skipUpdateIfNoValuesChanged: true, // 支持 postgres，如果更新不会改变行值，则跳过更新
        indexPredicate: "dateAdded > 2020-01-01", // 支持 postgres，允许部分索引
    },
)
/** 执行
 *  INSERT INTO user
 *  VALUES
 *      (externalId = abc123, firstName = Rizzrak, dateAdded = 2020-01-01),
 *      (externalId = cba321, firstName = Karzzir, dateAdded = 2022-01-01),
 *  ON CONFLICT (externalId) WHERE ( dateAdded > 2021-01-01 ) DO UPDATE
 *  SET firstName = EXCLUDED.firstName,
 *  SET dateAdded = EXCLUDED.dateAdded,
 *  WHERE user.firstName IS DISTINCT FROM EXCLUDED.firstName OR user.dateAdded IS DISTINCT FROM EXCLUDED.dateAdded
 **/

delete - 根据实体 ID、ID 数组或给定条件删除实体：

await repository.delete(1)
await repository.delete([1, 2, 3])
await repository.delete({ firstName: "Timber" })

softDelete 和 restore - 通过 ID 对行进行软删除和还原

const repository = dataSource.getRepository(Entity)
// 删除实体
await repository.softDelete(1)
// 使用 restore 可以还原它;
await repository.restore(1)

softRemove 和 recover - 这是 softDelete 和 restore 的替代方法。

// 使用 softRemove 可以进行软删除
const entities = await repository.find()
const entitiesAfterSoftRemove = await repository.softRemove(entities)

// 使用 recover 可以恢复它们
await repository.recover(entitiesAfterSoftRemove)

increment - 通过给定的值增加符合条件的实体的某一列。

await repository.increment({ firstName: "Timber" }, "age", 3)

decrement - 通过给定的值减少符合条件的实体的某一列。

await repository.decrement({ firstName: "Timber" }, "age", 3)

count - 统计符合 FindOptions 的实体数量。用于分页。

const count = await repository.count({
    where: {
        firstName: "Timber",
    },
})

countBy - 统计符合 FindOptionsWhere 的实体数量。用于分页。

const count = await repository.countBy({ firstName: "Timber" })

sum - 返回符合 FindOptionsWhere 的所有实体的某一数字字段的总和。

const sum = await repository.sum("age", { firstName: "Timber" })

average - 返回符合 FindOptionsWhere 的所有实体的某一数字字段的平均值。

const average = await repository.average("age", { firstName: "Timber" })

minimum - 返回符合 FindOptionsWhere 的所有实体的某一数字字段的最小值。

const minimum = await repository.minimum("age", { firstName: "Timber" })

maximum - 返回符合 FindOptionsWhere 的所有实体的某一数字字段的最大值。

const maximum = await repository.maximum("age", { firstName: "Timber" })

find - 查找与给定的 FindOptions 匹配的实体。

const timbers = await repository.find({
    where: {
        firstName: "Timber",
    },
})

findBy - 查找与给定的 FindWhereOptions 匹配的实体。

const timbers = await repository.findBy({
    firstName: "Timber",
})

findAndCount - 查找与给定的 FindOptions 匹配的实体。同时计算与给定条件匹配的所有实体的数量，但忽略分页设置（from 和 take 选项）。

const [timbers, timbersCount] = await repository.findAndCount({
    where: {
        firstName: "Timber",
    },
})

findAndCountBy - 查找与给定的 FindOptionsWhere 匹配的实体。同时计算与给定条件匹配的所有实体的数量，但忽略分页设置（from 和 take 选项）。

const [timbers, timbersCount] = await repository.findAndCountBy({
    firstName: "Timber",
})

findOne - 查找与给定的 FindOptions 匹配的第一个实体。

const timber = await repository.findOne({
    where: {
        firstName: "Timber",
    },
})

findOneBy - 查找与给定的 FindOptionsWhere 匹配的第一个实体。

const timber = await repository.findOneBy({ firstName: "Timber" })

findOneOrFail - 查找与某个 ID 或查找条件匹配的第一个实体。如果没有匹配项，则拒绝返回的 Promise。

const timber = await repository.findOneOrFail({
    where: {
        firstName: "Timber",
    },
})

findOneByOrFail - 查找与给定的 FindOptions 匹配的第一个实体。如果没有匹配项，则拒绝返回的 Promise。

const timber = await repository.findOneByOrFail({ firstName: "Timber" })

query - 执行原始的 SQL 查询。

const rawData = await repository.query(`SELECT * FROM USERS`)

clear - 清除给定表中的所有数据（截断/删除）。

await repository.clear()

Additional Options

save 方法的可选参数 SaveOptions。

data - 与 persist 方法一起传递的附加数据。这些数据可以在 subscribers 中使用。
listeners: boolean - 指示是否调用此操作的监听器和订阅者。默认情况下启用它们，可以通过在 save/remove 选项中设置 { listeners: false } 来禁用它们。
transaction: boolean - 默认情况下，事务是启用的，并且持久化操作中的所有查询都被包装在事务中。可以通过在持久性选项中设置 { transaction: false } 来禁用此行为。
chunk: number - 将持久化操作分解为多个分组的块。例如，如果您想保存 100,000 个对象，但在保存它们时遇到问题，您可以将它们分解为 10 组，每组 10,000 个对象（通过设置 { chunk: 10000 }），并单独保存每个组。当您遇到底层驱动程序参数数量限制问题时，可以使用此选项执行非常大的插入操作。
reload: boolean - 标志，确定在持久化操作期间是否重新加载正在持久化的实体。它仅适用于不支持 RETURNING / OUTPUT 语句的数据库。默认情况下启用。

示例：

// users 包含 User 实体的数组
userRepository.save(users, { chunk: users.length / 1000 })

可以将可选参数 RemoveOptions 作为参数传递给 remove 和 delete 方法。

data - 与 remove 方法一起传递的附加数据。这些数据可以在 subscribers 中使用。
listeners: boolean - 指示是否调用此操作的监听器和订阅者。默认情况下启用它们，可以通过在 save/remove 选项中设置 { listeners: false } 来禁用它们。
transaction: boolean - 默认情况下，事务是启用的，并且持久化操作中的所有查询都被包装在事务中。可以通过在持久性选项中设置 { transaction: false } 来禁用此行为。
chunk: number - 将删除操作分解为多个分组的块。例如，如果您想删除 100,000 个对象，但在执行删除操作时遇到问题，您可以将它们分解为 10 组，每组 10,000 个对象，通过设置 { chunk: 10000 }，并单独删除每个组。当您遇到底层驱动程序参数数量限制问题时，可以使用此选项执行非常大的删除操作。

示例：

// entities 包含 Entity 实体的数组
userRepository.remove(entities, { chunk: entities.length / 1000 })

`TreeRepository` API

有关 TreeRepository API，请参阅树实体文档。

`MongoRepository` API

有关 MongoRepository API，请参阅MongoDB 文档。

仓库 API

Repository API​

Additional Options​

TreeRepository API​

MongoRepository API​

`Repository` API

Additional Options

`TreeRepository` API

`MongoRepository` API