Neural query

Use the neural query for vector field search in neural search.

Request body fields

Include the following request fields in the neural query:

  1. "neural": {
  2. "<vector_field>": {
  3. "query_text": "<query_text>",
  4. "query_image": "<image_binary>",
  5. "model_id": "<model_id>",
  6. "k": 100
  7. }
  8. }

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

FieldData typeRequired/OptionalDescription
query_textStringOptionalThe query text from which to generate vector embeddings. You must specify at least one query_text or query_image.
query_imageStringOptionalA base-64 encoded string that corresponds to the query image from which to generate vector embeddings. You must specify at least one query_text or query_image.
model_idStringRequired if the default model ID is not set. For more information, see Setting a default model on an index or field.The ID of the 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 neural search. For more information, see Using custom models within OpenSearch and Neural search.
kIntegerOptionalThe number of results returned by the k-NN search. Only one variable, either k, min_score, or max_distance, can be specified. If a variable is not specified, the default is k with a value of 10.
min_scoreFloatOptionalThe minimum score threshold for the search results. Only one variable, either k, min_score, or max_distance, can be specified. For more information, see k-NN radial search.
max_distanceFloatOptionalThe maximum distance threshold for the search results. Only one variable, either k, min_score, or max_distance, can be specified. For more information, see k-NN radial search.
filterObjectOptionalA query that can be used to reduce the number of documents considered. For more information about filter usage, see k-NN search with filters. Important: Filter can only be used with the faiss or lucene engines.
method_parametersObjectOptionalParameters passed to the k-NN index during search. See Additional query parameters.
rescoreObjectOptionalParameters for configuring rescoring functionality for k-NN indexes built using quantization. See Rescoring.

Example request

The following example shows a search with a k value of 100 and a filter that includes a range query and a term query:

  1. GET /my-nlp-index/_search
  2. {
  3. "query": {
  4. "neural": {
  5. "passage_embedding": {
  6. "query_text": "Hi world",
  7. "query_image": "iVBORw0KGgoAAAAN...",
  8. "k": 100,
  9. "filter": {
  10. "bool": {
  11. "must": [
  12. {
  13. "range": {
  14. "rating": {
  15. "gte": 8,
  16. "lte": 10
  17. }
  18. }
  19. },
  20. {
  21. "term": {
  22. "parking": "true"
  23. }
  24. }
  25. ]
  26. }
  27. }
  28. }
  29. }
  30. }
  31. }

copy

The following search query includes a k-NN radial search min_score of 0.95 and a filter that includes a range query and a term query:

  1. GET /my-nlp-index/_search
  2. {
  3. "query": {
  4. "neural": {
  5. "passage_embedding": {
  6. "query_text": "Hi world",
  7. "query_image": "iVBORw0KGgoAAAAN...",
  8. "min_score": 0.95,
  9. "filter": {
  10. "bool": {
  11. "must": [
  12. {
  13. "range": {
  14. "rating": {
  15. "gte": 8,
  16. "lte": 10
  17. }
  18. }
  19. },
  20. {
  21. "term": {
  22. "parking": "true"
  23. }
  24. }
  25. ]
  26. }
  27. }
  28. }
  29. }
  30. }
  31. }

copy

The following search query includes a k-NN radial search max_distance of 10 and a filter that includes a range query and a term query:

  1. GET /my-nlp-index/_search
  2. {
  3. "query": {
  4. "neural": {
  5. "passage_embedding": {
  6. "query_text": "Hi world",
  7. "query_image": "iVBORw0KGgoAAAAN...",
  8. "max_distance": 10,
  9. "filter": {
  10. "bool": {
  11. "must": [
  12. {
  13. "range": {
  14. "rating": {
  15. "gte": 8,
  16. "lte": 10
  17. }
  18. }
  19. },
  20. {
  21. "term": {
  22. "parking": "true"
  23. }
  24. }
  25. ]
  26. }
  27. }
  28. }
  29. }
  30. }
  31. }

copy