gomog/manual/QUERY_OPERATORS.md

# Gomog 查询操作符参考文档

**版本**: v1.0.0-alpha  
**最后更新**: 2026-03-14

---

## 📖 目录

1. [比较操作符](#比较操作符)
2. [逻辑操作符](#逻辑操作符)
3. [元素操作符](#元素操作符)
4. [数组操作符](#数组操作符)
5. [正则表达式操作符](#正则表达式操作符)
6. [位运算操作符](#位运算操作符)
7. [使用示例](#使用示例)

---

## 比较操作符

### $eq - 等于

匹配等于指定值的文档。

**语法**:
```json
{"field": {"$eq": <value>}}
// 或简写
{"field": <value>}
```

**示例**:
```json
{"age": {"$eq": 30}}
// 等价于
{"age": 30}
```

### $ne - 不等于

匹配不等于指定值的文档。

**语法**:
```json
{"field": {"$ne": <value>}}
```

**示例**:
```json
{"status": {"$ne": "inactive"}}
```

### $gt - 大于

匹配大于指定值的文档。

**语法**:
```json
{"field": {"$gt": <value>}}
```

**示例**:
```json
{"price": {"$gt": 100}}
```

### $gte - 大于等于

匹配大于或等于指定值的文档。

**语法**:
```json
{"field": {"$gte": <value>}}
```

**示例**:
```json
{"age": {"$gte": 18}}
```

### $lt - 小于

匹配小于指定值的文档。

**语法**:
```json
{"field": {"$lt": <value>}}
```

**示例**:
```json
{"score": {"$lt": 60}}
```

### $lte - 小于等于

匹配小于或等于指定值的文档。

**语法**:
```json
{"field": {"$lte": <value>}}
```

**示例**:
```json
{"quantity": {"$lte": 10}}
```

### $in - 在数组中

匹配值在指定数组中的文档。

**语法**:
```json
{"field": {"$in": [<value1>, <value2>, ...]}}
```

**示例**:
```json
{"status": {"$in": ["active", "pending"]}}
{"age": {"$in": [18, 25, 30]}}
```

### $nin - 不在数组中

匹配值不在指定数组中的文档。

**语法**:
```json
{"field": {"$nin": [<value1>, <value2>, ...]}}
```

**示例**:
```json
{"category": {"$nin": ["deleted", "archived"]}}
```

---

## 逻辑操作符

### $and - 与

匹配所有条件都满足的文档。

**语法**:
```json
{"$and": [{"condition1"}, {"condition2"}, ...]}
```

**示例**:
```json
{
  "$and": [
    {"age": {"$gte": 18}},
    {"status": {"$eq": "active"}}
  ]
}
// 可简写为
{"age": {"$gte": 18}, "status": "active"}
```

### $or - 或

匹配至少一个条件满足的文档。

**语法**:
```json
{"$or": [{"condition1"}, {"condition2"}, ...]}
```

**示例**:
```json
{
  "$or": [
    {"age": {"$lt": 18}},
    {"senior": true}
  ]
}
```

### $not - 非

反转条件的结果。

**语法**:
```json
{"field": {"$not": {<expression>}}}
```

**示例**:
```json
{"price": {"$not": {"$gt": 100}}}
```

### $nor - 或非

匹配所有条件都不满足的文档。

**语法**:
```json
{"$nor": [{"condition1"}, {"condition2"}, ...]}
```

**示例**:
```json
{
  "$nor": [
    {"status": "draft"},
    {"archived": true}
  ]
}
```

---

## 元素操作符

### $exists - 字段存在

匹配包含或不包含指定字段的文档。

**语法**:
```json
{"field": {"$exists": <boolean>}}
```

**示例**:
```json
// 包含 email 字段的文档
{"email": {"$exists": true}}

// 不包含 phone 字段的文档
{"phone": {"$exists": false}}
```

### $type - 类型检查

匹配字段类型等于指定类型的文档。

**语法**:
```json
{"field": {"$type": <BSON type>}}
```

**支持的类型**:
- `"string"`: 字符串
- `"int"` / `"long"`: 整数
- `"double"`: 浮点数
- `"bool"`: 布尔值
- `"array"`: 数组
- `"object"`: 对象
- `"null"`: null 值
- `"date"`: 日期

**示例**:
```json
{"age": {"$type": "int"}}
{"data": {"$type": "array"}}
{"value": {"$type": "null"}}
```

---

## 数组操作符

### $all - 包含所有

匹配数组包含所有指定元素的文档。

**语法**:
```json
{"field": {"$all": [<value1>, <value2>, ...]}}
```

**示例**:
```json
{"tags": {"$all": ["mongodb", "database", "nosql"]}}
```

### $elemMatch - 元素匹配

匹配数组中至少有一个元素满足条件的文档。

**语法**:
```json
{"field": {"$elemMatch": {<query>}}}
```

**示例**:
```json
// 数组中有元素大于 80
{"scores": {"$elemMatch": {"$gt": 80}}}

// 数组中有对象满足多个条件
{"results": {"$elemMatch": {
  "product": "laptop",
  "price": {"$lt": 1000}
}}}
```

### $size - 数组大小

匹配数组长度等于指定值的文档。

**语法**:
```json
{"field": {"$size": <number>}}
```

**示例**:
```json
{"tags": {"$size": 3}}
```

---

## 正则表达式操作符

### $regex - 正则匹配

使用正则表达式匹配字符串。

**语法**:
```json
{"field": {"$regex": <pattern>, "$options": <options>}}
```

**选项**:
- `i`: 不区分大小写
- `m`: 多行匹配
- `s`: 单行模式（`.` 匹配换行）
- `x`: 扩展模式（忽略空白）

**示例**:
```json
// 以 "john" 开头
{"name": {"$regex": "^john"}}

// 包含 "test"，不区分大小写
{"title": {"$regex": "test", "$options": "i"}}

// 邮箱格式验证
{"email": {"$regex": "^[\\w-\\.]+@([\\w-]+\\.)+[\\w-]{2,4}$"}}
```

---

## 位运算操作符

### $bitsAllClear - 所有指定位为 0

匹配所有指定位都为 0 的文档。

**语法**:
```json
{"field": {"$bitsAllClear": <bitmask>}}
```

**示例**:
```json
{"flags": {"$bitsAllClear": 8}}  // 第 4 位为 0
```

### $bitsAllSet - 所有指定位为 1

匹配所有指定位都为 1 的文档。

**语法**:
```json
{"field": {"$bitsAllSet": <bitmask>}}
```

**示例**:
```json
{"permissions": {"$bitsAllSet": 7}}  // 第 1-3 位都为 1
```

### $bitsAnyClear - 任意指定位为 0

匹配任意指定位为 0 的文档。

**语法**:
```json
{"field": {"$bitsAnyClear": <bitmask>}}
```

**示例**:
```json
{"status": {"$bitsAnyClear": 15}}
```

### $bitsAnySet - 任意指定位为 1

匹配任意指定位为 1 的文档。

**语法**:
```json
{"field": {"$bitsAnySet": <bitmask>}}
```

**示例**:
```json
{"flags": {"$bitsAnySet": 1}}  // 第 1 位为 1
```

---

## 特殊操作符

### $expr - 表达式

允许在查询中使用聚合表达式。

**语法**:
```json
{"$expr": {<expression>}}
```

**示例**:
```json
// 比较两个字段
{"$expr": {"$gt": ["$salary", "$expenses"]}}

// 复杂计算
{"$expr": {"$lt": [{"$multiply": ["$price", "$quantity"]}, 100]}}
```

### $jsonSchema - JSON Schema 验证

使用 JSON Schema 验证文档。

**语法**:
```json
{"$jsonSchema": {<schema>}}
```

**示例**:
```json
{
  "$jsonSchema": {
    "bsonType": "object",
    "required": ["name", "age"],
    "properties": {
      "name": {"bsonType": "string"},
      "age": {"bsonType": "int", "minimum": 0}
    }
  }
}
```

### $mod - 模运算

匹配除以指定数的余数。

**语法**:
```json
{"field": {"$mod": [<divisor>, <remainder>]}}
```

**示例**:
```json
// 偶数
{"count": {"$mod": [2, 0]}}

// 除以 5 余 3
{"number": {"$mod": [5, 3]}}
```

### $where - JavaScript 表达式

使用 JavaScript 表达式进行匹配（性能较低）。

**语法**:
```json
{"$where": "<javascript>"}
```

**示例**:
```json
{"$where": "this.age > 18 && this.status === 'active'"}
```

---

## 使用示例

### 组合查询

```json
{
  "age": {"$gte": 18, "$lte": 65},
  "status": "active",
  "role": {"$in": ["admin", "user"]},
  "$or": [
    {"verified": true},
    {"score": {"$gte": 80}}
  ]
}
```

### 嵌套字段查询

```json
{
  "address.city": "Beijing",
  "contact.email": {"$regex": "@example.com$"}
}
```

### 数组查询

```json
{
  "skills": {"$all": ["Go", "Python"]},
  "projects": {"$elemMatch": {
    "status": "completed",
    "budget": {"$gte": 10000}
  }}
}
```

### 复杂逻辑查询

```json
{
  "$or": [
    {
      "$and": [
        {"age": {"$gte": 18}},
        {"senior": true}
      ]
    },
    {
      "$and": [
        {"age": {"$gte": 65}},
        {"retired": true}
      ]
    }
  ],
  "status": {"$ne": "banned"}
}
```

---

**维护者**: Gomog Team  
**许可证**: MIT