Dense vector field type

The dense_vector field type stores dense vectors of numeric values. Dense vector fields are primarily used for k-nearest neighbor (kNN) search.

The dense_vector type does not support aggregations or sorting.

You can provide vectors in two different input formats:

• Array of floats: A JSON array of numeric values representing each vector dimension.
• Base64-encoded string: A Base64-encoded binary representation of the vector. More compact than float arrays, reducing payload size and improving efficiency for large vectors and bulk indexing.

The following example creates an index with a dense_vector field (using default element_type float) and indexes documents using each format:

PUT my-index
{
  "mappings": {
    "properties": {
      "my_vector": {
        "type": "dense_vector",
        "dims": 3,
        "index_options": {
          "type": "bbq_disk"
        }
      },
      "my_text": {
        "type": "keyword"
      }
    }
  }
}
PUT my-index/_doc/1
{
  "my_text" : "text1",
  "my_vector" : [0.5, 10, 6]
}
PUT my-index/_doc/2
{
  "my_text" : "text2",
  "my_vector" : [-0.5, 10, 10]
}

PUT my-index
{
  "mappings": {
    "properties": {
      "my_vector": {
        "type": "dense_vector",
        "dims": 3
      },
      "my_text" : {
        "type" : "keyword"
      }
    }
  }
}
PUT my-index/_doc/1
{
  "my_text" : "text1",
  "my_vector" : "PwAAAEEgAABAwAAA"
}
PUT my-index/_doc/2
{
  "my_text" : "text2",
  "my_vector" : "vwAAAEEgAABBIAAA"
}

A k-nearest neighbor (kNN) search finds the k nearest vectors to a query vector, as measured by a similarity metric.

Dense vector fields can be used to rank documents in script_score queries. This lets you perform a brute-force kNN search by scanning all documents and ranking them by similarity.

In many cases, a brute-force kNN search is not efficient enough. For this reason, the dense_vector type supports indexing vectors into a specialized data structure to support fast kNN retrieval through the knn option in the search API

Unmapped array fields of float elements with size between 128 and 4096 are dynamically mapped as dense_vector with a default similarity of cosine. You can override the default similarity by explicitly mapping the field as dense_vector with the desired similarity.

Indexing is enabled by default for dense vector fields. When indexing float vectors, Elasticsearch uses a default index type. For other element types, such as byte and bit, the default index type is hnsw with no quantization.

When indexing is enabled, you can define the vector similarity to use in kNN search:

PUT my-index-2
{
  "mappings": {
    "properties": {
      "my_vector": {
        "type": "dense_vector",
        "dims": 3,
        "similarity": "dot_product"
      }
    }
  }
}

You can disable indexing by setting the index parameter to false:

PUT my-index-2
{
  "mappings": {
    "properties": {
      "my_vector": {
        "type": "dense_vector",
        "dims": 3,
        "index": false
      }
    }
  }
}

Elasticsearch uses the HNSW algorithm to support efficient kNN search. Like most kNN algorithms, HNSW is an approximate method that sacrifices result accuracy for improved speed.

By default, dense_vector fields are not included in _source in responses from the _search, _msearch, _get, and _mget APIs. This helps reduce response size and improve performance, especially in scenarios where vectors are used solely for similarity scoring and not required in the output.

To retrieve vector values explicitly, you can use:

• The fields option to request specific vector fields directly:

  POST my-index-2/_search
  {
    "fields": ["my_vector"]
  }

• The _source.exclude_vectors flag to re-enable vector inclusion in _source responses:

  POST my-index-2/_search
  {
    "_source": {
      "exclude_vectors": false
    }
  }

You can return dense vector doc values using the docvalue_fields search option. The response format can be controlled per field:

• format: array (default) returns the decoded vector values as a JSON array.
• format: binary returns the raw vector bytes encoded as base64. This works whether the vector was originally indexed from an array or from a binary string. Numeric element types (float, bfloat16) are emitted in big-endian order; byte and bit vectors are returned exactly as stored.

Example: retrieve dense vector doc values as arrays or base64-encoded bytes

PUT dv-format
{
  "mappings": {
    "properties": {
      "vec_float": {
        "type": "dense_vector",
        "element_type": "float",
        "dims": 3,
        "index": false
      }
    }
  }
}
POST dv-format/_bulk?refresh
{"index":{"_id":"1"}}
{"vec_float":[1.5, 2.0, -3.25]}
{"index":{"_id":"2"}}
{"vec_float":[1.25, -2.5, 4.0]}
POST dv-format/_search
{
  "_source": false,
  "query": { "match_all": {} },
  "docvalue_fields": ["vec_float"],
  "sort": "_id"
}

Sample response (array format):

{
  "hits": {
    "hits": [
      {
        "_id": "1",
        "fields": {
          "vec_float": [
            [1.5, 2.0, -3.25]
          ]
        }
      },
      {
        "_id": "2",
        "fields": {
          "vec_float": [
            [1.25, -2.5, 4.0]
          ]
        }
      }
    ]
  }
}

To retrieve the same vectors as base64-encoded bytes, request only the binary format:

POST dv-format/_search
{
  "_source": false,
  "query": { "match_all": {} },
  "docvalue_fields": [ { "field": "vec_float", "format": "binary" } ],
  "sort": "_id"
}

Sample response (binary format):

{
  "hits": {
    "hits": [
      {
        "_id": "1",
        "fields": {
          "vec_float": [
            "P8AAAEAAAADAUAAA"
          ]
        }
      },
      {
        "_id": "2",
        "fields": {
          "vec_float": [
            "P+AAAAAAAP+QEA=="
          ]
        }
      }
    ]
  }
}

By default, dense_vector fields are not stored in _source on disk. This is also controlled by the index setting index.mapping.exclude_source_vectors. This setting is enabled by default for newly created indices and can only be set at index creation time.

When enabled:

• dense_vector fields are removed from _source and the rest of the _source is stored as usual.
• If a request includes _source and vector values are needed (e.g., during recovery or reindex), the vectors are rehydrated from their internal format.

This setting is compatible with synthetic _source, where the entire _source document is reconstructed from columnar storage. In full synthetic mode, no _source is stored on disk, and all fields — including vectors — are rebuilt when needed.

When vector values are rehydrated (e.g., for reindex, recovery, or explicit _source requests), they are restored from their internal format. By default, vectors are stored at float precision, so if they were originally indexed as higher-precision types (e.g., double or long), the rehydrated values will have reduced precision. This lossy representation is intended to save space while preserving search quality. Additionally, using an element_type of bfloat16 will cause a further loss in precision in restored vectors.

If you want to preserve the original vector values exactly as they were provided, you can re-enable vector storage in _source:

PUT my-index-include-vectors
{
  "settings": {
    "index.mapping.exclude_source_vectors": false
  },
  "mappings": {
    "properties": {
      "my_vector": {
        "type": "dense_vector"
      }
    }
  }
}

When this setting is disabled:

• dense_vector fields are stored as part of the _source, exactly as indexed.
• The index will store both the original _source value and the internal representation used for vector search, resulting in increased storage usage.
• Vectors are once again returned in _source by default in all relevant APIs, with no need to use exclude_vectors or fields.

This configuration is appropriate when full source fidelity is required, such as for auditing or round-tripping exact input values.

The dense_vector field type supports quantization to reduce the memory footprint required when searching float vectors. The supported vector quantization strategies for dense_vector kNN indexing are:

• int8
• int4
• bbq, available as:
  • bbq_hnsw
  • bbq_flat
  • bbq_disk

Here is an example of configuring disk-based binary quantization using bbq_disk:

PUT my-bbq-disk-index
{
  "mappings": {
    "properties": {
      "my_vector": {
        "type": "dense_vector",
        "dims": 384,
        "index": true,
        "index_options": {
          "type": "bbq_disk"
        }
      }
    }
  }
}

Quantized vectors can use oversampling and rescoring to improve accuracy on approximate kNN search results.

For byte and bit element types, automatic quantization does not apply. These element types always default to hnsw with no quantization across all versions.

Quantizes each dimension of the vector to 1-byte integers. This reduces the memory footprint by 75% (or 4x) at the cost of some accuracy.

Here is an example of how to create a byte-quantized index:

PUT my-byte-quantized-index
{
  "mappings": {
    "properties": {
      "my_vector": {
        "type": "dense_vector",
        "dims": 3,
        "index": true,
        "index_options": {
          "type": "int8_hnsw"
        }
      }
    }
  }
}

Quantizes each dimension of the vector to half-byte integers. This reduces the memory footprint by 87% (or 8x) at the cost of accuracy.

Here is an example of how to create a half-byte-quantized index:

PUT my-byte-quantized-index
{
  "mappings": {
    "properties": {
      "my_vector": {
        "type": "dense_vector",
        "dims": 4,
        "index": true,
        "index_options": {
          "type": "int4_hnsw"
        }
      }
    }
  }
}

bbq or Better binary quantization reduces each dimension to a single bit precision. This reduces the memory footprint by 96% (or 32x) at a larger cost of accuracy. Generally, oversampling during query time and reranking can help mitigate the accuracy loss. You can choose one of the following BBQ index types:

• bbq_hnsw
• bbq_flat
• bbq_disk

Here is an example of how to create a binary quantized index:

PUT my-byte-quantized-index
{
  "mappings": {
    "properties": {
      "my_vector": {
        "type": "dense_vector",
        "dims": 64,
        "index": true,
        "index_options": {
          "type": "bbq_hnsw"
        }
      }
    }
  }
}

The following mapping parameters are accepted:

element_type

(Optional, string) The data type used to encode vectors.

dims

(Optional, integer) Number of vector dimensions. Can’t exceed 4096. If dims is not specified, it will be set to the length of the first vector added to the field.

index

(Optional, Boolean) If true, you can search this field using the knn query or knn in _search . Defaults to true.

similarity

(Optional¹, string) The vector similarity metric to use in kNN search. Documents are ranked by their vector field’s similarity to the query vector. The _score of each document will be derived from the similarity, in a way that ensures scores are positive and that a larger score corresponds to a higher ranking. Defaults to l2_norm when element_type: bit otherwise defaults to cosine.

¹ This parameter can only be specified when index is true.

Note

bit vectors only support l2_norm as their similarity metric.

index_options

(Optional², object) An optional section that configures the kNN indexing algorithm. The HNSW algorithm has two internal parameters that influence how the data structure is built. These can be adjusted to improve the accuracy of results, at the expense of slower indexing speed.

² This parameter can only be specified when index is true.

dense_vector fields support synthetic _source .

When using element_type: bit, this will treat all vectors as bit vectors. Bit vectors utilize only a single bit per dimension and are internally encoded as bytes. This can be useful for very high-dimensional vectors or models.

When using bit, the number of dimensions must be a multiple of 8 and must represent the number of bits. Additionally, with bit vectors, the typical vector similarity values are effectively all scored the same, e.g. with hamming distance.

Let’s compare two byte[] arrays, each representing 40 individual bits.

[-127, 0, 1, 42, 127] in bits 1000000100000000000000010010101001111111 [127, -127, 0, 1, 42] in bits 0111111110000001000000000000000100101010

When comparing these two bit, vectors, we first take the hamming distance.

xor result:

1000000100000000000000010010101001111111
^
0111111110000001000000000000000100101010
=
1111111010000001000000010010101101010101

Then, we gather the count of 1 bits in the xor result: 18. To scale for scoring, we subtract from the total number of bits and divide by the total number of bits: (40 - 18) / 40 = 0.55. This would be the _score between these two vectors.

Here is an example of indexing and searching bit vectors:

PUT my-bit-vectors
{
  "mappings": {
    "properties": {
      "my_vector": {
        "type": "dense_vector",
        "dims": 40,
        "element_type": "bit"
      }
    }
  }
}

1. The number of dimensions that represents the number of bits

POST /my-bit-vectors/_bulk?refresh
{"index": {"_id" : "1"}}
{"my_vector": [127, -127, 0, 1, 42]}
{"index": {"_id" : "2"}}
{"my_vector": "8100012a7f"}

1. 5 bytes representing the 40 bit dimensioned vector
2. A hexadecimal string representing the 40 bit dimensioned vector

Then, when searching, you can use the knn query to search for similar bit vectors:

POST /my-bit-vectors/_search?filter_path=hits.hits
{
  "query": {
    "knn": {
      "query_vector": [127, -127, 0, 1, 42],
      "field": "my_vector"
    }
  }
}

{
  "hits": {
    "hits": [
      {
        "_index": "my-bit-vectors",
        "_id": "1",
        "_score": 1,
        "_source": {
          "my_vector": [
            127,
            -127,
            0,
            1,
            42
          ]
        }
      },
      {
        "_index": "my-bit-vectors",
        "_id": "2",
        "_score": 0.55,
        "_source": {
          "my_vector": "8100012a7f"
        }
      }
    ]
  }
}

Elasticsearch can leverage GPU acceleration to speed up the indexing of dense vectors.

Stack 9.5+ The Elastic Stack includes Elastic's core products such as Elasticsearch, Kibana, Logstash, and Beats. Availability Generally available since 9.5 This functionality is generally available and ready for production usage. Unless stated otherwise on the page, this functionality is available when your Elastic Stack is deployed on Elastic Cloud Hosted, Elastic Cloud Enterprise, Elastic Cloud on Kubernetes, and self-managed environments. This documentation corresponds to the latest patch available for each minor version. If you're not using the latest patch, check the release notes for changes. Serverless Elastic Cloud Serverless projects are autoscaled environments, fully managed by Elastic and available on Elastic Cloud. Availability Generally available This functionality is generally available and ready for production usage. Serverless interfaces and procedures might differ from classic Elastic Stack deployments.

The vectordb_document index mode optimizes an index for vector search workloads.

You must set the mode at index creation time:

PUT my-vector-index
{
  "settings": {
    "index": {
      "mode": "vectordb_document"
    }
  }
}

When vectordb_document mode is active, the following settings are applied automatically unless you explicitly configure them:

element_type (dense_vector)

Defaults to bfloat16 instead of float, halving the storage cost of raw vectors while preserving most recall quality.

Dynamic float array mapping

Float arrays with at least 32 elements are automatically mapped to dense_vector during dynamic mapping, compared to the 128-element threshold used in other index modes.

index.mapping.exclude_source_vectors

Set to true. Vector field values are excluded from the stored _source, reducing storage overhead. This setting is required and cannot be overridden to false.

index.store.preload

Set to ["vex", "veq", "veb", "cenivf"]. These vector index file extensions (HNSW graph, scalar-quantized data, binary-quantized data, and IVF centroid data) are preloaded into the file system cache.

index.merge.intra_merge_parallelism_enabled

Set to true. Enables parallel execution within a single merge operation, which speeds up merging of segments.

index.merge.scheduler.auto_throttle

Set to false. Disables automatic throttling of merge I/O, allowing merges to proceed at full speed.

Stack Planned The Elastic Stack includes Elastic's core products such as Elasticsearch, Kibana, Logstash, and Beats. Availability Planned We plan to add this functionality in a future Elastic Stack update. Subject to changes. Unless stated otherwise on the page, this functionality is available when your Elastic Stack is deployed on Elastic Cloud Hosted, Elastic Cloud Enterprise, Elastic Cloud on Kubernetes, and self-managed environments. This documentation corresponds to the latest patch available for each minor version. If you're not using the latest patch, check the release notes for changes.

The vectordb_columnar index mode combines the vector search defaults of vectordb_document with the columnar storage model. Columnar modes store each field once, as doc values, and reconstruct _source from them, which reduces the storage footprint of the non-vector fields that accompany your vectors. Unlike the other columnar modes, vectordb_columnar is optimized for search rather than analytics, so dense_vector and text fields are also indexed by default. This makes it suitable for both vector search and hybrid search that combines text with vectors.

vectordb_columnar is a good fit for vector search, especially when your documents carry many non-vector, non-text fields. If your searches return many fields for many hits, consider the columnar_stored _source mode to speed up retrieval. Choose vectordb_document when you need _source returned with its original structure, such as arrays of objects or unmapped content.

You must set the mode at index creation time:

PUT my-vector-index
{
  "settings": {
    "index": {
      "mode": "vectordb_columnar"
    }
  }
}

vectordb_columnar applies the same vector search settings and defaults as vectordb_document.

It also inherits the behavior and limitations of the columnar modes, such as auto-flattened mappings, synthetic or columnar_stored _source, and the rejection of mapping-level runtime fields. Unlike the other columnar modes, it indexes dense_vector fields by default, keeps positions and norms on text fields, maps dynamic strings as text, and keeps the query cache enabled for filtered vector search. For the full list of settings and defaults, refer to vectordb_columnar settings.

To better accommodate scaling and performance needs, updating the type setting in index_options is possible with the Update Mapping API, according to the following graph (jumps allowed):

flat --> int8_flat --> int4_flat --> bbq_flat --> hnsw --> int8_hnsw --> int4_hnsw --> bbq_hnsw

flat --> int8_flat --> int4_flat --> hnsw --> int8_hnsw --> int4_hnsw

For updating all HNSW types (hnsw, int8_hnsw, int4_hnsw, bbq_hnsw) the number of connections m must either stay the same or increase.

Updating type in index_options will fail in all other scenarios.

Switching types won’t re-index vectors that have already been indexed (they will keep using their original type), vectors being indexed after the change will use the new type instead.

For example, it’s possible to define a dense vector field that utilizes the flat type (raw float32 arrays) for a first batch of data to be indexed.

PUT my-index-000001
{
    "mappings": {
        "properties": {
            "text_embedding": {
                "type": "dense_vector",
                "dims": 384,
                "index_options": {
                    "type": "flat"
                }
            }
        }
    }
}

Changing the type to int4_hnsw makes sure vectors indexed after the change will use an int4 scalar quantized representation and HNSW (e.g., for KNN queries). That includes new segments created by merging previously created segments.

PUT /my-index-000001/_mapping
{
    "properties": {
        "text_embedding": {
            "type": "dense_vector",
            "dims": 384,
            "index_options": {
                "type": "int4_hnsw"
            }
        }
    }
}

Vectors indexed before this change will keep using the flat type (raw float32 representation and brute force search for KNN queries).

In order to have all the vectors updated to the new type, either reindexing or force merging should be used.

For debugging purposes, it’s possible to inspect how many segments (and docs) exist for each type with the Index Segments API.