Azure Search Documents Ts

1---
2name: azure-search-documents-ts
3description: Build search applications using Azure AI Search SDK for JavaScript (@azure/search-documents). Use when creating/managing indexes, implementing vector/hybrid search, semantic ranking, or building agentic retrieval with knowledge bases.
4package: "@azure/search-documents"
5---
6 
7# Azure AI Search SDK for TypeScript
8 
9Build search applications with vector, hybrid, and semantic search capabilities.
10 
11## Installation
12 
13```bash
14npm install @azure/search-documents @azure/identity
15```
16 
17## Environment Variables
18 
19```bash
20AZURE_SEARCH_ENDPOINT=https://<service-name>.search.windows.net
21AZURE_SEARCH_INDEX_NAME=my-index
22AZURE_SEARCH_ADMIN_KEY=<admin-key>  # Optional if using Entra ID
23```
24 
25## Authentication
26 
27```typescript
28import { SearchClient, SearchIndexClient } from "@azure/search-documents";
29import { DefaultAzureCredential } from "@azure/identity";
30 
31const endpoint = process.env.AZURE_SEARCH_ENDPOINT!;
32const indexName = process.env.AZURE_SEARCH_INDEX_NAME!;
33const credential = new DefaultAzureCredential();
34 
35// For searching
36const searchClient = new SearchClient(endpoint, indexName, credential);
37 
38// For index management
39const indexClient = new SearchIndexClient(endpoint, credential);
40```
41 
42## Core Workflow
43 
44### Create Index with Vector Field
45 
46```typescript
47import { SearchIndex, SearchField, VectorSearch } from "@azure/search-documents";
48 
49const index: SearchIndex = {
50  name: "products",
51  fields: [
52    { name: "id", type: "Edm.String", key: true },
53    { name: "title", type: "Edm.String", searchable: true },
54    { name: "description", type: "Edm.String", searchable: true },
55    { name: "category", type: "Edm.String", filterable: true, facetable: true },
56    {
57      name: "embedding",
58      type: "Collection(Edm.Single)",
59      searchable: true,
60      vectorSearchDimensions: 1536,
61      vectorSearchProfileName: "vector-profile",
62    },
63  ],
64  vectorSearch: {
65    algorithms: [
66      { name: "hnsw-algorithm", kind: "hnsw" },
67    ],
68    profiles: [
69      { name: "vector-profile", algorithmConfigurationName: "hnsw-algorithm" },
70    ],
71  },
72};
73 
74await indexClient.createOrUpdateIndex(index);
75```
76 
77### Index Documents
78 
79```typescript
80const documents = [
81  { id: "1", title: "Widget", description: "A useful widget", category: "Tools", embedding: [...] },
82  { id: "2", title: "Gadget", description: "A cool gadget", category: "Electronics", embedding: [...] },
83];
84 
85const result = await searchClient.uploadDocuments(documents);
86console.log(`Indexed ${result.results.length} documents`);
87```
88 
89### Full-Text Search
90 
91```typescript
92const results = await searchClient.search("widget", {
93  select: ["id", "title", "description"],
94  filter: "category eq 'Tools'",
95  orderBy: ["title asc"],
96  top: 10,
97});
98 
99for await (const result of results.results) {
100  console.log(`${result.document.title}: ${result.score}`);
101}
102```
103 
104### Vector Search
105 
106```typescript
107const queryVector = await getEmbedding("useful tool"); // Your embedding function
108 
109const results = await searchClient.search("*", {
110  vectorSearchOptions: {
111    queries: [
112      {
113        kind: "vector",
114        vector: queryVector,
115        fields: ["embedding"],
116        kNearestNeighborsCount: 10,
117      },
118    ],
119  },
120  select: ["id", "title", "description"],
121});
122 
123for await (const result of results.results) {
124  console.log(`${result.document.title}: ${result.score}`);
125}
126```
127 
128### Hybrid Search (Text + Vector)
129 
130```typescript
131const queryVector = await getEmbedding("useful tool");
132 
133const results = await searchClient.search("tool", {
134  vectorSearchOptions: {
135    queries: [
136      {
137        kind: "vector",
138        vector: queryVector,
139        fields: ["embedding"],
140        kNearestNeighborsCount: 50,
141      },
142    ],
143  },
144  select: ["id", "title", "description"],
145  top: 10,
146});
147```
148 
149### Semantic Search
150 
151```typescript
152// Index must have semantic configuration
153const index: SearchIndex = {
154  name: "products",
155  fields: [...],
156  semanticSearch: {
157    configurations: [
158      {
159        name: "semantic-config",
160        prioritizedFields: {
161          titleField: { name: "title" },
162          contentFields: [{ name: "description" }],
163        },
164      },
165    ],
166  },
167};
168 
169// Search with semantic ranking
170const results = await searchClient.search("best tool for the job", {
171  queryType: "semantic",
172  semanticSearchOptions: {
173    configurationName: "semantic-config",
174    captions: { captionType: "extractive" },
175    answers: { answerType: "extractive", count: 3 },
176  },
177  select: ["id", "title", "description"],
178});
179 
180for await (const result of results.results) {
181  console.log(`${result.document.title}`);
182  console.log(`  Caption: ${result.captions?.[0]?.text}`);
183  console.log(`  Reranker Score: ${result.rerankerScore}`);
184}
185```
186 
187## Filtering and Facets
188 
189```typescript
190// Filter syntax
191const results = await searchClient.search("*", {
192  filter: "category eq 'Electronics' and price lt 100",
193  facets: ["category,count:10", "brand"],
194});
195 
196// Access facets
197for (const [facetName, facetResults] of Object.entries(results.facets || {})) {
198  console.log(`${facetName}:`);
199  for (const facet of facetResults) {
200    console.log(`  ${facet.value}: ${facet.count}`);
201  }
202}
203```
204 
205## Autocomplete and Suggestions
206 
207```typescript
208// Create suggester in index
209const index: SearchIndex = {
210  name: "products",
211  fields: [...],
212  suggesters: [
213    { name: "sg", sourceFields: ["title", "description"] },
214  ],
215};
216 
217// Autocomplete
218const autocomplete = await searchClient.autocomplete("wid", "sg", {
219  mode: "twoTerms",
220  top: 5,
221});
222 
223// Suggestions
224const suggestions = await searchClient.suggest("wid", "sg", {
225  select: ["title"],
226  top: 5,
227});
228```
229 
230## Batch Operations
231 
232```typescript
233// Batch upload, merge, delete
234const batch = [
235  { upload: { id: "1", title: "New Item" } },
236  { merge: { id: "2", title: "Updated Title" } },
237  { delete: { id: "3" } },
238];
239 
240const result = await searchClient.indexDocuments({ actions: batch });
241```
242 
243## Key Types
244 
245```typescript
246import {
247  SearchClient,
248  SearchIndexClient,
249  SearchIndexerClient,
250  SearchIndex,
251  SearchField,
252  SearchOptions,
253  VectorSearch,
254  SemanticSearch,
255  SearchIterator,
256} from "@azure/search-documents";
257```
258 
259## Best Practices
260 
2611. **Use hybrid search** - Combine vector + text for best results
2622. **Enable semantic ranking** - Improves relevance for natural language queries
2633. **Batch document uploads** - Use `uploadDocuments` with arrays, not single docs
2644. **Use filters for security** - Implement document-level security with filters
2655. **Index incrementally** - Use `mergeOrUploadDocuments` for updates
2666. **Monitor query performance** - Use `includeTotalCount: true` sparingly in production
267