diff --git a/docs/en-US/api/database/repository.md b/docs/en-US/api/database/repository.md index d7ca19c956..4dcdeafaa1 100644 --- a/docs/en-US/api/database/repository.md +++ b/docs/en-US/api/database/repository.md @@ -1,8 +1,8 @@ # Repository -## 概览 +## Overview -在一个给定的 `Collection` 对象上，可以获取到它的 `Repository` 对象来对数据表进行读写操作。 +On a given `Collection` object, you can get its `Repository` object to perform read and write operations on the data table. ```javascript const { UserCollection } = require("./collections"); @@ -19,11 +19,11 @@ user.name = "new name"; await user.save(); ``` -### 查询 +### Query -#### 基础查询 +#### Basic Query -在 `Repository` 对象上，调用 `find*` 相关方法，可执行查询操作，查询方法都支持传入 `filter` 参数，用于过滤数据。 +On the `Repository` object, call the `find*` methods to perform query. The `filter` parameter is supported by all query methods to filter the data. ```javascript // SELECT * FROM users WHERE id = 1 @@ -34,9 +34,9 @@ userRepository.find({ }); ``` -#### 操作符 +#### Operator -`Repository` 中的 `filter` 参数，还提供了多种操作符，执行更加多样的查询操作。 +The `filter` parameter in the `Repository` also provides a variety of operators to perform more diverse queries. ```javascript // SELECT * FROM users WHERE age > 18 @@ -60,39 +60,39 @@ userRepository.find({ ``` -操作符的更多详细信息请参考 [Filter Operators](/api/database/operators)。 +Refer to [Filter Operators](/api/database/operators) for more details on operators. -#### 字段控制 +#### Field Control -在查询操作时，通过 `fields`, `except`, `appends` 参数可以控制输出字段。 +Control the output fields by the `fields`, `except`, and `appends` parameters when performing query. -* `fields`: 指定输出字段 -* `except`: 排除输出字段 -* `appends`: 追加输出关联字段 +* `fields`: Specify output fields +* `except`: Exclude output fields +* `appends`: Append output associated fields ```javascript -// 获取的结果只包含 id 和 name 字段 +// The result contains only the id and name fields userRepository.find({ fields: ["id", "name"], }); -// 获取的结果不包含 password 字段 +// The result does not contain only the password field userRepository.find({ except: ["password"], }); -// 获取的结果会包含关联对象 posts 的数据 +// The result contains data associated with the posts object userRepository.find({ appends: ["posts"], }); ``` -#### 关联字段查询 +#### Associated Field Query -`filter` 参数支持按关联字段进行过滤，例如： +The `filter` parameter supports filtering by associated fields, for example: ```javascript -// 查询 user 对象，其所关联的 posts 存在 title 为 'title1' 的对象 +// Find the user objects whose associated posts have title of "post title" userRepository.find({ filter: { "posts.title": "post title" @@ -100,10 +100,10 @@ userRepository.find({ }); ``` -关联字段也可进行嵌套 +Associated fields can also be nested: ```javascript -// 查询 user 对象，查询结果满足其 posts 的 comments 包含 keywords +// Find the user objects whose associated posts have comments containing "keywords" await userRepository.find({ filter: { "posts.comments.content": { @@ -113,9 +113,9 @@ await userRepository.find({ }); ``` -#### 排序 +#### Sort -通过 `sort` 参数，可以对查询结果进行排序。 +Sort query results by the `sort` parameter. ```javascript @@ -136,7 +136,7 @@ await userRepository.find({ }); ``` -也可按照关联对象的字段进行排序 +Sort by the field of the associated object is also supported: ```javascript await userRepository.find({ @@ -144,38 +144,38 @@ await userRepository.find({ }); ``` -### 创建 +### Create -#### 基础创建 +#### Basic Create -通过 `Repository` 创建新的数据对象。 +Create new data objects via `Repository`. ```javascript await userRepository.create({ - name: "张三", + name: "Mark", age: 18, }); -// INSERT INTO users (name, age) VALUES ('张三', 18) +// INSERT INTO users (name, age) VALUES ('Mark', 18) -// 支持批量创建 +// Bulk creation await userRepository.create([ { - name: "张三", + name: "Mark", age: 18, }, { - name: "李四", + name: "Alex", age: 20, }, ]) ``` -#### 创建关联 +#### Create Association -创建时可以同时创建关联对象，和查询类似，也支持关联对象的嵌套使用，例如： +Create associated objects at the same time of creating data. Similar to query, nested use of associated objects is also supported. For example: ```javascript await userRepository.create({ @@ -196,9 +196,10 @@ await userRepository.create({ }, ], }); -// 创建用户的同时，创建 post 与用户关联，创建 tags 与 post 相关联。 +// When crearing a user, creat a post to associate with the user, and create tags to associate with the post ``` -若关联对象已在数据库中，可传入其ID，创建时会建立与关联对象的关联关系。 + +If the associated object is already in the database, you can pass its ID to create an association with it. ```javascript const tag1 = await tagRepository.findOne({ @@ -208,7 +209,7 @@ const tag1 = await tagRepository.findOne({ }); await userRepository.create({ - name: "张三", + name: "Mark", age: 18, posts: [ { @@ -216,7 +217,7 @@ await userRepository.create({ content: "post content", tags: [ { - id: tag1.id, // 建立与已存在关联对象的关联关系 + id: tag1.id, // Create an association with an existing associated object }, { name: "tag2", @@ -227,16 +228,16 @@ await userRepository.create({ }); ``` -### 更新 +### Update -#### 基础更新 +#### Basic Update -获取到数据对象后，可直接在数据对象(`Model`)上修改属性，然后调用 `save` 方法保存修改。 +After getting the data object, you can modify the properties directly on the data object (`Model`), and then call the `save` method to save the changes. ```javascript const user = await userRepository.findOne({ filter: { - name: "张三", + name: "Mark", }, }); @@ -245,15 +246,15 @@ user.age = 20; await user.save(); ``` -数据对象 `Model` 继承自 Sequelize Model，对 `Model` 的操作可参考 [Sequelize Model](https://sequelize.org/master/manual/model-basics.html)。 +The data object `Model` is inherited from Sequelize Model, refer to [Sequelize Model](https://sequelize.org/master/manual/model-basics.html) for the operations on `Model`. -也可通过 `Repository` 更新数据： +Or update data via `Repository`: ```javascript -// 修改满足筛选条件的数据记录 +// Update the records that meet the filtering condition await userRepository.update({ filter: { - name: "张三", + name: "Mark", }, values: { age: 20, @@ -261,24 +262,24 @@ await userRepository.update({ }); ``` -更新时，可以通过 `whitelist` 、`blacklist` 参数控制更新字段，例如： +Control which fields to update by the `whitelist` and `blacklist` parameters, for example: ```javascript await userRepository.update({ filter: { - name: "张三", + name: "Mark", }, values: { age: 20, - name: "李四", + name: "Alex", }, - whitelist: ["age"], // 仅更新 age 字段 + whitelist: ["age"], // Only update the age field }); ```` -#### 更新关联字段 +#### Update Associated Field -在更新时，可以设置关联对象，例如： +Associated objects can be set while updating, for example: ```javascript const tag1 = tagRepository.findOne({ @@ -295,10 +296,10 @@ await postRepository.update({ title: "new post title", tags: [ { - id: tag1.id // 与 tag1 建立关联 + id: tag1.id // Associate with tag1 }, { - name: "tag2", // 创建新的 tag 并建立关联 + name: "tag2", // Create new tag and associate with it }, ], }, @@ -310,14 +311,14 @@ await postRepository.update({ id: 1 }, values: { - tags: null // 解除 post 与 tags 的关联 + tags: null // Disassociate post from tags }, }) ``` -### 删除 +### Delete -可调用 `Repository` 中的 `destroy()`方法进行删除操作。删除时需指定筛选条件： +Call the `destroy()` method in `Repository` to perform the deletion operation. Filtering condition has to be specified to delete. ```javascript await userRepository.destroy({ @@ -327,15 +328,15 @@ await userRepository.destroy({ }); ``` -## 构造函数 +## Constructor -通常不会直接由开发者调用，主要通过 `db.registerRepositories()` 注册类型以后，在 `db.colletion()` 的参数中指定对应已注册的仓库类型，并完成实例化。 +It is usually not called directly by the developer, the instantiation is done mainly by specifying a coressponding repository type that is already registered in the parameter of `db.colletion()`. Repository type is registered through `db.registerRepositories()`. -**签名** +**Signature** * `constructor(collection: Collection)` -**示例** +**Example** ```ts import { Repository } from '@nocobase/database'; @@ -362,7 +363,7 @@ const books = db.getRepository('books') as MyRepository; await books.myQuery('SELECT * FROM books;'); ``` -## 实例成员 +## Instance Member ### `database` @@ -383,7 +384,7 @@ await books.myQuery('SELECT * FROM books;'); 从数据库查询数据集，可指定筛选条件、排序等。 -**签名** +**Signature** * `async find(options?: FindOptions): Promise` @@ -466,7 +467,7 @@ repository.find({ #### `offset: number` 查询偏移量，同 `SQL` 中的 `offset` -**示例** +**Example** ```ts const posts = db.getRepository('posts'); @@ -486,13 +487,13 @@ const results = await posts.find({ 从数据库查询特定条件的单条数据。相当于 Sequelize 中的 `Model.findOne()`。 -**签名** +**Signature** * `async findOne(options?: FindOneOptions): Promise` -**示例** +**Example** ```ts const posts = db.getRepository('posts'); @@ -506,7 +507,7 @@ const result = await posts.findOne({ 从数据库查询特定条件的数据总数。相当于 Sequelize 中的 `Model.count()`。 -**签名** +**Signature** * `count(options?: CountOptions): Promise` @@ -517,7 +518,7 @@ interface CountOptions extends Omit` @@ -551,13 +552,13 @@ type FindAndCountOptions = Omit(options: CreateOptions): Promise` -**示例** +**Example** ```ts const posts = db.getRepository('posts'); @@ -579,7 +580,7 @@ const result = await posts.create({ 向数据表插入多条新创建的数据。相当于多次调用 `create()` 方法。 -**签名** +**Signature** * `createMany(options: CreateManyOptions): Promise` @@ -595,7 +596,7 @@ interface CreateManyOptions extends BulkCreateOptions { * `records`：要创建的记录的数据对象数组。 * `transaction`: 事务对象。如果没有传入事务参数，该方法会自动创建一个内部事务。 -**示例** +**Example** ```ts const posts = db.getRepository('posts'); @@ -625,13 +626,13 @@ const results = await posts.createMany({ 更新数据表中的数据。相当于 Sequelize 中的 `Model.update()`。当要更新的数据对象携带关系字段的信息时，会一并创建或更新相应的关系数据记录。 -**签名** +**Signature** * `async update(options: UpdateOptions): Promise` -**示例** +**Example** ```ts const posts = db.getRepository('posts'); @@ -654,7 +655,7 @@ const result = await posts.update({ 删除数据表中的数据。相当于 Sequelize 中的 `Model.destroy()`。 -**签名** +**Signature** * `async destory(options?: TargetKey | TargetKey[] | DestoryOptions): Promise` @@ -675,3 +676,4 @@ interface DestroyOptions extends SequelizeDestroyOptions { * `filterByTk`：按 TargetKey 指定要删除的记录的过滤条件。 * `truncate`: 是否清空表数据，在没有传入 `filter` 或 `filterByTk` 参数时有效。 * `transaction`: 事务对象。如果没有传入事务参数，该方法会自动创建一个内部事务。 +![image](https://user-images.githubusercontent.com/63629092/213859493-1eb7eb5b-0368-41e8-8fb5-d0d735afd429.png)