Azure.Search.Documents 11.7.0 Released — Native Vector Search and Hybrid Retrieval

What’s New in 11.7.0

The 11.7.0 release stabilizes the vector search API surface and ships significant improvements for developers building RAG pipelines. The key changes:

• GA vector field API — VectorSearchField and related types are now stable
• Improved HNSW tuning — m, efConstruction, and efSearch parameters exposed
• Hybrid search first-class support — VectorizedQuery can be combined with SearchText
• Semantic ranking on hybrid results — three-stage retrieval in a single SDK call

Defining a Vector-Enabled Index

Creating an Azure AI Search index with vector capabilities:

using Azure.Search.Documents.Indexes;
using Azure.Search.Documents.Indexes.Models;

var indexClient = new SearchIndexClient(
    new Uri(configuration["AzureSearch:Endpoint"]!),
    new DefaultAzureCredential());

var index = new SearchIndex("documents")
{
    Fields =
    [
        new SimpleField("id", SearchFieldDataType.String) { IsKey = true },
        new SearchableField("title") { IsFilterable = true },
        new SearchableField("content"),
        new SearchableField("category") { IsFilterable = true, IsFacetable = true },
        // Vector field: 1536 dimensions matches text-embedding-3-small output
        new VectorSearchField("contentVector", dimensions: 1536, vectorSearchProfileName: "hnsw-profile")
    ],
    VectorSearch = new VectorSearch
    {
        Algorithms =
        {
            new HnswAlgorithmConfiguration("hnsw-config")
            {
                Parameters = new HnswParameters
                {
                    Metric = VectorSearchAlgorithmMetric.Cosine,
                    M = 4,                  // Bi-directional links per node
                    EfConstruction = 400,   // Accuracy during index build
                    EfSearch = 500          // Accuracy during query
                }
            }
        },
        Profiles =
        {
            new VectorSearchProfile("hnsw-profile", "hnsw-config")
        }
    }
};

await indexClient.CreateOrUpdateIndexAsync(index);

Indexing Documents with Embeddings

Generate embeddings and push documents to the index:

using Azure.AI.OpenAI;
using Azure.Search.Documents;

// Generate embedding for document content
EmbeddingClient embeddingClient = openAIClient.GetEmbeddingClient("text-embedding-3-small");
OpenAIEmbedding embedding = await embeddingClient.GenerateEmbeddingAsync(document.Content);
float[] vector = embedding.ToFloats().ToArray();

// Upload document with its vector
var searchClient = new SearchClient(
    new Uri(configuration["AzureSearch:Endpoint"]!),
    "documents",
    new DefaultAzureCredential());

var doc = new
{
    id = document.Id,
    title = document.Title,
    content = document.Content,
    category = document.Category,
    contentVector = vector
};

await searchClient.UploadDocumentsAsync([doc]);

Pure Vector Search

Query by semantic similarity:

// Generate query embedding
OpenAIEmbedding queryEmbedding = await embeddingClient.GenerateEmbeddingAsync(userQuery);
float[] queryVector = queryEmbedding.ToFloats().ToArray();

var options = new SearchOptions
{
    VectorSearch = new VectorSearchOptions
    {
        Queries =
        {
            new VectorizedQuery(queryVector)
            {
                KNearestNeighborsCount = 5,
                Fields = { "contentVector" }
            }
        }
    },
    Select = { "id", "title", "content", "category" }
};

SearchResults<SearchDocument> results = await searchClient.SearchAsync<SearchDocument>(
    searchText: null,   // null = pure vector, no text query
    options);

await foreach (SearchResult<SearchDocument> result in results.GetResultsAsync())
{
    Console.WriteLine($"[{result.Score:F4}] {result.Document["title"]}");
}

Hybrid Search (Recommended for Production)

Combine keyword and vector search for better recall:

var options = new SearchOptions
{
    // Full-text BM25 search
    QueryType = SearchQueryType.Full,

    // Vector search in same request
    VectorSearch = new VectorSearchOptions
    {
        Queries =
        {
            new VectorizedQuery(queryVector)
            {
                KNearestNeighborsCount = 50,  // Larger pool for RRF merging
                Fields = { "contentVector" }
            }
        }
    },

    // Optional: semantic ranking on top of hybrid results
    SemanticSearch = new SemanticSearchOptions
    {
        SemanticConfigurationName = "my-semantic-config",
        QueryCaption = new() { CaptionType = QueryCaptionType.Extractive },
        QueryAnswer = new() { AnswerType = QueryAnswerType.Extractive }
    },

    Select = { "id", "title", "content" },
    Size = 10
};

// Pass both a text query AND the vector query for hybrid
SearchResults<SearchDocument> results = await searchClient.SearchAsync<SearchDocument>(
    searchText: userQuery,
    options);

The RRF fusion algorithm merges the BM25 and vector result sets before returning the top-k documents. This consistently outperforms either mode alone on real RAG benchmarks.

How to Install

dotnet add package Azure.Search.Documents --version 11.7.0

Breaking Changes

None from 11.6.x. The changes in 11.7.0 are additive — new overloads and new tuning parameters.

If migrating from 11.5.x or earlier (pre-GA vector support), note that SearchField.VectorSearchDimensions was renamed to VectorSearchField.Dimensions in 11.6.0.

Resources

• Azure.Search.Documents on NuGet
• Azure AI Search vector search documentation
• Workshop: Build a RAG Chatbot with .NET 8+