EFCore.ComplexIndexes

https://github.com/caffeinatedcoder/efcore.complexindexes
Admin
EFCore.ComplexIndexes is a NuGet package that extends EF Core's migration tooling to automatically...
Tokens:64,237
Snippets:702
Trust Score:7.5
License:MIT
Update:2 months ago
Show doc for...
Tokens:
Raw
### UseGin Usage Example

Source: https://github.com/caffeinatedcoder/efcore.complexindexes/blob/main/_autodocs/postgresql-indexes.md

Example of applying a GIN index with specific operator classes.

```csharp
builder.HasComplexIndex(b => b
    .UseGin()
    .HasOperators("jsonb_path_ops"));
```

--------------------------------

### HasTemporalForeignKey Example

Source: https://github.com/caffeinatedcoder/efcore.complexindexes/blob/main/_autodocs/postgresql-constraints.md

Example of ensuring a booking exists within a room's availability period.

```csharp
// Booking must exist during Room's availability period
builder.HasTemporalForeignKey<Room>(
    x => x.RoomId,
    x => x.Period,
    y => y.Id,
    y => y.AvailablePeriod,
    name: "fk_booking_room_period");
```

--------------------------------

### IncludeProperties Usage Example

Source: https://github.com/caffeinatedcoder/efcore.complexindexes/blob/main/_autodocs/postgresql-indexes.md

Example of adding non-key columns to an index.

```csharp
builder.HasComplexIndex(b => b
    .UseGin()
    .IncludeProperties("Status", "UpdatedAt"));
```

--------------------------------

### HasTemporalConstraint Multi-Key Example

Source: https://github.com/caffeinatedcoder/efcore.complexindexes/blob/main/_autodocs/postgresql-constraints.md

Example of applying a temporal constraint using multiple key columns.

```csharp
builder.HasTemporalConstraint(
    x => new { x.BuildingId, x.RoomId },
    x => x.Period,
    name: "uq_building_room_period");

// ALTER TABLE room ADD CONSTRAINT uq_building_room_period
//   UNIQUE (building_id, room_id, period WITHOUT OVERLAPS)
```

--------------------------------

### IncludeProperties Usage Example

Source: https://github.com/caffeinatedcoder/efcore.complexindexes/blob/main/_autodocs/sqlserver-indexes.md

Example of creating a covering index using IncludeProperties.

```csharp
builder.HasComplexIndex(
    x => x.EmailAddress.Value,
    b => b
        .IsUnique()
        .IncludeProperties("Status", "UpdatedAt"));

// CREATE UNIQUE NONCLUSTERED INDEX ... ON table (email_address_value)
// INCLUDE (status, updated_at)
```

--------------------------------

### IsCreatedOnline Usage Example

Source: https://github.com/caffeinatedcoder/efcore.complexindexes/blob/main/_autodocs/sqlserver-indexes.md

Example of configuring an index to be built online.

```csharp
builder.HasComplexIndex(
    x => x.EmailAddress.Value,
    b => b
        .IsUnique()
        .IsCreatedOnline());

// CREATE UNIQUE NONCLUSTERED INDEX ... ON table (email_address_value)
// WITH (ONLINE = ON)
```

--------------------------------

### HasTemporalConstraint Single Key Example

Source: https://github.com/caffeinatedcoder/efcore.complexindexes/blob/main/_autodocs/postgresql-constraints.md

Example of applying a temporal constraint to a single room ID and period.

```csharp
builder.HasTemporalConstraint(
    x => x.RoomId,
    x => x.Period,
    name: "uq_room_occupancy");

// Renders as:
// ALTER TABLE room ADD CONSTRAINT uq_room_occupancy 
//   UNIQUE (room_id, period WITHOUT OVERLAPS)
```

--------------------------------

### HasAnnotation Usage Example

Source: https://github.com/caffeinatedcoder/efcore.complexindexes/blob/main/_autodocs/complex-index-builder.md

Example of iterating through annotations to apply them to a builder.

```csharp
foreach (var (key, value) in indexBuilder.Annotations)
    builder.HasAnnotation(key, value);
```

--------------------------------

### Placeholder Syntax Examples

Source: https://github.com/caffeinatedcoder/efcore.complexindexes/blob/main/_autodocs/filter-placeholders.md

Demonstrates valid placeholder syntax and patterns that are ignored by the resolution engine.

```csharp
// Placeholders
"{SimpleProperty}"
"{Complex.Nested.Property}"
"{Parent.Child}"

// NOT placeholders
'"{literal}"'        // Inside single quotes
'{"json": "literal"}'  // JSON literal
'It''s a string'     // Escape sequence
```

--------------------------------

### HasName Usage Example

Source: https://github.com/caffeinatedcoder/efcore.complexindexes/blob/main/_autodocs/complex-index-builder.md

Examples of setting custom names for indexes, including handling multiple indexes on the same column.

```csharp
builder.HasComplexIndex(
    x => x.EmailAddress.Value,
    b => b.HasName("ux_person_email_active"));

// When multiple indexes target the same column with different filters:
builder.HasComplexIndex(x => x.Email, b => b
    .IsUnique()
    .HasFilter("{IsActive} = true")
    .HasName("ux_email_active"));

builder.HasComplexIndex(x => x.Email, b => b
    .HasName("ix_email_all"));  // Must be explicitly named
```

--------------------------------

### IsClustered Usage Example

Source: https://github.com/caffeinatedcoder/efcore.complexindexes/blob/main/_autodocs/sqlserver-indexes.md

Example of configuring a clustered composite index.

```csharp
builder.HasComplexCompositeIndex(
    x => new { x.CreatedAt, x.Status },
    b => b.IsClustered());

// ALTER TABLE table ADD CONSTRAINT ix_... CLUSTERED (created_at, status)
```

--------------------------------

### HasExclusionConstraint Multi-Key Example

Source: https://github.com/caffeinatedcoder/efcore.complexindexes/blob/main/_autodocs/postgresql-constraints.md

Example of using multiple keys to ensure no two events of the same type overlap in the same room.

```csharp
builder.HasExclusionConstraint(
    x => new { x.RoomId, x.EventType },
    x => x.Period,
    name: "ex_room_event_period");

// No two events of the same type can overlap in the same room
```

--------------------------------

### UseNpgsqlComplexIndexes Usage

Source: https://github.com/caffeinatedcoder/efcore.complexindexes/blob/main/_autodocs/runtime-wiring.md

Example of how to register the complex index services within the AddDbContext configuration.

```csharp
services.AddDbContext<MyContext>(options =>
    options
        .UseNpgsql(connectionString)
        .UseNpgsqlComplexIndexes());
```

--------------------------------

### Storage Parameters Usage Example

Source: https://github.com/caffeinatedcoder/efcore.complexindexes/blob/main/_autodocs/postgresql-indexes.md

Sets PostgreSQL index storage parameters, which render as a WITH clause.

```csharp
builder.HasComplexIndex(b => b
    .HasStorageParameter("fillfactor", 70)
    .HasStorageParameter("fastupdate", false));

// Renders as: WITH (fillfactor=70, fastupdate=false)
```

--------------------------------

### HasFillFactor Usage Example

Source: https://github.com/caffeinatedcoder/efcore.complexindexes/blob/main/_autodocs/sqlserver-indexes.md

Example of setting a fill factor of 80 for an index.

```csharp
builder.HasComplexIndex(
    x => x.EmailAddress.Value,
    b => b
        .IsUnique()
        .HasFillFactor(80));

// CREATE UNIQUE NONCLUSTERED INDEX ... ON table (email_address_value)
// WITH (FILLFACTOR = 80)
```

--------------------------------

### Install EFCore.ComplexIndexes Packages

Source: https://github.com/caffeinatedcoder/efcore.complexindexes/blob/main/_autodocs/README.md

Use the dotnet CLI to add the core package or provider-specific packages to your project.

```bash
# Core only
dotnet add package EFCore.ComplexIndexes

# With PostgreSQL support
dotnet add package EFCore.ComplexIndexes.PostgreSQL

# With SQL Server support
dotnet add package EFCore.ComplexIndexes.SqlServer
```

--------------------------------

### HasExclusionConstraint Builder Callback Example

Source: https://github.com/caffeinatedcoder/efcore.complexindexes/blob/main/_autodocs/postgresql-constraints.md

Example of using the builder callback to define elements, filters, names, and deferrability.

```csharp
builder.HasExclusionConstraint(b => b
    .Element(x => x.GrantId, "=")
    .Element(x => x.Period, "&&")
    .HasFilter("{IsRevoked} IS NULL")
    .HasName("ex_grant_period")
    .IsDeferred(true)
    .UseMethod("gist"));
```

--------------------------------

### PostgreSQL Null Ordering SQL

Source: https://github.com/caffeinatedcoder/efcore.complexindexes/blob/main/_autodocs/types-and-definitions.md

SQL syntax examples for null ordering in PostgreSQL.

```sql
column NULLS FIRST   -- DbNullSort.First
column NULLS LAST    -- DbNullSort.Last
```

--------------------------------

### Placeholder Resolution Example

Source: https://github.com/caffeinatedcoder/efcore.complexindexes/blob/main/_autodocs/filter-placeholders.md

Shows the transformation of a placeholder from declaration in OnModelCreating to the final SQL output during migration scaffolding.

```csharp
// DeclarationTime (OnModelCreating)
builder.HasComplexIndex(filter: "{DeletedAt} IS NULL");

// ResolutionTime (dotnet ef migrations add)
// Input:  "{DeletedAt} IS NULL"
// Output: "deleted_at" IS NULL  (PostgreSQL)
// Output: [deleted_at] IS NULL  (SQL Server)
```

--------------------------------

### HasFilter Usage Example

Source: https://github.com/caffeinatedcoder/efcore.complexindexes/blob/main/_autodocs/complex-index-builder.md

Example of applying a filtered index with a custom name.

```csharp
builder.HasComplexIndex(b => b
    .IsUnique()
    .HasFilter("{DeletedAt} IS NULL")
    .HasName("ux_email_active"));

// Rendered as: CREATE UNIQUE INDEX ux_email_active ON table (column) WHERE "deleted_at" IS NULL
```

--------------------------------

### IsUnique Usage Example

Source: https://github.com/caffeinatedcoder/efcore.complexindexes/blob/main/_autodocs/complex-index-builder.md

Example of chaining IsUnique with HasFilter.

```csharp
builder.HasComplexIndex(b => b
    .IsUnique()
    .HasFilter("deleted_at IS NULL"));

// Equivalent to: .IsUnique(true)
```

--------------------------------

### HasOperators Usage Example

Source: https://github.com/caffeinatedcoder/efcore.complexindexes/blob/main/_autodocs/postgresql-indexes.md

Example of applying operator classes to a composite index.

```csharp
builder.HasComplexCompositeIndex(
    x => new { x.Tags, x.Metadata },
    b => b.UseGin().HasOperators("", "jsonb_path_ops"));
// First column default, second uses jsonb_path_ops
```

--------------------------------

### HasExclusionConstraint Simple Example

Source: https://github.com/caffeinatedcoder/efcore.complexindexes/blob/main/_autodocs/postgresql-constraints.md

Example of creating an exclusion constraint to prevent overlapping grant periods for the same user.

```csharp
// Grant periods cannot overlap for the same user, if both are active
builder.HasExclusionConstraint(
    x => x.UserId,
    x => x.Period,
    filter: "{IsRevoked} IS NULL",
    name: "ex_grant_period_active");

// Renders as:
// ALTER TABLE grant ADD CONSTRAINT ex_grant_period_active
//   EXCLUDE USING gist (user_id WITH =, period WITH &&) WHERE (revoked_at IS NULL)
```

--------------------------------

### Generic HasComplexIndex Usage Example

Source: https://github.com/caffeinatedcoder/efcore.complexindexes/blob/main/_autodocs/complex-index-extensions.md

Example showing the generic overload used in a fluent configuration chain.

```csharp
builder.ComplexProperty(x => x.EmailAddress, c =>
    c.Property(x => x.Value)
     .HasComplexIndex<string>(isUnique: true)
     .IsRequired());
```

--------------------------------

### HasComplexIndex Builder Callback Example

Source: https://github.com/caffeinatedcoder/efcore.complexindexes/blob/main/_autodocs/complex-index-extensions.md

Example of using the builder callback to define index properties fluently.

```csharp
c.Property(x => x.Value)
 .HasComplexIndex(b => b
     .IsUnique()
     .HasFilter("{DeletedAt} IS NULL"));
```

--------------------------------

### UseDataCompression Usage Example

Source: https://github.com/caffeinatedcoder/efcore.complexindexes/blob/main/_autodocs/sqlserver-indexes.md

Demonstrates applying Page data compression to an index on an email address property.

```csharp
using EFCore.ComplexIndexes.SqlServer;

builder.HasComplexIndex(
    x => x.EmailAddress.Value,
    b => b
        .UseDataCompression(DataCompressionType.Page));

// CREATE UNIQUE NONCLUSTERED INDEX ... ON table (email_address_value)
// WITH (DATA_COMPRESSION = PAGE)
```

--------------------------------

### SortInTempDb Usage Example

Source: https://github.com/caffeinatedcoder/efcore.complexindexes/blob/main/_autodocs/sqlserver-indexes.md

Demonstrates chaining SortInTempDb with HasFillFactor in a complex index configuration.

```csharp
builder.HasComplexCompositeIndex(
    x => new { x.CreatedAt, x.Status },
    b => b
        .SortInTempDb()
        .HasFillFactor(90));
```

--------------------------------

### UseGin Provider Extension Method

Source: https://github.com/caffeinatedcoder/efcore.complexindexes/blob/main/_autodocs/complex-index-builder.md

An example of a provider-specific extension method using the IIndexAnnotationBuilder interface to set index methods.

```csharp
public static TBuilder UseGin<TBuilder>(this TBuilder builder) 
    where TBuilder : IIndexAnnotationBuilder
{
    builder.Annotations[NpgsqlAnnotations.IndexMethod] = "gin";
    return builder;
}
```

--------------------------------

### Temporal Constraints

Source: https://github.com/caffeinatedcoder/efcore.complexindexes/blob/main/_autodocs/filter-placeholders.md

Example of a temporal constraint API which does not utilize placeholders directly.

```csharp
builder.HasTemporalConstraint(
    x => x.RoomId,
    x => x.Period,
    name: "uq_room_period");
// (No placeholders in this API, but filter on the underlying exclusion constraint would use them)
```

--------------------------------

### UseComplexIndexes() Usage

Source: https://github.com/caffeinatedcoder/efcore.complexindexes/blob/main/_autodocs/runtime-wiring.md

Example of registering the complex index differ within the AddDbContext configuration block.

```csharp
services.AddDbContext<MyContext>(options =>
    options
        .UseSqlite(connectionString)
        .UseComplexIndexes());
```

--------------------------------

### HasComplexIndex Usage Example

Source: https://github.com/caffeinatedcoder/efcore.complexindexes/blob/main/_autodocs/complex-index-extensions.md

Demonstrates configuring a unique index with a filter, including the use of property placeholders.

```csharp
builder.ComplexProperty(x => x.EmailAddress, c =>
    c.Property(x => x.Value)
     .HasComplexIndex(isUnique: true, filter: "deleted_at IS NULL"));

// With placeholder
c.Property(x => x.Value)
 .HasComplexIndex(isUnique: true, filter: "{Parent.DeletedAt} IS NULL");
```

--------------------------------

### AddExclusionConstraintFilter Usage Example

Source: https://github.com/caffeinatedcoder/efcore.complexindexes/blob/main/_autodocs/postgresql-constraints.md

Example of adding a soft-delete filter to all exclusion constraints at the end of OnModelCreating.

```csharp
// At end of OnModelCreating, add soft-delete filter to all exclusion constraints
foreach (var entityType in modelBuilder.Model.GetEntityTypes())
{
    ((IMutableEntityType)entityType).AddExclusionConstraintFilter(
        "{RevokedAt} IS NULL");
}
```

--------------------------------

### Migration SQL for Temporal and Exclusion Constraints

Source: https://github.com/caffeinatedcoder/efcore.complexindexes/blob/main/_autodocs/postgresql-constraints.md

Example of how temporal and exclusion constraints are rendered as raw SQL ALTER TABLE operations during migrations.

```sql
-- Temporal
ALTER TABLE room ADD CONSTRAINT uq_room_period
  UNIQUE (room_id, period WITHOUT OVERLAPS);

-- Exclusion
ALTER TABLE grant ADD CONSTRAINT ex_grant_period
  EXCLUDE USING gist (user_id WITH =, period WITH &&) WHERE (revoked_at IS NULL);
```

--------------------------------

### HasExpressionIndex Typed LINQ Usage Examples

Source: https://github.com/caffeinatedcoder/efcore.complexindexes/blob/main/_autodocs/postgresql-indexes.md

Demonstrates creating expression indexes using LINQ expressions, including complex property resolution and filtering.

```csharp
builder.HasExpressionIndex(x => x.Email.ToLower(), isUnique: true);
// Translates to raw SQL: lower("Email") with column names resolved from model

builder.HasExpressionIndex(x => x.Address.City.ToUpper(), filter: "{IsActive} = true");
// Complex property: resolves to upper("Address_City")
```

--------------------------------

### Per-Column Collation Usage Example

Source: https://github.com/caffeinatedcoder/efcore.complexindexes/blob/main/_autodocs/postgresql-indexes.md

Applies specific collations to columns in a composite index.

```csharp
builder.HasComplexCompositeIndex(
    x => new { x.Name, x.Code },
    b => b.UseCollation("en_US.utf8", "C"));
// Name uses en_US.utf8, Code uses C (binary)
```

--------------------------------

### HasComplexCompositeIndex Builder Callback Example

Source: https://github.com/caffeinatedcoder/efcore.complexindexes/blob/main/_autodocs/complex-index-extensions.md

Configures a composite index using the builder callback pattern to set uniqueness, filters, and custom names.

```csharp
builder.HasComplexCompositeIndex(
    x => new { x.Name, x.CreatedAt },
    b => b.IsUnique().HasFilter("{IsActive} = true").HasName("ux_name_created"));
```

--------------------------------

### AddComplexIndexFilter Usage Example

Source: https://github.com/caffeinatedcoder/efcore.complexindexes/blob/main/_autodocs/model-extensions.md

Demonstrates applying a filter to all unique complex indexes across all entity types.

```csharp
// At the end of OnModelCreating
foreach (var entityType in modelBuilder.Model.GetEntityTypes())
{
    ((IMutableEntityType)entityType).AddComplexIndexFilter(
        "{RevokedAt} IS NULL",
        where: ix => ix.IsUnique);
}

// Adds "AND {RevokedAt} IS NULL" to every unique complex index on every entity
```

--------------------------------

### HasExpressionIndex Builder Callback Usage Example

Source: https://github.com/caffeinatedcoder/efcore.complexindexes/blob/main/_autodocs/postgresql-indexes.md

Demonstrates using the builder callback to configure index expressions, uniqueness, index type, filters, and names.

```csharp
builder.HasExpressionIndex(b => b
    .Expression("lower(email)")
    .Expression("status")
    .IsUnique()
    .UseGin()
    .HasFilter("deleted_at IS NULL")
    .HasName("ix_email_status"));
```

--------------------------------

### HasExpressionIndex Raw SQL Usage Example

Source: https://github.com/caffeinatedcoder/efcore.complexindexes/blob/main/_autodocs/postgresql-indexes.md

Demonstrates creating a unique index on a lowercased email column using raw SQL.

```csharp
builder.HasExpressionIndex("lower(email)", isUnique: true);
// CREATE UNIQUE INDEX ... ON table ((lower(email)))
```

--------------------------------

### Build and test the project

Source: https://github.com/caffeinatedcoder/efcore.complexindexes/blob/main/CONTRIBUTING.md

Commands to build the solution and execute the test suite.

```bash
dotnet build EFCore.ComplexIndexes.slnx
dotnet test test/EFCore.ComplexIndexes.Tests/EFCore.ComplexIndexes.Tests.csproj
```

--------------------------------

### Soft-Delete Convention Installation

Source: https://github.com/caffeinatedcoder/efcore.complexindexes/blob/main/_autodocs/INDEX.md

Applies a global filter to all entity types in the model to enforce soft-delete logic.

```csharp
// At end of OnModelCreating
foreach (var entityType in modelBuilder.Model.GetEntityTypes())
    ((IMutableEntityType)entityType)
        .AddComplexIndexFilter("{RevokedAt} IS NULL");
```

--------------------------------

### AddComplexIndex Usage Example

Source: https://github.com/caffeinatedcoder/efcore.complexindexes/blob/main/_autodocs/model-extensions.md

Demonstrates adding a unique index with a filter to a Person entity within OnModelCreating.

```csharp
// Inside OnModelCreating, after configurations
var definition = new CompositeIndexDefinition
{
    PropertyPaths = ["Email_Value"],
    IsUnique = true,
    Filter = "deleted_at IS NULL",
    IndexName = "ux_person_email_active"
};

((IMutableEntityType)modelBuilder.Model.FindEntityType(typeof(Person)))
    .AddComplexIndex(definition);
```

--------------------------------

### Build and Test Commands

Source: https://github.com/caffeinatedcoder/efcore.complexindexes/blob/main/CLAUDE.md

Standard CLI commands for building the solution, running the full test suite, executing specific test classes or methods, and packing NuGet packages.

```bash
# Build
dotnet build EFCore.ComplexIndexes.slnx

# Test
dotnet test test/EFCore.ComplexIndexes.Tests/EFCore.ComplexIndexes.Tests.csproj

# Run a single test class
dotnet test --filter "ClassName=MigrationModelDifferTests"

# Run a single test method
dotnet test --filter "FullyQualifiedName~MigrationModelDifferTests.SingleIndex_IsCreated"

# Pack NuGet packages
dotnet pack src/EFCore.ComplexIndexes/EFCore.ComplexIndexes.csproj
```

--------------------------------

### SQL Server Unsupported Option Error

Source: https://github.com/caffeinatedcoder/efcore.complexindexes/blob/main/_autodocs/sqlserver-indexes.md

Example of an error message generated when using provider-specific options that are not supported by SQL Server.

```text
EntityTypeBuilder: The complex index declares 'Npgsql:IndexMethod' = 'gin', 
which is not supported by SQL Server. Use IsClustered, IncludeProperties, or 
IsCreatedOnline instead.
```

--------------------------------

### GetComplexIndexes(IReadOnlyModel) Usage Example

Source: https://github.com/caffeinatedcoder/efcore.complexindexes/blob/main/_autodocs/model-extensions.md

Demonstrates using the model-level extension to enforce a convention that all unique indexes must have a filter.

```csharp
// Check a convention: "every unique index is filtered"
var unfiltered = context.Model.GetComplexIndexes()
    .Where(ix => ix.IsUnique && ix.Filter is null)
    .ToList();

if (unfiltered.Any())
    throw new InvalidOperationException(
        $"Found {unfiltered.Count} unfiltered unique indexes on complex properties. " +
        "All unique indexes must be filtered to active rows.");
```

--------------------------------

### Configure Complex Index with Provider Extensions

Source: https://github.com/caffeinatedcoder/efcore.complexindexes/blob/main/_autodocs/complex-index-builder.md

Demonstrates how to chain core index configuration methods with provider-specific extension methods like UseGin and IncludeProperties on a single builder instance.

```csharp
builder.HasComplexIndex(b => b
    .IsUnique()                    // Core
    .HasFilter("{DeletedAt} IS NULL")  // Core
    .UseGin()                      // PostgreSQL
    .IncludeProperties("Status")   // PostgreSQL
    .HasName("ux_email_gin"));     // Core
```

--------------------------------

### Configure PostgreSQL with Custom Service Provider

Source: https://github.com/caffeinatedcoder/efcore.complexindexes/blob/main/_autodocs/runtime-wiring.md

Demonstrates how to manually build a service provider and inject it into the DbContext when using PostgreSQL complex indexes.

```csharp
// Build services
var services = new ServiceCollection()
    .AddLogging(b => b.AddConsole())
    .AddEntityFrameworkNpgsql()
    .AddNpgsqlComplexIndexes()
    .AddScoped<IMyService, MyService>()
    .BuildServiceProvider();

// Configure DbContext to use it
services.AddDbContext<AppContext>(
    options =>
        options
            .UseNpgsql("Server=localhost;Database=app")
            .UseInternalServiceProvider(services.GetRequiredService<IServiceProvider>()),
    ServiceLifetime.Scoped);
```

--------------------------------

### PostgreSQL Complex Index and Constraint SQL

Source: https://github.com/caffeinatedcoder/efcore.complexindexes/blob/main/_autodocs/README.md

Examples for creating unique filtered indexes, expression indexes, exclusion constraints, and temporal constraints in PostgreSQL.

```sql
-- Single-column unique filtered index on complex property
CREATE UNIQUE INDEX ux_person_email_active
  ON person ("email_value")
  WHERE "deleted_at" IS NULL;

-- Expression index
CREATE UNIQUE INDEX ix_person_email_lower
  ON person (lower("email"))
  WHERE "is_active" = true;

-- Exclusion constraint
ALTER TABLE grant ADD CONSTRAINT ex_grant_period
  EXCLUDE USING gist (user_id WITH =, period WITH &&)
  WHERE (revoked_at IS NULL);

-- Temporal constraint
ALTER TABLE room ADD CONSTRAINT uq_room_period
  UNIQUE (room_id, period WITHOUT OVERLAPS);
```

--------------------------------

### Configuration Callback Integration

Source: https://github.com/caffeinatedcoder/efcore.complexindexes/blob/main/_autodocs/complex-index-builder.md

Demonstrates how a builder is instantiated, configured via a callback, and its annotations applied to the model.

```csharp
// From ComplexIndexExtensions.HasComplexIndex
var indexBuilder = new ComplexIndexBuilder();
configure(indexBuilder);  // Callback populates builder

builder.HasAnnotation(ComplexIndexAnnotations.IsIndexed, true);
foreach (var (key, value) in indexBuilder.Annotations)
    builder.HasAnnotation(key, value);
```

--------------------------------

### Configure full control exclusion constraints

Source: https://github.com/caffeinatedcoder/efcore.complexindexes/blob/main/docs/postgresql-constraints.md

Demonstrates advanced configuration including arbitrary operators, expressions, custom methods, and deferrability.

```csharp
builder.HasExclusionConstraint(ex => ex
    .WithEquality(x => x.Slot.Resource)      // complex-property members resolve to columns
    .WithOverlaps(x => x.Slot.Period)
    .WithExpression("lower(code)", "=")      // verbatim SQL element
    .UseMethod("gist")                        // the default
    .HasFilter("deleted_at IS NULL")
    .HasName("ex_booking_slot")
    .IsDeferrable(initiallyDeferred: true));
```

--------------------------------

### Verify Design-Time Wiring

Source: https://github.com/caffeinatedcoder/efcore.complexindexes/blob/main/_autodocs/runtime-wiring.md

Command to verify that migrations can be generated without errors after configuring complex indexes.

```bash
# Should generate indexes without error
dotnet ef migrations add TestMigration
```

--------------------------------

### SQLite Filtered Unique Index

Source: https://github.com/caffeinatedcoder/efcore.complexindexes/blob/main/_autodocs/README.md

Example of a simple filtered unique index for SQLite.

```sql
-- Simple filtered unique index
CREATE UNIQUE INDEX ux_person_email_active
  ON Person("Email_Value")
  WHERE "DeletedAt" IS NULL;
```

--------------------------------

### Configure Multiple Contexts

Source: https://github.com/caffeinatedcoder/efcore.complexindexes/blob/main/_autodocs/runtime-wiring.md

Shows how to register complex index support for multiple different database contexts in the same service collection.

```csharp
services
    .AddDbContext<PostgresContext>(options =>
        options
            .UseNpgsql(pgConnection)
            .UseNpgsqlComplexIndexes())
    .AddDbContext<SqliteContext>(options =>
        options
            .UseSqlite(sqliteConnection)
            .UseComplexIndexes());
```

--------------------------------

### Configure Complex Property Index with SQL Server Options

Source: https://github.com/caffeinatedcoder/efcore.complexindexes/blob/main/docs/sqlserver.md

Demonstrates how to define a complex property and apply SQL Server-specific index options like unique constraints, covering columns, online creation, and fill factor.

```csharp
builder.ComplexProperty(x => x.Email, c =>
    c.Property(x => x.Value).HasColumnName("email"));

builder.HasComplexIndex(x => x.Email.Value, ix => ix
    .IsUnique()
    .HasName("ux_person_email")
    .IncludeProperties("name")   // covering index
    .IsCreatedOnline()           // ONLINE = ON
    .HasFillFactor(80));
// CREATE UNIQUE INDEX [ux_person_email] ON [person] ([email])
//   INCLUDE ([name]) WITH (FILLFACTOR = 80, ONLINE = ON);
```

--------------------------------

### EF Core HasTemporalConstraint with composite keys

Source: https://github.com/caffeinatedcoder/efcore.complexindexes/blob/main/docs/postgresql-constraints.md

Configuring a temporal constraint using multiple key columns.

```csharp
builder.HasTemporalConstraint(
    keyColumns: b => new { b.Facility, b.RoomId },
    period:     b => b.ValidPeriod);
// UNIQUE ("Facility", "RoomId", "ValidPeriod" WITHOUT OVERLAPS)
```

--------------------------------

### PostgreSQL Temporal Constraints

Source: https://github.com/caffeinatedcoder/efcore.complexindexes/blob/main/_autodocs/api-overview.md

Configure temporal constraints for PostgreSQL using HasTemporalConstraint.

```csharp
builder.HasTemporalConstraint(
    x => x.RoomId,
    x => x.Period,  // NpgsqlRange<DateRange> or similar
    name: "uq_room_period");
```

--------------------------------

### Verify Runtime Wiring

Source: https://github.com/caffeinatedcoder/efcore.complexindexes/blob/main/_autodocs/runtime-wiring.md

Code to verify that the database schema is generated correctly and migrations can be applied at runtime.

```csharp
using var context = serviceProvider.GetRequiredService<AppContext>();

// Should include complex indexes
var schema = context.Database.GenerateCreateScript();
Console.WriteLine(schema);

// Should not warn about pending model changes
context.Database.Migrate();
```

--------------------------------

### Index whole JSON documents with GIN

Source: https://github.com/caffeinatedcoder/efcore.complexindexes/blob/main/docs/postgresql-indexes.md

Shows how to apply GIN indexes to JSON-mapped complex properties and collections. This approach uses the stock generator and does not require runtime wiring.

```csharp
builder.ComplexProperty(x => x.Payload, c => c.ToJson("payload"));
builder.ComplexCollection(x => x.Tags,  c => c.ToJson("tags"));

builder.HasComplexIndex(x => x.Payload, ix => ix.UseGin().HasOperators("jsonb_path_ops"));
// CREATE INDEX "IX_orders_payload" ON orders USING gin (payload jsonb_path_ops);

builder.HasComplexIndex(x => x.Tags, ix => ix.UseGin());
// CREATE INDEX "IX_orders_tags" ON orders USING gin (tags);
```

--------------------------------

### FindComplexIndex Usage Example

Source: https://github.com/caffeinatedcoder/efcore.complexindexes/blob/main/_autodocs/model-extensions.md

Finds a specific complex index by its explicit name and throws an exception if it is not found.

```csharp
var index = context.Model.FindComplexIndex("ux_person_email_active");
if (index is null)
    throw new InvalidOperationException("Expected index ux_person_email_active not found");
```

--------------------------------

### GetComplexIndexes(IReadOnlyEntityType) Usage Example

Source: https://github.com/caffeinatedcoder/efcore.complexindexes/blob/main/_autodocs/model-extensions.md

Retrieves all complex indexes for an entity, including those inherited from base types.

```csharp
var allIndexes = context.Model.FindEntityType(typeof(Employee))
    .GetComplexIndexes();
// Includes indexes declared on Employee itself and any base types (Person, etc.)
```

--------------------------------

### Configure index collations and storage parameters

Source: https://github.com/caffeinatedcoder/efcore.complexindexes/blob/main/docs/postgresql-indexes.md

Set index-level collations and storage parameters using HasCollation and HasStorageParameter. Storage parameters render as WITH clauses.

```csharp
builder.HasComplexCompositeIndex(x => new { x.Name, x.Email.Value }, idx => idx
    .UseCollation("C", "")
    .HasStorageParameter("fillfactor", 70)
    .HasStorageParameter("deduplicate_items", false));
// CREATE INDEX ... ON people ("Name" COLLATE "C", email) WITH (fillfactor=70, deduplicate_items=false);
```

--------------------------------

### Register NpgsqlComplexIndexes with custom Internal Service Provider

Source: https://github.com/caffeinatedcoder/efcore.complexindexes/blob/main/README.md

Use this registration method when your application manually builds its own IServiceProvider.

```csharp
var provider = new ServiceCollection()
.AddEntityFrameworkNpgsql()
.AddNpgsqlComplexIndexes() // ← Add this for expression indexes
.BuildServiceProvider();
```

--------------------------------

### EF Core HasTemporalConstraint with single key

Source: https://github.com/caffeinatedcoder/efcore.complexindexes/blob/main/docs/postgresql-constraints.md

Configuring a temporal constraint using a single key column and a period column.

```csharp
builder.HasTemporalConstraint(
    keyColumns: b => b.RoomId,
    period:     b => b.ValidPeriod);
// ALTER TABLE "Bookings" ADD CONSTRAINT "AK_Bookings__RoomId_ValidPeriod"
//   UNIQUE ("RoomId", "ValidPeriod" WITHOUT OVERLAPS);
```

--------------------------------

### Placeholder Resolution by Provider

Source: https://github.com/caffeinatedcoder/efcore.complexindexes/blob/main/_autodocs/filter-placeholders.md

Shows how placeholders are transformed into provider-specific quoted column names during migration.

```csharp
"{DeletedAt}"
// PostgreSQL → "deleted_at"
// SQL Server → [deleted_at]
```

--------------------------------

### Check EF Tooling in Project File

Source: https://github.com/caffeinatedcoder/efcore.complexindexes/blob/main/_autodocs/runtime-wiring.md

Ensure the EF tooling reference is present in your project file to resolve design-time service errors.

```xml
<DotNetCliToolReference Include="Microsoft.EntityFrameworkCore.Tools" />
```

--------------------------------

### SQL WITHOUT OVERLAPS constraint

Source: https://github.com/caffeinatedcoder/efcore.complexindexes/blob/main/docs/postgresql-constraints.md

Example of the raw SQL syntax for a temporal unique constraint in PostgreSQL 18.

```sql
ALTER TABLE bookings
  ADD CONSTRAINT ak_bookings_room_period
    UNIQUE (room_id, period WITHOUT OVERLAPS);
```

--------------------------------

### Register services for custom internal service provider

Source: https://github.com/caffeinatedcoder/efcore.complexindexes/blob/main/src/EFCore.ComplexIndexes.PostgreSQL/README.md

Use this approach when manually building an internal service provider to register the generator and differ directly.

```csharp
var provider = new ServiceCollection()
    .AddEntityFrameworkNpgsql()
    .AddNpgsqlComplexIndexes()
    .BuildServiceProvider();
```

--------------------------------

### GetDeclaredComplexIndexes Usage Example

Source: https://github.com/caffeinatedcoder/efcore.complexindexes/blob/main/_autodocs/model-extensions.md

Iterates through complex indexes declared directly on a specific entity type and prints their details.

```csharp
var declared = context.Model.FindEntityType(typeof(Person))
    .GetDeclaredComplexIndexes();

foreach (var index in declared)
{
    Console.WriteLine($"{index.Name}: {string.Join(", ", index.Parts.Select(p => p.PropertyPath))}");
    if (index.IsUnique) Console.WriteLine("  UNIQUE");
    if (index.Filter is not null) Console.WriteLine($"  WHERE {index.Filter}");
}
```

--------------------------------

### Null Distinctness Usage Example

Source: https://github.com/caffeinatedcoder/efcore.complexindexes/blob/main/_autodocs/postgresql-indexes.md

Configures a unique index where only one row is allowed to have a NULL value in the email column.

```csharp
// Only one row can have NULL email
builder.HasComplexIndex(b => b
    .IsUnique()
    .AreNullsDistinct(false));
```

--------------------------------

### Configure JSON Member Indexes

Source: https://github.com/caffeinatedcoder/efcore.complexindexes/blob/main/_autodocs/postgresql-indexes.md

Demonstrates how to define property-level or entity-level indexes on JSON properties using .ToJson() and HasComplexIndex.

```csharp
builder.ComplexProperty(x => x.Metadata, c => c.ToJson());

// This property-level declaration becomes (col ->> 'Key') at migration time
c.Property(x => x.Key).HasComplexIndex(isUnique: true);

// Or entity-level with explicit naming
builder.HasComplexIndex(x => x.Metadata.Key, indexName: "ix_metadata_key");
// Renders as: CREATE INDEX ix_metadata_key ON table (("Metadata" ->> 'Key'))
```

--------------------------------

### HasComplexIndex Filtered Index Example

Source: https://github.com/caffeinatedcoder/efcore.complexindexes/blob/main/_autodocs/complex-index-extensions.md

Demonstrates declaring two filtered indexes on the same column, requiring explicit index names.

```csharp
// Two filtered indexes on the same column
builder.HasComplexIndex(
    x => x.EmailAddress.Value,
    isUnique: true, 
    filter: "{DeletedAt} IS NULL", 
    indexName: "ux_email_active");

builder.HasComplexIndex(
    x => x.EmailAddress.Value,
    indexName: "ix_email_all");
```

--------------------------------

### UseMethod Method

Source: https://github.com/caffeinatedcoder/efcore.complexindexes/blob/main/_autodocs/postgresql-constraints.md

Specifies the index method for the constraint, defaulting to 'gist'.

```csharp
public ExclusionConstraintBuilder<TEntity> UseMethod(string method)
```

--------------------------------

### SQL Server Clustered Unique Index

Source: https://github.com/caffeinatedcoder/efcore.complexindexes/blob/main/_autodocs/README.md

Example of a clustered unique index with covering columns and fill factor settings for SQL Server.

```sql
-- Clustered unique index with covering columns
CREATE UNIQUE CLUSTERED INDEX ux_person_email_active
  ON Person ([Email_Value])
  INCLUDE ([Status], [UpdatedAt])
  WITH (FILLFACTOR = 85)
  WHERE [DeletedAt] IS NULL;
```

--------------------------------

### PostgreSQL Expression Index Declaration

Source: https://github.com/caffeinatedcoder/efcore.complexindexes/blob/main/_autodocs/api-overview.md

Demonstrates creating expression indexes using either raw SQL or typed LINQ expressions.

```csharp
// Raw SQL expression
builder.HasExpressionIndex("lower(email)", isUnique: true);

// Typed LINQ expression (resolved at migration time)
builder.HasExpressionIndex(x => x.Email.ToLower(), isUnique: true);
```

--------------------------------

### Configure Basic Indexes in OnModelCreating

Source: https://github.com/caffeinatedcoder/efcore.complexindexes/blob/main/_autodocs/README.md

Define property-level single-column indexes, entity-level composite indexes, and indexes with custom sort directions within the OnModelCreating method.

```csharp
// In OnModelCreating:

// Property-level single-column index
builder.ComplexProperty(x => x.EmailAddress, c =>
    c.Property(x => x.Value)
     .HasComplexIndex(isUnique: true, filter: "{DeletedAt} IS NULL"));

// Entity-level composite index
builder.HasComplexCompositeIndex(
    x => new { x.Name, x.EmailAddress.Value },
    isUnique: true);

// With sort direction
builder.HasComplexCompositeIndex(
    x => new { 
        x.Name, 
        CreatedAtDesc = DbOrder.Desc(x.CreatedAt)
    });
```

--------------------------------

### UseGin Method Definition

Source: https://github.com/caffeinatedcoder/efcore.complexindexes/blob/main/_autodocs/postgresql-indexes.md

Defines the UseGin extension method for IIndexAnnotationBuilder.

```csharp
public static TBuilder UseGin<TBuilder>(this TBuilder builder) 
    where TBuilder : IIndexAnnotationBuilder
```

--------------------------------

### NpgsqlAnnotations class

Source: https://github.com/caffeinatedcoder/efcore.complexindexes/blob/main/_autodocs/types-and-definitions.md

Defines the PostgreSQL-specific annotation key constants for index configuration.

```csharp
public static class NpgsqlAnnotations
{
    public const string IndexMethod = "Npgsql:IndexMethod";
    public const string IndexOperators = "Npgsql:IndexOperators";
    public const string IndexInclude = "Npgsql:IndexInclude";
    public const string CreatedConcurrently = "Npgsql:CreatedConcurrently";
    public const string NullsDistinct = "Npgsql:NullsDistinct";
    public const string IndexCollation = "Npgsql:IndexCollation";
    public const string StorageParameterPrefix = "Npgsql:StorageParameter:";
}
```

--------------------------------

### Defining Typed Filters for Complex Indexes

Source: https://github.com/caffeinatedcoder/efcore.complexindexes/blob/main/docs/postgresql-indexes.md

Examples of using HasComplexIndex, HasComplexCompositeIndex, HasExpressionIndex, and ComplexProperty with typed filters. Note that HasFilter<TEntity> requires an explicit entity type.

```csharp
builder.HasComplexIndex(x => x.Email, x => x.RevokedAt == null, isUnique: true);
// CREATE UNIQUE INDEX ... WHERE "revoked_at" IS NULL

builder.HasComplexCompositeIndex(x => new { x.GranteeId, x.Kind },
    x => x.RevokedAt != null && x.Kind == "federated");
// WHERE ("revoked_at" IS NOT NULL AND "kind" = 'federated')

builder.HasExpressionIndex(x => x.Email.ToLower(), x => !x.IsDeleted);

builder.ComplexProperty(x => x.Address, c => c.Property(a => a.City)
    .HasComplexIndex(ix => ix.HasFilter<Person>(p => p.DeletedAt == null)));
```

--------------------------------

### EF Core HasTemporalConstraint with explicit name

Source: https://github.com/caffeinatedcoder/efcore.complexindexes/blob/main/docs/postgresql-constraints.md

Configuring a temporal constraint while providing a custom constraint name.

```csharp
builder.HasTemporalConstraint(
    keyColumns: b => b.RoomId,
    period:     b => b.ValidPeriod,
    name:       "uk_room_no_overlap");
```

--------------------------------

### AddComplexIndexFilter(IMutableEntityType, string, Func<ComplexIndexDeclaration, bool>?)

Source: https://github.com/caffeinatedcoder/efcore.complexindexes/blob/main/_autodocs/model-extensions.md

Adds or conjoins a SQL predicate to the filter of selected indexes, with idempotence. Used to install soft-delete or other application-wide filtering rules.

```APIDOC
## AddComplexIndexFilter(IMutableEntityType, string, Func<ComplexIndexDeclaration, bool>?)

### Description
Adds or conjoins a SQL predicate to the filter of selected indexes, with idempotence. Used to install soft-delete or other application-wide filtering rules.

### Parameters
- **entityType** (IMutableEntityType) - The entity type to which the filter is applied.
- **predicate** (string) - SQL WHERE clause to add, with {Property.Path} placeholder support.
- **where** (Func<ComplexIndexDeclaration, bool>?) - Optional selector; null matches all indexes on this type.

### Returns
- int: Count of amended declarations
```

--------------------------------

### AddSqlServerComplexIndexes Method Signature

Source: https://github.com/caffeinatedcoder/efcore.complexindexes/blob/main/_autodocs/runtime-wiring.md

Defines the extension method for registering the SQL Server differ on a custom service collection.

```csharp
public static IServiceCollection AddSqlServerComplexIndexes(
    this IServiceCollection services
)
```

--------------------------------

### Configure Complex Composite Index

Source: https://github.com/caffeinatedcoder/efcore.complexindexes/blob/main/_autodocs/sqlserver-indexes.md

Demonstrates how to define a complex composite index using the HasComplexCompositeIndex builder, including clustering, included properties, and performance tuning options.

```csharp
builder.HasComplexCompositeIndex(
    x => new { x.CreatedAt, x.Status, x.UserId },
    b => b
        .IsClustered()
        .IncludeProperties("Email", "IsActive")
        .IsCreatedOnline()
        .HasFillFactor(85)
        .SortInTempDb()
        .UseDataCompression(DataCompressionType.Row)
        .IsUnique()
        .HasFilter("{IsDeleted} = 0")
        .HasName("ix_user_created_status_user"));
```

--------------------------------

### Define coexisting partial exclusion constraints

Source: https://github.com/caffeinatedcoder/efcore.complexindexes/blob/main/docs/postgresql-constraints.md

Shows how to define multiple partial constraints on the same columns by using different filters and unique names.

```csharp
b.HasExclusionConstraint(x => x.GranteeId, x => x.Period,
                         filter: "revoked_at IS NULL",     name: "ex_grant_active");
b.HasExclusionConstraint(x => x.GranteeId, x => x.Period,
                         filter: "revoked_at IS NOT NULL", name: "ex_grant_revoked");
```

--------------------------------

### Create a multi-part expression index with builder callback

Source: https://github.com/caffeinatedcoder/efcore.complexindexes/blob/main/docs/postgresql-indexes.md

Uses a builder callback to define multiple index parts, uniqueness, filters, and a custom name.

```csharp
builder.HasExpressionIndex(idx => idx
    .Expression("country")            // a plain column, written as raw SQL
    .Expression("lower(email)")       // a SQL expression
    .IsUnique()
    .HasFilter("deleted_at IS NULL")
    .HasName("ix_person_country_email_ci"));
// CREATE UNIQUE INDEX "ix_person_country_email_ci"
//   ON person ((country), (lower(email)))
//   WHERE deleted_at IS NULL;
```

--------------------------------

### SQL Server Index Options

Source: https://github.com/caffeinatedcoder/efcore.complexindexes/blob/main/_autodocs/api-overview.md

Configure clustered indexes, included properties, and fill factor for SQL Server complex properties.

```csharp
builder.ComplexProperty(x => x.Email, c =>
    c.Property(x => x.Value)
     .HasComplexIndex(b => b
         .IsClustered()
         .IncludeProperties("Email_Status")
         .HasFillFactor(90)));
```

--------------------------------

### Create a GIN expression index

Source: https://github.com/caffeinatedcoder/efcore.complexindexes/blob/main/docs/postgresql-indexes.md

Configures a GIN index for full-text search or JSONB operations.

```csharp
builder.HasExpressionIndex(idx => idx
    .Expression("to_tsvector('english', body)")
    .UseGin());
// CREATE INDEX ... ON articles USING gin ((to_tsvector('english', body)));
```

--------------------------------

### UseNpgsqlComplexIndexes Method Signatures

Source: https://github.com/caffeinatedcoder/efcore.complexindexes/blob/main/_autodocs/runtime-wiring.md

The method signatures for UseNpgsqlComplexIndexes, available for both generic and non-generic DbContextOptionsBuilder.

```csharp
public static DbContextOptionsBuilder UseNpgsqlComplexIndexes(
    this DbContextOptionsBuilder optionsBuilder
)

public static DbContextOptionsBuilder<TContext> UseNpgsqlComplexIndexes<TContext>(
    this DbContextOptionsBuilder<TContext> optionsBuilder
) where TContext : DbContext
```

--------------------------------

### Configure Sort Direction and Null Ordering

Source: https://github.com/caffeinatedcoder/efcore.complexindexes/blob/main/_autodocs/api-overview.md

Use DbOrder.Desc for provider-agnostic descending order. Null ordering is specific to PostgreSQL and requires the UseNpgsqlComplexIndexes() configuration.

```csharp
// Per-column descending (provider-agnostic via DbOrder.Desc)
builder.HasComplexCompositeIndex(
    x => new { x.Name, Desc = DbOrder.Desc(x.CreatedAt) });

// Null ordering (PostgreSQL only, requires UseNpgsqlComplexIndexes())
builder.HasExpressionIndex(x => x.Email.ToLower(), b => b
    .Part(DbOrder.NullsFirst(x => x.Status)));
```

--------------------------------

### Configure Expression Indexes

Source: https://github.com/caffeinatedcoder/efcore.complexindexes/blob/main/src/EFCore.ComplexIndexes.PostgreSQL/README.md

Defines expression indexes using raw SQL or lambda expressions.

```csharp
builder.HasExpressionIndex("lower(email)", isUnique: true, filter: "deleted_at IS NULL");

builder.HasExpressionIndex(idx => idx
    .Expression("country")
    .Expression("lower(email)").Descending()
    .UseGin()
    .HasName("ix_person_country_email_ci"));
```

```csharp
builder.HasExpressionIndex(x => x.Email.Value.ToLower(), isUnique: true);
// CREATE UNIQUE INDEX ... ON people ((lower("email")));
```

--------------------------------

### HasTemporalConstraint Method Signature

Source: https://github.com/caffeinatedcoder/efcore.complexindexes/blob/main/_autodocs/postgresql-constraints.md

The method signature for defining a temporal unique constraint in PostgreSQL.

```csharp
public static EntityTypeBuilder<TEntity> HasTemporalConstraint<TKey>(
    this EntityTypeBuilder<TEntity>    builder,
    Expression<Func<TEntity, TKey>>    keyColumns,
    Expression<Func<TEntity, object?>> period,
    string?                            name = null
) where TEntity : class
```

--------------------------------

### Configure PostgreSQL Specific Indexes and Constraints

Source: https://github.com/caffeinatedcoder/efcore.complexindexes/blob/main/_autodocs/README.md

Utilize PostgreSQL-specific features such as expression indexes, GIN indexes, temporal constraints, and exclusion constraints.

```csharp
// Expression index
builder.HasExpressionIndex(x => x.Email.ToLower(), isUnique: true);

// GIN index on complex property
builder.HasComplexIndex(b => b
    .UseGin()
    .IncludeProperties("Status"));

// Temporal constraint (PostgreSQL 18+)
builder.HasTemporalConstraint(
    x => x.RoomId,
    x => x.Period);

// Exclusion constraint (filtered overlap protection)
builder.HasExclusionConstraint(
    x => x.GrantId,
    x => x.Period,
    filter: "{IsRevoked} IS NULL");
```

--------------------------------

### Builder Callback Index Declaration

Source: https://github.com/caffeinatedcoder/efcore.complexindexes/blob/main/_autodocs/README.md

Provides full control over index configuration, including provider-specific options like GIN indexes for PostgreSQL.

```csharp
builder.HasComplexIndex(b => b
    .IsUnique()
    .HasFilter("{DeletedAt} IS NULL")
    .UseGin());  // PostgreSQL
// Full control; provider options available as extensions
```

--------------------------------

### Verify PostgreSQL Expression Rendering

Source: https://github.com/caffeinatedcoder/efcore.complexindexes/blob/main/_autodocs/runtime-wiring.md

Verifies that expression indexes are correctly rendered in PostgreSQL migrations. Failure to use UseNpgsqlComplexIndexes will result in an error.

```csharp
// Without UseNpgsqlComplexIndexes(), this would fail with:
// "Error: unknown option "__requires_UseNpgsqlComplexIndexes__" in message ..."
builder.HasExpressionIndex(x => x.Email.ToLower(), isUnique: true);
var migration = scaffold.Migrations.First();
Assert.Contains("lower(", migration.UpOperations);
```

--------------------------------

### Composite Index Declaration

Source: https://github.com/caffeinatedcoder/efcore.complexindexes/blob/main/_autodocs/api-overview.md

Illustrates creating composite indexes, including options for filters and per-column sort directions.

```csharp
builder.HasComplexCompositeIndex(
    x => new { x.Name, x.EmailAddress.Value },
    isUnique: true,
    filter: "{DeletedAt} IS NULL");

// With per-column sort direction
builder.HasComplexCompositeIndex(
    x => new { x.Name, Desc = DbOrder.Desc(x.CreatedAt) },
    isUnique: true);
```

--------------------------------

### Runtime Service Registration

Source: https://github.com/caffeinatedcoder/efcore.complexindexes/blob/main/_autodocs/api-overview.md

Explicitly register complex index services for different database providers or custom service providers.

```csharp
// Core package (any provider without a satellite)
services.AddDbContext<Context>(options =>
    options.UseSqlite(connection).UseComplexIndexes());

// PostgreSQL (expression indexes, NULLS ordering)
services.AddDbContext<Context>(options =>
    options.UseNpgsql(connection).UseNpgsqlComplexIndexes());

// SQL Server
services.AddDbContext<Context>(options =>
    options.UseSqlServer(connection).UseSqlServerComplexIndexes());

// Custom internal service provider
var services = new ServiceCollection()
    .AddEntityFrameworkNpgsql()
    .AddNpgsqlComplexIndexes()  // or .AddComplexIndexes(), .AddSqlServerComplexIndexes()
    .BuildServiceProvider();
```

--------------------------------

### HasName Method Signature

Source: https://github.com/caffeinatedcoder/efcore.complexindexes/blob/main/_autodocs/complex-index-builder.md

Method signature for setting a custom index name.

```csharp
public ComplexIndexBuilder HasName(string name)
```

--------------------------------

### Multi-Level Nesting in Complex Index

Source: https://github.com/caffeinatedcoder/efcore.complexindexes/blob/main/_autodocs/filter-placeholders.md

Demonstrates resolving placeholders through nested properties like Person.Address.Country.

```csharp
builder.HasComplexIndex(
    x => x.Person.Address.City,
    filter: "{Person.Address.Country} = 'US'");
// Resolves through Person → Address → Country
```

--------------------------------

### Placeholders in Exclusion Constraints

Source: https://github.com/caffeinatedcoder/efcore.complexindexes/blob/main/_autodocs/filter-placeholders.md

Demonstrates using multiple placeholders within an exclusion constraint filter.

```csharp
builder.HasExclusionConstraint(
    x => new { x.GrantId },
    x => x.Period,
    filter: "{IsRevoked} = false AND {DepartmentId} = {RequestDepartmentId}");
// All placeholders resolved in the context of the entity
```

--------------------------------

### Create a covering expression index

Source: https://github.com/caffeinatedcoder/efcore.complexindexes/blob/main/docs/postgresql-indexes.md

Uses IncludeProperties to add non-key columns to the index for covering index performance.

```csharp
builder.HasExpressionIndex(idx => idx
    .Expression("lower(email)")
    .IsUnique()
    .IncludeProperties("display_name"));
```

--------------------------------

### UseSqlServerComplexIndexes Method Signature

Source: https://github.com/caffeinatedcoder/efcore.complexindexes/blob/main/_autodocs/runtime-wiring.md

Defines the extension methods for registering the SQL Server complex-index differ.

```csharp
public static DbContextOptionsBuilder UseSqlServerComplexIndexes(
    this DbContextOptionsBuilder optionsBuilder
)

public static DbContextOptionsBuilder<TContext> UseSqlServerComplexIndexes<TContext>(
    this DbContextOptionsBuilder<TContext> optionsBuilder
) where TContext : DbContext
```

--------------------------------

### Full Path Entity Root Filter

Source: https://github.com/caffeinatedcoder/efcore.complexindexes/blob/main/_autodocs/filter-placeholders.md

Demonstrates using the full path from the entity root for complex type members.

```csharp
builder.HasComplexIndex(
    x => x.Address.City,
    filter: "{Address.State} IS NOT NULL");
// Both City and State are in Address complex type
```

--------------------------------

### Complex Index with JSON Columns (PostgreSQL)

Source: https://github.com/caffeinatedcoder/efcore.complexindexes/blob/main/_autodocs/filter-placeholders.md

Illustrates using placeholders with JSON properties in PostgreSQL.

```csharp
builder.ComplexProperty(x => x.Attributes, c =>
{
    c.ToJson();
    c.Property(x => x.Color);
});

builder.HasComplexIndex(
    x => x.Attributes.Color,
    filter: "{Attributes.Color} = 'red'");
// Resolves to: ("Attributes" ->> 'Color')::text = 'red'
```

--------------------------------

### Migration Declaration and Generated SQL

Source: https://github.com/caffeinatedcoder/efcore.complexindexes/blob/main/_autodocs/sqlserver-indexes.md

Shows the C# declaration for a complex index and the corresponding SQL generated during the migration process.

```csharp
// C# Declaration
builder.HasComplexCompositeIndex(
    x => new { x.Status, x.CreatedAt },
    b => b
        .IsUnique()
        .IsClustered()
        .IncludeProperties("Email")
        .HasFillFactor(85)
        .HasFilter("[DeletedAt] IS NULL")
        .HasName("ix_status_created_unique"));
```

```sql
CREATE UNIQUE CLUSTERED INDEX ix_status_created_unique
  ON dbo.Table ("Status", "CreatedAt")
  INCLUDE ("Email")
  WITH (FILLFACTOR = 85)
  WHERE ([DeletedAt] IS NULL);
```

--------------------------------

### IncludeProperties Method Definition

Source: https://github.com/caffeinatedcoder/efcore.complexindexes/blob/main/_autodocs/sqlserver-indexes.md

Method signature for adding non-key columns to an index.

```csharp
public static TBuilder IncludeProperties<TBuilder>(this TBuilder builder, params string[] properties) 
    where TBuilder : IIndexAnnotationBuilder
```

--------------------------------

### UseNpgsqlComplexIndexes()

Source: https://github.com/caffeinatedcoder/efcore.complexindexes/blob/main/_autodocs/runtime-wiring.md

Registers the PostgreSQL complex-index differ and custom SQL generator at runtime for EF Core DbContextOptionsBuilder.

```APIDOC
## UseNpgsqlComplexIndexes()

### Description
Registers the PostgreSQL complex-index differ and custom SQL generator at runtime. This method is required for all PostgreSQL contexts using this package to enable complex-property indexes, expression indexes, and custom null ordering.

### Signature
- public static DbContextOptionsBuilder UseNpgsqlComplexIndexes(this DbContextOptionsBuilder optionsBuilder)
- public static DbContextOptionsBuilder<TContext> UseNpgsqlComplexIndexes<TContext>(this DbContextOptionsBuilder<TContext> optionsBuilder) where TContext : DbContext

### Parameters
- None

### Returns
- DbContextOptionsBuilder / DbContextOptionsBuilder<TContext> for chaining

### Usage Example
```csharp
services.AddDbContext<MyContext>(options =>
    options
        .UseNpgsql(connectionString)
        .UseNpgsqlComplexIndexes());
```
```

--------------------------------

### DataCompressionType SQL Rendering

Source: https://github.com/caffeinatedcoder/efcore.complexindexes/blob/main/_autodocs/types-and-definitions.md

Shows how the DataCompressionType values are rendered in SQL Server syntax.

```sql
WITH (DATA_COMPRESSION = NONE)  -- None
WITH (DATA_COMPRESSION = ROW)   -- Row
WITH (DATA_COMPRESSION = PAGE)  -- Page
```

--------------------------------

### AddNpgsqlComplexIndexes Usage

Source: https://github.com/caffeinatedcoder/efcore.complexindexes/blob/main/_autodocs/runtime-wiring.md

Registers the PostgreSQL differ when using a custom internal service provider.

```csharp
var provider = new ServiceCollection()
    .AddEntityFrameworkNpgsql()
    .AddNpgsqlComplexIndexes()
    .BuildServiceProvider();

services.AddDbContext<MyContext>(
    optionsBuilder => optionsBuilder
        .UseNpgsql(connection)
        .UseInternalServiceProvider(provider));
```

--------------------------------

### HasExpressionIndex (Raw SQL)

Source: https://github.com/caffeinatedcoder/efcore.complexindexes/blob/main/_autodocs/postgresql-indexes.md

Creates an index on a raw SQL expression. Requires UseNpgsqlComplexIndexes() to be configured.

```APIDOC
## HasExpressionIndex<TEntity>(string expression, bool isUnique, string? filter, string? indexName)

### Description
Creates an index on a raw SQL expression.

### Parameters
- **expression** (string) - Required - SQL expression, e.g., "lower(email)" or "(created_at, status)"
- **isUnique** (bool) - Optional - Uniqueness flag
- **filter** (string?) - Optional - WHERE predicate
- **indexName** (string?) - Optional - Custom name

### Returns
- **EntityTypeBuilder<TEntity>** - Builder for chaining

### Example
```csharp
builder.HasExpressionIndex("lower(email)", isUnique: true);
```
```

--------------------------------

### Part Method

Source: https://github.com/caffeinatedcoder/efcore.complexindexes/blob/main/_autodocs/postgresql-indexes.md

An alias for the Expression(string) method.

```csharp
public ExpressionIndexBuilder Part(string expression)
```

--------------------------------

### AddSqlServerComplexIndexes

Source: https://github.com/caffeinatedcoder/efcore.complexindexes/blob/main/_autodocs/runtime-wiring.md

Registers the SQL Server differ on a custom IServiceCollection.

```APIDOC
## AddSqlServerComplexIndexes

### Description
Registers the SQL Server differ on a custom service collection for use with custom service providers.

### Signature
public static IServiceCollection AddSqlServerComplexIndexes(this IServiceCollection services)

### Returns
IServiceCollection for chaining.
```

--------------------------------

### AddComplexIndexes Method Signature

Source: https://github.com/caffeinatedcoder/efcore.complexindexes/blob/main/_autodocs/runtime-wiring.md

Defines the extension method for registering the core differ on a custom service collection.

```csharp
public static IServiceCollection AddComplexIndexes(
    this IServiceCollection services
)
```

--------------------------------

### Property-Level Single-Column Index Declaration

Source: https://github.com/caffeinatedcoder/efcore.complexindexes/blob/main/_autodocs/api-overview.md

Demonstrates how to declare a single-column index on a complex property using either the Fluent method or a builder callback.

```csharp
// Fluent method on ComplexTypePropertyBuilder
builder.ComplexProperty(x => x.EmailAddress, c =>
    c.Property(x => x.Value)
     .HasComplexIndex(isUnique: true, filter: "deleted_at IS NULL"));

// With builder callback
c.Property(x => x.Value).HasComplexIndex(b => b.IsUnique(true).HasFilter("{DeletedAt} IS NULL"));
```

--------------------------------

### PostgreSQL GIN Index

Source: https://github.com/caffeinatedcoder/efcore.complexindexes/blob/main/_autodocs/INDEX.md

Configures a GIN index with specific operators and included properties.

```csharp
builder.HasComplexIndex(b => b
    .UseGin()
    .HasOperators("jsonb_path_ops")
    .IncludeProperties("Status"));
```

--------------------------------

### IsUnique Method Signature

Source: https://github.com/caffeinatedcoder/efcore.complexindexes/blob/main/_autodocs/complex-index-builder.md

Method signature for marking an index as unique.

```csharp
public ComplexIndexBuilder IsUnique(bool unique = true)
```
Tokens:
Raw