boss install github.com/gabrielcb08/query4d@v1.0.0

..\Query4D\src
..\Query4D\src\Shared
..\Query4D\src\Model
..\Query4D\src\View
..\Query4D\src\Controller

uses
  Query4D.Controller,   // TQuery4DController
  Query4D.View.MySQL;   // TMySQL8View (or PostgreSQL, Firebird, SQLite)

uses
  Query4D.Controller,
  Query4D.View.MySQL;

var
  R := TQuery4DController.New(TMySQL8View.New)
    .From('orders', 'o')
    .Select(['o.id', 'o.number', 'o.total'])
    .BeginWhere
      .Equal('o.status', 'approved')
      .GreaterThan('o.total', '100')
    .EndWhere
    .OrderBy('o.created_at', odDesc)
    .Limit(20)
    .Build;

if R.IsOk then
  MyConnection.Execute(R.Value.SQL, R.Value.Params);

SELECT o.id, o.number, o.total
FROM orders AS `o`
WHERE o.status = ?
  AND o.total > ?
ORDER BY o.created_at DESC
LIMIT 20

// QueryBuilder: TQuery4D (on the form, Dialect = dPostgreSQL)
var R := QueryBuilder.NewQuery
  .From('customers')
  .WhereEq('active', '1')
  .Limit(10)
  .Build;

.From('orders')              // FROM orders
.From('orders', 'o')         // FROM orders AS `o`  (delimiter per dialect)

.Select(['o.id', 'o.name', 'COUNT(*) AS total'])
.SelectAll                   // SELECT *  (default if nothing is specified)
.Select(['o.status']).Distinct   // SELECT DISTINCT o.status

// Field sub-builder with typed alias:
.BeginFields
  .Add('o.id')
  .AddAs('o.total', 'amount')
.EndFields

.WhereEq('status', 'active')             // WHERE status = ?   (param: 'active')
.WhereRaw('YEAR(created_at) = 2024')     // raw expression (NOT parameterized)

.BeginWhere
  .Equal('o.status', 'active')
  .GreaterThanOrEqualTo('o.stock', '1')
  .Contains('o.name', 'Silva')             // LIKE ?  → param '%Silva%'
  .IsIn('o.channel', ['web', 'app', 'api'])  // IN (?, ?, ?)
  .IsBetween('o.created_at', '2026-01-01', '2026-12-31')
  .IsNotNull('o.email')
.EndWhere

.BeginWhere
  .Equal('o.active', '1')          // AND
  .OrBegin
    .Equal('o.channel', 'web')     // OR
    .Equal('o.channel', 'app')     // OR
  .OrEnd
.EndWhere
// WHERE o.active = ? AND (o.channel = ? OR o.channel = ?)

.OrBegin
  .AndBegin
    .Equal('o.type', 'physical')
    .GreaterThan('o.weight', '0')
  .AndEnd
  .Equal('o.type', 'digital')
.OrEnd
// ((o.type = ? AND o.weight > ?) OR o.type = ?)

// Shortcuts:
.Join('customers', 'c', 'c.id = o.customer_id')      // INNER JOIN
.LeftJoin('addresses', 'a', 'a.id = o.address_id')   // LEFT JOIN

// Full sub-builder:
.BeginJoins
  .InnerJoin('customers', 'c', 'c.id = o.customer_id')
  .LeftJoin('addresses', 'a', 'a.id = o.address_id')
  .RightJoin('categories', 'cat', 'cat.id = o.category_id')
  .CrossJoin('settings', 'cfg')
.EndJoins

.OrderBy('o.name')                  // ASC implied
.OrderBy('o.created_at', odDesc)    // DESC

// With NULLS FIRST/LAST (native or dialect-emulated):
.BeginOrder
  .Asc('o.name', noFirst)
  .Desc('o.date', noLast)
.EndOrder

// GROUP BY + HAVING:
.BeginGroup
  .By('o.customer_id')
  .By('o.status')
  .Having('SUM(o.total) > 1000')
.EndGroup

.Limit(20)     // LIMIT 20  — raises EInvalidQuery if < 1
.Offset(40)    // OFFSET 40
.First         // LIMIT 1 (Firebird: SELECT FIRST 1 …)

.BeginWith
  .Add('summary',
    'SELECT customer_id, SUM(total) AS total FROM orders GROUP BY customer_id')
  .AddRecursive('hierarchy',
    'SELECT id, parent_id, 0 AS level FROM categories WHERE parent_id IS NULL',
    'SELECT c.id, c.parent_id, h.level + 1 FROM categories c ' +
    'INNER JOIN hierarchy h ON h.id = c.parent_id')
.EndWith

TQuery4DController.New(TMySQL8View.New)
  .InsertInto('orders')
  .BeginRow
    .Value('customer_id', '42')
    .Value('total', '199.90')
    .Value('status', 'pending')
  .Build;
// INSERT INTO orders (customer_id, total, status) VALUES (?, ?, ?)

.InsertInto('items')
  .BeginRow.Value('order_id', '1').Value('product', 'A')
  .BeginRow.Value('order_id', '1').Value('product', 'B')
  .Build;
// INSERT INTO items (order_id, product) VALUES (?, ?), (?, ?)

.Update('orders')
  .SetValue('status', 'approved')       // parameterized
  .SetRaw('approved_at', 'NOW()')       // raw expression (not parameterized)
  .WhereEq('id', '42')
  .Build;
// UPDATE orders SET status = ?, approved_at = NOW() WHERE id = ?

.DeleteFrom('sessions')
  .WhereEq('user_id', '10')
  .Build;
// DELETE FROM sessions WHERE user_id = ?

.InsertInto('orders')
  .BeginRow.Value('status', 'pending')
  .Returning(['id', 'created_at'])
  .Build;
// PostgreSQL: INSERT INTO orders (status) VALUES ($1) RETURNING id, created_at
// MySQL:      INSERT INTO orders (status) VALUES (?)      ← RETURNING omitted

var R := Q.Build;
if R.IsOk then
  ExecuteQuery(R.Value.SQL, R.Value.Params)
else
  ShowMessage(R.Error.Message);

// Or via chained callbacks:
R.OnSuccess(procedure(V: TQueryResult)
   begin ExecuteQuery(V.SQL, V.Params); end)
 .OnFailure(procedure(E: TResultError)
   begin LogError(E.Message, E.Code); end);

TQuery4DController.New(TPostgreSQLView.New). ... .Build;   // directly
QueryBuilder.Dialect := dSQLite;                            // via the component

flowchart LR
    App["Your code"] -->|fluent calls| Ctrl["Controller<br/>IQuery4DController + sub-controllers"]
    Ctrl -->|mutates| Model["Model<br/>TQueryModel + sub-models"]
    Ctrl -->|Build| View["View<br/>IDialectView (chosen dialect)"]
    View -->|reads| Model
    View -->|TResult&lt;TQueryResult&gt;| App
    Ctrl -. validates .-> Shared["Shared<br/>TGuard · TResult&lt;T&gt; · exceptions"]
    View -. uses .-> Shared

Query4D/
?????? src/
???  ?????? Shared/        TResult<T>, TGuard, exceptions, utilities
???  ?????? Model/         TQueryModel and sub-models (query state)
???  ?????? View/          IDialectView + the 4 dialect implementations
???  ?????? Controller/    TQuery4DController (fluent) + sub-controllers
?????? tests/
???  ?????? Unit/          database-free tests (Given_When_Then naming)
???  ?????? Fixtures/
?????? samples/          VCL demo app (Query4DDemo)
?????? docs/             full documentation
?????? packages/Delphi12/Query4D.dpk    installable package (TQuery4D component)
?????? Query4D.groupproj                group: lib + tests