API 快速参考 (v3.0)

基础搜索

POST /search/
{
  "query": "芭比娃娃",
  "size": 20
}

---

精确匹配过滤

{
  "filters": {
    "categoryName_keyword": "玩具",          // 单值
    "brandName_keyword": ["乐高", "美泰"]    // 多值（OR）
  }
}

---

范围过滤

{
  "range_filters": {
    "price": {
      "gte": 50,    // >=
      "lte": 200    // <=
    }
  }
}

操作符: gte (>=), gt (>), lte (lt (

---

分面搜索

简单模式

{
  "facets": ["categoryName_keyword", "brandName_keyword"]
}

高级模式

{
  "facets": [
    {"field": "categoryName_keyword", "size": 15},
    {
      "field": "price",
      "type": "range",
      "ranges": [
        {"key": "0-50", "to": 50},
        {"key": "50-100", "from": 50, "to": 100}
      ]
    }
  ]
}

---

排序

{
  "sort_by": "min_price",
  "sort_order": "asc"    // asc 或 desc
}

---

布尔表达式

{
  "query": "玩具 AND (乐高 OR 芭比) ANDNOT 电动"
}

操作符优先级: () > ANDNOT > AND > OR > RANK

---

分页

{
  "size": 20,      // 每页数量
  "from": 0        // 偏移量（第1页=0，第2页=20）
}

---

完整示例

POST /search/
{
  "query": "玩具",
  "size": 20,
  "from": 0,
  "filters": {
    "categoryName_keyword": ["玩具", "益智玩具"]
  },
  "range_filters": {
    "price": {"gte": 50, "lte": 200}
  },
  "facets": [
    {"field": "brandName_keyword", "size": 15},
    {"field": "categoryName_keyword", "size": 15}
  ],
  "sort_by": "min_price",
  "sort_order": "asc"
}

---

响应格式

{
  "hits": [
    {
      "_id": "12345",
      "_score": 8.5,
      "_source": {...}
    }
  ],
  "total": 118,
  "max_score": 8.5,
  "took_ms": 45,
  "facets": [
    {
      "field": "categoryName_keyword",
      "label": "商品类目",
      "type": "terms",
      "values": [
        {
          "value": "玩具",
          "label": "玩具",
          "count": 85,
          "selected": false
        }
      ]
    }
  ]
}

---

其他端点

POST /search/image
{
  "image_url": "https://example.com/image.jpg",
  "size": 20
}

GET /search/suggestions?q=芭&size=5

GET /search/instant?q=玩具&size=5

GET /search/{doc_id}

GET /admin/health
GET /admin/config
GET /admin/stats

---

Python 快速示例

import requests

result = requests.post('http://localhost:6002/search/', json={
    "query": "玩具",
    "filters": {"categoryName_keyword": "玩具"},
    "range_filters": {"price": {"gte": 50, "lte": 200}},
    "facets": ["brandName_keyword"],
    "sort_by": "min_price",
    "sort_order": "asc"
}).json()

print(f"找到 {result['total']} 个结果")

---

JavaScript 快速示例

const result = await fetch('http://localhost:6002/search/', {
    method: 'POST',
    headers: {'Content-Type': 'application/json'},
    body: JSON.stringify({
        query: "玩具",
        filters: {categoryName_keyword: "玩具"},
        range_filters: {price: {gte: 50, lte: 200}},
        facets: ["brandName_keyword"],
        sort_by: "min_price",
        sort_order: "asc"
    })
}).then(r => r.json());

console.log(`找到 ${result.total} 个结果`);

---

详细文档: API_DOCUMENTATION.md
更多示例: API_EXAMPLES.md
在线文档: http://localhost:6002/docs