Pervaxis.Genesis.Search.AWS 2.0.0

Pervaxis.Genesis.Search.AWS

AWS OpenSearch search provider for the Pervaxis Genesis platform — full-text search, document indexing, and query capabilities with native AWS integration.

Overview

Pervaxis.Genesis.Search.AWS implements the ISearch abstraction from Pervaxis.Core.Abstractions using OpenSearch.Client for AWS OpenSearch. It provides:

• Document indexing with automatic ID and type management
• Full-text search with query string syntax
• Bulk indexing for efficient batch operations
• Document deletion with soft-delete support
• Index prefix support for multi-tenancy
• Basic authentication for self-managed OpenSearch clusters
• Configurable timeouts and retries

Installation

<PackageReference Include="Pervaxis.Genesis.Search.AWS" Version="1.0.0" />

Configuration

appsettings.json

{
  "Search": {
    "Region": "us-east-1",
    "DomainEndpoint": "https://my-domain.us-east-1.es.amazonaws.com",
    "IndexPrefix": "prod-",
    "DefaultPageSize": 10,
    "RequestTimeoutSeconds": 30,
    "MaxRetries": 3,
    "EnableDebugMode": false
  }
}

Option properties

Basic Authentication (Self-Managed OpenSearch)

For self-managed OpenSearch clusters with basic authentication:

{
  "Search": {
    "Region": "us-east-1",
    "DomainEndpoint": "https://my-opensearch-cluster.example.com:9200",
    "Username": "admin",
    "Password": "strong-password"
  }
}

Registration

Using IConfiguration

using Pervaxis.Genesis.Search.AWS.Extensions;

var builder = WebApplication.CreateBuilder(args);

// Register OpenSearch
builder.Services.AddGenesisSearch(
    builder.Configuration.GetSection("Search"));

Using Action Delegate

using Pervaxis.Genesis.Search.AWS.Extensions;
using Pervaxis.Genesis.Search.AWS.Options;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddGenesisSearch(options =>
{
    options.Region = "us-east-1";
    options.DomainEndpoint = "https://my-domain.us-east-1.es.amazonaws.com";
    options.IndexPrefix = "prod-";
    options.DefaultPageSize = 20;
});

Usage

Indexing Documents

using Pervaxis.Core.Abstractions.Genesis.Modules;

public class ProductService
{
    private readonly ISearch _search;

    public ProductService(ISearch search)
    {
        _search = search;
    }

    public async Task IndexProductAsync(Product product)
    {
        var indexed = await _search.IndexAsync(
            index: "products",
            id: product.Id.ToString(),
            document: product);

        Console.WriteLine($"Product indexed: {indexed}");
    }
}

Searching Documents

public async Task<IEnumerable<Product>> SearchProductsAsync(string query)
{
    var results = await _search.SearchAsync<Product>(
        index: "products",
        query: query);

    return results;
}

Query String Syntax

OpenSearch supports rich query string syntax:

// Simple term search
var results = await _search.SearchAsync<Product>("products", "laptop");

// Field-specific search
var results = await _search.SearchAsync<Product>("products", "name:laptop");

// Boolean operators
var results = await _search.SearchAsync<Product>("products", "laptop AND available:true");

// Wildcard search
var results = await _search.SearchAsync<Product>("products", "lap*");

// Range queries
var results = await _search.SearchAsync<Product>("products", "price:[100 TO 500]");

Bulk Indexing

public async Task BulkIndexProductsAsync(List<Product> products)
{
    var documents = products.ToDictionary(
        p => p.Id.ToString(),
        p => p);

    var successCount = await _search.BulkIndexAsync(
        index: "products",
        documents: documents);

    Console.WriteLine($"{successCount}/{products.Count} products indexed");
}

Deleting Documents

public async Task DeleteProductAsync(string productId)
{
    var deleted = await _search.DeleteAsync(
        index: "products",
        id: productId);

    Console.WriteLine($"Product deleted: {deleted}");
}

Index Prefix & Multi-Tenancy

Use index prefixes to isolate data by tenant or environment:

// Configuration
options.IndexPrefix = "tenant-123-";

// Indexes to "tenant-123-products"
await _search.IndexAsync("products", "1", product);

// Searches "tenant-123-products"
await _search.SearchAsync<Product>("products", "laptop");

IAM Permissions

Your application needs these IAM permissions for AWS OpenSearch:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "es:ESHttpGet",
        "es:ESHttpHead",
        "es:ESHttpPost",
        "es:ESHttpPut",
        "es:ESHttpDelete"
      ],
      "Resource": "arn:aws:es:region:account-id:domain/domain-name/*"
    }
  ]
}

Error Handling

All methods throw GenesisException on failure:

using Pervaxis.Genesis.Base.Exceptions;

try
{
    await _search.IndexAsync("products", "1", product);
}
catch (GenesisException ex)
{
    _logger.LogError(ex, "Failed to index product: {Message}", ex.Message);
}

Best Practices

Index Naming

• Use lowercase index names
• Use hyphens for word separation (e.g., "product-catalog")
• Apply consistent prefixes for multi-tenancy

Performance

• Use bulk operations for batch indexing (>10 documents)
• Configure appropriate DefaultPageSize based on your use case
• Enable EnableDebugMode only for development
• Tune RequestTimeoutSeconds based on your query complexity

Security

• Never log credentials
• Use AWS IAM roles instead of basic authentication when possible
• Restrict IAM permissions to specific indices
• Enable VPC access for production OpenSearch domains

Troubleshooting

Connection Timeout

Increase RequestTimeoutSeconds:

{
  "Search": {
    "RequestTimeoutSeconds": 60
  }
}

Too Many Requests (429)

Increase MaxRetries or implement exponential backoff:

{
  "Search": {
    "MaxRetries": 5
  }
}

Debug Mode

Enable debug logging to see detailed request/response information:

{
  "Search": {
    "EnableDebugMode": true
  }
}

Limitations

• AWS managed OpenSearch only supports AWS Signature Version 4 authentication
• Self-managed clusters require basic authentication (Username/Password)
• Query string syntax is documented at OpenSearch Query String Syntax
• Maximum document size is 100MB by default (OpenSearch limit)

License

Copyright © 2026 Clarivex Technologies Private Limited. All rights reserved.