Azure Search Documents Dotnet

1---
2name: azure-search-documents-dotnet
3description: |
4  Azure AI Search SDK for .NET (Azure.Search.Documents). Use for building search applications with full-text, vector, semantic, and hybrid search. Covers SearchClient (queries, document CRUD), SearchIndexClient (index management), and SearchIndexerClient (indexers, skillsets). Triggers: "Azure Search .NET", "SearchClient", "SearchIndexClient", "vector search C#", "semantic search .NET", "hybrid search", "Azure.Search.Documents".
5package: Azure.Search.Documents
6---
7 
8# Azure.Search.Documents (.NET)
9 
10Build search applications with full-text, vector, semantic, and hybrid search capabilities.
11 
12## Installation
13 
14```bash
15dotnet add package Azure.Search.Documents
16dotnet add package Azure.Identity
17```
18 
19**Current Versions**: Stable v11.7.0, Preview v11.8.0-beta.1
20 
21## Environment Variables
22 
23```bash
24SEARCH_ENDPOINT=https://<search-service>.search.windows.net
25SEARCH_INDEX_NAME=<index-name>
26# For API key auth (not recommended for production)
27SEARCH_API_KEY=<api-key>
28```
29 
30## Authentication
31 
32**DefaultAzureCredential (preferred)**:
33```csharp
34using Azure.Identity;
35using Azure.Search.Documents;
36 
37var credential = new DefaultAzureCredential();
38var client = new SearchClient(
39    new Uri(Environment.GetEnvironmentVariable("SEARCH_ENDPOINT")),
40    Environment.GetEnvironmentVariable("SEARCH_INDEX_NAME"),
41    credential);
42```
43 
44**API Key**:
45```csharp
46using Azure;
47using Azure.Search.Documents;
48 
49var credential = new AzureKeyCredential(
50    Environment.GetEnvironmentVariable("SEARCH_API_KEY"));
51var client = new SearchClient(
52    new Uri(Environment.GetEnvironmentVariable("SEARCH_ENDPOINT")),
53    Environment.GetEnvironmentVariable("SEARCH_INDEX_NAME"),
54    credential);
55```
56 
57## Client Selection
58 
59| Client | Purpose |
60|--------|---------|
61| `SearchClient` | Query indexes, upload/update/delete documents |
62| `SearchIndexClient` | Create/manage indexes, synonym maps |
63| `SearchIndexerClient` | Manage indexers, skillsets, data sources |
64 
65## Index Creation
66 
67### Using FieldBuilder (Recommended)
68 
69```csharp
70using Azure.Search.Documents.Indexes;
71using Azure.Search.Documents.Indexes.Models;
72 
73// Define model with attributes
74public class Hotel
75{
76    [SimpleField(IsKey = true, IsFilterable = true)]
77    public string HotelId { get; set; }
78 
79    [SearchableField(IsSortable = true)]
80    public string HotelName { get; set; }
81 
82    [SearchableField(AnalyzerName = LexicalAnalyzerName.EnLucene)]
83    public string Description { get; set; }
84 
85    [SimpleField(IsFilterable = true, IsSortable = true, IsFacetable = true)]
86    public double? Rating { get; set; }
87 
88    [VectorSearchField(VectorSearchDimensions = 1536, VectorSearchProfileName = "vector-profile")]
89    public ReadOnlyMemory<float>? DescriptionVector { get; set; }
90}
91 
92// Create index
93var indexClient = new SearchIndexClient(endpoint, credential);
94var fieldBuilder = new FieldBuilder();
95var fields = fieldBuilder.Build(typeof(Hotel));
96 
97var index = new SearchIndex("hotels")
98{
99    Fields = fields,
100    VectorSearch = new VectorSearch
101    {
102        Profiles = { new VectorSearchProfile("vector-profile", "hnsw-algo") },
103        Algorithms = { new HnswAlgorithmConfiguration("hnsw-algo") }
104    }
105};
106 
107await indexClient.CreateOrUpdateIndexAsync(index);
108```
109 
110### Manual Field Definition
111 
112```csharp
113var index = new SearchIndex("hotels")
114{
115    Fields =
116    {
117        new SimpleField("hotelId", SearchFieldDataType.String) { IsKey = true, IsFilterable = true },
118        new SearchableField("hotelName") { IsSortable = true },
119        new SearchableField("description") { AnalyzerName = LexicalAnalyzerName.EnLucene },
120        new SimpleField("rating", SearchFieldDataType.Double) { IsFilterable = true, IsSortable = true },
121        new SearchField("descriptionVector", SearchFieldDataType.Collection(SearchFieldDataType.Single))
122        {
123            VectorSearchDimensions = 1536,
124            VectorSearchProfileName = "vector-profile"
125        }
126    }
127};
128```
129 
130## Document Operations
131 
132```csharp
133var searchClient = new SearchClient(endpoint, indexName, credential);
134 
135// Upload (add new)
136var hotels = new[] { new Hotel { HotelId = "1", HotelName = "Hotel A" } };
137await searchClient.UploadDocumentsAsync(hotels);
138 
139// Merge (update existing)
140await searchClient.MergeDocumentsAsync(hotels);
141 
142// Merge or Upload (upsert)
143await searchClient.MergeOrUploadDocumentsAsync(hotels);
144 
145// Delete
146await searchClient.DeleteDocumentsAsync("hotelId", new[] { "1", "2" });
147 
148// Batch operations
149var batch = IndexDocumentsBatch.Create(
150    IndexDocumentsAction.Upload(hotel1),
151    IndexDocumentsAction.Merge(hotel2),
152    IndexDocumentsAction.Delete(hotel3));
153await searchClient.IndexDocumentsAsync(batch);
154```
155 
156## Search Patterns
157 
158### Basic Search
159 
160```csharp
161var options = new SearchOptions
162{
163    Filter = "rating ge 4",
164    OrderBy = { "rating desc" },
165    Select = { "hotelId", "hotelName", "rating" },
166    Size = 10,
167    Skip = 0,
168    IncludeTotalCount = true
169};
170 
171SearchResults<Hotel> results = await searchClient.SearchAsync<Hotel>("luxury", options);
172 
173Console.WriteLine($"Total: {results.TotalCount}");
174await foreach (SearchResult<Hotel> result in results.GetResultsAsync())
175{
176    Console.WriteLine($"{result.Document.HotelName} (Score: {result.Score})");
177}
178```
179 
180### Faceted Search
181 
182```csharp
183var options = new SearchOptions
184{
185    Facets = { "rating,count:5", "category" }
186};
187 
188var results = await searchClient.SearchAsync<Hotel>("*", options);
189 
190foreach (var facet in results.Value.Facets["rating"])
191{
192    Console.WriteLine($"Rating {facet.Value}: {facet.Count}");
193}
194```
195 
196### Autocomplete and Suggestions
197 
198```csharp
199// Autocomplete
200var autocompleteOptions = new AutocompleteOptions { Mode = AutocompleteMode.OneTermWithContext };
201var autocomplete = await searchClient.AutocompleteAsync("lux", "suggester-name", autocompleteOptions);
202 
203// Suggestions
204var suggestOptions = new SuggestOptions { UseFuzzyMatching = true };
205var suggestions = await searchClient.SuggestAsync<Hotel>("lux", "suggester-name", suggestOptions);
206```
207 
208## Vector Search
209 
210See [references/vector-search.md](references/vector-search.md) for detailed patterns.
211 
212```csharp
213using Azure.Search.Documents.Models;
214 
215// Pure vector search
216var vectorQuery = new VectorizedQuery(embedding)
217{
218    KNearestNeighborsCount = 5,
219    Fields = { "descriptionVector" }
220};
221 
222var options = new SearchOptions
223{
224    VectorSearch = new VectorSearchOptions
225    {
226        Queries = { vectorQuery }
227    }
228};
229 
230var results = await searchClient.SearchAsync<Hotel>(null, options);
231```
232 
233## Semantic Search
234 
235See [references/semantic-search.md](references/semantic-search.md) for detailed patterns.
236 
237```csharp
238var options = new SearchOptions
239{
240    QueryType = SearchQueryType.Semantic,
241    SemanticSearch = new SemanticSearchOptions
242    {
243        SemanticConfigurationName = "my-semantic-config",
244        QueryCaption = new QueryCaption(QueryCaptionType.Extractive),
245        QueryAnswer = new QueryAnswer(QueryAnswerType.Extractive)
246    }
247};
248 
249var results = await searchClient.SearchAsync<Hotel>("best hotel for families", options);
250 
251// Access semantic answers
252foreach (var answer in results.Value.SemanticSearch.Answers)
253{
254    Console.WriteLine($"Answer: {answer.Text} (Score: {answer.Score})");
255}
256 
257// Access captions
258await foreach (var result in results.Value.GetResultsAsync())
259{
260    var caption = result.SemanticSearch?.Captions?.FirstOrDefault();
261    Console.WriteLine($"Caption: {caption?.Text}");
262}
263```
264 
265## Hybrid Search (Vector + Keyword + Semantic)
266 
267```csharp
268var vectorQuery = new VectorizedQuery(embedding)
269{
270    KNearestNeighborsCount = 5,
271    Fields = { "descriptionVector" }
272};
273 
274var options = new SearchOptions
275{
276    QueryType = SearchQueryType.Semantic,
277    SemanticSearch = new SemanticSearchOptions
278    {
279        SemanticConfigurationName = "my-semantic-config"
280    },
281    VectorSearch = new VectorSearchOptions
282    {
283        Queries = { vectorQuery }
284    }
285};
286 
287// Combines keyword search, vector search, and semantic ranking
288var results = await searchClient.SearchAsync<Hotel>("luxury beachfront", options);
289```
290 
291## Field Attributes Reference
292 
293| Attribute | Purpose |
294|-----------|---------|
295| `SimpleField` | Non-searchable field (filters, sorting, facets) |
296| `SearchableField` | Full-text searchable field |
297| `VectorSearchField` | Vector embedding field |
298| `IsKey = true` | Document key (required, one per index) |
299| `IsFilterable = true` | Enable $filter expressions |
300| `IsSortable = true` | Enable $orderby |
301| `IsFacetable = true` | Enable faceted navigation |
302| `IsHidden = true` | Exclude from results |
303| `AnalyzerName` | Specify text analyzer |
304 
305## Error Handling
306 
307```csharp
308using Azure;
309 
310try
311{
312    var results = await searchClient.SearchAsync<Hotel>("query");
313}
314catch (RequestFailedException ex) when (ex.Status == 404)
315{
316    Console.WriteLine("Index not found");
317}
318catch (RequestFailedException ex)
319{
320    Console.WriteLine($"Search error: {ex.Status} - {ex.ErrorCode}: {ex.Message}");
321}
322```
323 
324## Best Practices
325 
3261. **Use `DefaultAzureCredential`** over API keys for production
3272. **Use `FieldBuilder`** with model attributes for type-safe index definitions
3283. **Use `CreateOrUpdateIndexAsync`** for idempotent index creation
3294. **Batch document operations** for better throughput
3305. **Use `Select`** to return only needed fields
3316. **Configure semantic search** for natural language queries
3327. **Combine vector + keyword + semantic** for best relevance
333 
334## Reference Files
335 
336| File | Contents |
337|------|----------|
338| [references/vector-search.md](references/vector-search.md) | Vector search, hybrid search, vectorizers |
339| [references/semantic-search.md](references/semantic-search.md) | Semantic ranking, captions, answers |
340