Elasticsearch 最佳实践指南：索引设计、分片优化与集群配置

elasticsearch-best-practices by mindrally/skills

269 周安装量

42 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/mindrally/skills --skill elasticsearch-best-practices

数据库开发运维性能优化

🇨🇳中文介绍

Elasticsearch 最佳实践

核心原则

基于查询模式设计索引和映射
通过适当的分析和索引优化搜索性能
使用合适的分片大小和集群配置
实施适当的安全和访问控制
监控集群健康状况并优化查询

索引设计

映射最佳实践

定义显式映射，而不是依赖动态映射
为每个字段使用适当的数据类型
对不用于搜索的字段禁用索引
精确匹配使用 keyword 类型，全文搜索使用 text 类型

{ "mappings": { "properties": { "product_id": { "type": "keyword" }, "name": { "type": "text", "analyzer": "standard", "fields": { "keyword": { "type": "keyword", "ignore_above": 256 } } }, "description": { "type": "text", "analyzer": "english" }, "price": { "type": "scaled_float", "scaling_factor": 100 }, "category": { "type": "keyword" }, "tags": { "type": "keyword" }, "created_at": { "type": "date" }, "metadata": { "type": "object", "enabled": false }, "location": { "type": "geo_point" } } } }

字段类型

keyword: 精确值、过滤、聚合、排序
text: 带有分析的全文搜索
date: 带有格式规范的日期/时间值
numeric types: long, integer, short, byte, double, float, scaled_float

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

索引生命周期管理 (ILM)

{
  "policy": {
    "phases": {
      "hot": {
        "min_age": "0ms",
        "actions": {
          "rollover": {
            "max_size": "50gb",
            "max_age": "7d"
          }
        }
      },
      "warm": {
        "min_age": "30d",
        "actions": {
          "shrink": {
            "number_of_shards": 1
          },
          "forcemerge": {
            "max_num_segments": 1
          }
        }
      },
      "delete": {
        "min_age": "90d",
        "actions": {
          "delete": {}
        }
      }
    }
  }
}

匹配查询 (全文搜索)

{
  "query": {
    "match": {
      "description": {
        "query": "wireless bluetooth headphones",
        "operator": "and",
        "fuzziness": "AUTO"
      }
    }
  }
}

词项查询 (精确匹配)

{
  "query": {
    "term": {
      "status": "active"
    }
  }
}

布尔查询 (组合查询)

{
  "query": {
    "bool": {
      "must": [
        { "match": { "name": "laptop" } }
      ],
      "filter": [
        { "term": { "category": "electronics" } },
        { "range": { "price": { "gte": 500, "lte": 2000 } } }
      ],
      "should": [
        { "term": { "brand": "apple" } }
      ],
      "must_not": [
        { "term": { "status": "discontinued" } }
      ]
    }
  }
}

对非评分查询（可缓存）使用 filter 上下文
仅在需要评分时使用 must
避免在词项开头使用通配符
精确匹配使用 keyword 字段
使用 size 参数限制结果大小

{ "query": { "bool": { "must": { "multi_match": { "query": "search terms", "fields": ["name^3", "description", "tags^2"], "type": "best_fields" } }, "filter": [ { "term": { "active": true } }, { "range": { "created_at": { "gte": "now-30d" } } } ] } }, "size": 20, "from": 0, "_source": ["name", "price", "category"] }

{
  "size": 0,
  "aggs": {
    "categories": {
      "terms": {
        "field": "category",
        "size": 10
      },
      "aggs": {
        "avg_price": {
          "avg": { "field": "price" }
        }
      }
    },
    "price_ranges": {
      "range": {
        "field": "price",
        "ranges": [
          { "to": 100 },
          { "from": 100, "to": 500 },
          { "from": 500 }
        ]
      }
    },
    "date_histogram": {
      "date_histogram": {
        "field": "created_at",
        "calendar_interval": "month"
      }
    }
  }
}

当只需要聚合时使用 size: 0
为词项聚合设置适当的 shard_size
使用复合聚合进行分页
考虑使用 aggs 过滤器来缩小范围

POST _bulk
{ "index": { "_index": "products", "_id": "1" } }
{ "name": "Product 1", "price": 99.99 }
{ "index": { "_index": "products", "_id": "2" } }
{ "name": "Product 2", "price": 149.99 }

批量操作使用批量 API
最佳批量大小：每个请求 5-15MB
监控被拒绝的请求（线程池队列已满）
批量索引期间禁用刷新以获得更好的性能

PUT /products/_settings { "refresh_interval": "-1" }

// 批量索引后： PUT /products/_settings { "refresh_interval": "1s" }

POST /products/_refresh

POST /products/_update/1
{
  "doc": {
    "price": 89.99,
    "updated_at": "2024-01-15T10:30:00Z"
  }
}

// 按查询更新
POST /products/_update_by_query
{
  "query": {
    "term": { "category": "electronics" }
  },
  "script": {
    "source": "ctx._source.on_sale = true"
  }
}

{
  "settings": {
    "analysis": {
      "analyzer": {
        "product_analyzer": {
          "type": "custom",
          "tokenizer": "standard",
          "filter": [
            "lowercase",
            "asciifolding",
            "english_stop",
            "english_stemmer"
          ]
        },
        "autocomplete_analyzer": {
          "type": "custom",
          "tokenizer": "standard",
          "filter": [
            "lowercase",
            "edge_ngram_filter"
          ]
        }
      },
      "filter": {
        "english_stop": {
          "type": "stop",
          "stopwords": "_english_"
        },
        "english_stemmer": {
          "type": "stemmer",
          "language": "english"
        },
        "edge_ngram_filter": {
          "type": "edge_ngram",
          "min_gram": 2,
          "max_gram": 15
        }
      }
    }
  }
}

POST /products/_analyze
{
  "analyzer": "product_analyzer",
  "text": "Wireless Bluetooth Headphones"
}

{
  "mappings": {
    "properties": {
      "name": {
        "type": "text",
        "fields": {
          "suggest": {
            "type": "completion"
          }
        }
      }
    }
  }
}

// 查询建议
{
  "suggest": {
    "product-suggest": {
      "prefix": "wire",
      "completion": {
        "field": "name.suggest",
        "size": 5
      }
    }
  }
}

{
  "query": {
    "match": { "description": "wireless" }
  },
  "highlight": {
    "fields": {
      "description": {
        "pre_tags": ["<em>"],
        "post_tags": ["</em>"],
        "fragment_size": 150
      }
    }
  }
}

过滤器查询会自动缓存
对频繁重复的条件使用 filter 上下文
监控缓存命中率

避免深度分页（改用 search_after）
限制返回的 _source 字段
排序和聚合使用 doc_values
为常见的排序顺序预排序索引

{ "query": { "match_all": {} }, "size": 20, "search_after": [1705329600000, "product_123"], "sort": [ { "created_at": "desc" }, { "_id": "asc" } ] }

GET _cluster/health
GET _cat/indices?v
GET _cat/shards?v
GET _nodes/stats

POST /products/_forcemerge?max_num_segments=1
POST /products/_cache/clear
POST /products/_refresh

PUT /products/_settings
{
  "index.search.slowlog.threshold.query.warn": "10s",
  "index.search.slowlog.threshold.query.info": "5s",
  "index.search.slowlog.threshold.fetch.warn": "1s"
}

PUT _security/role/products_reader
{
  "indices": [
    {
      "names": ["products*"],
      "privileges": ["read"]
    }
  ]
}

PUT _security/role/limited_access
{
  "indices": [
    {
      "names": ["users"],
      "privileges": ["read"],
      "field_security": {
        "grant": ["name", "email", "created_at"]
      }
    }
  ]
}

别名和重新索引

POST _aliases
{
  "actions": [
    { "add": { "index": "products_v2", "alias": "products" } },
    { "remove": { "index": "products_v1", "alias": "products" } }
  ]
}

带转换的重新索引

POST _reindex
{
  "source": {
    "index": "products_v1"
  },
  "dest": {
    "index": "products_v2"
  },
  "script": {
    "source": "ctx._source.migrated_at = new Date().toString()"
  }
}

🇺🇸English

Elasticsearch Best Practices

Core Principles

Design indices and mappings based on query patterns
Optimize for search performance with proper analysis and indexing
Use appropriate shard sizing and cluster configuration
Implement proper security and access control
Monitor cluster health and optimize queries

Index Design

Mapping Best Practices

Define explicit mappings instead of relying on dynamic mapping
Use appropriate data types for each field
Disable indexing for fields you do not search on
Use keyword type for exact matches, text for full-text search

{ "mappings": { "properties": { "product_id": { "type": "keyword" }, "name": { "type": "text", "analyzer": "standard", "fields": { "keyword": { "type": "keyword", "ignore_above": 256 } } }, "description": { "type": "text", "analyzer": "english" }, "price": { "type": "scaled_float", "scaling_factor": 100 }, "category": { "type": "keyword" }, "tags": { "type": "keyword" }, "created_at": { "type": "date" }, "metadata": { "type": "object", "enabled": false }, "location": { "type": "geo_point" } } } }

Field Types

keyword: Exact values, filtering, aggregations, sorting
text: Full-text search with analysis
date: Date/time values with format specification
numeric types: long, integer, short, byte, double, float, scaled_float
boolean: True/false values
geo_point: Latitude/longitude pairs
nested: Arrays of objects that need independent querying

Index Settings

{
  "settings": {
    "number_of_shards": 3,
    "number_of_replicas": 1,
    "refresh_interval": "30s",
    "analysis": {
      "analyzer": {
        "custom_analyzer": {
          "type": "custom",
          "tokenizer": "standard",
          "filter": ["lowercase", "asciifolding", "synonym_filter"]
        }
      },
      "filter": {
        "synonym_filter": {
          "type": "synonym",
          "synonyms": ["laptop, notebook", "phone, mobile, smartphone"]
        }
      }
    }
  }
}

Shard Sizing

Guidelines

Target 20-40GB per shard
Aim for ~20 shards per GB of heap
Avoid oversharding (too many small shards)
Consider time-based indices for time-series data

{ "settings": { "number_of_shards": 3, "number_of_replicas": 1 } }

Index Lifecycle Management (ILM)

{
  "policy": {
    "phases": {
      "hot": {
        "min_age": "0ms",
        "actions": {
          "rollover": {
            "max_size": "50gb",
            "max_age": "7d"
          }
        }
      },
      "warm": {
        "min_age": "30d",
        "actions": {
          "shrink": {
            "number_of_shards": 1
          },
          "forcemerge": {
            "max_num_segments": 1
          }
        }
      },
      "delete": {
        "min_age": "90d",
        "actions": {
          "delete": {}
        }
      }
    }
  }
}

Query Optimization

Query Types

Match Query (Full-text search)

{
  "query": {
    "match": {
      "description": {
        "query": "wireless bluetooth headphones",
        "operator": "and",
        "fuzziness": "AUTO"
      }
    }
  }
}

Term Query (Exact match)

{
  "query": {
    "term": {
      "status": "active"
    }
  }
}

Bool Query (Combining queries)

{
  "query": {
    "bool": {
      "must": [
        { "match": { "name": "laptop" } }
      ],
      "filter": [
        { "term": { "category": "electronics" } },
        { "range": { "price": { "gte": 500, "lte": 2000 } } }
      ],
      "should": [
        { "term": { "brand": "apple" } }
      ],
      "must_not": [
        { "term": { "status": "discontinued" } }
      ]
    }
  }
}

Query Best Practices

Use filter context for non-scoring queries (cacheable)
Use must only when scoring is needed
Avoid wildcards at the beginning of terms
Use keyword fields for exact matches
Limit result size with size parameter

{ "query": { "bool": { "must": { "multi_match": { "query": "search terms", "fields": ["name^3", "description", "tags^2"], "type": "best_fields" } }, "filter": [ { "term": { "active": true } }, { "range": { "created_at": { "gte": "now-30d" } } } ] } }, "size": 20, "from": 0, "_source": ["name", "price", "category"] }

Aggregations

Common Aggregation Patterns

{
  "size": 0,
  "aggs": {
    "categories": {
      "terms": {
        "field": "category",
        "size": 10
      },
      "aggs": {
        "avg_price": {
          "avg": { "field": "price" }
        }
      }
    },
    "price_ranges": {
      "range": {
        "field": "price",
        "ranges": [
          { "to": 100 },
          { "from": 100, "to": 500 },
          { "from": 500 }
        ]
      }
    },
    "date_histogram": {
      "date_histogram": {
        "field": "created_at",
        "calendar_interval": "month"
      }
    }
  }
}

Aggregation Best Practices

Use size: 0 when you only need aggregations
Set appropriate shard_size for terms aggregations
Use composite aggregations for pagination
Consider using aggs filters to narrow scope

Indexing Best Practices

Bulk Indexing

POST _bulk
{ "index": { "_index": "products", "_id": "1" } }
{ "name": "Product 1", "price": 99.99 }
{ "index": { "_index": "products", "_id": "2" } }
{ "name": "Product 2", "price": 149.99 }

Bulk API Guidelines

Use bulk API for batch operations
Optimal bulk size: 5-15MB per request
Monitor for rejected requests (thread pool queue full)
Disable refresh during bulk indexing for better performance

PUT /products/_settings { "refresh_interval": "-1" }

// After bulk indexing: PUT /products/_settings { "refresh_interval": "1s" }

POST /products/_refresh

Document Updates

POST /products/_update/1
{
  "doc": {
    "price": 89.99,
    "updated_at": "2024-01-15T10:30:00Z"
  }
}

// Update by query
POST /products/_update_by_query
{
  "query": {
    "term": { "category": "electronics" }
  },
  "script": {
    "source": "ctx._source.on_sale = true"
  }
}

Analysis and Tokenization

Custom Analyzers

{
  "settings": {
    "analysis": {
      "analyzer": {
        "product_analyzer": {
          "type": "custom",
          "tokenizer": "standard",
          "filter": [
            "lowercase",
            "asciifolding",
            "english_stop",
            "english_stemmer"
          ]
        },
        "autocomplete_analyzer": {
          "type": "custom",
          "tokenizer": "standard",
          "filter": [
            "lowercase",
            "edge_ngram_filter"
          ]
        }
      },
      "filter": {
        "english_stop": {
          "type": "stop",
          "stopwords": "_english_"
        },
        "english_stemmer": {
          "type": "stemmer",
          "language": "english"
        },
        "edge_ngram_filter": {
          "type": "edge_ngram",
          "min_gram": 2,
          "max_gram": 15
        }
      }
    }
  }
}

Test Analyzer

POST /products/_analyze
{
  "analyzer": "product_analyzer",
  "text": "Wireless Bluetooth Headphones"
}

Search Features

Autocomplete/Suggestions

{
  "mappings": {
    "properties": {
      "name": {
        "type": "text",
        "fields": {
          "suggest": {
            "type": "completion"
          }
        }
      }
    }
  }
}

// Query suggestions
{
  "suggest": {
    "product-suggest": {
      "prefix": "wire",
      "completion": {
        "field": "name.suggest",
        "size": 5
      }
    }
  }
}

Highlighting

{
  "query": {
    "match": { "description": "wireless" }
  },
  "highlight": {
    "fields": {
      "description": {
        "pre_tags": ["<em>"],
        "post_tags": ["</em>"],
        "fragment_size": 150
      }
    }
  }
}

Performance Optimization

Query Caching

Filter queries are cached automatically
Use filter context for frequently repeated conditions
Monitor cache hit rates

Search Performance

Avoid deep pagination (use search_after instead)
Limit _source fields returned
Use doc_values for sorting and aggregations
Pre-sort index for common sort orders

{ "query": { "match_all": {} }, "size": 20, "search_after": [1705329600000, "product_123"], "sort": [ { "created_at": "desc" }, { "_id": "asc" } ] }

Monitoring and Maintenance

Cluster Health

GET _cluster/health
GET _cat/indices?v
GET _cat/shards?v
GET _nodes/stats

Index Maintenance

POST /products/_forcemerge?max_num_segments=1
POST /products/_cache/clear
POST /products/_refresh

Slow Query Log

PUT /products/_settings
{
  "index.search.slowlog.threshold.query.warn": "10s",
  "index.search.slowlog.threshold.query.info": "5s",
  "index.search.slowlog.threshold.fetch.warn": "1s"
}

Security

Index-Level Security

PUT _security/role/products_reader
{
  "indices": [
    {
      "names": ["products*"],
      "privileges": ["read"]
    }
  ]
}

Field-Level Security

PUT _security/role/limited_access
{
  "indices": [
    {
      "names": ["users"],
      "privileges": ["read"],
      "field_security": {
        "grant": ["name", "email", "created_at"]
      }
    }
  ]
}

Aliases and Reindexing

Index Aliases

POST _aliases
{
  "actions": [
    { "add": { "index": "products_v2", "alias": "products" } },
    { "remove": { "index": "products_v1", "alias": "products" } }
  ]
}

Reindex with Transformation

POST _reindex
{
  "source": {
    "index": "products_v1"
  },
  "dest": {
    "index": "products_v2"
  },
  "script": {
    "source": "ctx._source.migrated_at = new Date().toString()"
  }
}

Weekly Installs

269

Repository

mindrally/skills

GitHub Stars

First Seen

Jan 25, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykPass

Installed on

opencode206

gemini-cli200

codex197

github-copilot195

claude-code193

cursor182

Azure 升级评估与自动化工具 - 轻松迁移 Functions 计划、托管层级和 SKU

68,100 周安装

Elasticsearch 最佳实践指南：索引设计、分片优化与集群配置

🇨🇳中文介绍

Elasticsearch 最佳实践

核心原则

索引设计

映射最佳实践

字段类型

相关 Skills

索引设置

分片大小调整

指导原则

索引生命周期管理 (ILM)

查询优化

查询类型

匹配查询 (全文搜索)

词项查询 (精确匹配)

布尔查询 (组合查询)

查询最佳实践

聚合

常见聚合模式

聚合最佳实践

索引最佳实践

批量索引

批量 API 指南

文档更新

分析和分词

自定义分析器

测试分析器

搜索功能

自动补全/建议

高亮显示

性能优化

查询缓存

搜索性能

监控与维护

集群健康

索引维护

慢查询日志

安全

索引级安全

字段级安全