DataQL.AspNetCore 1.0.0-preview.4

DataQL

DataQL is a provider-independent JSON query DSL for .NET. Clients express query intent once — filters, projection, ordering, grouping, and cursor pagination — and DataQL validates, translates, and executes against the registered backend.

Use it when you want a single query contract across relational and document stores, without exposing SQL or provider-specific syntax to API consumers.

Client  →  JSON Query DSL  →  Validate / AST  →  Provider Translator  →  Native Query  →  Results

Packages

Providers and compatibility

Capabilities are advertised per provider and enforced at validation time. Unsupported operators or features return structured capability errors (for example Capability.OperatorNotSupported).

Feature matrix

* Cosmos grouped queries return the full aggregate set: limit is ignored and continuation is not supported.
† Cosmos includeCount runs a separate COUNT query (extra RU cost).
‡ On Cosmos, order is optional unless a continuation token is supplied. On SQLite and SQL Server, order is required on every query for deterministic paging.

Filter operators

Group metric operations

Provider notes

At runtime you can also inspect capabilities via meta endpoints (see How to use).

How to use

1. Install packages

dotnet add package DataQL
dotnet add package DataQL.AspNetCore
dotnet add package DataQL.Sqlite      # and/or SqlServer / Cosmos

2. Register sources

using DataQL;
using DataQL.AspNetCore;
using DataQL.Sqlite.DependencyInjection;
using Microsoft.Data.Sqlite;

builder.Services
    .AddDataQL(options =>
    {
        options.AddSqliteSource("employees", _ =>
            new SqliteConnection("Data Source=app.db"));

        // options.AddSqlServerSource("hr", _ => new SqlConnection(cs));
        // options.AddCosmosSource("docs", endpoint, key, databaseId);
    })
    .AddDataQLOpenApi();

3. Map endpoints (ASP.NET Core)

var app = builder.Build();
app.MapDataQL("/dataql");
app.Run();

This exposes:

4. Call the query API

Request — POST /dataql/query/employees/Employees

{
  "where": {
    "$and": [
      { "City": "Delhi" },
      { "Age": { "$gte": 18 } }
    ]
  },
  "order": [
    { "field": "Id", "direction": "asc" }
  ],
  "select": ["Id", "Name", "Age", "City"],
  "limit": 50,
  "includeCount": false
}

Response

{
  "results": [ /* rows */ ],
  "hasMore": true,
  "continuationToken": "...",
  "count": null
}

Pass continuationToken on the next request (same filter/order/select shape) to page forward. Offset/skip pagination is not supported.

5. Execute from code

var response = await dataQLService.ExecuteAsync<object>(
    sourceKey: "employees",
    table: "Employees",
    request: queryRequest,
    cancellationToken);

You can also harden queries before execution — for example force IsActive = true with QueryFilterBuilder — as shown in DataQL.ExampleApi.

Query shape (reference)

Full grammar and examples: specs/Generic-Query-DSL-Specification-v1.0.md.

Example API

The solution includes DataQL.ExampleApi, a runnable sample with SQLite seed data and optional SQL Server / Cosmos wiring:

dotnet run --project DataQL.ExampleApi

License

MIT — see LICENSE.

Versioning and release process: docs/release-process.md.