GitHub Copilot ChatGPT Claude Codex CLI Cursor opencode Skill Text

azure-search-documents-ts

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.

Ciza · 0 points · 25 views 1 listing impressions 0 install-command copies
Download microsoft-skills-.github_plugins_azure-sdk-typescript_skills_azure-search-documents-ts-e58528d.zip · 8 KB

Install

skills CLI npx skills add https://github.com/microsoft/skills/tree/main/.github/plugins/azure-sdk-typescript/skills/azure-search-documents-ts
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install microsoft-skills@llmmart
Git git clone https://github.com/microsoft/skills.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole microsoft/skills collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

Azure AI Search SDK for TypeScript

Build search applications with vector, hybrid, and semantic search capabilities.

Installation

npm install @azure/search-documents @azure/identity

Environment Variables

AZURE_SEARCH_ENDPOINT=https://<service-name>.search.windows.net
AZURE_SEARCH_INDEX_NAME=my-index
AZURE_SEARCH_ADMIN_KEY=<admin-key>  # Optional if using Entra ID
AZURE_TOKEN_CREDENTIALS=prod # Required only if DefaultAzureCredential is used in production

Authentication

import { SearchClient, SearchIndexClient } from "@azure/search-documents";
import { DefaultAzureCredential, ManagedIdentityCredential } from "@azure/identity";

const endpoint = process.env.AZURE_SEARCH_ENDPOINT!;
const indexName = process.env.AZURE_SEARCH_INDEX_NAME!;
// Local dev: DefaultAzureCredential. Production: set AZURE_TOKEN_CREDENTIALS=prod or AZURE_TOKEN_CREDENTIALS=<specific_credential>
const credential = new DefaultAzureCredential({requiredEnvVars: ["AZURE_TOKEN_CREDENTIALS"]});
// Or use a specific credential directly in production:
// See https://learn.microsoft.com/javascript/api/overview/azure/identity-readme?view=azure-node-latest#credential-classes
// const credential = new ManagedIdentityCredential();

// For searching
const searchClient = new SearchClient(endpoint, indexName, credential);

// For index management
const indexClient = new SearchIndexClient(endpoint, credential);

Core Workflow

Create Index with Vector Field

import { SearchIndex, SearchField, VectorSearch } from "@azure/search-documents";

const index: SearchIndex = {
  name: "products",
  fields: [
    { name: "id", type: "Edm.String", key: true },
    { name: "title", type: "Edm.String", searchable: true },
    { name: "description", type: "Edm.String", searchable: true },
    { name: "category", type: "Edm.String", filterable: true, facetable: 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.createOrUpdateIndex(index);

Index Documents

const documents = [
  { id: "1", title: "Widget", description: "A useful widget", category: "Tools", embedding: [...] },
  { id: "2", title: "Gadget", description: "A cool gadget", category: "Electronics", embedding: [...] },
];

const result = await searchClient.uploadDocuments(documents);
console.log(`Indexed ${result.results.length} documents`);

Full-Text Search

const results = await searchClient.search("widget", {
  select: ["id", "title", "description"],
  filter: "category eq 'Tools'",
  orderBy: ["title asc"],
  top: 10,
});

for await (const result of results.results) {
  console.log(`${result.document.title}: ${result.score}`);
}

Vector Search

const queryVector = await getEmbedding("useful tool"); // Your embedding function

const results = await searchClient.search("*", {
  vectorSearchOptions: {
    queries: [
      {
        kind: "vector",
        vector: queryVector,
        fields: ["embedding"],
        kNearestNeighborsCount: 10,
      },
    ],
  },
  select: ["id", "title", "description"],
});

for await (const result of results.results) {
  console.log(`${result.document.title}: ${result.score}`);
}

Hybrid Search (Text + Vector)

const queryVector = await getEmbedding("useful tool");

const results = await searchClient.search("tool", {
  vectorSearchOptions: {
    queries: [
      {
        kind: "vector",
        vector: queryVector,
        fields: ["embedding"],
        kNearestNeighborsCount: 50,
      },
    ],
  },
  select: ["id", "title", "description"],
  top: 10,
});

Semantic Search

// Index must have semantic configuration
const index: SearchIndex = {
  name: "products",
  fields: [...],
  semanticSearch: {
    configurations: [
      {
        name: "semantic-config",
        prioritizedFields: {
          titleField: { name: "title" },
          contentFields: [{ name: "description" }],
        },
      },
    ],
  },
};

// Search with semantic ranking
const results = await searchClient.search("best tool for the job", {
  queryType: "semantic",
  semanticSearchOptions: {
    configurationName: "semantic-config",
    captions: { captionType: "extractive" },
    answers: { answerType: "extractive", count: 3 },
  },
  select: ["id", "title", "description"],
});

for await (const result of results.results) {
  console.log(`${result.document.title}`);
  console.log(`  Caption: ${result.captions?.[0]?.text}`);
  console.log(`  Reranker Score: ${result.rerankerScore}`);
}

Filtering and Facets

// Filter syntax
const results = await searchClient.search("*", {
  filter: "category eq 'Electronics' and price lt 100",
  facets: ["category,count:10", "brand"],
});

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

Autocomplete and Suggestions

// Create suggester in index
const index: SearchIndex = {
  name: "products",
  fields: [...],
  suggesters: [
    { name: "sg", sourceFields: ["title", "description"] },
  ],
};

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

// Suggestions
const suggestions = await searchClient.suggest("wid", "sg", {
  select: ["title"],
  top: 5,
});

Batch Operations

// Batch upload, merge, delete
const batch = [
  { upload: { id: "1", title: "New Item" } },
  { merge: { id: "2", title: "Updated Title" } },
  { delete: { id: "3" } },
];

const result = await searchClient.indexDocuments({ actions: batch });

Key Types

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

Best Practices

  1. Use hybrid search - Combine vector + text for best results
  2. Enable semantic ranking - Improves relevance for natural language queries
  3. Batch document uploads - Use uploadDocuments with arrays, not single docs
  4. Use filters for security - Implement document-level security with filters
  5. Index incrementally - Use mergeOrUploadDocuments for updates
  6. Monitor query performance - Use includeTotalCount: true sparingly in production
Files (skills)
  • references
    • semantic-ranking.md 11.1 KB
      Loading…
    • vector-search.md 9.8 KB
      Loading…
  • SKILL.md 7.1 KB
    ---
    name: azure-search-documents-ts
    description: 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.
    license: MIT
    metadata:
      author: Microsoft
      version: "1.0.0"
      package: '@azure/search-documents'
    ---
    
    # Azure AI Search SDK for TypeScript
    
    Build search applications with vector, hybrid, and semantic search capabilities.
    
    ## Installation
    
    ```bash
    npm install @azure/search-documents @azure/identity
    ```
    
    ## Environment Variables
    
    ```bash
    AZURE_SEARCH_ENDPOINT=https://<service-name>.search.windows.net
    AZURE_SEARCH_INDEX_NAME=my-index
    AZURE_SEARCH_ADMIN_KEY=<admin-key>  # Optional if using Entra ID
    AZURE_TOKEN_CREDENTIALS=prod # Required only if DefaultAzureCredential is used in production
    ```
    
    ## Authentication
    
    ```typescript
    import { SearchClient, SearchIndexClient } from "@azure/search-documents";
    import { DefaultAzureCredential, ManagedIdentityCredential } from "@azure/identity";
    
    const endpoint = process.env.AZURE_SEARCH_ENDPOINT!;
    const indexName = process.env.AZURE_SEARCH_INDEX_NAME!;
    // Local dev: DefaultAzureCredential. Production: set AZURE_TOKEN_CREDENTIALS=prod or AZURE_TOKEN_CREDENTIALS=<specific_credential>
    const credential = new DefaultAzureCredential({requiredEnvVars: ["AZURE_TOKEN_CREDENTIALS"]});
    // Or use a specific credential directly in production:
    // See https://learn.microsoft.com/javascript/api/overview/azure/identity-readme?view=azure-node-latest#credential-classes
    // const credential = new ManagedIdentityCredential();
    
    // For searching
    const searchClient = new SearchClient(endpoint, indexName, credential);
    
    // For index management
    const indexClient = new SearchIndexClient(endpoint, credential);
    ```
    
    ## Core Workflow
    
    ### Create Index with Vector Field
    
    ```typescript
    import { SearchIndex, SearchField, VectorSearch } from "@azure/search-documents";
    
    const index: SearchIndex = {
      name: "products",
      fields: [
        { name: "id", type: "Edm.String", key: true },
        { name: "title", type: "Edm.String", searchable: true },
        { name: "description", type: "Edm.String", searchable: true },
        { name: "category", type: "Edm.String", filterable: true, facetable: 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.createOrUpdateIndex(index);
    ```
    
    ### Index Documents
    
    ```typescript
    const documents = [
      { id: "1", title: "Widget", description: "A useful widget", category: "Tools", embedding: [...] },
      { id: "2", title: "Gadget", description: "A cool gadget", category: "Electronics", embedding: [...] },
    ];
    
    const result = await searchClient.uploadDocuments(documents);
    console.log(`Indexed ${result.results.length} documents`);
    ```
    
    ### Full-Text Search
    
    ```typescript
    const results = await searchClient.search("widget", {
      select: ["id", "title", "description"],
      filter: "category eq 'Tools'",
      orderBy: ["title asc"],
      top: 10,
    });
    
    for await (const result of results.results) {
      console.log(`${result.document.title}: ${result.score}`);
    }
    ```
    
    ### Vector Search
    
    ```typescript
    const queryVector = await getEmbedding("useful tool"); // Your embedding function
    
    const results = await searchClient.search("*", {
      vectorSearchOptions: {
        queries: [
          {
            kind: "vector",
            vector: queryVector,
            fields: ["embedding"],
            kNearestNeighborsCount: 10,
          },
        ],
      },
      select: ["id", "title", "description"],
    });
    
    for await (const result of results.results) {
      console.log(`${result.document.title}: ${result.score}`);
    }
    ```
    
    ### Hybrid Search (Text + Vector)
    
    ```typescript
    const queryVector = await getEmbedding("useful tool");
    
    const results = await searchClient.search("tool", {
      vectorSearchOptions: {
        queries: [
          {
            kind: "vector",
            vector: queryVector,
            fields: ["embedding"],
            kNearestNeighborsCount: 50,
          },
        ],
      },
      select: ["id", "title", "description"],
      top: 10,
    });
    ```
    
    ### Semantic Search
    
    ```typescript
    // Index must have semantic configuration
    const index: SearchIndex = {
      name: "products",
      fields: [...],
      semanticSearch: {
        configurations: [
          {
            name: "semantic-config",
            prioritizedFields: {
              titleField: { name: "title" },
              contentFields: [{ name: "description" }],
            },
          },
        ],
      },
    };
    
    // Search with semantic ranking
    const results = await searchClient.search("best tool for the job", {
      queryType: "semantic",
      semanticSearchOptions: {
        configurationName: "semantic-config",
        captions: { captionType: "extractive" },
        answers: { answerType: "extractive", count: 3 },
      },
      select: ["id", "title", "description"],
    });
    
    for await (const result of results.results) {
      console.log(`${result.document.title}`);
      console.log(`  Caption: ${result.captions?.[0]?.text}`);
      console.log(`  Reranker Score: ${result.rerankerScore}`);
    }
    ```
    
    ## Filtering and Facets
    
    ```typescript
    // Filter syntax
    const results = await searchClient.search("*", {
      filter: "category eq 'Electronics' and price lt 100",
      facets: ["category,count:10", "brand"],
    });
    
    // Access facets
    for (const [facetName, facetResults] of Object.entries(results.facets || {})) {
      console.log(`${facetName}:`);
      for (const facet of facetResults) {
        console.log(`  ${facet.value}: ${facet.count}`);
      }
    }
    ```
    
    ## Autocomplete and Suggestions
    
    ```typescript
    // Create suggester in index
    const index: SearchIndex = {
      name: "products",
      fields: [...],
      suggesters: [
        { name: "sg", sourceFields: ["title", "description"] },
      ],
    };
    
    // Autocomplete
    const autocomplete = await searchClient.autocomplete("wid", "sg", {
      mode: "twoTerms",
      top: 5,
    });
    
    // Suggestions
    const suggestions = await searchClient.suggest("wid", "sg", {
      select: ["title"],
      top: 5,
    });
    ```
    
    ## Batch Operations
    
    ```typescript
    // Batch upload, merge, delete
    const batch = [
      { upload: { id: "1", title: "New Item" } },
      { merge: { id: "2", title: "Updated Title" } },
      { delete: { id: "3" } },
    ];
    
    const result = await searchClient.indexDocuments({ actions: batch });
    ```
    
    ## Key Types
    
    ```typescript
    import {
      SearchClient,
      SearchIndexClient,
      SearchIndexerClient,
      SearchIndex,
      SearchField,
      SearchOptions,
      VectorSearch,
      SemanticSearch,
      SearchIterator,
    } from "@azure/search-documents";
    ```
    
    ## Best Practices
    
    1. **Use hybrid search** - Combine vector + text for best results
    2. **Enable semantic ranking** - Improves relevance for natural language queries
    3. **Batch document uploads** - Use `uploadDocuments` with arrays, not single docs
    4. **Use filters for security** - Implement document-level security with filters
    5. **Index incrementally** - Use `mergeOrUploadDocuments` for updates
    6. **Monitor query performance** - Use `includeTotalCount: true` sparingly in production
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.