仓库接口

非官方测试版翻译

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

`Repository` 接口

manager - 当前仓库使用的 EntityManager。

const manager = repository.manager

metadata - 当前仓库管理的实体对应的 EntityMetadata。

const metadata = repository.metadata

queryRunner - EntityManager 使用的查询运行器（Query Runner）。仅在事务型 EntityManager 实例中使用。

const queryRunner = repository.queryRunner

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

const target = repository.target

createQueryBuilder - 创建用于构建 SQL 查询的查询构建器（Query Builder）。了解更多关于查询构建器的信息。

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

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

if (repository.hasId(user)) {
    // ... do something
}

getId - 获取给定实体的主键列属性值。若实体使用复合主键，则返回值为包含主键列名称和值的对象。

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

create - 创建 User 的新实例。可选接收包含用户属性的对象字面量，这些属性将被写入新创建的用户对象。

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

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

const user = new User()
repository.merge(user, { firstName: "Timber" }, { lastName: "Saw" }) // same as 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 will contain all missing data from partialUser with partialUser property values:
// { id: 1, firstName: "Rizzrak", lastName: "Saw", profile: { id: 1, ... } }

save - 保存给定实体或实体数组。若实体已存在于数据库，则执行更新操作。若实体不存在于数据库，则执行插入操作。所有给定实体将在单个事务中保存（非事务性 EntityManager 除外）。支持部分更新，未定义的属性将被跳过。返回保存后的实体/实体数组。

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

remove - 移除给定实体或实体数组。所有给定实体将在单个事务中移除（非事务性 EntityManager 除外）。返回被移除的实体/实体数组。

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、ID 数组或条件更新实体。使用提供的部分实体设置字段值。

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

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

// optionally request RETURNING / OUTPUT values (supported drivers only)
const result = await repository.update(
    1,
    { firstName: "Rizzrak" },
    { returning: ["id", "firstName"] },
)
console.log(result.raw) // [{ id: 1, firstName: "Rizzrak" }]

updateAll - 更新目标类型的所有实体（无 WHERE 子句）。使用提供的部分实体设置字段值。

await repository.updateAll({ category: "ADULT" })
// executes UPDATE user SET category = ADULT

await repository.updateAll(
    { category: "ADULT" },
    { returning: "*" }, // limited to drivers that support returning clauses
)

upsert - 插入新实体或实体数组（若已存在则更新）。由 AuroraDataApi、Cockroach、Mysql、Postgres 和 Sqlite 数据库驱动支持。

当upsert操作因冲突导致更新时，特殊列（如 @UpdateDateColumn 和 @VersionColumn）会自动更新为当前值。

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

您还可以请求从 upsert 操作返回值（需数据库驱动支持 RETURNING / OUTPUT 功能）：

const { raw } = await repository.upsert(
    { externalId: "abc123", firstName: "Rizzrak" },
    {
        conflictPaths: ["externalId"],
        returning: ["externalId", "firstName"],
    },
)
console.log(raw) // [{ externalId: "abc123", firstName: "Rizzrak" }]

await repository.upsert(
    [
        { externalId: "abc123", firstName: "Rizzrak" },
        { externalId: "bca321", firstName: "Karzzir" },
    ],
    {
        conflictPaths: ["externalId"],
        skipUpdateIfNoValuesChanged: true, // supported by postgres, skips update if it would not change row values
        upsertType: "upsert", //  "on-conflict-do-update" | "on-duplicate-key-update" | "upsert" - optionally provide an UpsertType - 'upsert' is currently only supported by CockroachDB
    },
)
/** executes
 *  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, // supported by postgres, skips update if it would not change row values
        indexPredicate: "dateAdded > 2020-01-01", // supported by postgres, allows for partial indexes
    },
)
/** executes
 *  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" })

deleteAll - 删除目标类型的所有实体（无 WHERE 子句）。

await repository.deleteAll()
// executes DELETE FROM user

另请参考执行数据库 TRUNCATE TABLE 操作的 clear 方法。

softDelete 和 restore - 通过 ID、ID 数组或给定条件实现软删除和恢复：

const repository = dataSource.getRepository(Entity)
// Soft delete an entity
await repository.softDelete(1)
// And you can restore it using restore;
await repository.restore(1)
// Soft delete multiple entities
await repository.softDelete([1, 2, 3])
// Or soft delete by other attribute
await repository.softDelete({ firstName: "Jake" })

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

// You can soft-delete them using softRemove
const entities = await repository.find()
const entitiesAfterSoftRemove = await repository.softRemove(entities)

// And You can recover them using recover;
await repository.recover(entitiesAfterSoftRemove)

increment - 将匹配给定选项的实体的指定列按提供值递增。

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

decrement - 将匹配给定选项的实体的指定列按提供值递减。

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

exists - 检查是否存在匹配 FindOptions 的实体。

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

existsBy - 检查是否存在匹配 FindOptionsWhere 的实体。

const exists = await repository.existsBy({ firstName: "Timber" })

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`)

// You can also use parameters to avoid SQL injection
// The syntax differs between the drivers

// aurora-mysql, better-sqlite3, capacitor, cordova,
// expo, mariadb, mysql, nativescript, react-native,
// sap, sqlite, sqljs
const rawData = await repository.query(
    "SELECT * FROM USERS WHERE name = ? and age = ?",
    ["John", 24],
)

// aurora-postgres, cockroachdb, postgres
const rawData = await repository.query(
    "SELECT * FROM USERS WHERE name = $1 and age = $2",
    ["John", 24],
)

// oracle
const rawData = await repository.query(
    "SELECT * FROM USERS WHERE name = :1 and age = :2",
    ["John", 24],
)

// spanner
const rawData = await repository.query(
    "SELECT * FROM USERS WHERE name = @param0 and age = @param1",
    ["John", 24],
)

// mssql
const rawData = await repository.query(
    "SELECT * FROM USERS WHERE name = @0 and age = @1",
    ["John", 24],
)

clear - 清除给定表中的所有数据（执行 TRUNCATE TABLE 或 DROP TABLE 操作）。

await repository.clear()

附加选项

save 方法可接收可选的 SaveOptions 参数。

data - 随持久化方法传递的附加数据，可在订阅者中使用。
listeners: boolean - 是否为此操作调用监听器和订阅者。默认启用，可通过在 save/remove 选项中设置 { listeners: false } 禁用。
transaction: boolean - 默认启用事务，持久化操作中的所有查询会被包裹在事务中。可通过在持久化选项中设置 { transaction: false } 禁用此行为。
chunk: number - 将保存操作拆分为多个数据块组。例如需保存 100,000 个对象时，可设置为 { chunk: 10000 } 将其拆分为 10 组分别保存，适用于底层驱动参数数量限制导致的大批量插入问题。
reload: boolean - 是否在持久化操作期间重新加载正在保存的实体。仅在不支持 RETURNING/OUTPUT 语句的数据库中生效，默认启用。

示例：

userRepository.save(users, { chunk: 1000 })

remove 和 delete 方法可接收可选的 RemoveOptions 参数。

data - 随删除方法传递的附加数据，可在订阅者中使用。
listeners: boolean - 是否为此操作调用监听器和订阅者。默认启用，可通过在 save/remove 选项中设置 { listeners: false } 禁用。
transaction: boolean - 默认启用事务，持久化操作中的所有查询会被包裹在事务中。可通过在持久化选项中设置 { transaction: false } 禁用此行为。
chunk: number - 将删除操作拆分为多个数据块组。例如需删除 100,000 个对象时，可设置为 { chunk: 10000 } 将其拆分为 10 组分别删除，适用于底层驱动参数数量限制导致的大批量删除问题。

示例：

userRepository.remove(users, { chunk: 1000 })

`TreeRepository` API

关于 TreeRepository API 的详细信息，请参阅树形实体文档。

`MongoRepository` API

关于 MongoRepository API 的详细信息，请参阅MongoDB 文档。

Repository 接口​

附加选项​

TreeRepository API​

MongoRepository API​

`Repository` 接口

附加选项

`TreeRepository` API

`MongoRepository` API