Azure AI Search vector store

The AzureAISearchVector class provides vector search using Azure AI Search, Microsoft's cloud search service with native vector search support. It offers metadata filtering, hybrid (vector + text) search, and semantic ranking on top of an existing Azure AI Search resource.

Constructor options

id:

string

Unique identifier for this vector store instance.

endpoint:

string

The endpoint URL of your Azure AI Search service, e.g. 'https://your-service.search.windows.net'.

credential:

string | AzureKeyCredential | TokenCredential

An admin API key string, an AzureKeyCredential, or an Azure Identity TokenCredential (e.g. DefaultAzureCredential) for Azure AD authentication.

apiVersion?:

string

Azure AI Search REST API version to use. Defaults to the SDK default.

clientOptions?:

SearchClientOptions

Additional options passed to the underlying SearchClient/SearchIndexClient, such as additionalPolicies for proxies, custom headers, or retry behavior.

autoIndexMetadata?:

boolean

= true

Add a filterable field to the index the first time a top-level string, number, or boolean metadata key is seen in upsert() or updateVector(). Azure AI Search can only filter on declared fields, so this is required for Memory semantic recall (which filters by thread_id and resource_id) unless you declare those keys via metadataIndexes. Set to false to manage the schema yourself.

import { AzureAISearchVector } from '@mastra/azure-ai-search'

const vectorStore = new AzureAISearchVector({
  id: 'azure-search-vectors',
  endpoint: process.env.AZURE_AI_SEARCH_ENDPOINT!,
  credential: process.env.AZURE_AI_SEARCH_CREDENTIAL!,
})

Methods

createIndex()

indexName:

string

Name of the index to create

dimension:

number

Vector dimension (must match your embedding model)

metric?:

'cosine' | 'euclidean' | 'dotproduct'

= cosine

Distance metric for similarity search

metadataIndexes?:

Array<string | { name: string; type: 'string' | 'number' | 'boolean' }>

Metadata keys to declare as explicit filterable fields up front. Optional when autoIndexMetadata is enabled (the default), since fields are then added on first write. Values whose JavaScript type does not match the declared field type are kept in the JSON metadata blob only.

For Azure AI Search-specific index features (custom vector field name, additional schema fields, HNSW parameters, semantic configuration), use createAdvancedIndex() with AzureAISearchCreateIndexParams.

upsert()

indexName:

string

Name of the index to upsert into

vectors:

number[][]

Array of embedding vectors

metadata?:

Record<string, any>[]

Metadata for each vector

ids?:

string[]

Optional vector IDs (auto-generated if not provided). IDs containing characters other than letters, digits, _, - and = are stored base64url-encoded and decoded back on read, so any string is accepted.

deleteFilter?:

AzureAISearchVectorFilter

Azure AI Search-specific: delete documents matching this filter before upserting.

query()

indexName:

string

Name of the index to query

queryVector:

number[]

Query vector to find similar vectors

topK?:

number

= 10

Number of results to return

filter?:

AzureAISearchVectorFilter

Metadata filter for the query, using Mastra operators ($eq, $ne, $gt, $gte, $lt, $lte, $in, $nin, $exists, $and, $or, $not). Translated to an Azure OData $filter; raw OData strings are not accepted.

includeVector?:

boolean

= false

Whether to include vectors in the results

Unsupported filter operators (for example $regex, $size, or $all, none of which map to Azure AI Search's OData filter syntax) throw an error rather than being silently dropped from the query.

listIndexes()

Returns an array of index names as strings.

describeIndex()

indexName:

string

Name of the index to describe

Returns:

interface IndexStats {
  dimension: number
  count: number
  metric: 'cosine' | 'euclidean' | 'dotproduct'
}

deleteIndex()

indexName:

string

Name of the index to delete

updateVector()

Update a single vector by ID or by metadata filter. Either id or filter must be provided, but not both.

indexName:

string

Name of the index containing the vector to update

id?:

string

ID of the vector to update (mutually exclusive with filter)

filter?:

AzureAISearchVectorFilter

Metadata filter to identify vector(s) to update (mutually exclusive with id)

update:

object

Update parameters: { vector?: number[]; metadata?: Record<string, any> }

deleteVector()

indexName:

string

Name of the index containing the vector to delete

id:

string

ID of the vector to delete

deleteVectors()

Delete multiple vectors by IDs or by metadata filter. Either ids or filter must be provided, but not both.

indexName:

string

Name of the index containing the vectors to delete

ids?:

string[]

Array of vector IDs to delete (mutually exclusive with filter)

filter?:

AzureAISearchVectorFilter

Metadata filter to identify vectors to delete (mutually exclusive with ids)

Azure-specific query methods

Beyond the standard query() method, AzureAISearchVector exposes Azure AI Search-specific capabilities:

• advancedQuery(): exposes Azure AI Search vector query parameters directly, including exhaustive search, query weighting, oversampling, additional vector queries for multi-vector search, pre/post filtering mode, and text-based query types (semantic, hybrid).
• semanticQuery(): convenience wrapper around advancedQuery() for semantic ranking with a configured semantic configuration.
• hybridQuery(): convenience wrapper combining vector search with a full-text query.
• multiVectorQuery(): convenience wrapper for querying against multiple weighted vectors at once.
• exactQuery(): convenience wrapper for advancedQuery() with exhaustive (non-approximate) search enabled.

These methods are additive: query() remains the Memory-compatible entry point used by Mastra's semantic recall.

Response types

Query results are returned in this format:

interface QueryResult {
  id: string
  score: number
  metadata: Record<string, any>
  vector?: number[] // Only included if includeVector is true
}

Related

• Metadata Filters