Azure.Search.Documents 11.4.0

The ID prefix of this package has been reserved for one of the owners of this package by Prefix Reserved
There is a newer version of this package available.
See the version list below for details.
dotnet add package Azure.Search.Documents --version 11.4.0
NuGet\Install-Package Azure.Search.Documents -Version 11.4.0
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Azure.Search.Documents" Version="11.4.0" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add Azure.Search.Documents --version 11.4.0
#r "nuget: Azure.Search.Documents, 11.4.0"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install Azure.Search.Documents as a Cake Addin
#addin nuget:?package=Azure.Search.Documents&version=11.4.0

// Install Azure.Search.Documents as a Cake Tool
#tool nuget:?package=Azure.Search.Documents&version=11.4.0

Azure Cognitive Search client library for .NET

Azure Cognitive Search is a search-as-a-service cloud solution that gives developers APIs and tools for adding a rich search experience over private, heterogeneous content in web, mobile, and enterprise applications.

The Azure Cognitive Search service is well suited for the following application scenarios:

  • Consolidate varied content types into a single searchable index. To populate an index, you can push JSON documents that contain your content, or if your data is already in Azure, create an indexer to pull in data automatically.
  • Attach skillsets to an indexer to create searchable content from images and large text documents. A skillset leverages AI from Cognitive Services for built-in OCR, entity recognition, key phrase extraction, language detection, text translation, and sentiment analysis. You can also add custom skills to integrate external processing of your content during data ingestion.
  • In a search client application, implement query logic and user experiences similar to commercial web search engines.

Use the Azure.Search.Documents client library to:

  • Submit queries for simple and advanced query forms that include fuzzy search, wildcard search, regular expressions.
  • Implement filtered queries for faceted navigation, geospatial search, or to narrow results based on filter criteria.
  • Create and manage search indexes.
  • Upload and update documents in the search index.
  • Create and manage indexers that pull data from Azure into an index.
  • Create and manage skillsets that add AI enrichment to data ingestion.
  • Create and manage analyzers for advanced text analysis or multi-lingual content.
  • Optimize results through scoring profiles to factor in business logic or freshness.

Source code | Package (NuGet) | API reference documentation | REST API documentation | Product documentation | Samples

Getting started

Install the package

Install the Azure Cognitive Search client library for .NET with NuGet:

dotnet add package Azure.Search.Documents


You need an Azure subscription and a search service to use this package.

To create a new search service, you can use the Azure portal, Azure PowerShell, or the Azure CLI. Here's an example using the Azure CLI to create a free instance for getting started:

az search service create --name <mysearch> --resource-group <mysearch-rg> --sku free --location westus

See choosing a pricing tier for more information about available options.

Authenticate the client

All requests to a search service need an api-key that was generated specifically for your service. The api-key is the sole mechanism for authenticating access to your search service endpoint. You can obtain your api-key from the Azure portal or via the Azure CLI:

az search admin-key show --service-name <mysearch> --resource-group <mysearch-rg>

There are two types of keys used to access your search service: admin (read-write) and query (read-only) keys. Restricting access and operations in client apps is essential to safeguarding the search assets on your service. Always use a query key rather than an admin key for any query originating from a client app.

Note: The example Azure CLI snippet above retrieves an admin key so it's easier to get started exploring APIs, but it should be managed carefully.

We can use the api-key to create a new SearchClient.

string indexName = "nycjobs";

// Get the service endpoint and API key from the environment
Uri endpoint = new Uri(Environment.GetEnvironmentVariable("SEARCH_ENDPOINT"));
string key = Environment.GetEnvironmentVariable("SEARCH_API_KEY");

// Create a client
AzureKeyCredential credential = new AzureKeyCredential(key);
SearchClient client = new SearchClient(endpoint, indexName, credential);


To inject SearchClient as a dependency in an ASP.NET Core app, first install the package Microsoft.Extensions.Azure. Then register the client in the Startup.ConfigureServices method:

public void ConfigureServices(IServiceCollection services)
    services.AddAzureClients(builder =>

To use the preceding code, add this to your configuration:

    "SearchClient": {
      "endpoint": "https://<resource-name>",
      "indexname": "nycjobs"

You'll also need to provide your resource key to authenticate the client, but you shouldn't be putting that information in the configuration. Instead, when in development, use User-Secrets. Add the following to secrets.json:

    "SearchClient": {
      "credential": { "key": "<you resource key>" }

When running in production, it's preferable to use environment variables:


Or use other secure ways of storing secrets like Azure Key Vault.

For more details about Dependency Injection in ASP.NET Core apps, see Dependency injection with the Azure SDK for .NET.

Key concepts

An Azure Cognitive Search service contains one or more indexes that provide persistent storage of searchable data in the form of JSON documents. (If you're brand new to search, you can make a very rough analogy between indexes and database tables.) The Azure.Search.Documents client library exposes operations on these resources through three main client types.

The Azure.Search.Documents client library (v11) is a brand new offering for .NET developers who want to use search technology in their applications. There is an older, fully featured Microsoft.Azure.Search client library (v10) with many similar looking APIs, so please be careful to avoid confusion when exploring online resources. A good rule of thumb is to check for the namespace using Azure.Search.Documents; when you're looking for us.

Thread safety

We guarantee that all client instance methods are thread-safe and independent of each other (guideline). This ensures that the recommendation of reusing client instances is always safe, even across threads.

Additional concepts

Client options | Accessing the response | Long-running operations | Handling failures | Diagnostics | Mocking | Client lifetime


The following examples all use a simple Hotel data set that you can import into your own index from the Azure portal. These are just a few of the basics - please check out our Samples for much more.

Advanced authentication


Let's start by importing our namespaces.

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

We'll then create a SearchClient to access our hotels search index.

// Get the service endpoint and API key from the environment
Uri endpoint = new Uri(Environment.GetEnvironmentVariable("SEARCH_ENDPOINT"));
string key = Environment.GetEnvironmentVariable("SEARCH_API_KEY");
string indexName = "hotels";

// Create a client
AzureKeyCredential credential = new AzureKeyCredential(key);
SearchClient client = new SearchClient(endpoint, indexName, credential);

There are two ways to interact with the data returned from a search query. Let's explore them with a search for a "luxury" hotel.

Use C# types for search results

We can decorate our own C# types with attributes from System.Text.Json:

public class Hotel
    [SimpleField(IsKey = true, IsFilterable = true, IsSortable = true)]
    public string Id { get; set; }

    [SearchableField(IsFilterable = true, IsSortable = true)]
    public string Name { get; set; }

Then we use them as the type parameter when querying to return strongly-typed search results:

SearchResults<Hotel> response = client.Search<Hotel>("luxury");
foreach (SearchResult<Hotel> result in response.GetResults())
    Hotel doc = result.Document;
    Console.WriteLine($"{doc.Id}: {doc.Name}");

If you're working with a search index and know the schema, creating C# types is recommended.

Use SearchDocument like a dictionary for search results

If you don't have your own type for search results, SearchDocument can be used instead. Here we perform the search, enumerate over the results, and extract data using SearchDocument's dictionary indexer.

SearchResults<SearchDocument> response = client.Search<SearchDocument>("luxury");
foreach (SearchResult<SearchDocument> result in response.GetResults())
    SearchDocument doc = result.Document;
    string id = (string)doc["HotelId"];
    string name = (string)doc["HotelName"];
    Console.WriteLine("{id}: {name}");

The SearchOptions provide powerful control over the behavior of our queries. Let's search for the top 5 luxury hotels with a good rating.

int stars = 4;
SearchOptions options = new SearchOptions
    // Filter to only Rating greater than or equal our preference
    Filter = SearchFilter.Create($"Rating ge {stars}"),
    Size = 5, // Take only 5 results
    OrderBy = { "Rating desc" } // Sort by Rating from high to low
SearchResults<Hotel> response = client.Search<Hotel>("luxury", options);
// ...

Creating an index

You can use the SearchIndexClient to create a search index. Fields can be defined from a model class using FieldBuilder. Indexes can also define suggesters, lexical analyzers, and more:

Uri endpoint = new Uri(Environment.GetEnvironmentVariable("SEARCH_ENDPOINT"));
string key = Environment.GetEnvironmentVariable("SEARCH_API_KEY");

// Create a service client
AzureKeyCredential credential = new AzureKeyCredential(key);
SearchIndexClient client = new SearchIndexClient(endpoint, credential);

// Create the index using FieldBuilder.
SearchIndex index = new SearchIndex("hotels")
    Fields = new FieldBuilder().Build(typeof(Hotel)),
    Suggesters =
        // Suggest query terms from the hotelName field.
        new SearchSuggester("sg", "hotelName")


In scenarios when the model is not known or cannot be modified, you can also create fields explicitly using convenient SimpleField, SearchableField, or ComplexField classes:

// Create the index using field definitions.
SearchIndex index = new SearchIndex("hotels")
    Fields =
        new SimpleField("hotelId", SearchFieldDataType.String) { IsKey = true, IsFilterable = true, IsSortable = true },
        new SearchableField("hotelName") { IsFilterable = true, IsSortable = true },
        new SearchableField("description") { AnalyzerName = LexicalAnalyzerName.EnLucene },
        new SearchableField("tags", collection: true) { IsFilterable = true, IsFacetable = true },
        new ComplexField("address")
            Fields =
                new SearchableField("streetAddress"),
                new SearchableField("city") { IsFilterable = true, IsSortable = true, IsFacetable = true },
                new SearchableField("stateProvince") { IsFilterable = true, IsSortable = true, IsFacetable = true },
                new SearchableField("country") { IsFilterable = true, IsSortable = true, IsFacetable = true },
                new SearchableField("postalCode") { IsFilterable = true, IsSortable = true, IsFacetable = true }
    Suggesters =
        // Suggest query terms from the hotelName field.
        new SearchSuggester("sg", "hotelName")


Adding documents to your index

You can Upload, Merge, MergeOrUpload, and Delete multiple documents from an index in a single batched request. There are a few special rules for merging to be aware of.

IndexDocumentsBatch<Hotel> batch = IndexDocumentsBatch.Create(
    IndexDocumentsAction.Upload(new Hotel { Id = "783", Name = "Upload Inn" }),
    IndexDocumentsAction.Merge(new Hotel { Id = "12", Name = "Renovated Ranch" }));

IndexDocumentsOptions options = new IndexDocumentsOptions { ThrowOnAnyError = true };
client.IndexDocuments(batch, options);

The request will succeed even if any of the individual actions fail and return an IndexDocumentsResult for inspection. There's also a ThrowOnAnyError option if you only care about success or failure of the whole batch.

Retrieving a specific document from your index

In addition to querying for documents using keywords and optional filters, you can retrieve a specific document from your index if you already know the key. You could get the key from a query, for example, and want to show more information about it or navigate your customer to that document.

Hotel doc = client.GetDocument<Hotel>("1");
Console.WriteLine($"{doc.Id}: {doc.Name}");

Async APIs

All of the examples so far have been using synchronous APIs, but we provide full support for async APIs as well. You'll generally just add an Async suffix to the name of the method and await it.

SearchResults<Hotel> response = await client.SearchAsync<Hotel>("luxury");
await foreach (SearchResult<Hotel> result in response.GetResultsAsync())
    Hotel doc = result.Document;
    Console.WriteLine($"{doc.Id}: {doc.Name}");

Authenticate in a National Cloud

To authenticate in a National Cloud, you will need to make the following additions to your client configuration:

  • Set the AuthorityHost in the credential options or via the AZURE_AUTHORITY_HOST environment variable
  • Set the Audience in SearchClientOptions
// Create a SearchClient that will authenticate through AAD in the China national cloud
string indexName = "nycjobs";
Uri endpoint = new Uri(Environment.GetEnvironmentVariable("SEARCH_ENDPOINT"));
SearchClient client = new SearchClient(endpoint, indexName,
    new DefaultAzureCredential(
        new DefaultAzureCredentialOptions()
            AuthorityHost = AzureAuthorityHosts.AzureChina
    new SearchClientOptions()
        Audience = SearchAudience.AzureChina


Any Azure.Search.Documents operation that fails will throw a RequestFailedException with helpful Status codes. Many of these errors are recoverable.

    return client.GetDocument<Hotel>("12345");
catch (RequestFailedException ex) when (ex.Status == 404)
    Console.WriteLine("We couldn't find the hotel you are looking for!");
    Console.WriteLine("Please try selecting another.");
    return null;

You can also easily enable console logging if you want to dig deeper into the requests you're making against the service.

See our troubleshooting guide for details on how to diagnose various failure scenarios.

Next steps


See our Search for details on building, testing, and contributing to this library.

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact with any additional questions or comments.

Product Compatible and additional computed target framework versions.
.NET net5.0 was computed.  net5.0-windows was computed.  net6.0 was computed.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 was computed.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
.NET Core netcoreapp2.0 was computed.  netcoreapp2.1 was computed.  netcoreapp2.2 was computed.  netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard2.0 is compatible.  netstandard2.1 was computed. 
.NET Framework net461 was computed.  net462 was computed.  net463 was computed.  net47 was computed.  net471 was computed.  net472 was computed.  net48 was computed.  net481 was computed. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen40 was computed.  tizen60 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (39)

Showing the top 5 NuGet packages that depend on Azure.Search.Documents:

Package Downloads

Shared entities and contracts for Hilma Domain


This NuGet package contains Data Access Layer for Indigina projects.

Microsoft.Azure.Workflows.WebJobs.Extension The ID prefix of this package has been reserved for one of the owners of this package by

Extensions for running workflows in Azure Functions


An Examine implementation with Azure Search

Microsoft.KernelMemory.MemoryDb.AzureAISearch The ID prefix of this package has been reserved for one of the owners of this package by

Azure AI Search connector for Microsoft Kernel Memory, to store and search memory using Azure AI Search vector indexing and semantic features.

GitHub repositories (11)

Showing the top 5 popular GitHub repositories that depend on Azure.Search.Documents:

Repository Stars
Integrate cutting-edge LLM technology quickly and easily into your apps
Orchard Core is an open-source modular and multi-tenant application framework built with ASP.NET Core, and a content management system (CMS) built on top of that framework.
Enterprise HealthChecks for ASP.NET Core Diagnostics Package
Headless CMS and Content Managment Hub
Index and query any data using LLM and natural language, tracking sources and showing citations.
Version Downloads Last updated
11.6.0-beta.3 7,939 3/6/2024
11.6.0-beta.2 21,324 2/5/2024
11.6.0-beta.1 26,206 1/17/2024
11.5.1 851,221 11/29/2023
11.5.0 116,508 11/10/2023
11.5.0-beta.5 157,421 10/9/2023
11.5.0-beta.4 181,387 8/7/2023
11.5.0-beta.3 145,943 7/11/2023
11.5.0-beta.2 782,491 10/11/2022
11.5.0-beta.1 27,864 9/7/2022
11.4.0 3,727,046 9/6/2022
11.4.0-beta.9 13,461 8/8/2022
11.4.0-beta.8 3,500 7/7/2022
11.4.0-beta.7 99,584 3/8/2022
11.4.0-beta.6 8,398 2/8/2022
11.4.0-beta.5 77,934 11/19/2021
11.4.0-beta.4 12,204 10/7/2021
11.4.0-beta.3 13,518 9/8/2021
11.4.0-beta.2 17,003 8/10/2021
11.4.0-beta.1 3,609 7/9/2021
11.3.0 3,989,307 6/10/2021
11.3.0-beta.2 2,216 5/11/2021
11.3.0-beta.1 10,427 4/6/2021
11.2.1 207,254 5/10/2021
11.2.0 3,240,327 2/10/2021
11.2.0-beta.2 52,536 11/11/2020
11.2.0-beta.1 5,538 10/9/2020
11.1.1 941,578 8/18/2020
11.0.0 37,141 7/7/2020
1.0.0-preview.4 577 6/9/2020
1.0.0-preview.3 320 5/5/2020
1.0.0-preview.2 669 4/6/2020