Acceptance Criteria: azure-search-documents-ts

Overview

This document defines the acceptance criteria for code generated using the @azure/search-documents SDK for TypeScript/JavaScript.

Package: @azure/search-documents
Repository: https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/search/search-documents

---

1. Import Statements

✅ MUST

// ESM imports
import {
  SearchClient,
  SearchIndexClient,
  SearchIndexerClient,
  AzureKeyCredential,
} from "@azure/search-documents";
import { DefaultAzureCredential } from "@azure/identity";

❌ MUST NOT

// CommonJS require
const { SearchClient } = require("@azure/search-documents");

// Old package names
import { SearchServiceClient } from "azure-search";

---

2. Client Instantiation

SearchClient (for querying)

// ✅ Correct - with DefaultAzureCredential
const credential = new DefaultAzureCredential();
const client = new SearchClient("<endpoint>", "<indexName>", credential);

// ✅ Correct - with API key
const client = new SearchClient(
  "<endpoint>",
  "<indexName>",
  new AzureKeyCredential("<apiKey>")
);

SearchIndexClient (for index management)

// ✅ Correct
const indexClient = new SearchIndexClient("<endpoint>", credential);
const indexClient = new SearchIndexClient("<endpoint>", new AzureKeyCredential("<apiKey>"));

SearchIndexerClient (for indexers)

// ✅ Correct
const indexerClient = new SearchIndexerClient("<endpoint>", credential);

❌ MUST NOT

// Hardcoded credentials
const client = new SearchClient(endpoint, indexName, "api-key-string");

// Missing index name for SearchClient
const client = new SearchClient(endpoint, credential);

---

3. Search Operations

Basic Search

// ✅ Correct - async iteration
const results = await searchClient.search("wifi -luxury");
for await (const result of results.results) {
  console.log(result.document);
}

// ✅ Correct - with options
const results = await searchClient.search("wifi", {
  select: ["hotelId", "hotelName"],
  filter: "rating ge 4",
  orderBy: ["rating desc"],
  top: 10,
});

Vector Search

// ✅ Correct - vector query
const results = await searchClient.search("*", {
  vectorSearchOptions: {
    queries: [
      {
        kind: "vector",
        vector: queryVector,
        fields: ["descriptionVector"],
        kNearestNeighborsCount: 3,
      },
    ],
  },
});

// ❌ Incorrect - old vector syntax
const results = await searchClient.search("*", {
  vectors: [{ value: queryVector, fields: ["embedding"], k: 3 }],
});

Hybrid Search (Text + Vector)

// ✅ Correct - combine text and vector
const results = await searchClient.search("luxury hotel", {
  vectorSearchOptions: {
    queries: [
      {
        kind: "vector",
        vector: queryVector,
        fields: ["descriptionVector"],
        kNearestNeighborsCount: 50,
      },
    ],
  },
  select: ["hotelId", "hotelName", "description"],
  top: 10,
});

Semantic Search

// ✅ Correct
const results = await searchClient.search("best hotel for families", {
  queryType: "semantic",
  semanticSearchOptions: {
    configurationName: "semantic-config",
    captions: { captionType: "extractive" },
    answers: { answerType: "extractive", count: 3 },
  },
});

// Access semantic results
for await (const result of results.results) {
  console.log(result.rerankerScore);
  console.log(result.captions);
}

---

4. Index Operations

Create Index

// ✅ Correct - with typed fields
const index: SearchIndex = {
  name: "hotels",
  fields: [
    { name: "id", type: "Edm.String", key: true },
    { name: "name", type: "Edm.String", searchable: true },
    { name: "rating", type: "Edm.Double", filterable: true, sortable: true },
    {
      name: "embedding",
      type: "Collection(Edm.Single)",
      searchable: true,
      vectorSearchDimensions: 1536,
      vectorSearchProfileName: "vector-profile",
    },
  ],
  vectorSearch: {
    algorithms: [{ name: "hnsw-algorithm", kind: "hnsw" }],
    profiles: [
      { name: "vector-profile", algorithmConfigurationName: "hnsw-algorithm" },
    ],
  },
};

await indexClient.createIndex(index);

// ✅ Correct - create or update (idempotent)
await indexClient.createOrUpdateIndex(index);

Semantic Configuration

// ✅ Correct
const index: SearchIndex = {
  name: "hotels",
  fields: [...],
  semanticSearch: {
    configurations: [
      {
        name: "semantic-config",
        prioritizedFields: {
          titleField: { name: "name" },
          contentFields: [{ name: "description" }],
          keywordsFields: [{ name: "tags" }],
        },
      },
    ],
  },
};

---

5. Document Operations

Upload Documents

// ✅ Correct - batch upload
const result = await searchClient.uploadDocuments([
  { id: "1", name: "Hotel A", rating: 4.5 },
  { id: "2", name: "Hotel B", rating: 4.0 },
]);

for (const r of result.results) {
  console.log(`${r.key}: ${r.succeeded}`);
}

Merge or Upload (Upsert)

// ✅ Correct - idempotent upsert
const result = await searchClient.mergeOrUploadDocuments([
  { id: "1", name: "Updated Hotel A" },
]);

Delete Documents

// ✅ Correct
const result = await searchClient.deleteDocuments([
  { id: "1" },
  { id: "2" },
]);

Get Document

// ✅ Correct - retrieve by key
const document = await searchClient.getDocument("1");

---

6. Filtering and Facets

Filter Syntax

// ✅ Correct - OData filter
const results = await searchClient.search("*", {
  filter: "rating ge 4 and category eq 'luxury'",
});

// ✅ Correct - using odata helper
import { odata } from "@azure/search-documents";

const minRating = 4;
const results = await searchClient.search("*", {
  filter: odata`rating ge ${minRating}`,
});

Facets

// ✅ Correct
const results = await searchClient.search("*", {
  facets: ["category,count:10", "rating,interval:1"],
});

// Access facets
for (const [facetName, facetResults] of Object.entries(results.facets || {})) {
  for (const facet of facetResults) {
    console.log(`${facet.value}: ${facet.count}`);
  }
}

---

7. Autocomplete and Suggestions

Suggester Definition

// ✅ Correct - in index definition
const index: SearchIndex = {
  name: "hotels",
  fields: [...],
  suggesters: [
    { name: "sg", sourceFields: ["name", "description"] },
  ],
};

Autocomplete

// ✅ Correct
const autocomplete = await searchClient.autocomplete("lux", "sg", {
  mode: "twoTerms",
  top: 5,
});

for (const result of autocomplete.results) {
  console.log(result.text);
}

Suggestions

// ✅ Correct
const suggestions = await searchClient.suggest("lux", "sg", {
  select: ["name"],
  top: 5,
});

for (const result of suggestions.results) {
  console.log(result.document.name);
}

---

8. TypeScript Typing

Typed Documents

// ✅ Correct - generic type parameter
interface Hotel {
  id: string;
  name: string;
  rating: number;
  description?: string;
}

const searchClient = new SearchClient<Hotel>(endpoint, indexName, credential);

const results = await searchClient.search("luxury", {
  select: ["id", "name", "rating"], // Type-checked
});

for await (const result of results.results) {
  // result.document is typed as Hotel
  console.log(result.document.name);
}

Select Fields Type Helper

import { SelectFields } from "@azure/search-documents";

const select: SelectFields<Hotel>[] = ["id", "name"];

---

9. Error Handling

✅ MUST

import { RestError } from "@azure/core-rest-pipeline";

try {
  const results = await searchClient.search("query");
} catch (error) {
  if (error instanceof RestError) {
    console.log(`Search error: ${error.statusCode} - ${error.message}`);
  } else {
    throw error;
  }
}

---

10. Anti-Patterns to Avoid

Anti-Pattern	Correct Pattern
require("@azure/search-documents")	import \{ SearchClient \} from "@azure/search-documents"
Hardcoded credentials	Use DefaultAzureCredential or AzureKeyCredential
vectors: [...] (old syntax)	vectorSearchOptions: \{ queries: [...] \}
Missing for await	Always use for await with search results
Sync iteration	All search operations are async

---

11. Type Imports

import {
  SearchClient,
  SearchIndexClient,
  SearchIndexerClient,
  SearchIndex,
  SearchField,
  SearchOptions,
  VectorSearch,
  SemanticSearch,
  AzureKeyCredential,
  odata,
  SelectFields,
} from "@azure/search-documents";

---

References

• Official SDK README
• API Reference
• Samples