Neural sparse query

Introduced 2.11

Use the neural_sparse query for vector field search in neural sparse search. The query can use either raw text or sparse vector tokens.

Request body fields

Include the following request fields in the neural_sparse query:

Example: Query by raw text

  1. "neural_sparse": {
  2.   "<vector_field>": {
  3.     "query_text": "<query_text>",
  4.     "model_id": "<model_id>"
  5.   }
  6. }

Example: Query by sparse vector

  1. "neural_sparse": {
  2.   "<vector_field>": {
  3.     "query_tokens": "<query_tokens>"
  4.   }
  5. }

The top-level vector_field specifies the vector field against which to run a search query. The following table lists the other neural_sparse query fields.

FieldData typeRequired/OptionalDescription
query_textStringOptionalThe query text from which to generate sparse vector embeddings.
model_idStringOptionalThe ID of the sparse encoding model or tokenizer model that will be used to generate vector embeddings from the query text. The model must be deployed in OpenSearch before it can be used in sparse neural search. For more information, see Using custom models within OpenSearch and Neural sparse search. For information on setting a default model ID in a neural sparse query, see neural_query_enricher.
query_tokensMap<String, Float>OptionalThe query tokens, sometimes referred to as sparse vector embeddings. Similarly to dense semantic retrieval, you can use raw sparse vectors generated by neural models or tokenizers to perform a semantic search query. Use either the query_text option for raw field vectors or the query_tokens option for sparse vectors. Must be provided in order for the neural_sparse query to operate.
max_token_scoreFloatOptional(Deprecated) The theoretical upper bound of the score for all tokens in the vocabulary (required for performance optimization). For OpenSearch-provided pretrained sparse embedding models, we recommend setting max_token_score to 2 for amazon/neural-sparse/opensearch-neural-sparse-encoding-doc-v1 and to 3.5 for amazon/neural-sparse/opensearch-neural-sparse-encoding-v1. This field has been deprecated as of OpenSearch 2.12.

Example request

Query by raw text

  1. GET my-nlp-index/_search
  2. {
  3.   "query": {
  4.     "neural_sparse": {
  5.       "passage_embedding": {
  6.         "query_text": "Hi world",
  7.         "model_id": "aP2Q8ooBpBj3wT4HVS8a"
  8.       }
  9.     }
  10.   }
  11. }

Query by sparse vector

  1. GET my-nlp-index/_search
  2. {
  3.   "query": {
  4.     "neural_sparse": {
  5.       "passage_embedding": {
  6.         "query_tokens": {
  7.           "hi" : 4.338913,
  8.           "planets" : 2.7755864,
  9.           "planet" : 5.0969057,
  10.           "mars" : 1.7405145,
  11.           "earth" : 2.6087382,
  12.           "hello" : 3.3210192
  13.         }
  14.       }
  15.     }
  16.   }
  17. }

copy