Evolution & Versioning

Template Versioning Strategy

Because template catalogue codes are embedded in workflow definitions, expression directives, and external API calls, changing or removing a template code is a breaking change. Use the following strategy to evolve templates safely while maintaining backward compatibility:

• Assign version suffixes to catalogue codes for non-trivial changes: PAYROLL_REPORT becomes PAYROLL_REPORT_v2. The original code remains active and served to existing callers.
• Use the name field in the template JSON for a human-readable label (e.g., "name": "Payroll Department Summary v2"). This label appears in administrative listings without affecting the code-based lookup.
• Track a version integer inside the JSON object to support audit history and rollback identification. Increment it on every update.
• Communicate a migration window to all callers before retiring an old version code. Set IsActive = 0 on the old code only after all callers have migrated to the new code.
• Keep old template codes active in staging and production simultaneously during the migration window. The database overhead of an additional row is negligible.

// Template JSON with version tracking
{
  "name": "Payroll Department Summary v2",
  "version": 2,
  "isTemplate": true,
  "sql": "SELECT d.ID, d.DeptName, d.CostCentre FROM dbo.Departments d WHERE d.TenantID = @TenantID",
  "collectionName": "departments",
  "children": [ ... ]
}

Adding New SQL Engines

The Multi-Query system is engine-agnostic. The sqlserver engine is the built-in implementation, but additional engines can be registered by implementing ISqlDeriveEngine and registering the implementation in the DI container.

public class PostgreSqlDeriveEngine : ISqlDeriveEngine
{
    public string EngineName => "postgresql";

    public Task<MultiQueryResult> ExecuteAsync(
        MultiQueryTemplate template,
        MultiQueryExecutionContext context)
    {
        // Implement PostgreSQL-specific query tree execution
    }
}

// In your module registration or Startup.cs
services.AddSingleton<ISqlDeriveEngine, SqlServerDeriveEngine>();
services.AddSingleton<ISqlDeriveEngine, PostgreSqlDeriveEngine>();

{{multi-query:postgresql.ORG_CHART_SUMMARY}}

GET /api/v1/expressions/multiquery/ORG_CHART_SUMMARY
    (engine resolved from template metadata or directive)

Engine Resolution

When a directive or endpoint is evaluated, MultiQueryExpressionDirectiveService resolves the target engine using a simple linear enumeration:

// Engine resolution — simplified illustration
var engine = _engines.FirstOrDefault(e =>
    string.Equals(e.EngineName, engineName, StringComparison.OrdinalIgnoreCase));

if (engine is null)
{
    _logger.LogWarning(
        "Multi-Query directive: no engine registered for '{EngineName}'. Returning empty string.",
        engineName);
    return string.Empty;
}

If no registered engine matches the name parsed from the directive, the service returns an empty string and writes a warning to the platform log. No exception propagates to the caller. This makes it safe to deploy a new engine incrementally — templates referencing the new engine name will silently return empty until the engine implementation is registered.

Schema Evolution

Backward Compatibility Rules

The following rules define the Multi-Query compatibility contract. Violating them constitutes a breaking change and requires a new template code (version suffix) to avoid disrupting existing callers.

• Never change the meaning of a catalogue code. A code is a stable identifier. Once callers depend on a code's output structure, changing the root query or child structure under the same code is a breaking change.
• Add new codes for breaking changes. Use a version suffix (_v2, _v3) and deprecate the old code with a documented migration window.
• Keep isTemplate: true only on root records. This flag marks the root of the query tree. Child nodes must not carry this flag — it causes incorrect template resolution.
• Do not rename collectionName without versioning the code. The collectionName value is the JSON key that callers use to access the collection in the output. Renaming it silently breaks all downstream code that references the old key.
• Adding new columns to a query is non-breaking — callers that do not reference the new column are unaffected.
• Removing or renaming a column from a query is breaking — version the code before making this change.

Future Directions

The following extensions are under consideration for future releases of the Multi-Query engine:

Changelog