Vector engine best practices

Set HNSW parameters

The m and ef_construction parameters control the recall rate of the HNSW graph. Configure them when creating a dense_vector index. For parameter details, see Dense vector field type.

Reduce memory usage with quantization

Quantization reduces vector memory by compressing each value. Use the following table to estimate memory usage by element_type and quantization level.

BBQ quantization provides the greatest memory reduction but increases the proportion of memory consumed by the HNSW graph index itself. Factor this into your memory estimates when using bbq.

Calculate vector index memory

Total memory has two components: vector data and the HNSW graph index.

Vector data memory (multiply by num_vectors):

HNSW graph index memory:

num_vectors * 4 * HNSW.m

With the default m=16, this equals num_vectors * 4 * 16.

Replicas: The default number_of_replicas is 1, so total memory is 2× the single-copy calculation.

Total memory = (vector data + graph index) × (1 + number_of_replicas)

2 × (10,000,000 × (1,024 + 4) + 10,000,000 × 4 × 16) = 20.34 GB

Check off-heap memory capacity

Off-heap memory is the portion of node memory available for vector data after the Java heap is reserved.

• Node with ≤64 GB total memory: off-heap ≈ half of total memory

• Node with >64 GB total memory: off-heap = total memory − 31 GB (default)

To get the exact value for a node, run:

GET _nodes/stats?human&filter_path=**.os.mem.total,**.jvm.mem.heap_max

Off-heap memory = os.mem.total − jvm.mem.heap_max

Preload the file system buffer

After a node restarts, the OS clears the file system buffer and must reload index data from disk before searches run at full speed. Use index.store.preload to instruct the OS to load specific index files into memory immediately on startup.

Set index.store.preload when creating an index:

PUT /my_vector_index
{
  "settings": {
    "number_of_shards": 1,
    "number_of_replicas": 1,
    "index.store.preload": ["vex", "veq"]
  },
  "mappings": {
    "properties": {
      "my_vector": {
        "type": "dense_vector",
        "dims": 3
      },
      "my_text": {
        "type": "keyword"
      }
    }
  }
}

POST my_vector_index/_close

PUT my_vector_index/_settings
{
  "index.store.preload": ["vex", "veq"]
}

POST my_vector_index/_open

Reduce segment count

Each Elasticsearch shard stores vectors as a separate HNSW graph per segment. kNN search must scan every segment, so fewer segments directly improve search performance — often by several times.

Elasticsearch merges smaller segments in the background automatically. If the default merge behavior is insufficient, use the following approaches.

PUT my_vector_index/_settings
{
  "index.merge.policy.max_merged_segment": "10gb"
}

Exclude vector fields from _source

Elasticsearch stores the full source document in the _source field. For documents with high-dimensional dense_vector fields, loading _source on every kNN search hit adds significant overhead.

Use the excludes mapping parameter to omit vector fields from _source:

PUT /my_vector_index
{
  "mappings": {
    "_source": {
      "excludes": [
        "my_vector"
      ]
    },
    "properties": {
      "my_vector": {
        "type": "dense_vector",
        "dims": 3
      },
      "my_text": {
        "type": "keyword"
      }
    }
  }
}

A vector field excluded from _source remains fully usable for kNN search — the search process uses a separate data structure, not _source.

GET my_vector_index/_search
{
  "docvalue_fields": ["my_vector"]
}

GET my_vector_index/_search
{
  "script_fields": {
    "vector_field": {
      "script": {
        "source": "doc['my_vector'].vectorValue"
      }
    }
  }
}

Upgrade to a Turbo instance type

Vector similarity calculation is CPU-intensive. Turbo instance types provide more than double the CPU performance of standard instance types. Use a blue-green deployment to upgrade to a Turbo instance type of the same specification with minimal disruption.