Search

The query operation finds the closest vector matches to an input vector using the index’s configured metric.

Basic Query

Pass a query vector to find the nearest neighbors:

const result = await docs.query({
  vector: [0.1, 0.2, 0.3],
})

Returns a VectorQueryResult:

interface VectorQueryResult {
  matches: VectorMatch[]
  count: number
}

interface VectorMatch {
  id: string
  score: number
  values?: number[]
  metadata?: Record<string, unknown>
}

The score field contains the similarity or distance value returned by Cloudflare Vectorize. Higher or lower values are better depending on the metric (cosine and dot-product prefer higher scores; euclidean prefers lower).

Limit Results

Use topK to control the maximum number of matches returned:

const result = await docs.query({
  vector: [0.1, 0.2, 0.3],
  topK: 10,
})

Filter by Metadata

When the index has metadata indexes configured, filter results by metadata field values:

const result = await docs.query({
  vector: [0.1, 0.2, 0.3],
  filter: {
    tenantId: "tenant_1",
  },
})

Only records matching all filter conditions are considered for the similarity ranking.

Return Vector Values

Include the matching vector values in each result:

const result = await docs.query({
  vector: [0.1, 0.2, 0.3],
  returnValues: true,
})

Return Metadata

Include the metadata of each match in the result:

const result = await docs.query({
  vector: [0.1, 0.2, 0.3],
  returnMetadata: true,
})

All Options

interface VectorQueryOptions {
  topK?: number
  filter?: Record<string, unknown>
  returnValues?: boolean
  returnMetadata?: boolean
}

interface VectorQueryInput extends VectorQueryOptions {
  vector: number[]
}

The vector array length must match the index dimensions.