From d96bc1178604e75c31ef5880645ac3e7633e8b56 Mon Sep 17 00:00:00 2001 From: heibaiying <2806718453@qq.com> Date: Tue, 30 Jul 2019 18:06:12 +0800 Subject: [PATCH] =?UTF-8?q?mongodb=E7=B4=A2=E5=BC=95?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- notes/Java_设计模式.md | 34 ++++ notes/MongoDB_基础.md | 334 +++++++++++++++++++++++++++++++ notes/MongoDB_基础操作.md | 0 notes/MongoDB_索引.md | 357 +++++++++++++++++++++++++++++++++ notes/MongoDB_聚合.md | 367 ++++++++++++++++++++++++++++++++++ pictures/b-tree.png | Bin 0 -> 29787 bytes 6 files changed, 1092 insertions(+) create mode 100644 notes/Java_设计模式.md create mode 100644 notes/MongoDB_基础.md delete mode 100644 notes/MongoDB_基础操作.md create mode 100644 pictures/b-tree.png diff --git a/notes/Java_设计模式.md b/notes/Java_设计模式.md new file mode 100644 index 0000000..71143b8 --- /dev/null +++ b/notes/Java_设计模式.md @@ -0,0 +1,34 @@ +# 设计模式 + +## 软件设计的原则 + +### 开闭原则 + +定义：软件实体应当对扩展开放，对修改关闭。 + +### 里氏替换原则 + +定义：继承必须保证确保超类所拥有的性质在子类中仍然成立。即子类在继承父类时，除了添加新的方法来新增功能外，尽量避免重写父类方法，因为这会导致整个继承体系的复用性变差。 + +### 依赖倒置原则 + +定义：高层模块不应该依赖低层模块，两者都应该依赖其抽象；抽象不应该依赖细节，细节应该依赖抽象。其核心思想是要面向接口编程，而不是面向实现编程，这样可以降低耦合性，提高系统稳定性，提高代码的可读性和可维护性。 + +### 单一职责原则 + +定义：一个类应该有且仅有一个引起它变化的原则，否则应类应该被拆分。其核心思想是控制类的粒度大小、提高类的内聚性。 + +### 接口隔离原则 + +定义：一个类对另一个类的依赖应该建立在最小的接口上。其核心思想是要为每个特定的功能建立对应的接口，而不是在一个接口中试图去包含所有功能，既要保证相对独立，也要避免过多接口所导致的臃肿。 + +### 迪米特法则 (最少知道原则) + +定义：如果两个软件实体不需要直接通讯，那么就应该避免直接互相调用，而是通过第三方转发该调用，从而降低耦合度，保证模块的相对独立。 + +### 合成复用原则 (组合复用原则) + +定义：应该优先使用组合、聚合等关联关系来实现复用，其次才是考虑使用继承关系。 + +在软件设计当中应该尽量遵守这七大原则，它们之间要求的侧重点不同：开闭原则是总纲，它告诉我们要对扩展开放，对修改关闭；里氏替换原则告诉我们不要破坏继承体系；依赖倒置原则告诉我们要面向接口编程；单一职责原则告诉我们实现类要职责单一；接口隔离原则告诉我们在设计接口的时候要精简单一；迪米特法则告诉我们要降低耦合度；合成复用原则告诉我们要优先使用组合或者聚合关系复用，少用继承关系复用。 + diff --git a/notes/MongoDB_基础.md b/notes/MongoDB_基础.md new file mode 100644 index 0000000..b23c81b --- /dev/null +++ b/notes/MongoDB_基础.md @@ -0,0 +1,334 @@ +# MongoDB 基础 + +## 一、数据类型 + +### 1.1 BSON + +文档 (Documents) 是 MongoDB 中数据的基本单元，它是键值对的有序集合，在数据结构上类似于 JSON，但是由于 JSON 只支持基本的 6 种数据类型：null，布尔，数字，字符串，数组和对象，因此其表达能力有限，所以 MongoDB 基于 JSON 拓展出新的数据格式 BSON 。BSON (Binary JSON) 是类似 JSON 文档的二进制编码序列化格式，与 JSON 类似，但支持更多的数据类型。当前 MongoDB 4.0 的 BSON 支持以下所有的数据类型： + +| Type （类型） | Alias （别名） | Notes （注释） | +| :---------------------- | :-------------------- | :----------------------------------------------------------- | +| Double | “double” | 双精度型 | +| String | “string” | 字符串类型，默认的编码类型为 UTF-8 | +| Object | “object” | 对象类型 | +| Array | “array” | 数据类型 | +| Binary data | “binData” | 二进制数据 | +| Undefined | “undefined” | 该数据类型已经废弃 | +| ObjectId | “objectId” | 对象 id | +| Boolean | “bool” | 布尔值 | +| Date | “date” | 日志类型 | +| Null | “null” | 空 | +| Regular Expression | “regex” | 正则表达式 | +| DBPointer | “dbPointer” | 该数据类型已经废弃 | +| JavaScript | “javascript” | | +| Symbol | “symbol” | 该数据类型已经废弃 | +| JavaScript (with scope) | “javascriptWithScope” | | +| 32-bit integer | “int” | 32 位整型 | +| Timestamp | “timestamp” | 时间戳类型 | +| 64-bit integer | “long” | 64 位整型 | +| Decimal128 | “decimal” | 3.4 版本新增的数据类型，类似 Java 中的 BigDecimal 类型，
用于解决浮点型丢失精度的问题 | +| Min key | “minKey” | | +| Max key | “maxKey” | | + +### 1.2 ObjectId + +在上面的表格中有一个比较重要的数据类型是：ObjectId 。存储在 MongoDB 集合中的每个文档都有一个唯一的 `_id` 字段作为主键，可以在插入的时候手动指定，或者由程序自动生成，这个字段可以是任何的数据类型，默认是 ObjectId 类型。ObjectId 使用 12 字节的存储空间，是一个由 24 个十六进制数字组成的字符串，每个字符串可以存储两个十六进制数字： + ++ 前 4 个字节是从标准纪元开始的时间戳，单位为秒； + ++ 中 5 个字节是由两个部分组成：前 3 个字节是所在主机的唯一标识，通常是主机名的散列值，用于保证不同主机生成不同 ObjectId ，后两个字节是进程标识符 (PID) ，用于保证同一主机上不同进程产生不同的 ObjectId。 + ++ 最后 3 个字节是一个自动增加的计数器，确保相同主机上相同进程在同一秒产生的 ObjectId 也是不同的，即每个进程一秒最多可以拥有 16777216 个不同的 ObjectId (16777216 = (2\*\*8)\*\*3，1 个字节等于 8 位二进制) 。 + + +## 二、新增数据 + +```shell +db.collection.insert() +``` + +在 MongoDB 3.2 之前，插入数据的语法如上，可以用于插入单条或者多条数据。在 3.2 之后，MongoDB 为了增强 API 的语义，增加了如下两个 API ，分别用于显示表达插入单条数据和多条数据的行为。 + +```shell +db.collection.insertOne() +db.collection.insertMany() +``` + +新增单条数据的示例如下。额外需要说明的是，在插入文档前，文档所属的集合不必预先创建，程序会自动创建： + +```json +db.user.insertOne({ + name: "heibai", + age: 26, + birthday: new Date(1998,08,23), + createTime: new Timestamp(), + Hobby: ["basketball", "football", "tennis"] +}) +``` + +新增多条数据的示例如下： + +```json +db.user.insertMany([ + { + name: "hei", + age: 32, + birthday: new Date(1989,08,23), + createTime: new Timestamp(), + Hobby: ["basketball", "football", "tennis"] + }, + { + name: "ying", + age: 46, + birthday: new Date(1978,08,23), + createTime: new Timestamp(), + Hobby: ["basketball", "football", "tennis"] + } +]) + +# 此时会返回新插入的数据的ObjectId +{ + "acknowledged" : true, + "insertedIds" : [ + ObjectId("5d3d0489ad38cd3becc7b03b"), + ObjectId("5d3d0489ad38cd3becc7b03c") + ] +} +``` + +## 三、查询数据 + +### 3.1 基本 API + +查询数据的基本语法如下： + +```shell +db.collection.find(, ) +``` + ++ ``：用于指定查询条件，不加任何条件则默认查询集合中全部数据； ++ ``：可选操作，用于自定查询的返回字段，1 表示该字段包含在返回结果中，0 表示不返回，示例如下： + +```json +db.user.find({},{name: 1, ObjectId:-1})} +``` + +### 3.2 等值查询 + +想要查询某个字段等于指定值的数据，可以使用如下语法： + +```shell +db.user.find({name:"heibai"}) +``` + +上面的语法实际上是 `$eq` 操作的简写形式，如下： + +```json +db.user.find({name: {$eq: "heibai"}}) +``` + +所以如果你想要进行非等值查询，则可以使用 `$ne` 操作符，代表 not equal ，示例如下： + +```json +db.user.find({name: {$ne: "heibai"}}) +``` + +特别的，如果你想允许某个字段等于多个值，可以使用 `$in` 操作符，示例如下： + +```json +db.user.find({name: {$in:["heibai","ying"]} }) +``` + +### 3.3 范围查询 + +Mongodb 提供了比较操作符 `$lt`、`$lte`、`$gt` 和 `$gte` ，分别对应 <、 <=、 >和 >= ，主要用于范围查查询，示例如下： + +```json +db.user.find({age: {$gt: 20, $lt: 40}}) +``` + +### 3.4 逻辑查询 + +Mongodb 提供了逻辑操作符 `$or`、`$and`、`$not`、`$nor` ，用于处理多个条件间的逻辑关系，示例如下： + +查询姓名为 heibai 或者年龄大于 30 岁的所有用户，此时可以使用 $or 操作符： + +```json +db.user.find( { $or: [{ name: "heibai" }, { age: { $gt: 30 } }] }) +``` +查询所有姓名不是以 hei 开头的所有用户，此时可以使用 $not 操作符来配合正则表达式： + +```json +db.user.find({name: {$not: /^hei*/}}) +``` + +如果文档中存在 name 字段，则它的值不能为 heibai，如果文档中存在 age 字段，则它的值不能大于 30 ，只有满足以上两个条件的文档才会被查询出来，示例如下： + +```json +db.user.find( { $nor: [{ name: "heibai" }, { age: { $gt: 30 } }] }) +``` + +$and 操作符的使用率比较低，因为此时更好的方式是把多个条件写到同一个对象中，从而减少额外嵌套。 + +### 3.5 集合查询 + +如果需要查询个人爱好中有 football 的所有用户，即只要集合 Hobby 中存在 football 即可，对应的查询方法如下： + +```json +db.user.find({Hobby: "football"}) +``` +如果想要获取集合中指定位置等于指定值的文档，对应的查询方法如下： + +```json +db.user.find({"Hobby.2": "football"}) +``` +如果想要约束集合必须包含多个指定值，此时可以使用 $all 操作符： + +```json +db.user.find({Hobby:{ $all: ["football", "tennis"]}}) +``` +查询时如果只想返回集合的部分内容，则可以使用 $slice ，$slice 接收一个参数 n，正数表示获取集合的前 n 个参数，负数表示获取集合末尾的 n 个参数，示例如下： + +```json +db.user.find({name: "heibai"},{Hobby:{$slice: 2}}) +``` + +### 3.6 额外操作 + +在查询操作之后，MongoDB 还提供了三个额外的函数 `skip`、`sort` 和 `limit` ，分别用于表示跳过一定量的数据、按照指定规则对数据进行排序和限制返回数据的量，示例如下： + +```shell +db.user.find({}) + .skip(1) + .sort({_id:-1}) + .limit(10) +``` + +## 四、修改数据 + +### 4.1 基本 API + +MongoDB 提供了以下三个 API，分别用于修改单条数据、多条数据和执行单条数据替换： + +```shell +db.collection.replaceOne(, , ) +db.collection.updateOne(, , ) +db.collection.updateMany(, , ) +``` + ++ ``：过滤条件，用于查询需要修改的数据； ++ ``：更改操作或新文档数据； ++ ` `：可选操作，常用的可选操作是 `upsert` ，当其为 true 时，代表如果按照过滤条件没有找到对应的文档，则将待更改的数据插入到集合中；当其为 false 时，如果没有找到数据，则不执行任何操作。示例如下： + +```json +db.user.replaceOne( + { _id: ObjectId("5d3d00a4ad383d3becc7b03a")}, + { + name: "danrenying", + age: 32, + birthday: new Date(1995,08,23), + createTime: new Timestamp(), + Hobby: ["basketball", "football", "tennis"] + }, + {upsert : true} +) +``` + +### 4.2 常规修改器 + +想要对数据进行修改，必须明确表达修改行为，在 MongoDB 中这是通过修改器来实现的，常用的修改器如下： + +#### 1. $set + +用于修改具体的字段，如果待修改的字段不存在，则会新增该字段。示例如下： + +```json +db.user.updateOne( + { name: "danrenying"}, + { $set: {age: 66} } +) +``` + +#### 2. $inc + +用于对指定字段的值进行增加或减少，示例如下： + +```json +db.user.updateOne( + { name: "danrenying"}, + { $inc: {age: -10} } +) +``` + +### 4.3 数组修改器 + +在修改操作中，比较复杂的是对数组数据的修改，为了解决这个问题，MongoDB 提供了一系列的修改器，用于数组操作： + +#### 1. $push + +用于往数组中新增数据，示例如下。使用 `$each` 可以一次添加多个元素： + +```json +db.user.updateOne( + { name: "danrenying"}, + { $push: {"Hobby": {$each: ["film","music"]}} } +) +``` + +#### 2. $addToSet + +该修改器可以把数组当做集 (set) 来使用，即只能添加当前数组中不存在的数据，示例如下： + +```json +db.user.updateOne( + { name: "danrenying"}, + { $addToSet: {"Hobby": {$each: ["film","music"]}} } +) +``` + +#### 3. $pop + +该修改器可以从数组任意一端删除元素，`-1` 代表从数组头删除元素，`1` 代表从数组尾删除元素，示例如下： + +```json +db.user.updateOne( + { name: "danrenying"}, + { $pop: {"Hobby": -1} } +) +``` + +#### 4. index + +对于数组还可以直接修改指定下标位置的元素，示例如下： + +```shell +db.user.updateOne( + { name: "danrenying"}, + { $set: {"Hobby.0": "Cooking"} } +) +``` + +## 五、删除数据 + +MongoDB 提供了以下两个 API 用于删除操作： + +```shell +db.collection.deleteMany() +db.collection.deleteOne() +``` + +使用示例如下： + +```json +db.user.deleteOne( + { name: "danrenying"} +) +``` + + + +## 参考资料 + ++ 官方文档：[MongoDB CRUD Operations](https://docs.mongodb.com/manual/crud/) + ++ Kristina Chodorow . MongoDB权威指南（第2版）. 人民邮件出版社 . 2014-01 \ No newline at end of file diff --git a/notes/MongoDB_基础操作.md b/notes/MongoDB_基础操作.md deleted file mode 100644 index e69de29..0000000 diff --git a/notes/MongoDB_索引.md b/notes/MongoDB_索引.md index e69de29..b3b2b21 100644 --- a/notes/MongoDB_索引.md +++ b/notes/MongoDB_索引.md @@ -0,0 +1,357 @@ +# MongoDB 索引 + +## 一、索引简介 + +### 1.1 创建索引 + +和大多数关系型数据库一样，MongoDB 支持使用索引来进行查询优化，采用类似 B-Tree 的数据结构来储存索引和文档的位置信息，同样也支持前缀索引和覆盖索引。在当前最新的 MongoDB 4.0 中，索引的创建语法如下： + +```shell +db.collection.createIndex( , ) +``` + ++ ``：用于指定建立索引的字段和升降序等属性； ++ ` `：可选配置，通常用于指定索引的性质。 + +为方便后面的演示，这里先插入部分测试数据，并针对 name 字段创建一个索引： + +```shell +db.user.insertMany([ + { + name: "heibai", + age: 26, + birthday: new Date(1998,08,23), + createTime: new Timestamp(), + Hobby: ["basketball", "football", "tennis"] + }, + { + name: "hei", + age: 32, + birthday: new Date(1989,08,23), + createTime: new Timestamp(), + Hobby: ["basketball", "tennis"] + }, + { + name: "ying", + age: 46, + birthday: new Date(1978,08,23), + createTime: new Timestamp(), + Hobby: ["tennis"] + } +]) + + +# 创建索引, -1表示以降序的顺序存储索引 +db.user.createIndex( { name: -1 } ) +``` + +### 1.2 查看索引 + +创建索引后可以使用 `getIndexes()` 查看集合的所有索引信息，示例如下： + +```shell +db.user.getIndexes() +``` + +从输出中可以看到默认的索引名为：字段名+排序规则。这里除了我们为 name 字段创建的索引外，集合中还有一个 `_id` 字段的索引，这是程序自动创建的，用于禁止插入相同 `_id` 的文档。 + +```json +{ + "v" : 2, + "key" : { + "_id" : 1 + }, + "name" : "_id_", + "ns" : "test.user" +}, + +{ + "v" : 2, + "key" : { + "name" : -1 + }, + "name" : "name_-1", + "ns" : "test.user" +} +``` + +## 二、索引的类型 + +当前 MongoDB 4.x 支持以下六种类型的索引： + +### 2.1 单字段索引 + +支持为单个字段建立索引，这是最基本的索引形式，上面我们针对 name 字段创建的索引就是一个单字段索引。需要特别说明的是，在为 name 字段创建索引时，我们为其指定了排序规则。但实际上，在涉及单字段索引的排序查询中，索引键的排序规则是无关紧要，因为 MongoDB 支持在任一方向上遍历索引。即以下两个查询都可以使用 `name_-1` 索引进行排序： + +```shell +db.user.find({}).sort({name:-1}) +db.user.find({}).sort({name:1}) +``` + +当前大多数数据库都支持双向遍历索引，这和存储结构有关 (如下图)。在 B-Tree 结构的叶子节点上，存储了索引键的值及其对应文档的位置信息，而每个叶子节点间则类似于双向链表，所以如下图既可以从值为 4 的索引遍历到值为 92 的索引，反之亦然。 + +![b-tree](D:\Full-Stack-Notes\pictures\b-tree.png) + + + +### 2.2 复合索引 + +支持为多个字段创建索引，示例如下： + +```shell +db.user.createIndex( { name: -1,birthday: 1} ) +``` + +需要注意的是 MongoDB 的复合索引具备前缀索引的特征，即如果你创建了索引 `{ a:1, b: 1, c: 1, d: 1 }`，那么等价于在该集合上，还存在了以下三个索引，这三个隐式索引同样可以用于优化查询和排序操作： + +```json +{ a: 1 } +{ a: 1, b: 1 } +{ a: 1, b: 1, c: 1 } +``` + +所以应该尽量避免创建冗余的索引，冗余索引会导致额外的性能开销。即如果你创建了索引 `{ name: -1, birthday: 1} `，那么再创建 `{name:-1}` 索引，就属于冗余创建。 + +对于复合索引还需要注意它在排序上的限制，例如索引 `{a：1, b：-1}` 支持 `{a：1, b：-1}` 和 `{a：-1, b：1}` 形式的排序查询，但不支持 `{a： - 1, b：-1} ` 或 `{a：1, b：1}` 的排序查询。即字段的排序规则要么与索引键的排序规则完全相同，要么完全相反，此时才能进行双向遍历查找。 + +### 2.3 多键索引 + +如果索引包含类型为数组的字段，MongoDB 会自动为数组中的每个元素创建单独的索引条目，这就是多键索引。MongoDB 使用多键索引来优化查询存储在数组中的内容。创建示例如下： + +```shell +db.user.createIndex( { Hobby: 1 } ) +``` + +### 2.4 哈希索引 + +为了支持基于哈希分片，MongoDB 提供了哈希索引，通过对索引值进行哈希运算然后计算出所处的分片位置。语法如下： + +```shell +db.collection.createIndex( { _id: "hashed" } ) +``` + +采用哈希运算得到的结果值会比较分散， 所以哈希索引不能用于范围查询，只能用于等值查询。 + +### 2.5 地理空间索引 + +为了支持对地理空间坐标数据的有效查询，MongoDB提供了两个特殊索引： + +- 使用平面几何的 2d 索引，主要用于平面地图数据 (如游戏地图数据)、连续时间的数据； +- 使用球形几何的 2dsphere 索引，主要用于实际的球形地图数据。 + +这些数据通常是用于解决实际的地理查询，如附近的美食、查询范围内所有商家等功能。其创建语法如下： + +```shell +db..createIndex( { : "2d" , + : } , + { } ) +db.collection.createIndex( { : "2dsphere" } ) +``` + +### 2.6 文本索引 + +MongoDB 支持全文本索引，用于对指定字段的内容进行全文检索。其创建语法如下： + +```shell +db..createIndex( { field: "text" } ) +``` + +需要注意的是一个集合最多可以有一个文本索引，但一个文本索引可以包含多个字段，语法如下： + +```shell +db..createIndex( + { + field0: "text", + field1: "text" + } + ) +``` + +创建文本索引是一个非常昂贵的操作，因为创建文本索引时需要对文本进行语义分析和有效拆分，还需要将拆分后的关键词存储在内存中，这对设备的运算能力和存储空间都有非常高的要求，同时也会降低 MongoDB 的性能，所以需要谨慎使用。 + +## 三、索引的性质 + +创建索引时，可以传入第二个参数 ` ` 用于指定索引的性质，常用的索引性质如下： + +### 3.1 唯一索引 + +唯一索引可以确保在同一个集合中唯一索引列的值只出现一次。 示例如下： + +```shell +db.user.createIndex( { name: -1,birthday: 1}, { unique: true }) +``` + +此时再执行下面的操作就会报错，因为 name = heibai 并且 birthday = new Date(1998,08,23) 的数据已经存在。 + +```shell +db.user.insertOne({ + name: "heibai", + birthday: new Date(1998,08,23) +}) +``` + +上面这种情况比较明显，但是如果你执行下面这个操作两次，你会发现只有第一次能够插入成功，第二个就会报 duplicate key 异常。这是因为在唯一索引的约束下，不存在这种状态也会被当做一种唯一值。 + +```shell +db.user.insertOne({ + age: 12 +}) +``` + +想要解决这个问题，就需要用到索引的稀疏性。 + +### 3.2 稀疏性 + +为了解决上面的问题，我们需要为索引添加稀疏性。由于索引不能修改，所以只能先将上面的索引先删除，然后再创建，并为其指定 `sparse` 属性为 true，具体的创建语句如下： + +```shell +db.user.dropIndex("name_-1_birthday_1") +db.user.createIndex( { name: -1,birthday: 1}, { unique: true,sparse: true}) +``` + +此时你再多次执行上面的插入语句就能插入成功。原因是对于稀疏索引而言，它仅包含具有索引字段的文档的索引信息，即使索引字段的值为 null 也可以，但不能缺少相应的索引字段。如果缺少，则相应的文档就不会被包含在索引信息中。 + +### 3.3 部分索引 + +部分索引主要用于为符合条件的部分数据创建索引，它必须与 partialFilterExpression 选项一起使用。 partialFilterExpression 选项可以使用以下表达式来确定数据范围： + +- 等式表达式（即 字段: 值 或使用 $eq 运算符）; +- $exists: true 表达式； +- $gt、$gte、$lt、$lte 操作符； +- $type 操作符； +- 处于顶层的 $and 操作符。 + +使用示例如下： + +```shell +db.user.createIndex( + { name: -1 }, + { partialFilterExpression: { age: { $gt: 30 } } } +) +``` + +### 3.4 TTL 索引 + +TTL 索引允许为每个文档设置一个超时时间，当一个文档达到超时时间后，就会被删除。TTL索引的到期时间等于索引字段的值 + 指定的秒数，示例如下： + +```shell +db.user.createIndex( { "birthday": 1 }, { expireAfterSeconds: 60 } ) +``` + +这里我们在 birthday 字段上建立 TTL 索引只是用于演示，实际上 TTL 索引主要是用于那些只需要在特定时间内保存的数据，如会话状态、临时日志等。在使用 TTL 索引时，还有以下事项需要注意： + +- TTL 属性只能用于单字段索引，不支持复合索引。 +- 建立 TTL 索引的字段的类型只能是 Date 类型，时间戳类型也不可以。 +- 如果字段是数组，并且索引中有多个日期值，则 MongoDB 会使用数组中的最早的日期值来计算到期时间。 +- 如果文档中的索引字段不是日期或包含日期值的数组，则文档将不会过期。 +- 如果文档不包含索引字段，则文档不会过期。 + +## 四、删除索引 + +删除索引的语法比较简单，只需要调用 `dropIndex` 方法，可以传入索引的名称也可以传入索引的定义，示例如下： + +``` +db.user.dropIndex("name_-1") +db.user.dropIndex({ name: -1,birthday: 1}) +``` + +如果想要删除全部的索引，则可以调用 `dropIndexes` 方法，需要注意的是建立在 `_id` 上的默认索引是不会被删除的。 + +```shell +db.collection.dropIndexes() +``` + +另外这个命令会获取对应数据库的写锁，并会阻塞其他操作，直到索引删除完成。 + +## 五、EXPLAIN + +### 5.1 输出参数 + +MongoDB 的 `explain()` 方法和 MySQL 的 explain 关键字一样，都是用于显示执行计划的相关信息。示例如下： + +```shell +db.user.find({name:"heibai"},{name:1,age:1}).sort({ name:1}).explain() +``` + +此时执行计划的部分输出如下： + +```json +"inputStage" : { + "stage" : "FETCH", + "inputStage" : { + "stage" : "IXSCAN", + "keyPattern" : { + "name" : -1, + "birthday" : 1 + }, + "indexName" : "name_-1_birthday_1", + "isMultiKey" : false, + "multiKeyPaths" : { + "name" : [ ], + "birthday" : [ ] + }, + "isUnique" : true, + "isSparse" : true, + "isPartial" : false, + "indexVersion" : 2, + "direction" : "backward", + "indexBounds" : { + "name" : [ + "[\"heibai\", \"heibai\"]" + ], + "birthday" : [ + "[MaxKey, MinKey]" + ] + } + } +} +``` + +输出结果中内层的 inputStage.stage 的值为 `IXSCAN`，代表此时用到了索引进行扫描，并且 indexName 字段显示了对应的索引为 name_-1_birthday_1。而外层 inputStage.stage 的值为 `FETCH`，代表除了从索引上获取数据外，还需要去对应的文档上获取数据，因为 age 信息并不存储在索引上。这个输出可以证明 MongoDB 是支持前缀索引的，且单键索引支持双向扫描。 + +### 5.2 覆盖索引 + +这里我们对上面的查询语句略做修改，不返回 age 字段和默认的 _id 字段，语句如下： + +```shell +db.user.find({name:"heibai"},{_id:0, name:1}).sort({ name:1 }).explain() +``` + +此时输出结果如下。可以看到该查询少了一个 `FETCH` 阶段。代表此时只需要扫描索引就可以获取到所需的全部信息，这种情况下 name_-1_birthday_1 索引就是这一次查询操作的覆盖索引。 + +```json +"inputStage" : { + "stage" : "IXSCAN", + "keyPattern" : { + "name" : -1, + "birthday" : 1 + }, + "indexName" : "name_-1_birthday_1", + "isMultiKey" : false, + "multiKeyPaths" : { + "name" : [ ], + "birthday" : [ ] + }, + "isUnique" : true, + "isSparse" : true, + "isPartial" : false, + "indexVersion" : 2, + "direction" : "backward", + "indexBounds" : { + "name" : [ + "[\"heibai\", \"heibai\"]" + ], + "birthday" : [ + "[MaxKey, MinKey]" + ] + } +} +``` + + + +## 参考资料 + +1. 官方文档：[Indexes](https://docs.mongodb.com/manual/indexes/) 、[sort-on-multiple-fields](https://docs.mongodb.com/manual/tutorial/sort-results-with-indexes/#sort-on-multiple-fields) +2. Kristina Chodorow . MongoDB权威指南（第2版）. 人民邮件出版社 . 2014-01 + diff --git a/notes/MongoDB_聚合.md b/notes/MongoDB_聚合.md index e69de29..342b9a5 100644 --- a/notes/MongoDB_聚合.md +++ b/notes/MongoDB_聚合.md @@ -0,0 +1,367 @@ +# MongoDB 聚合操作 + +## 一、聚合简述 + +在日常开发中，我们通常需要对存储数据进行聚合分析后，再返回给客户端。MongoDB提供了三种聚合的方式，分别是聚合管道，map-reduce 函数和单用途聚合方法。 + +## 二、聚合管道 + +MongoDB 的聚合操作类似于流水线处理，文档会依次进入多个管道阶段并执行相应的操作。这里先插入部分演示数据： + +```shell +db.employees.insertMany([ + { + emp_no: 10001, + name: {firstName:"Georgi",lastName:"Facello"}, + age: 26, + gender: "F", + hobby: ["basketball", "football"] + }, + { + emp_no: 10002, + name: {firstName:"Bezalel",lastName:"Simmel"}, + age: 32, + gender: "M", + hobby: ["basketball", "tennis"] + }, + { + emp_no: 10003, + name: {firstName:"Parto",lastName:"Bamford"}, + age: 46, + gender: "M", + hobby: [] + }, + { + emp_no: 10004, + name: {firstName:"Chirstian",lastName:"Koblick"}, + age: 40, + gender: "F", + hobby: ["football", "tennis"] + } +]) +``` + +一个简单的聚合操作如下，这个聚合操作会经过两个阶段的数据处理： + ++ 第一个管道阶段为 $match：会筛选出所有性别值为 F 的雇员的文档，然后输出到下一个管道操作中； ++ 第二个管道阶段为 $project：用于定义返回的字段内容，这里返回 fullname 字段，它由 firstName + lastName 组成。 + +```shell +db.employees.aggregate([ + { $match: { gender: "F" } }, + { $project: + { fullName: + { $concat: ["$name.firstName", "$name.lastName"]} + } + } +]) +``` + +所以最后的输出结果如下： + +```json +{ + "_id" : ObjectId("5d3fe6488ba16934ccce999d"), + "fullName" : "GeorgiFacello" +}, +{ + "_id" : ObjectId("5d3fe6488ba16934ccce99a0"), + "fullName" : "ChirstianKoblick" +} +``` + +在当前最新的 MongoDB 4.x 中，MongoDB 提供了将近 30 个管道阶段，用于满足不同数据处理的需求。以下主要介绍常用几个管道阶段，如果想要了解全部的管道阶段，可以参见官方文档：[Aggregation Pipeline Stages](https://docs.mongodb.com/manual/reference/operator/aggregation-pipeline/) + +### 1.1 $match + +$match 主要用于筛选符合条件的数据，通常应该把 $match 放在尽量靠前的位置，这时候它会利用索引来优化查询，同时还可以降低后续阶段所需要处理的数据量。示例如下： + +```shell +db.employees.aggregate([ + { $match: { gender: "F" } } +]) +``` + +### 1.2 $project + +$project 主要用于定义需要返回的字段，1 代表包含该字段，0 代表不包含，除了可以作用于顶层字段外，还可以作用于内嵌字段。同时 $project 还支持使用表达式将多个字段或变量进行组合，并作为新的字段返回。示例如下： + +```shell +db.employees.aggregate([ + { + $project: { + _id: 0, + "name.firstName": 1, + gender: 1, + fullName: { $concat: ["$name.firstName", "$name.lastName"] } + } + } +]) +``` + +从 MongoDB 3.6 开始，还可以在聚合表达式中使用 $project + 变量 REMOVE 来按照条件定义返回字段，设置为 REMOVE 变量的字段将会从 $projection 的输出中排除。示例如下： + +```shell +db.employees.aggregate([ + { + $project: { + hobby: { + $cond: { + if: { $eq: [ [], "$hobby" ] }, + then: "$$REMOVE", + else: "$hobby" + } + } + } + } +]) +``` + +这里判断当文档的 hobby 属性为空数组时，则其 hobby 属性不会被输出到下一个管道阶段。 + +### 1.3 $group + +$group 管道阶段和大多数关系型数据库中的 group by 字句功能类似，都是用于分组计算。示例如下： + +```json +db.employees.aggregate( + [ + { $group : { + _id : "$gender", + totalAge: { $sum: "$age"}, + avgAge: { $avg: "$age" }, + count: { $sum: 1 } + } + } + ] +) +``` + +上面的语句会按照性别进行分组，并计算分组后两组人的总年龄、平均年龄和总人数，输出如下： + +```json +{ + "_id" : "M", + "totalAge" : 78, + "avgAge" : 39, + "count" : 2 +}, +{ + "_id" : "F", + "totalAge" : 66, + "avgAge" : 33, + "count" : 2 +} +``` + +如果你想计算所有员工的年龄总和、平均年龄、以及员工总数，则可以将 $group 管道阶段的 _id 字段设置为 null ，语句如下： + +```shell +db.employees.aggregate( + [ + { $group : { + _id : null, + totalAge: { $sum: "$age"}, + avgAge: { $avg: "$age" }, + count: { $sum: 1 } + } + } + ] +) + +# 输出如下 +{ + "_id" : null, + "totalAge" : 144, + "avgAge" : 36, + "count" : 4 +} +``` + +### 1.4 $unwind + +$unwind 将文档按照数组中的每一个元素进行拆分，类似于大多数流式计算中的 flatMap 算子。其语法格式如下： + +```shell +{ + $unwind: + { + path: , + includeArrayIndex: , + preserveNullAndEmptyArrays: + } +} +``` + ++ **path**：用于展开的数组字段； + ++ **includeArrayIndex**：用于显示对应元素在原数组的位置信息； + ++ **preserveNullAndEmptyArrays**：如果用于展开的字段值为 null 或空数组时，则对应的文档不会被输出到下一阶段。如果想要输出到下一阶段则需要将该属性设置为 true。示例语句如下： + +```json +db.employees.aggregate( [ + {$project: {_id: 0, emp_no: 1, hobby:1}}, + { $unwind: + { path: "$hobby", + includeArrayIndex: "arrayIndex", + preserveNullAndEmptyArrays: true + } + } +] ) +``` + +此时输出内容如下。如果 preserveNullAndEmptyArrays 的值为 false 或者没有设置，则 10003 这条数据不会被输出。 + +```json +{"emp_no":10001,"hobby":"basketball","arrayIndex":0}, +{"emp_no":10001,"hobby":"football","arrayIndex":1}, + +{"emp_no":10002,"hobby":"basketball","arrayIndex":0}, +{"emp_no":10002,"hobby":"tennis","arrayIndex":1}, + +{"emp_no":10003,"arrayIndex":null}, + +{"emp_no":10004,"hobby":"football","arrayIndex":0}, +{"emp_no":10004,"hobby":"tennis","arrayIndex":1} +``` + +### 1.5 $sort + +$sort 主要用于排序操作，需要注意的是如果可以，应当尽量将该操作放置在管道的第一阶段，从而可以利用索引进行排序，否则就需要使用内存进行排序，这时排序操作就会变得相当昂贵，需要额外的内存和计算资源的开销。 + +示例如下： + +```shell +db.employees.aggregate([ + {$skip: 2} , + {$sort: {age: 1}}, + {$limit: 10} +]) +``` + +### 1.6 $limit + +限制返回文档的数量。 + +### 1.7 $skip + +跳过一定数量的文档。 + +### 1.8 $lookup + +```shell +db.titles.insertMany([ + { + emp_no: 10001, + title: "Senior Engineer" + }, + { + emp_no: 10002, + title: "Staff" + }, + { + emp_no: 10003, + title: "Senior Engineer" + }, + { + emp_no: 10004, + title: "Engineer" + }, + { + emp_no: 10004, + title: "Senior Engineer " + } +]) +``` + +```shell +db.employees.aggregate([ + { + $lookup: + { + from: "titles", + localField: "emp_no", + foreignField: "emp_no", + as: "emp_title" + } + } +]) + + +db.employees.aggregate([ + { + $lookup: + { + from: "titles", + let: { gender: "$gender"}, + pipeline: [ + { $match: + { $expr: { $eq: [ "$$gender","M"]}} + } + ], + as: "emp_title" + } + } +]) + + + +db.employees.aggregate([ + { + $lookup: + { + from: "titles", + pipeline: [ + { $match: + { $expr: { $eq: [ "$title","M"]}} + } + ], + as: "emp_title" + } + } +]) +``` + +### 1.9 $out + +$out 用于将数据写入指定的集合，它必须是管道中的最后一个阶段。如果指定的集合不存在，则会自动新建；如果指定的集合存在，它会覆盖原有集合的数据。其实际的步骤如下： + +- 创建临时集合； +- 将索引从现有集合复制到临时集合； +- 将文档插入临时集合中； +- 调用 db.collection.renameCollection(target, true) 方法将临时集合重命名为目标集合。 + +$out 的使用示例如下： + +```shell +db.employees.aggregate([ + { $out: "emps"} +]) +``` + +### 1.10 自动优化 + +在大多数情况下 MongoDB 会按照我们定义管道的先后顺序执行管道操作，但是某些情况下，MongoDB 会在不影响结果的前提下，改变管道执行顺序，从而获得更好的性能表现。常见的优化策略如下： + +#### $project or $addFields + $match + +当投影操作后面有匹配操作时，MongoDB 会将 $match 阶段中不需要进行投影操作的字段的过滤条件提前到投影操作前执行。 + +#### $sort + $match + +当排序操作后面有匹配操作时，会将匹配操作提前，以减少需要排序的数据量。 + +#### $project + $skip + +当投影操作后面有跳过操作时，会先执行跳过操作，从而减少需要进行投影操作的数据量。 + +#### $sort + $limit + +当排序操作在限制操作之前时，如果没有中间阶段会修改文档数量 (例如 $unwind，$group)，优化器会将 $limit 合并到 $sort中。如果在 $sort 和 $limit 之间存在修改文档数量的管道阶段，MongoDB 将不会执行合并。 + +了解这些优化策略可以有助于我们在开发中合理设置管道的顺序。想要了解全部的优化策略，可以参阅 MongoDB 的官方文档：[Aggregation Pipeline Optimization](https://docs.mongodb.com/manual/core/aggregation-pipeline-optimization/) + +## 三、MapReduce + +## 四、单用途聚合方法 \ No newline at end of file diff --git a/pictures/b-tree.png b/pictures/b-tree.png new file mode 100644 index 0000000000000000000000000000000000000000..1b13b0fa1d151f08d5d9d710b213719c7033d50e GIT binary patch literal 29787 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