vectorSearch

Performs an approximate nearest neighbor (ANN) vector search. This command is an extension of the $vectorSearch MongoDB® aggregation pipeline operator. To create a vector index on a collection, use the createIndexes command.

Syntax

{
"$vectorSearch": {
"index": "<index-name>",
"path": "<field-to-search>",
"queryVector": [<array-of-numbers>],
"numCandidates": <number-of-candidates>, // this values is ignored
"limit": <number-of-results>,
"filter": {<filter-specification>},
"kaiSearchOptions": "<json-object>" // additional search parameters
} }

Arguments

Field

Type

Requirement

Description

index

String

Required

The name of the vector index to use.

path

String

Required

The field to search.

queryVector

Array of numbers

Required

An array of numbers that represents the query vector to search.

numCandidates

Number

Optional

SingleStore ignores this field.

limit

Number

Optional

The number of documents to return in the result.

filter

Document

Optional

An expression to filter the indexed fields.

kaiSearchOptions

JSON object

Optional

Specifies search parameters based on the type of vector index used.

Remarks

Examples

The following examples create a vector index, add vectors to a collection, and then search for a specified vector in the collection using vectorSearch.

Example 1

The following example creates a IVF_PQFS type vector index with EUCLIDEAN_DISTANCE metric_type.

1. Create a Vector Index

Use the createIndexes command to create a IVF_PQFS type vector index named searchVector_EUC.

col = db.exampleCollection
res = db.runCommand({
createIndexes: "exampleCollection",
indexes: [
{ key: { "sampleVectors": "vector" },
name: "searchVector_EUC",
kaiIndexOptions: {
index_type: "IVF_PQFS",
m: 4,
nprobe: 20,
nlist: 128,
metric_type: "EUCLIDEAN_DISTANCE",
dimensions: 4
}
}]})

2. Add Vectors

Run the following command to add vectors to a collection named exampleCollection. This example uses fictional vectors for simplicity.

col.insertMany([
{name: "John Doe", occupation: "Software Engineer", sampleVectors: [0.8, 0.2, 0.5, 0.1]},
{name: "Jane Smith", occupation: "Data Scientist", sampleVectors: [0.6, 0.9, 0.3, 0.7]},
{name: "Alice Johnson", occupation: "Marketing Manager", sampleVectors: [0.3, 0.7, 0.4, 0.2]},
{name: "Bob Brown", occupation: "Project Manager", sampleVectors: [0.5, 0.6, 0.8, 0.3]},
{name: "Emily Davis", occupation: "Graphic Designer", sampleVectors: [0.2, 0.4, 0.6, 0.9]}
])
{
  acknowledged: true,
  insertedIds: {
    '0': ObjectId('666944f2b98d7f1d23ee870e'),
    '1': ObjectId('666944f2b98d7f1d23ee870f'),
    '2': ObjectId('666944f2b98d7f1d23ee8710'),
    '3': ObjectId('666944f2b98d7f1d23ee8711'),
    '4': ObjectId('666944f2b98d7f1d23ee8712')
  }
}

Use the $vectorSearch command to perform a vector search on your vector data using the searchVector_EUC vector index created earlier.

res = col.aggregate([
{ $vectorSearch: {
index: "searchVector_EUC",
path: "sampleVectors",
queryVector: [0.6, 0.8, 0.9, 0.1],
k: 20,
numCandidates: 5,
limit: 2
}
}]).toArray()
[
  {
    _id: ObjectId('666944f2b98d7f1d23ee8711'),
    name: 'Bob Brown',
    occupation: 'Project Manager',
    sampleVectors: [ 0.5, 0.6, 0.8, 0.3 ]
  },
  {
    _id: ObjectId('666944f2b98d7f1d23ee8710'),
    name: 'Alice Johnson',
    occupation: 'Marketing Manager',
    sampleVectors: [ 0.3, 0.7, 0.4, 0.2 ]
  }
]

Example 2

The following example creates a HNSW_FLAT type vector index with DOT_PRODUCT metric_type.

  1. Create a vector index named searchVector_HNSW_DOT:

    col = db.exampleCollection2
    res = db.runCommand({
    createIndexes: "exampleCollection2",
    indexes: [
    { key: { "sampleVectors": "vector" },
    name: "searchVector_HNSW_DOT",
    kaiIndexOptions: {
    index_type: "HNSW_FLAT",
    M: 12,
    efConstruction: 120,
    dimensions: 4
    }
    }]})
  2. Add vectors to the collection. This example uses fictional vectors for simplicity.

    col.insertMany([
    {name: "John Doe", occupation: "Software Engineer", sampleVectors: [0.8, 0.2, 0.5, 0.1]},
    {name: "Jane Smith", occupation: "Data Scientist", sampleVectors: [0.6, 0.9, 0.3, 0.7]},
    {name: "Alice Johnson", occupation: "Marketing Manager", sampleVectors: [0.3, 0.7, 0.4, 0.2]},
    {name: "Bob Brown", occupation: "Project Manager", sampleVectors: [0.5, 0.6, 0.8, 0.3]},
    {name: "Emily Davis", occupation: "Graphic Designer", sampleVectors: [0.2, 0.4, 0.6, 0.9]}
    ])
    {
      acknowledged: true,
      insertedIds: {
        '0': ObjectId('66694706b98d7f1d23ee8718'),
        '1': ObjectId('66694706b98d7f1d23ee8719'),
        '2': ObjectId('66694706b98d7f1d23ee871a'),
        '3': ObjectId('66694706b98d7f1d23ee871b'),
        '4': ObjectId('66694706b98d7f1d23ee871c')
      }
    }
  3. Perform a vector search using the searchVector_HNSW_DOT vector index created earlier.

    res = col.aggregate([
    { $vectorSearch: {
    index: "searchVector_HNSW_DOT",
    path: "sampleVectors",
    queryVector: [0.1, 0.6, 0.3, 0.8],
    numCandidates: 5,
    limit: 2
    }
    }]).toArray()
    [
      {
        _id: ObjectId('66694706b98d7f1d23ee8719'),
        name: 'Jane Smith',
        occupation: 'Data Scientist',
        sampleVectors: [ 0.6, 0.9, 0.3, 0.7 ]
      },
      {
        _id: ObjectId('66694706b98d7f1d23ee871c'),
        name: 'Emily Davis',
        occupation: 'Graphic Designer',
        sampleVectors: [ 0.2, 0.4, 0.6, 0.9 ]
      }
    ]

References

Last modified: June 12, 2024

Was this article helpful?