# Semantic Search Patterns

Detailed patterns for semantic ranking, captions, and answers with Azure.Search.Documents.

## Index Configuration for Semantic Search

```csharp
using Azure.Search.Documents.Indexes.Models;

var index = new SearchIndex("articles")
{
    Fields =
    {
        new SimpleField("id", SearchFieldDataType.String) { IsKey = true },
        new SearchableField("title"),
        new SearchableField("content"),
        new SearchableField("summary"),
        new SimpleField("category", SearchFieldDataType.String) { IsFilterable = true }
    },
    SemanticSearch = new SemanticSearch
    {
        DefaultConfigurationName = "my-semantic-config",
        Configurations =
        {
            new SemanticConfiguration("my-semantic-config", new SemanticPrioritizedFields
            {
                TitleField = new SemanticField("title"),
                ContentFields =
                {
                    new SemanticField("content"),
                    new SemanticField("summary")
                },
                KeywordsFields =
                {
                    new SemanticField("category")
                }
            })
        }
    }
};

await indexClient.CreateOrUpdateIndexAsync(index);
```

## Basic Semantic Search

```csharp
using Azure.Search.Documents.Models;

var options = new SearchOptions
{
    QueryType = SearchQueryType.Semantic,
    SemanticSearch = new SemanticSearchOptions
    {
        SemanticConfigurationName = "my-semantic-config"
    },
    Select = { "id", "title", "content" },
    Size = 10
};

var results = await searchClient.SearchAsync<Article>(
    "What are the best practices for cloud security?", 
    options);

await foreach (var result in results.Value.GetResultsAsync())
{
    Console.WriteLine($"{result.Document.Title} (Score: {result.Score})");
}
```

## Semantic Search with Captions

Captions provide highlighted excerpts showing why a document matched:

```csharp
var options = new SearchOptions
{
    QueryType = SearchQueryType.Semantic,
    SemanticSearch = new SemanticSearchOptions
    {
        SemanticConfigurationName = "my-semantic-config",
        QueryCaption = new QueryCaption(QueryCaptionType.Extractive)
        {
            HighlightEnabled = true
        }
    }
};

var results = await searchClient.SearchAsync<Article>("cloud security best practices", options);

await foreach (var result in results.Value.GetResultsAsync())
{
    Console.WriteLine($"Title: {result.Document.Title}");
    
    if (result.SemanticSearch?.Captions != null)
    {
        foreach (var caption in result.SemanticSearch.Captions)
        {
            // Highlights contains <em> tags around key phrases
            Console.WriteLine($"Caption: {caption.Highlights ?? caption.Text}");
        }
    }
}
```

## Semantic Search with Answers

Answers extract direct responses from the content:

```csharp
var options = new SearchOptions
{
    QueryType = SearchQueryType.Semantic,
    SemanticSearch = new SemanticSearchOptions
    {
        SemanticConfigurationName = "my-semantic-config",
        QueryAnswer = new QueryAnswer(QueryAnswerType.Extractive)
        {
            Count = 3,  // Number of answers to return
            Threshold = 0.7  // Minimum confidence threshold
        },
        QueryCaption = new QueryCaption(QueryCaptionType.Extractive)
    }
};

var results = await searchClient.SearchAsync<Article>(
    "What is zero trust security?", 
    options);

// Check for semantic answers (appear before documents)
if (results.Value.SemanticSearch?.Answers != null)
{
    foreach (var answer in results.Value.SemanticSearch.Answers)
    {
        Console.WriteLine($"Answer: {answer.Highlights ?? answer.Text}");
        Console.WriteLine($"Score: {answer.Score}");
        Console.WriteLine($"Document Key: {answer.Key}");
    }
}

// Process documents with captions
await foreach (var result in results.Value.GetResultsAsync())
{
    Console.WriteLine($"\nDocument: {result.Document.Title}");
    Console.WriteLine($"Reranker Score: {result.SemanticSearch?.RerankerScore}");
}
```

## Semantic Hybrid Search (Vector + Keyword + Semantic)

Combines all three search modalities for best relevance:

```csharp
var vectorQuery = new VectorizedQuery(embedding)
{
    KNearestNeighborsCount = 50,
    Fields = { "contentVector" }
};

var options = new SearchOptions
{
    QueryType = SearchQueryType.Semantic,
    SemanticSearch = new SemanticSearchOptions
    {
        SemanticConfigurationName = "my-semantic-config",
        QueryCaption = new QueryCaption(QueryCaptionType.Extractive),
        QueryAnswer = new QueryAnswer(QueryAnswerType.Extractive)
    },
    VectorSearch = new VectorSearchOptions
    {
        Queries = { vectorQuery }
    },
    Select = { "id", "title", "content" },
    Size = 10
};

// Keyword search + vector search + semantic reranking
var results = await searchClient.SearchAsync<Article>(
    "best practices for securing cloud infrastructure", 
    options);
```

## Semantic Configuration Options

### SemanticPrioritizedFields

| Field | Purpose | Recommendation |
|-------|---------|----------------|
| `TitleField` | Document title | Short, descriptive field |
| `ContentFields` | Main content (ordered by priority) | Up to 10 fields, most important first |
| `KeywordsFields` | Keywords/tags | Categorical or tag fields |

### QueryCaption Options

```csharp
new QueryCaption(QueryCaptionType.Extractive)
{
    HighlightEnabled = true  // Wrap key phrases in <em> tags
}
```

### QueryAnswer Options

```csharp
new QueryAnswer(QueryAnswerType.Extractive)
{
    Count = 3,        // Max answers to return (1-10)
    Threshold = 0.7   // Minimum confidence (0.0-1.0)
}
```

## Semantic Ranking Scores

| Score | Description |
|-------|-------------|
| `result.Score` | BM25 keyword relevance score |
| `result.SemanticSearch.RerankerScore` | Semantic relevance (0-4 scale) |
| `answer.Score` | Answer confidence (0-1 scale) |

## Error Handling

```csharp
var results = await searchClient.SearchAsync<Article>(query, options);

// Check if semantic search was applied
if (results.Value.SemanticSearch?.ErrorReason != null)
{
    Console.WriteLine($"Semantic search warning: {results.Value.SemanticSearch.ErrorReason}");
    // Results still returned, but without semantic ranking
}
```

## Best Practices

1. **Configure semantic fields carefully** - Title and content fields significantly impact quality
2. **Use answers for Q&A scenarios** - Set appropriate threshold to filter low-confidence answers
3. **Combine with vector search** - Semantic hybrid provides best relevance
4. **Monitor reranker scores** - Scores below 1.0 indicate weak semantic match
5. **Enable captions** - Helps users understand why documents matched
6. **Set answer count appropriately** - More answers = more latency
7. **Use filters before semantic ranking** - Reduces documents to rerank

# Vector Search Patterns

Detailed patterns for vector and hybrid search with Azure.Search.Documents.

## Index Configuration for Vector Search

```csharp
using Azure.Search.Documents.Indexes.Models;

var index = new SearchIndex("products")
{
    Fields =
    {
        new SimpleField("id", SearchFieldDataType.String) { IsKey = true },
        new SearchableField("name"),
        new SearchableField("description"),
        new SearchField("descriptionVector", SearchFieldDataType.Collection(SearchFieldDataType.Single))
        {
            VectorSearchDimensions = 1536,  // Must match embedding model
            VectorSearchProfileName = "vector-profile"
        }
    },
    VectorSearch = new VectorSearch
    {
        Profiles =
        {
            new VectorSearchProfile("vector-profile", "hnsw-algo")
            {
                VectorizerName = "openai-vectorizer"  // Optional: for integrated vectorization
            }
        },
        Algorithms =
        {
            new HnswAlgorithmConfiguration("hnsw-algo")
            {
                Parameters = new HnswParameters
                {
                    M = 4,
                    EfConstruction = 400,
                    EfSearch = 500,
                    Metric = VectorSearchAlgorithmMetric.Cosine
                }
            }
        },
        Vectorizers =
        {
            new AzureOpenAIVectorizer("openai-vectorizer")
            {
                Parameters = new AzureOpenAIVectorizerParameters
                {
                    ResourceUri = new Uri("https://<resource>.openai.azure.com"),
                    DeploymentName = "text-embedding-ada-002",
                    ModelName = "text-embedding-ada-002"
                }
            }
        }
    }
};
```

## Pure Vector Search

```csharp
using Azure.Search.Documents.Models;

// Get embedding from your embedding model
float[] embedding = await GetEmbeddingAsync("luxury hotel with pool");

var vectorQuery = new VectorizedQuery(embedding)
{
    KNearestNeighborsCount = 10,
    Fields = { "descriptionVector" },
    Exhaustive = false  // Use HNSW index (faster)
};

var options = new SearchOptions
{
    VectorSearch = new VectorSearchOptions
    {
        Queries = { vectorQuery }
    },
    Select = { "id", "name", "description" }
};

// Pass null for search text in pure vector search
var results = await searchClient.SearchAsync<Product>(null, options);

await foreach (var result in results.Value.GetResultsAsync())
{
    Console.WriteLine($"{result.Document.Name} (Score: {result.Score})");
}
```

## Hybrid Search (Vector + Keyword)

```csharp
var vectorQuery = new VectorizedQuery(embedding)
{
    KNearestNeighborsCount = 10,
    Fields = { "descriptionVector" }
};

var options = new SearchOptions
{
    VectorSearch = new VectorSearchOptions
    {
        Queries = { vectorQuery }
    },
    Select = { "id", "name", "description" },
    Size = 10
};

// Pass search text for hybrid search
var results = await searchClient.SearchAsync<Product>("luxury pool", options);
```

## Multi-Vector Search

Search across multiple vector fields:

```csharp
var titleVector = new VectorizedQuery(titleEmbedding)
{
    KNearestNeighborsCount = 10,
    Fields = { "titleVector" }
};

var descriptionVector = new VectorizedQuery(descriptionEmbedding)
{
    KNearestNeighborsCount = 10,
    Fields = { "descriptionVector" }
};

var options = new SearchOptions
{
    VectorSearch = new VectorSearchOptions
    {
        Queries = { titleVector, descriptionVector }
    }
};
```

## Vector Search with Filters

```csharp
var vectorQuery = new VectorizedQuery(embedding)
{
    KNearestNeighborsCount = 10,
    Fields = { "descriptionVector" }
};

var options = new SearchOptions
{
    VectorSearch = new VectorSearchOptions
    {
        Queries = { vectorQuery }
    },
    Filter = "category eq 'Electronics' and price lt 500",
    Select = { "id", "name", "price", "category" }
};

var results = await searchClient.SearchAsync<Product>(null, options);
```

## Integrated Vectorization (Text-to-Vector)

When a vectorizer is configured, you can search with text directly:

```csharp
var vectorQuery = new VectorizableTextQuery("luxury hotel with ocean view")
{
    KNearestNeighborsCount = 10,
    Fields = { "descriptionVector" }
};

var options = new SearchOptions
{
    VectorSearch = new VectorSearchOptions
    {
        Queries = { vectorQuery }
    }
};

// No need to generate embeddings client-side
var results = await searchClient.SearchAsync<Hotel>(null, options);
```

## Algorithm Configuration

### HNSW (Hierarchical Navigable Small World)

Best for most scenarios - fast approximate nearest neighbor search:

```csharp
new HnswAlgorithmConfiguration("hnsw-algo")
{
    Parameters = new HnswParameters
    {
        M = 4,              // Connections per layer (4-10 typical)
        EfConstruction = 400,  // Index build quality (higher = better, slower)
        EfSearch = 500,     // Search quality (higher = better, slower)
        Metric = VectorSearchAlgorithmMetric.Cosine
    }
}
```

### Exhaustive KNN

Exact nearest neighbor search (slower but precise):

```csharp
new ExhaustiveKnnAlgorithmConfiguration("exhaustive-algo")
{
    Parameters = new ExhaustiveKnnParameters
    {
        Metric = VectorSearchAlgorithmMetric.Cosine
    }
}
```

## Vector Search Metrics

| Metric | Use Case |
|--------|----------|
| `Cosine` | Text embeddings (most common) |
| `Euclidean` | When magnitude matters |
| `DotProduct` | Normalized vectors, performance |

## Best Practices

1. **Match dimensions** to your embedding model (e.g., 1536 for text-embedding-ada-002)
2. **Use HNSW** for production workloads (faster than exhaustive)
3. **Tune EfSearch** based on latency vs. recall requirements
4. **Apply filters** to reduce search space before vector comparison
5. **Use integrated vectorization** to simplify client code
6. **Combine with semantic ranking** for best relevance