// 索引设置
PUT /my_index
{
  "settings": {
    "index": {
      "number_of_shards": 10, // 分片设置，根据未来规模增长合理评估分片数量
      "number_of_replicas": 1 // 副本设置，根据高可用和并发要求设置
    }
  },
  "mappings": {
    "properties": {
     ...
  }
}

// Mappping 设置
PUT /my-index
{
  "mappings": {
    "properties": {
      "category": {
        "type": "keyword"
      },    
      "title": {
        "type": "text"
      },
      "title_vector": {
        "type": "dense_vector",
        "dims": 768, // 向量维度
        "similarity": "cosine",  // 向量相似度算法
        "index_options": {
          "type": "hnsw",// 索引算法
          "m": 16,  // HNSW 图中每个节点的最大连接数
          "ef_construction": 100  // 构建HNSW时，为每个新节点考察的候选邻居数量，影响构建索引的质量和速度
        }        
      }    
    }
  }
}

// 批量写入
POST /_bulk
{ "index" : { "_index" : "my-index", "_id" : "1" } }
{ "category":"cat", "title": "慵懒的猫", "title_vector": [0.1, 0.2, ... ] }
{ "index" : { "_index" : "my-index", "_id" : "2" } }
{ "category":"dog", "title": "遛弯的狗", "title_vector": [0.3, 0.4, ... ] }
//... 更多数据 ...

// 索引设置
PUT /my_index
{
  "settings": {
    "index": {
      "number_of_shards": 10, // 分片设置，根据未来规模增长合理评估分片数量
      "number_of_replicas": 0, // 初期批量写入时，临时关闭副本，写完再恢复
      "refresh_interval": -1 // 通过禁止自动刷新，来提升写入性能
    }
  },
  "mappings": {
    "properties": {
     ...
  }
}

// 向量搜索 - 只需召回少量非text字段
GET /my-index/_search
{
  "size" : 3,
  "knn": {
      "field": "title_vector",
      "query_vector": [-5, 9, -12，...],
      "k": 10, // 返回的 top k 结果数量
      "num_candidates": 100  // 指定每个分片上要检索的候选向量数量    
  }
  "fields": ["category"],
  "_source": false 
}

// 向量搜索 - 召回字段较多或有text字段时
GET /my-index/_search
{
  "size" : 3,
  "knn": {
      "field": "title_vector",
      "query_vector": [-5, 9, -12，...],
      "k": 10, // 返回的 top k 结果数量
      "num_candidates": 100  // 指定每个分片上要检索的候选向量数量    
  }
  "_source": {
    "excludes": ["title_vector"] // 排除掉向量字段
    // "excludes": ["*_vector"] // 使用通配符，例如排除所有以 vector 开头的字段
    // "_source": ["doc_id", "title"] // 明确列出需要返回的业务字段    
    // "_source": false // 完全不返回原始文档数据,拿到文档 _id 后，会去另一个数据库如 MySQL根据查询详情
  }
}


// Mapping 设置（向量采用 int8 量化）
PUT /my-quantized-index
{
  "mappings": {
    "properties": {
      "title": {
        "type": "text",
      },
      "title_vector": {
        "type": "dense_vector",
        "dims": 768,           
        "index": true,         
        "similarity": "cosine", 
        "index_options": {
          "type": "int8_hnsw", // 启用 8位标量量化 HNSW 索引
          "m": 16,
          "ef_construction": 100
        }
      }
    }
  }
}

// 向量搜索（过采样）
GET my-quantized-index/_search
{
  "knn": {
    "field": "title_vector",
    "query_vector": [0.15, 0.50, ..., 0.05], // 查询向量
    "k": 10,                  // 返回的 top k 结果数
    "num_candidates": 100,    // 需要 >= k
    "rescore_vector": {
      "oversample": 2.0 // 过采样系数
    }
  }
}

// 索引创建时，设置预加载
PUT /my-preloaded-index
{
  "settings": {
    "index.store.preload": ["ve*"], // 预加载
    //"index.store.preload": ["vex", "vec"], // 预加载，也可以精细化指定
    "index.store.type": "mmapfs" // 将索引文件映射到进程虚拟内存地址空间
  },
  "mappings": {
    ...
  }
}

index.store.preload: ["ve*"] // 预加载特定数据文件到 Page Cache
index.store.type: mmapfs // 将索引文件映射到进程虚拟内存地址空间

// 1. 关闭索引
POST /my-existing-index/_close

// 2. 更新索引设置
PUT /my-existing-index/_settings
{
  "index.store.preload": ["ve*"] // 预加载特定数据文件到 Page Cache
  "index.store.type": "mmapfs" // 将索引文件映射到进程虚拟内存地址空间  
}

// 3. 重新打开索引。打开过程中会触发预加载操作，打开速度会变慢。
POST /my-existing-index/_open

// 1. 关闭索引
POST /my-index/_close

// 2. 更新索引设置
PUT /my-index/_settings
{
    "merge.policy.floor_segment": "300mb",   // 段的最小值
    "merge.policy.max_merged_segment": "10g" // 段的最大值
}

// 3. 重新打开索引
POST my-index/_open

// 前置过滤搜索
GET  /my-index/_search
{
    "knn":{
        "field":"title_vector",
        "query_vector": [-5, 9, -12，...], 
        "k": 10, 
        "num_candidates": 100,
        "filter":{
            "term":{
                "category":"cat"
            }
        }
    }
}

// 预过滤优化
PUT /my-index/_settings
{
    "index.query.knn.optimize_prefilter_enable": "true"   // 启用预过滤优化，提升前置过滤的性能
}


// 采用 script_score 进行向量暴力搜索举例
GET my-index/_search
{
  "query": {
    "script_score": {
      "query" : {
        "bool" : {
          "filter" : {
            "term" : {
              "status" : "published"
            }
          }
        }
      },
      "script": {
        // 调用内置函数计算余弦相似度
        // title_vector 是文档中的向量
        // params.query_vector 是外部传入的查询向量
        // + 1.0 是为了保证得分为正数（余弦相似度范围是 -1 到 1）     
        "source": "cosineSimilarity(params.query_vector, 'title_vector') + 1.0",
        "params": {
          "query_vector": [4, 3.4, -0.2]
        }
      }
    }
  }
}