Performance tuning

Shard count planning

A shard is the basic unit of data distribution and parallel processing. Planning the shard count properly is critical to performance.

Key principles:

• Keep each shard between 30 GB and 50 GB.

• The shard count should not exceed the node count multiplied by 20.

• The shard count cannot be modified after index creation, so plan ahead.

• Too many shards increase cluster metadata overhead and coordination cost.

Replica count selection

Mapping design best practices

curl -XPUT "http://<Search engine address>:<port>/my-index" \
  -u "<username>:<password>" -k \
  -H "Content-Type: application/json" \
  -d '{
    "settings": { "index.mapping.total_fields.limit": 1000 },
    "mappings": {
      "dynamic": "strict",
      "properties": {
        "title":      { "type": "text",    "analyzer": "ik_max_word" },
        "status":     { "type": "keyword" },
        "price":      { "type": "float" },
        "created_at": { "type": "date" }
      }
    }
  }'

• Set "dynamic": "strict" to disallow automatically adding undefined fields and prevent mapping bloat.

• For fields that do not need to be searched, set "index": false to reduce indexing overhead.

• Do not add a keyword subfield to text fields that are not used for aggregation or sorting.

• Use keyword instead of text for exact-match fields.

• Choose the appropriate numeric type for numeric fields. Do not use long for all numbers.

Disable unnecessary features

Bulk write configuration

• Size per _bulk request: 5 MB to 15 MB. Larger sizes cause memory pressure.

• Documents per request: 1,000 to 5,000, depending on document size.

• Concurrent write threads: 2 to 4, adjusted based on the CPU core count of the node.

Index settings tuning during writes

Before importing a large batch of data, temporarily adjust index settings to boost write throughput:

# Before writing: disable replicas and increase the refresh interval
curl -XPUT "http://<Search engine address>:<port>/my-index/_settings" \
  -u "<username>:<password>" -k \
  -H "Content-Type: application/json" \
  -d '{
    "number_of_replicas":            0,
    "refresh_interval":              "-1",
    "translog.durability":           "async",
    "translog.flush_threshold_size": "1gb"
  }'

# === Run the bulk data import ===

# After writing: restore normal settings
curl -XPUT "http://<Search engine address>:<port>/my-index/_settings" \
  -u "<username>:<password>" -k \
  -H "Content-Type: application/json" \
  -d '{
    "number_of_replicas":  1,
    "refresh_interval":    "1s",
    "translog.durability": "request"
  }'

curl -XPOST "http://<Search engine address>:<port>/my-index/_refresh"                        -u "<username>:<password>" -k
curl -XPOST "http://<Search engine address>:<port>/my-index/_forcemerge?max_num_segments=1"  -u "<username>:<password>" -k

Avoid deep pagination

// Not recommended: deep pagination performs poorly
{ "from": 10000, "size": 10 }

// Recommended: use search_after
{
  "size": 10,
  "sort": [ { "created_at": "desc" }, { "_id": "asc" } ],
  "search_after": ["2025-05-25T10:00:00Z", "doc_id_123"]
}

Use filter context appropriately

A filter clause does not participate in scoring and can leverage caching, delivering better performance than must. Place any condition that does not need to affect relevance scoring inside a filter.

Limit returned fields

{
  "query": { "match": { "content": "search" } },
  "_source": ["title", "summary", "created_at"],
  "size": 10
}

Avoid returning large fields such as full-text content or vector embedding. Return only the fields required for display.

Avoid expensive queries

• Leading wildcard *abc: use a reverse token filter or ngram.

• Complex script_score: use precomputed fields.

• Deeply nested nested query: denormalize the schema.

• Large numbers of should clauses (> 100): use a terms query.

• match_all with a large size: use pagination or scroll.

Vector dimension selection

HNSW parameter tuning