FractalDataWorks.Commands.Data.Extensions 0.6.0-rc.1

FractalDataWorks.Commands.Data.Extensions

Fluent query builder and filter operator extensions for data commands.

Overview

This package provides fluent APIs for constructing data commands:

• QueryCommandBuilder: Chain methods to construct complex queries
• DataStores / Query: Entry points for fluent query construction
• Filter Operator Extensions: .WhereEqual(), .WhereContains(), etc.
• Hierarchical Groups: .BeginAndGroup(), .BeginOrGroup() for complex logic

Target Frameworks: .NET Standard 2.0, .NET 10.0

Quick Start

From Reference.Translators/Program.cs:175-181:

var hierarchicalQuery = DataStores.For("AzureRestApi")
    .Container<OrderDto>("Orders")
    .Where("TotalAmount", FilterOperators.GreaterThan, 1000.00m)
    .WhereNotEqual("Status", "Cancelled")  // Extension method!
    .OrderByDescending("OrderDate")
    .Paging(skip: 0, take: 25)
    .Build();

Entry Points

DataStores.For() - Hierarchical Navigation

From QueryCommandBuilder.cs:341-353:

// Query from SQL Server
var sqlCommand = DataStores.For("DefaultSqlServer")
    .Container<Customer>("Customers")
    .Where(nameof(Customer.IsActive), true)
    .Build();

// Query from REST API
var restCommand = DataStores.For("AzureRestApi")
    .Container<ResearchMetric>("ResearchDashboard/Metrics")
    .Where(nameof(ResearchMetric.MetricDate), new GreaterThanOperator(), DateTime.Now.AddMonths(-1))
    .Build();

Query.From<T>() - Direct Query Builder

From QueryCommandBuilderTests.cs:274-277:

var command = Query.From<TestEntity>("Users", "CustomConnection")
    .Where(nameof(TestEntity.Name), "John")
    .Build();

Filter Conditions

Basic Equality (Default Operator)

From QueryCommandBuilder.cs:68-71:

// Add an equality WHERE condition (operator = Equal)
public QueryCommandBuilder<T> Where(string propertyName, object? value)
{
    return Where(propertyName, new EqualOperator(), value);
}

Usage:

builder.Where("IsActive", true);          // IsActive = true
builder.Where("City", "Seattle");         // City = 'Seattle'

Specific Operators

From Reference.Translators/Program.cs:137-147:

var fluentQuery = new QueryCommandBuilder<CustomerDto>("dbo.Customers")
    .WithConnection("ProductionDb")
    .Where("IsActive", FilterOperators.Equal, true)
    .BeginOrGroup()
        .Where("Status", FilterOperators.Equal, "Active")
        .Where("Status", FilterOperators.Equal, "Pending")
    .EndGroup()
    .OrderBy("CustomerName")
    .OrderByDescending("CreatedDate")
    .Paging(skip: 0, take: 50)
    .Build();

Extension Method Shortcuts

From FilterOperatorExtensions.cs:15-80:

builder.WhereEqual("Status", "Active");
builder.WhereNotEqual("Status", "Deleted");
builder.WhereGreaterThan("Age", 18);
builder.WhereGreaterThanOrEqual("Score", 90);
builder.WhereLessThan("Price", 100);
builder.WhereLessThanOrEqual("Quantity", 10);
builder.WhereContains("Email", "@example");
builder.WhereStartsWith("Name", "John");
builder.WhereEndsWith("Email", ".com");
builder.WhereIn("Status", new[] { "Active", "Pending" });

Hierarchical Filter Groups

From QueryCommandBuilder.cs:98-106:

// Begin a new OR group: (condition1 OR condition2 OR ...)
// Produces: (Name = 'Acme' OR Name = 'Corp') AND IsActive = true
builder
    .BeginOrGroup()
        .Where("Name", "Acme")
        .Where("Name", "Corp")
    .EndGroup()
    .Where("IsActive", true);

Nested Groups

From QueryCommandBuilderTests.cs:127-135:

// ((Name = 'John' OR Name = 'Jane') AND IsActive = true)
var command = new QueryCommandBuilder<TestEntity>("Users")
    .BeginAndGroup()
        .BeginOrGroup()
            .Where(nameof(TestEntity.Name), "John")
            .Where(nameof(TestEntity.Name), "Jane")
        .EndGroup()
        .Where(nameof(TestEntity.IsActive), true)
    .EndGroup()
    .Build();

Ordering

From QueryCommandBuilder.cs:155-183:

// Add an ORDER BY clause in ascending order
builder.OrderBy("LastName");

// Add a descending ORDER BY clause
builder.OrderByDescending("CreatedDate");

// With explicit direction using SortDirections TypeCollection
builder.OrderBy("LastName", SortDirections.ByName("Ascending"));

Multiple fields (from QueryCommandBuilderTests.cs:209-213):

var command = new QueryCommandBuilder<TestEntity>("Users")
    .OrderBy(nameof(TestEntity.Name))
    .OrderByDescending(nameof(TestEntity.Id))
    .Build();

Paging

From QueryCommandBuilder.cs:192-200:

// Add SKIP and TAKE for pagination
builder.Paging(skip: 0, take: 50);   // First 50 records
builder.Paging(skip: 50, take: 50);  // Records 51-100

Connection Selection

From QueryCommandBuilder.cs:208-215:

// Change the connection name for this query
builder.WithConnection("BackupServer");

Or set during construction (from QueryCommandBuilderTests.cs:261-264):

var command = DataStores.For("CustomConnection")
    .Container<TestEntity>("Users")
    .Where(nameof(TestEntity.Name), "John")
    .Build();

Complete Example

From Reference.Pipeline/Program.cs:128-136:

// Query with complex filter - steps that failed and need retry
var retryableStepsQuery = DataStores.For("DefaultSqlServer")
    .Container<StepExecution>("dbo.StepExecutions")
    .BeginAndGroup()
        .WhereEqual("StatusId", PipelineStatuses.Failed.Id)
        .WhereLessThan("RetryCount", 3)
        .Where("StepTypeId", FilterOperators.NotEqual, StepTypes.Cleanup.Id)
    .EndGroup()
    .OrderBy("FailedAt")
    .Build();

API Reference

QueryCommandBuilder<T>

Filter Operator Extensions

Dependencies

• FractalDataWorks.Commands.Data: Core commands and operators
• FractalDataWorks.Commands.Data.Abstractions: Interfaces

Next Steps

• See QueryCommandBuilder.cs for full API
• See FilterOperatorExtensions.cs for all extension methods
• See Reference.Translators sample for complete usage examples
• See FractalDataWorks.Data for FilterOperators TypeCollection