@gordon.gan/specflow 1.4.0-beta → 1.4.1

package/skills/database/elasticsearch/references/01-query-dsl-fulltext.md

@@ -0,0 +1,162 @@
+# 全文查询 (Full Text Queries)
+
+全文查询会对查询文本进行分词，然后搜索倒排索引。这些查询会计算相关性分数 (`_score`)。
+
+## match — 标准全文匹配
+
+```bash
+# 基本 match (默认 OR 逻辑)
+GET /products/_search
+{
+  "query": {
+    "match": {
+      "title": "apple macbook"
+    }
+  }
+}
+
+# AND 逻辑 (必须匹配所有词项)
+GET /products/_search
+{
+  "query": {
+    "match": {
+      "title": {
+        "query": "apple macbook",
+        "operator": "and"
+      }
+    }
+  }
+}
+
+# minimum_should_match (至少匹配 75% 词项)
+GET /products/_search
+{
+  "query": {
+    "match": {
+      "title": {
+        "query": "apple macbook pro",
+        "minimum_should_match": "75%"
+      }
+    }
+  }
+}
+```
+
+**业务场景**：商品搜索、文章搜索、文档搜索。用户输入关键词时自动分词匹配。
+
+## match_phrase — 短语匹配
+
+```bash
+# 精确短语匹配 (顺序必须一致)
+GET /products/_search
+{
+  "query": {
+    "match_phrase": {
+      "title": "macbook pro"
+    }
+  }
+}
+
+# 带 slop 的短语匹配 (允许词项间插入 slop 个词)
+GET /products/_search
+{
+  "query": {
+    "match_phrase": {
+      "title": {
+        "query": "macbook pro",
+        "slop": 1
+      }
+    }
+  }
+}
+```
+
+**业务场景**：搜索"红米手机"不希望匹配"红色小米手机"；搜索完整书名/产品名。
+
+## multi_match — 多字段匹配
+
+```bash
+# 同时在 title 和 description 中搜索
+GET /products/_search
+{
+  "query": {
+    "multi_match": {
+      "query": "轻薄笔记本",
+      "fields": ["title", "description"]
+    }
+  }
+}
+
+# 带权重 (title 字段权重 2 倍)
+GET /products/_search
+{
+  "query": {
+    "multi_match": {
+      "query": "轻薄笔记本",
+      "fields": ["title^2", "description", "tags^0.5"]
+    }
+  }
+}
+
+# type 说明:
+# - best_fields (默认): 取最佳匹配字段分数
+# - most_fields: 合并所有匹配字段分数
+# - cross_fields: 将词项拆分到多字段 (适合姓名搜索)
+GET /products/_search
+{
+  "query": {
+    "multi_match": {
+      "query": "Will Smith",
+      "fields": ["first_name", "last_name"],
+      "type": "cross_fields"
+    }
+  }
+}
+```
+
+**业务场景**：搜索框同时匹配标题、描述、标签等字段；人名搜索。
+
+## query_string — 完整查询语法
+
+```bash
+# 支持 AND/OR/NOT, 通配符, 正则等
+GET /products/_search
+{
+  "query": {
+    "query_string": {
+      "query": "title:(apple AND macbook) AND price:[10000 TO 20000]",
+      "default_operator": "and"
+    }
+  }
+}
+
+# 支持短语和多字段
+GET /products/_search
+{
+  "query": {
+    "query_string": {
+      "query": "\"macbook pro\" OR \"iphone\"",
+      "fields": ["title^2", "description"]
+    }
+  }
+}
+```
+
+**注意**：query_string 解析语法错误会抛出异常，生产环境推荐用 `simple_query_string`。
+
+## simple_query_string — 安全版查询语法
+
+```bash
+GET /products/_search
+{
+  "query": {
+    "simple_query_string": {
+      "query": "\"macbook pro\" +apple -samsung",
+      "fields": ["title", "description"],
+      "default_operator": "or"
+    }
+  }
+}
+```
+
+**支持语法**：`+` (AND), `|` (OR), `-` (NOT), `"` (短语), `*` (前缀)。语法错误不会抛异常。

package/skills/database/elasticsearch/references/02-query-dsl-term.md

@@ -0,0 +1,210 @@
+# 精确查询与复合查询
+
+精确查询不会对搜索词进行分词，直接匹配倒排索引中的精确值。
+
+## term / terms — 精确值匹配
+
+```bash
+# 精确匹配 keyword 字段 (不要对 text 字段用 term!)
+GET /products/_search
+{
+  "query": {
+    "term": {
+      "tags": "electronics"
+    }
+  }
+}
+
+# 多值匹配
+GET /products/_search
+{
+  "query": {
+    "terms": {
+      "tags": ["electronics", "laptop"]
+    }
+  }
+}
+
+# ids 查询
+GET /products/_search
+{
+  "query": {
+    "ids": {
+      "values": ["1", "2", "3"]
+    }
+  }
+}
+```
+
+**⚠️ 常见陷阱**：`term` 查询对 `text` 字段几乎永远不匹配，因为 text 字段被分词后存储的是词项而非完整内容。
+
+## range — 范围查询
+
+```bash
+# 数值范围
+GET /products/_search
+{
+  "query": {
+    "range": {
+      "price": { "gte": 10000, "lte": 20000 }
+    }
+  }
+}
+
+# 日期范围 (支持日期数学)
+GET /products/_search
+{
+  "query": {
+    "range": {
+      "created_at": { "gte": "now-7d/d", "lte": "now" }
+    }
+  }
+}
+
+# 日期数学: now-1h, now+1d, now/d, now-1M/M, 2024-01-01||+1y
+```
+
+## exists — 存在性检查
+
+```bash
+# 查找有 description 字段的文档
+GET /products/_search
+{
+  "query": {
+    "exists": { "field": "description" }
+  }
+}
+
+# 查找没有 description 的文档 (using must_not)
+GET /products/_search
+{
+  "query": {
+    "bool": {
+      "must_not": [
+        { "exists": { "field": "description" } }
+      ]
+    }
+  }
+}
+```
+
+## bool 查询 — 最常用的组合查询
+
+```bash
+# bool 结构: must (AND+算分), filter (AND+缓存), should (OR), must_not (NOT)
+GET /products/_search
+{
+  "query": {
+    "bool": {
+      "must": [
+        { "match": { "title": "轻薄笔记本" } }
+      ],
+      "filter": [
+        { "term": { "status": "active" } },
+        { "range": { "price": { "gte": 3000, "lte": 8000 } } }
+      ],
+      "should": [
+        { "match": { "description": "轻薄" } }
+      ],
+      "minimum_should_match": 1
+    }
+  }
+}
+```
+
+**filter vs query 选择**：
+- filter：精确匹配、范围过滤 → 可缓存，不贡献算分
+- query：全文搜索 → 贡献算分，不可缓存
+
+## nested — 嵌套对象查询
+
+```json
+// mapping 定义
+PUT /orders
+{
+  "mappings": {
+    "properties": {
+      "items": {
+        "type": "nested",
+        "properties": {
+          "product_id": { "type": "keyword" },
+          "quantity": { "type": "integer" },
+          "price": { "type": "float" }
+        }
+      }
+    }
+  }
+}
+```
+
+```bash
+# nested 查询 (保证跨字段关联正确)
+GET /orders/_search
+{
+  "query": {
+    "nested": {
+      "path": "items",
+      "query": {
+        "bool": {
+          "must": [
+            { "term": { "items.product_id": "p100" } },
+            { "range": { "items.quantity": { "gte": 2 } } }
+          ]
+        }
+      }
+    }
+  }
+}
+```
+
+## 其他特殊查询
+
+```bash
+# fuzzy — 模糊纠错
+GET /products/_search
+{
+  "query": {
+    "fuzzy": {
+      "title": {
+        "value": "macbok",
+        "fuzziness": "AUTO",
+        "prefix_length": 2,
+        "transpositions": true
+      }
+    }
+  }
+}
+# "macbok" → 匹配 "macbook"
+
+# wildcard — 通配符 (性能差, 谨慎使用)
+GET /products/_search
+{
+  "query": {
+    "wildcard": {
+      "title.keyword": "Mac*"
+    }
+  }
+}
+
+# regexp — 正则查询 (性能开销大)
+GET /products/_search
+{
+  "query": {
+    "regexp": {
+      "title.keyword": "Macbook\\s(Pro|Air)"
+    }
+  }
+}
+
+# boosting — 权重控制 (降权不排除)
+GET /products/_search
+{
+  "query": {
+    "boosting": {
+      "positive": { "match": { "title": "手机" } },
+      "negative": { "term": { "status": "discontinued" } },
+      "negative_boost": 0.2
+    }
+  }
+}
+```

package/skills/database/elasticsearch/references/03-aggregations-metric.md

@@ -0,0 +1,161 @@
+# 指标聚合 (Metric Aggregations)
+
+指标聚合对文档集中的某个字段进行数值计算，类似于 SQL 聚合函数。
+
+## 基本结构
+
+```json
+{
+  "size": 0,
+  "aggs": {
+    "my_agg_name": {       // 自定义聚合名称
+      "avg": {              // 聚合类型
+        "field": "price"
+      }
+    }
+  }
+}
+```
+
+## 常用指标聚合
+
+### avg — 平均值
+
+```bash
+GET /products/_search
+{
+  "size": 0,
+  "aggs": {
+    "avg_price": {
+      "avg": { "field": "price" }
+    }
+  }
+}
+```
+
+### sum / min / max
+
+```bash
+GET /products/_search
+{
+  "size": 0,
+  "aggs": {
+    "total_revenue": { "sum": { "field": "price" } },
+    "min_price": { "min": { "field": "price" } },
+    "max_price": { "max": { "field": "price" } }
+  }
+}
+```
+
+### stats — 批量统计
+
+```bash
+# 一次性返回 count/min/max/avg/sum
+GET /products/_search
+{
+  "size": 0,
+  "aggs": {
+    "price_stats": {
+      "stats": { "field": "price" }
+    }
+  }
+}
+```
+
+### extended_stats — 扩展统计
+
+```bash
+# 额外返回方差、标准差、总和平方等
+GET /products/_search
+{
+  "size": 0,
+  "aggs": {
+    "price_extended": {
+      "extended_stats": { "field": "price" }
+    }
+  }
+}
+```
+
+### cardinality — 去重计数 (COUNT DISTINCT)
+
+```bash
+GET /products/_search
+{
+  "size": 0,
+  "aggs": {
+    "unique_brands": {
+      "cardinality": {
+        "field": "brand",
+        "precision_threshold": 100   // 精度阈值 (默认 3000)
+      }
+    }
+  }
+}
+```
+
+**说明**：cardinality 基于 HyperLogLog++ 算法，近似去重。`precision_threshold` 越高越精确，但消耗更多内存。
+
+### value_count — 非空值计数
+
+```bash
+GET /products/_search
+{
+  "size": 0,
+  "aggs": {
+    "by_brand": {
+      "terms": { "field": "brand" },
+      "aggs": {
+        "price_count": { "value_count": { "field": "price" } }
+      }
+    }
+  }
+}
+```
+
+通常作为子聚合，用于计算每个桶的样本数。
+
+### percentiles — 百分位
+
+```bash
+GET /products/_search
+{
+  "size": 0,
+  "aggs": {
+    "price_percentiles": {
+      "percentiles": {
+        "field": "price",
+        "percents": [1, 5, 25, 50, 75, 95, 99]
+      }
+    }
+  }
+}
+```
+
+### percentile_ranks — 百分位排名
+
+```bash
+# 值落在指定阈值内的百分比
+GET /products/_search
+{
+  "size": 0,
+  "aggs": {
+    "price_ranks": {
+      "percentile_ranks": {
+        "field": "price",
+        "values": [5000, 10000]
+      }
+    }
+  }
+}
+```
+
+## 业务场景速查
+
+| 聚合 | 典型场景 |
+|------|---------|
+| avg | 商品均价、平均评分、平均响应时间 |
+| sum | 总销售额、总库存量、总访问量 |
+| stats | 批量统计摘要（报表概览） |
+| cardinality | 独立访客 UV、去重品牌数、唯一 IP 数 |
+| percentiles | 价格分布分析、APM P99 延迟、收入分布 |