Best Practices - Search Explorer & Portal Tools¶

Overview¶

This guide provides best practices for effectively using Azure AI Search portal tools, including Search Explorer, Import Data wizard, and management interfaces. Following these guidelines will help you maximize productivity and avoid common pitfalls.

Search Explorer Best Practices¶

1. Query Development Workflow¶

Start Simple, Build Complexity¶

// ✅ Good: Progressive query development
// Step 1: Basic search
{
  "search": "hotel"
}

// Step 2: Add filtering
{
  "search": "hotel",
  "filter": "Rating gt 4.0"
}

// Step 3: Add sorting and field selection
{
  "search": "hotel",
  "filter": "Rating gt 4.0",
  "orderby": "Rating desc",
  "select": "HotelName,Rating,Category"
}

Use Meaningful Test Queries¶

// ✅ Good: Test with realistic scenarios
{
  "search": "luxury hotel spa",
  "filter": "Category eq 'Resort' and Rating ge 4.5",
  "facets": ["Category", "Rating", "Address/City"]
}

// ❌ Avoid: Generic or meaningless tests
{
  "search": "test"
}

2. Query Parameter Optimization¶

Limit Result Sets During Testing¶

// ✅ Good: Use small result sets for testing
{
  "search": "*",
  "top": 10,
  "skip": 0
}

// ❌ Avoid: Large result sets during development
{
  "search": "*",
  "top": 1000
}

Select Only Needed Fields¶

// ✅ Good: Specific field selection
{
  "search": "hotel",
  "select": "HotelName,Rating,Address/City"
}

// ❌ Avoid: Returning all fields unnecessarily
{
  "search": "hotel"
  // No select parameter returns all fields
}

3. Query Syntax Best Practices¶

Use Proper Escaping¶

// ✅ Good: Properly escaped special characters
{
  "search": "O'Reilly hotel",
  "searchMode": "all"
}

// ✅ Good: Quoted phrases
{
  "search": "\"luxury resort\"",
  "queryType": "simple"
}

Leverage Query Types Appropriately¶

// ✅ Good: Simple syntax for basic queries
{
  "search": "hotel pool wifi",
  "queryType": "simple",
  "searchMode": "any"
}

// ✅ Good: Full Lucene for advanced queries
{
  "search": "hotel AND (pool OR spa) AND rating:[4 TO 5]",
  "queryType": "full"
}

4. Testing and Validation¶

Document Working Queries¶

// ✅ Good: Save successful query patterns
const workingQueries = {
  "luxury-hotels": {
    "search": "luxury",
    "filter": "Category eq 'Luxury' and Rating ge 4.5",
    "orderby": "Rating desc"
  },
  "budget-options": {
    "search": "*",
    "filter": "Rating ge 3.0 and ParkingIncluded eq true",
    "orderby": "Rating desc"
  }
};

Test Edge Cases¶

// ✅ Good: Test empty results
{
  "search": "nonexistentterm12345"
}

// ✅ Good: Test special characters
{
  "search": "café & restaurant"
}

// ✅ Good: Test numeric ranges
{
  "filter": "Rating ge 0 and Rating le 5"
}

5. Performance Considerations¶

Monitor Query Performance¶

Use browser developer tools to monitor response times
Test with realistic data volumes
Identify slow queries early in development
Document performance benchmarks

Optimize for Common Use Cases¶

// ✅ Good: Optimize frequent query patterns
{
  "search": "hotel",
  "filter": "Category eq 'Business' and Rating ge 4.0",
  "facets": ["Address/City", "Rating"],
  "top": 20
}

Import Data Wizard Best Practices¶

1. Data Source Preparation¶

Organize Source Data¶

✅ Good data organization:
/data
  /hotels
    - hotels.json (consistent schema)
    - metadata.json (data descriptions)
  /reviews
    - reviews.json (related data)

Validate Data Quality¶

Check for consistent field names and types
Ensure required fields are populated
Validate date formats (ISO 8601 recommended)
Remove or handle null values appropriately

2. Index Schema Design¶

Plan Field Attributes Carefully¶

// ✅ Good: Thoughtful field configuration
{
  "name": "HotelName",
  "type": "Edm.String",
  "searchable": true,    // Enable text search
  "filterable": true,    // Enable filtering
  "sortable": true,      // Enable sorting
  "facetable": false,    // Disable if not needed for facets
  "retrievable": true    // Include in results
}

Use Appropriate Data Types¶

// ✅ Good: Correct data types
{
  "name": "Rating",
  "type": "Edm.Double",     // For decimal ratings
  "filterable": true,
  "sortable": true
},
{
  "name": "LastRenovationDate",
  "type": "Edm.DateTimeOffset",  // For dates
  "filterable": true,
  "sortable": true
}

3. Skillset Configuration¶

Start with Built-in Skills¶

// ✅ Good: Use proven cognitive skills
{
  "@odata.type": "#Microsoft.Skills.Text.KeyPhraseExtractionSkill",
  "context": "/document",
  "inputs": [
    {
      "name": "text",
      "source": "/document/Description"
    }
  ],
  "outputs": [
    {
      "name": "keyPhrases",
      "targetName": "keyPhrases"
    }
  ]
}

Monitor Cognitive Services Costs¶

Start with small data sets for testing
Monitor usage and costs in Azure portal
Use free tier limits effectively
Consider cost implications of complex skillsets

4. Indexer Configuration¶

Set Appropriate Schedules¶

// ✅ Good: Reasonable indexer schedule
{
  "schedule": {
    "interval": "PT24H",  // Daily updates
    "startTime": "2024-01-01T02:00:00Z"  // Off-peak hours
  }
}

// ❌ Avoid: Too frequent updates
{
  "schedule": {
    "interval": "PT5M"  // Every 5 minutes - usually unnecessary
  }
}

Configure Change Detection¶

// ✅ Good: Efficient change detection
{
  "dataChangeDetectionPolicy": {
    "@odata.type": "#Microsoft.Azure.Search.HighWaterMarkChangeDetectionPolicy",
    "highWaterMarkColumnName": "LastModified"
  }
}

5. Testing and Validation¶

Test with Small Data Sets First¶

Use subset of data for initial testing
Validate field mappings and transformations
Check for indexing errors and warnings
Monitor performance with small batches

Validate Results¶

Check document count matches expectations
Verify field mappings are correct
Test search functionality on indexed data
Review any indexer warnings or errors

Portal Management Best Practices¶

1. Service Monitoring¶

Set Up Appropriate Alerts¶

// ✅ Good: Meaningful alert thresholds
{
  "alertName": "High Query Latency",
  "metric": "SearchLatency",
  "threshold": 1000,  // 1 second
  "condition": "GreaterThan"
}

Monitor Key Metrics¶

Search latency and throughput
Indexing performance and errors
Storage usage and quotas
API key usage patterns

2. Index Management¶

Use Consistent Naming Conventions¶

✅ Good naming patterns:
- hotels-prod
- hotels-staging  
- hotels-dev
- products-v2
- reviews-2024

❌ Avoid inconsistent names:
- myindex
- test123
- index_final_v2_new

Document Index Schemas¶

Maintain schema documentation
Track field attribute changes
Document business logic for field mappings
Keep version history of schema changes

3. Security and Access Control¶

Use Principle of Least Privilege¶

✅ Good: Role-based access
- Developers: Search Index Data Reader
- Data Engineers: Search Index Data Contributor  
- Administrators: Search Service Contributor

❌ Avoid: Overprivileged access
- Everyone: Search Service Contributor

Rotate API Keys Regularly¶

Establish key rotation schedule
Use Azure Key Vault for key management
Monitor key usage patterns
Have key rotation procedures documented

4. Development Workflow¶

Use Environment Separation¶

✅ Good: Clear environment separation
Development → Staging → Production

Each with:
- Separate search services
- Environment-specific configurations
- Appropriate access controls
- Different data sets

Version Control Configurations¶

# ✅ Good: Track configurations in version control
/search-config
  /indexes
    - hotels-index.json
    - products-index.json
  /indexers
    - hotels-indexer.json
  /skillsets
    - content-extraction-skillset.json

Performance Optimization¶

1. Query Optimization¶

Use Efficient Query Patterns¶

// ✅ Good: Specific, targeted queries
{
  "search": "luxury hotel",
  "searchFields": "HotelName,Description",
  "filter": "Category eq 'Luxury'",
  "select": "HotelName,Rating,Address/City"
}

// ❌ Avoid: Overly broad queries
{
  "search": "*",
  "top": 1000
}

Leverage Caching¶

Use browser caching for static results
Implement application-level caching
Cache facet results when appropriate
Consider CDN for frequently accessed data

2. Index Optimization¶

Design for Query Patterns¶

// ✅ Good: Fields optimized for usage patterns
{
  "name": "Category",
  "type": "Edm.String",
  "searchable": false,   // Not searched, only filtered
  "filterable": true,
  "facetable": true
}

Monitor Index Size and Performance¶

Track index size growth over time
Monitor query performance trends
Identify and optimize slow queries
Consider index partitioning for large datasets

3. Resource Management¶

Right-size Your Service Tier¶

Start with appropriate tier for workload
Monitor usage patterns and scale accordingly
Consider replica and partition needs
Plan for peak usage scenarios

Optimize Indexer Performance¶

Use appropriate batch sizes
Schedule indexers during off-peak hours
Monitor indexer execution times
Optimize data source queries

Error Handling and Troubleshooting¶

1. Common Portal Issues¶

Search Explorer Problems¶

// ✅ Good: Validate query syntax
{
  "search": "hotel",
  "filter": "Rating gt 4.0"  // Correct OData syntax
}

// ❌ Common mistake: Invalid syntax
{
  "search": "hotel",
  "filter": "Rating > 4.0"  // Invalid operator
}

Import Data Wizard Issues¶

Verify data source connectivity
Check field mapping configurations
Validate skillset configurations
Monitor indexer execution logs

2. Debugging Strategies¶

Use Systematic Approach¶

Test with minimal query first
Add complexity incrementally
Check each component individually
Validate data and schema alignment

Leverage Portal Diagnostics¶

Review indexer execution history
Check service health metrics
Monitor API usage patterns
Use activity logs for troubleshooting

3. Documentation and Logging¶

Maintain Troubleshooting Logs¶

✅ Good: Structured problem tracking
Date: 2024-01-15
Issue: Search Explorer timeout
Query: {complex query}
Resolution: Reduced result set size
Prevention: Added query optimization guidelines

Integration with Development Workflow¶

1. Portal to Code Transition¶

Export Portal Configurations¶

# ✅ Good: Save working configurations
# Export index definition from portal
# Save as JSON for version control
# Use in automated deployments

Document Portal Discoveries¶

Save successful query patterns
Document optimal configurations
Record performance benchmarks
Create reusable templates

2. Automation Strategies¶

Automate Repetitive Tasks¶

# ✅ Good: Automate index creation
$indexDefinition = Get-Content "hotels-index.json" | ConvertFrom-Json
New-AzSearchIndex -SearchService $searchService -Definition $indexDefinition

Use Infrastructure as Code¶

Define indexes in ARM templates
Use Azure CLI for service management
Implement CI/CD for search configurations
Version control all configurations

1. Team Practices¶

Document useful query patterns
Share troubleshooting solutions
Create team knowledge base
Conduct regular knowledge sharing sessions

Establish Standards¶

Consistent naming conventions
Standard field attribute patterns
Common query templates
Shared troubleshooting procedures

2. Documentation¶

Maintain Living Documentation¶

Update based on portal discoveries
Document configuration changes
Track performance optimizations
Share lessons learned

Module Documentation¶

Prerequisites - Required setup and knowledge
Main Documentation - Complete module overview
Practice & Implementation - Hands-on exercises
Troubleshooting - Common issues and solutions
Code Samples - Automation examples

External Resources¶

Azure AI Search Portal Documentation
Import Data Wizard Guide
Performance Optimization Guide

When You Need Help¶

Portal Issues: Check the Troubleshooting Guide
Performance Problems: Review Portal Management Examples
Complex Scenarios: Explore Search Explorer Examples

By following these best practices, you'll use Azure AI Search portal tools effectively and efficiently, leading to better search implementations and smoother development workflows.