fastify-auto-sqlapi 0.0.5 → 0.1.2

package/AGENTS_FRONTEND.md

@@ -2,6 +2,8 @@
 
 How to call the auto-generated CRUD endpoints.
 
+> ⚠️ **Migrating from a previous version?** The join API was redesigned (no backward compat). See **[BREAKING_CHANGES.md](./BREAKING_CHANGES.md)** for the full migration guide — request/response key renames, new `joinLeft` family, dotted notation rules, secondaries key renames. Common to backend and frontend.
+
 ## Generated Endpoints
 
 The plugin defines routes with these base paths: `/search/`, `/rest/`, `/bulk/`. The prefix from `register()` is prepended by Fastify. For a table `customer` with `prefix: '/auto'`:
@@ -32,7 +34,7 @@ Without prefix, routes are at root: `/search/customer`, `/rest/customer/:id`, et
 &computeMin=id&computeMax=id&computeSum=total&computeAvg=total
 ```
 
-- `orderBy` — SQL ORDER BY clause (default: `defaultOrder` from table config)
+- `orderBy` — SQL ORDER BY clause (default: `defaultOrder` from table config). Supports dotted notations for joins, see below.
 - `page` + `itemsPerPage` — pagination (when either is present, response includes `pagination` object; `page` defaults to 1, `itemsPerPage` defaults to 500)
 - `computeMin`, `computeMax`, `computeSum`, `computeAvg` — aggregate a column, returned in `pagination.computed`
 
@@ -44,14 +46,14 @@ Without prefix, routes are at root: `/search/customer`, `/rest/customer/:id`, et
   "conditions": [
     { "field": "createdAt", "method": "isGreater", "params": ["2024-01-01"] }
   ],
-  "joinFilters": {
-    "customer_label_link": { "labelId": 1 }
+  "joinMustExist": {
+    "labels": { "filters": { "labelId": 1 } }
   },
-  "joins": {
-    "customer_order": { "filters": { "status": "pending" } }
+  "joinMultiple": {
+    "orders": { "filters": { "status": "pending" } }
   },
-  "joinGroups": {
-    "customer_order": {
+  "joinGroup": {
+    "orders": {
       "aggregations": {
         "by": "status",
         "sum": ["total"],
@@ -61,10 +63,15 @@ Without prefix, routes are at root: `/search/customer`, `/rest/customer/:id`, et
       },
       "filters": { "status": "active" }
     }
+  },
+  "joinLeft": {
+    "creator": { "selection": "id,name,email" }
   }
 }
 ```
 
+The keys inside `joinMustExist`, `joinMultiple`, `joinGroup`, `joinLeft` are **aliases** declared by the backend in `buildRelation`. By default an alias equals the joined table's name; backends may override it (e.g. `'orders'` instead of `'customer_order'`) or declare multiple aliases for the same table (e.g. `'creator'` and `'updater'` both pointing to `user`). Check the Swagger description of each `/search/{table}` endpoint to see the available aliases.
+
 ### Filters
 
 Pass any schema field as a key in `filters`. The plugin auto-applies `WHERE col = value` for each. Extra filters (defined via `extraFiltersValidation` in the table config) are also accepted but handled by custom logic.
@@ -103,23 +110,23 @@ Pass any schema field as a key in `filters`. The plugin auto-applies `WHERE col
 Also available: `isNotGreater`, `isNotGreaterOrEqual`, `isNotLess`, `isNotLessOrEqual`.
 
 - **Multiple conditions on the same field** — it's an array, so `total > 100 AND total < 500` is natural
-- **Combinable** with `filters` (equality), `joinFilters` (EXISTS), pagination, etc.
+- **Combinable** with `filters` (equality), `joinMustExist` (EXISTS), pagination, etc.
 - **Field validation** — field names are validated against the table schema (400 if unknown)
 - **Method validation** — only whitelisted methods are allowed (`raw`, `append` etc. are blocked)
 
 #### Conditions on joinGroup aggregations (HAVING-style)
 
-You can filter main rows based on the value of a joinGroup aggregation using the same dot notation as `orderBy`: `<joinTable>.<fn>.<field>`.
+You can filter main rows based on the value of a `joinGroup` aggregation using 3-parti dot notation: `<alias>.<fn>.<field>`.
 
 Example: "users with at least 4 sessions":
 
 ```json
 {
   "conditions": [
-    { "field": "session.count.id", "method": "isGreaterOrEqual", "params": [4] }
+    { "field": "sessions.count.id", "method": "isGreaterOrEqual", "params": [4] }
   ],
-  "joinGroups": {
-    "session": { "aggregations": { "count": ["id"] } }
+  "joinGroup": {
+    "sessions": { "aggregations": { "count": ["id"] } }
   }
 }
 ```
@@ -135,21 +142,21 @@ WHERE COALESCE((
 ```
 
 **Rules:**
-- Same declaration requirement as orderBy: the joinGroup must be declared in `joinGroups.<table>.aggregations.<fn>` with the referenced field.
-- The joinGroup's own `filters` are applied inside the correlated subquery (consistent with the breakdown). Example: filter customers whose SUM of *completed* orders > 1000 by declaring `joinGroups.order.filters: { status: 'completed' }`.
+- The joinGroup must be declared in `joinGroup.<alias>.aggregations.<fn>` with the referenced field. The engine refuses undeclared references with 400.
+- The joinGroup's own `filters` are applied inside the correlated subquery (consistent with the breakdown).
 - All ConditionBuilder methods work: `isEqual`, `isGreater`, `isLess`, `isBetween`, `isIn`, `isNull`, `isNotNull`, etc.
 - Can be combined with plain-field conditions and with aggregation `orderBy` in the same request.
-- Respects `aggregations.by` rules: allowed when `by` equals the correlation FK, otherwise 400.
+- Respects `aggregations.by` rules: allowed only when `by` equals the correlation FK, otherwise 400.
 
-### Join Filters (filter main by related table)
+### `joinMustExist` (filter main by related table — EXISTS)
 
-`joinFilters` restrict **main table results** based on conditions on a related table. Only tables listed in `allowedReadJoins` are available. Uses `EXISTS` subquery — no duplicate rows, works correctly with pagination.
+`joinMustExist` restricts **main table results** based on conditions on a related child table. Aliases must come from `allowedReadJoins` declarations with `unique: false`. Uses `EXISTS` subquery — no duplicate rows, works correctly with pagination.
 
 ```json
 {
   "filters": { "name": "Mario" },
-  "joinFilters": {
-    "customer_label_link": { "labelId": 1 }
+  "joinMustExist": {
+    "labels": { "filters": { "labelId": 1 } }
   }
 }
 ```
@@ -162,24 +169,37 @@ WHERE "name" = $1
     WHERE "customer_id" = "customer"."id" AND "label_id" = $2)
 ```
 
-`joinFilters` support the same filter fields as the related table (schema fields + extra filters defined via `extendedCondition`). Can be combined with `filters`, `joins`, `joinGroups`, and pagination.
+`joinMustExist` accepts `{ filters, conditions }` (both optional). Supports schema fields + extra filters defined via `extendedCondition` on the related table. Combinable with `filters`, `joinMultiple`, `joinGroup`, `joinLeft`, and pagination.
 
-**Key difference from `joins`**: `joinFilters` filter which main records are returned. `joins` fetch related data for the returned main records. They can be used together.
+**Difference from `joinMultiple`**: `joinMustExist` filters which main records are returned. `joinMultiple` fetches related child data for the returned main records. They can be used together.
 
-### Joins
+### `joinMultiple` (fetch related child rows)
 
-Request related table data via `joins`. Only tables listed in `allowedReadJoins` are available. Each join key is the table name, with optional `filters` to narrow the joined results.
+Request related child table data via `joinMultiple`. Aliases must come from `allowedReadJoins` declarations with `unique: false`. Each entry accepts `{ filters?, conditions?, selection? }`.
 
-The join executes as a separate query: `SELECT ... FROM {joinTable} WHERE {fk} IN ({main PKs})`. Results are grouped by FK.
+```json
+{
+  "joinMultiple": {
+    "orders": {
+      "filters": { "status": "pending" },
+      "selection": "id,total,status"
+    }
+  }
+}
+```
+
+`selection` is optional and overrides the default declared in `buildRelation` (which itself defaults to `'*'`).
 
-### Join Groups (Aggregations)
+The fetch executes as a separate side query: `SELECT {selection} FROM {childTable} WHERE {fk} IN ({main PKs})`. Returned in `result.joinMultiple.<alias>` as an array.
 
-`joinGroups` compute aggregated data on related tables:
+### `joinGroup` (aggregations on related child rows)
+
+`joinGroup` computes aggregated values on a related child table:
 
 ```json
 {
-  "joinGroups": {
-    "customer_order": {
+  "joinGroup": {
+    "orders": {
       "aggregations": {
         "by": "status",
         "sum": ["total"],
@@ -195,39 +215,99 @@ The join executes as a separate query: `SELECT ... FROM {joinTable} WHERE {fk} I
 }
 ```
 
-- `by` — GROUP BY field
+- `by` — GROUP BY name (optional). Either a schema field on the join table or a **computed field** declared on it (e.g. for date bucketing, the backend declares a computed using `db.dateTrunc(unit, qiCol('orderDate'))` and you reference it by name).
 - `sum`, `min`, `max`, `avg` — aggregate functions on specified columns
 - `count` — COUNT(col)
 - `distinctCount` — COUNT(DISTINCT col)
 - `filters` — optional, narrow rows before aggregation
 
-### Ordering
+Example — monthly revenue per customer (the backend declared a `monthBucket` computed):
 
-Use the `orderBy` query parameter:
+```json
+{
+  "joinGroup": {
+    "orders": {
+      "aggregations": {
+        "by": "monthBucket",
+        "sum": ["total"]
+      }
+    }
+  }
+}
+```
 
+Response:
+```json
+{
+  "joinGroup": {
+    "orders": {
+      "rows": [
+        { "by": "2026-01-01", "sum_total": 150 },
+        { "by": "2026-02-01", "sum_total": 200 }
+      ]
+    }
+  }
+}
 ```
-?orderBy=name ASC
-?orderBy=name ASC, id DESC
-?orderBy=created_at DESC
+
+Returned as `result.joinGroup.<alias>` — keyed by the function name when no `by`, or with a `rows` array when `by` is set.
+
+Aliases must come from `allowedReadJoins` declarations with `unique: false`.
+
+### `joinLeft` (embed N:1 parent inline)
+
+`joinLeft` embeds a parent record (N:1 relation) into the result. Aliases must come from `allowedReadJoins` declarations with `unique: true`. Each entry accepts `{ filters?, conditions?, selection? }`.
+
+```json
+{
+  "joinLeft": {
+    "creator": {},
+    "updater": { "filters": { "active": true }, "selection": "id,name" }
+  }
+}
 ```
 
-If not specified, the table's `defaultOrder` is used.
+The engine attaches a real `LEFT JOIN <parentTable> AS <alias>` to the main query **only when needed**:
+- when the request includes `filters` or `conditions` on the parent (effectively turns into INNER JOIN behavior on those aliases — main rows whose parent doesn't match are excluded);
+- when `orderBy` uses 2-parti dotted notation referring to a parent field (`<alias>.<field>`).
+
+Otherwise only a side query `WHERE pk IN (distinct fk values)` is issued — no LEFT JOIN, no row duplication. Either way, the response shape is the same.
+
+The parent rows are returned in `result.joinLeft.<alias>` as a deduplicated array. The client maps a main row to its parent by FK lookup:
+
+```js
+const parent = result.joinLeft.creator.find((u) => u.id === mainRow.userId);
+```
 
-#### Ordering by joinGroup aggregations
+> **Limitation**: `extraFilters` declared via `extendedCondition` on the parent table are **not** applied inside `joinLeft.filters` (only schema fields). The other join families fully support extraFilters.
 
-You can order the main results by an aggregation computed on a joined table using dot notation: `<joinTable>.<fn>.<field>`.
+### Ordering
+
+Use the `orderBy` query parameter. Three forms are supported:
+
+| Form | Source of `<alias>` | Example |
+|------|---------------------|---------|
+| `<field> [ASC\|DESC]` | main schema | `?orderBy=name ASC` |
+| `<alias>.<field> [ASC\|DESC]` | `joinLeft`-eligible (`unique: true`) | `?orderBy=creator.name ASC` |
+| `<alias>.<fn>.<field> [ASC\|DESC]` | `joinGroup` declared in same body | `?orderBy=orders.sum.total DESC` |
+
+Multiple parts may be comma-separated: `?orderBy=creator.name ASC, id DESC`.
+
+If not specified, the table's `defaultOrder` is used.
+
+#### Ordering by joinGroup aggregations (3-parti)
 
 Supported functions: `sum`, `min`, `max`, `avg`, `count`, `distinctCount`.
 
 Example: get users ordered by total session duration DESC.
 
 ```
-POST /auto/search/user?orderBy=session.sum.duration%20DESC
+POST /auto/search/user?orderBy=sessions.sum.duration%20DESC
 ```
 ```json
 {
-  "joinGroups": {
-    "session": {
+  "joinGroup": {
+    "sessions": {
       "aggregations": { "sum": ["duration"] }
     }
   }
@@ -245,13 +325,21 @@ ORDER BY (
 ```
 
 **Rules:**
-- The joinGroup **must be declared in the request body** (`joinGroups.<table>.aggregations.<fn>` must include the field). The engine refuses undeclared references with 400.
-- If the joinGroup declares `aggregations.filters`, those filters are applied inside the correlated subquery — consistent with the breakdown.
-- **`aggregations.by`**: allowed **only** when `by` is the same field used for the join correlation (e.g. `by: "userId"` when joining user→session via userId). In that case each main row maps to exactly one group, so the ordering is well-defined *and* the response contains the per-row breakdown you can render next to each row. Using `by` on any other column is rejected with 400 (the result would be bucketed per group, not per row).
+- The joinGroup **must be declared in the request body** (`joinGroup.<alias>.aggregations.<fn>` must include the field). The engine refuses undeclared references with 400.
+- If the joinGroup declares `filters`, those filters are applied inside the correlated subquery — consistent with the breakdown.
+- **`aggregations.by`**: allowed only when `by` is the same field used for the join correlation. Using `by` on any other column is rejected with 400.
 - **Not allowed** when the main table has `distinctResults: true`. 400 error.
-- Can be combined with plain field ordering: `?orderBy=session.sum.duration DESC, name ASC`.
-- The joinGroup breakdown is still returned in the response (`joinGroups.session.sum.duration` etc.) as before — you get both ordered main results and the aggregated summary.
-- **No-data rows**: rows with no matching joined records are coalesced to `0` via `COALESCE(..., 0)`. Practically: on DESC they appear last, on ASC they appear first. This is universal across PostgreSQL, MySQL, and MariaDB.
+- Can be combined with plain-field ordering and with 2-parti `joinLeft` ordering: `?orderBy=sessions.sum.duration DESC, creator.name ASC, name`.
+- The joinGroup breakdown is still returned in the response (`result.joinGroup.<alias>`) — you get both ordered main results and the aggregated summary.
+- **No-data rows**: rows with no matching joined records are coalesced to `0` via `COALESCE(..., 0)`. On DESC they appear last, on ASC they appear first.
+
+#### Ordering by parent fields (2-parti)
+
+```
+?orderBy=creator.name ASC
+```
+
+The alias must be declared with `unique: true` (so it's eligible for `joinLeft`). The engine adds a real `LEFT JOIN` on the main query to make the column orderable. Main row count is preserved (no duplication, since N:1).
 
 ### Pagination
 
@@ -278,11 +366,14 @@ These compute aggregates on the main table's result set (respecting filters). Re
 {
   "table": "customer",
   "main": [{ "id": 1, "name": "Mario", "email": "m@t.it" }],
-  "joins": {
-    "customer_order": [{ "id": 10, "customerId": 1, "total": 50 }]
+  "joinLeft": {
+    "creator": [{ "id": 7, "name": "Alice", "email": "a@x.it" }]
+  },
+  "joinMultiple": {
+    "orders": [{ "id": 10, "customerId": 1, "total": 50 }]
   },
-  "joinGroups": {
-    "customer_order": {
+  "joinGroup": {
+    "orders": {
       "sum": { "total": 150 },
       "rows": [{ "by": "pending", "sum_total": 100 }]
     }
@@ -296,7 +387,7 @@ These compute aggregates on the main table's result set (respecting filters). Re
 }
 ```
 
-`joins`, `joinGroups`, `pagination` appear ONLY if requested. A simple search returns just `{ table, main }`.
+`joinLeft`, `joinMultiple`, `joinGroup`, `pagination` appear ONLY if requested. A simple search returns just `{ table, main }`.
 
 ---
 
@@ -322,7 +413,7 @@ Returns 404 if not found.
 {
   "main": { "name": "Mario", "email": "m@t.it" },
   "secondaries": {
-    "customer_order": [
+    "orders": [
       { "total": 50, "status": "pending" }
     ]
   }
@@ -330,7 +421,7 @@ Returns 404 if not found.
 ```
 
 - `main` — the record to insert. Omit auto-increment PKs (they are in `excludeFromCreation`).
-- `secondaries` — optional. Related records to insert. Only tables in `allowedWriteJoins` are accepted. FK fields (e.g. `customerId` in orders) are auto-filled from the inserted main record's PK.
+- `secondaries` — optional. Related records to insert. Keys are **aliases** from `allowedWriteJoins`. FK fields (e.g. `customerId` in orders) are auto-filled from the inserted main record's PK.
 
 **Response (201):** PK-only for main and secondaries.
 
@@ -338,7 +429,7 @@ Returns 404 if not found.
 {
   "main": { "id": 1 },
   "secondaries": {
-    "customer_order": [{ "id": 10 }]
+    "orders": [{ "id": 10 }]
   }
 }
 ```
@@ -353,25 +444,25 @@ Returns 404 if not found.
 {
   "main": { "id": 1, "name": "Mario Updated", "email": "new@t.it" },
   "secondaries": {
-    "customer_order": [{ "total": 75, "status": "shipped" }]
+    "orders": [{ "total": 75, "status": "shipped" }]
   },
   "deletions": {
-    "customer_order": [{ "id": 10 }]
+    "orders": [{ "id": 10 }]
   }
 }
 ```
 
 - `main` — MUST include the PK. Only changed fields need to be sent (partial update).
-- `secondaries` — optional. New related records to insert (FK auto-filled).
-- `deletions` — optional. Related records to delete (by PK).
+- `secondaries` — optional. New related records to insert (FK auto-filled). Keys are **aliases**.
+- `deletions` — optional. Related records to delete (by PK). Keys are **aliases**.
 
 **Response (200):** PK-only for main, secondaries, and deletions.
 
 ```json
 {
   "main": { "id": 1 },
-  "secondaries": { "customer_order": [{ "id": 20 }] },
-  "deletions": { "customer_order": [{ "id": 10 }] }
+  "secondaries": { "orders": [{ "id": 20 }] },
+  "deletions":   { "orders": [{ "id": 10 }] }
 }
 ```
 
@@ -401,8 +492,8 @@ Insert or update multiple records in a single request.
 [
   {
     "main": { "name": "Mario", "email": "m@t.it" },
-    "secondaries": { "customer_order": [{ "total": 50 }] },
-    "deletions": { "customer_order": [{ "id": 99 }] }
+    "secondaries": { "orders": [{ "total": 50 }] },
+    "deletions": { "orders": [{ "id": 99 }] }
   },
   {
     "main": { "name": "Luigi", "email": "l@t.it" }
@@ -410,7 +501,7 @@ Insert or update multiple records in a single request.
 ]
 ```
 
-All main records are inserted/upserted in a single SQL query. Secondaries and deletions are processed per-item.
+All main records are inserted/upserted in a single SQL query. Secondaries and deletions are processed per-item. `secondaries`/`deletions` keys are **aliases**.
 
 **Response (200):** Array of `{ main (PK-only), secondaries? (PK-only), deletions? }`.
 
@@ -452,13 +543,13 @@ Both return the same response format:
   "message": "Validation failed",
   "fields": [
     { "path": "body.main.name", "code": "required", "message": "must have required property 'name'" },
-    { "path": "session_period[1].startDate", "code": "overlap", "message": "overlaps with another period" }
+    { "path": "periods[1].startDate", "code": "overlap", "message": "overlaps with another period" }
   ]
 }
 ```
 
 Each entry in `fields`:
-- `path` — the field path (e.g. `body.main.name` for schema errors, `name` or `session_period[1].startDate` for custom validation)
+- `path` — the field path (e.g. `body.main.name` for schema errors, `name` or `periods[1].startDate` for custom validation)
 - `code` — machine-readable error code (e.g. `required`, `type`, `overlap`, `unique`)
 - `message` — human-readable description
 
@@ -468,7 +559,7 @@ Each entry in `fields`:
 const response = await fetch('/api/rest/session', {
   method: 'POST',
   headers: { 'Content-Type': 'application/json' },
-  body: JSON.stringify({ main: { name: '' }, secondaries: { session_period: periods } }),
+  body: JSON.stringify({ main: { name: '' }, secondaries: { periods } }),
 });
 
 if (!response.ok) {
@@ -488,4 +579,7 @@ if (!response.ok) {
 
 - **PK-only responses**: Insert, update, delete, bulk operations return only the primary key fields, not the full record. This is by design for performance and consistency.
 - **camelCase fields**: All request and response fields use camelCase (e.g. `customerId`, not `customer_id`). The plugin converts automatically.
-- **Joins are virtual**: Not SQL JOINs. They execute separate queries and group results by FK. This keeps the main query simple and avoids N+1 issues through batching.
+- **Aliases everywhere**: in request bodies, response payloads, `secondaries`/`deletions`, and dotted notation, the keys are aliases declared by the backend in `buildRelation`. Default = the joined table's name; can be overridden (e.g. `orders` for `customer_order`).
+- **Computed fields**: the backend may declare virtual fields via `computedFields` on a table. They appear in Swagger as additional filter/orderBy names, behave exactly like schema fields (filters, conditions, orderBy, computeMin/Max/Sum/Avg), and are projected into the main response only when explicitly listed in `selectComputed: ['<name>']` in the body.
+- **`joinMultiple` / `joinMustExist` / `joinGroup`** are 1:N (child→main) and use side queries / EXISTS / correlated subqueries — no row duplication of main.
+- **`joinLeft`** is N:1 (parent→main) and adds a real `LEFT JOIN` on demand (only when filtering/ordering by parent).

package/README.md

@@ -9,7 +9,8 @@ Point it at your database, and get a full REST API with search, advanced conditi
 - **Zero boilerplate** — define your tables, get 7 endpoints each
 - **No ORM** — raw SQL via `pg` + parameterized queries
 - **TypeBox validation** — request/response schemas auto-generated from your DB
-- **Virtual joins** — fetch related records without complex SQL
+- **Joins** — four explicit families (`joinMustExist`, `joinMultiple`, `joinGroup`, `joinLeft`) with alias support
+- **Computed fields** — declare virtual fields as SQL expressions in `defineTable`; usable like schema fields in filters/orderBy/conditions, and opt-in projected in the response via `selectComputed`. Covers JSON extraction, derived columns, dialect-aware date bucketing
 - **Bulk operations** — batch insert/upsert/delete in single queries
 - **Multi-tenant** — automatic row-level isolation, zero code in handlers
 - **Validation** — structured field-level validation with cross-entity support
@@ -17,6 +18,8 @@ Point it at your database, and get a full REST API with search, advanced conditi
 - **Swagger UI** — optional, auto-configured from your schemas
 - **Composable** — register all routes or pick only what you need
 
+> ⚠️ **Migrating from a previous version?** The join API was redesigned. See **[BREAKING_CHANGES.md](./BREAKING_CHANGES.md)** for the full migration guide.
+
 ## Quick Start
 
 ### 1. Install
@@ -143,12 +146,16 @@ const TableCustomer = defineTable({
   excludeFromCreation: ['id'],              // omit from INSERT (e.g. auto-increment)
   distinctResults: true,                    // SELECT DISTINCT
 
-  // Relations
+  // Relations — alias defaults to joinSchema.tableName. Override with `{ alias: '...' }`
+  // when you join the same table twice (e.g. `createdBy`/`updatedBy`) or want a friendlier
+  // name. Set `unique: true` for N:1 (parent) relations to enable `joinLeft`.
   allowedReadJoins: [
-    buildRelation(SchemaCustomer, 'id', SchemaOrder, 'customerId'),
+    buildRelation(SchemaCustomer, 'id', SchemaOrder, 'customerId'),                       // alias = 'order'
+    buildRelation(SchemaSession, 'userId', SchemaUser, 'id', { unique: true }),           // alias = 'user', N:1
+    buildRelation(SchemaSession, 'updatedBy', SchemaUser, 'id', { alias: 'updater', unique: true }),
   ],
   allowedWriteJoins: [
-    buildRelation(SchemaCustomer, 'id', SchemaOrder, 'customerId'),
+    buildRelation(SchemaCustomer, 'id', SchemaOrder, 'customerId'),                       // alias = 'order'
   ],
 
   // Upsert (ON CONFLICT)
@@ -255,20 +262,20 @@ Search with filters, advanced conditions, pagination, ordering, joins, and aggre
     { "field": "total", "method": "isGreater", "params": [100] },
     { "field": "createdAt", "method": "isBetween", "params": ["2024-01-01", "2024-12-31"] }
   ],
-  "joinFilters": {
-    "order": {
+  "joinMustExist": {
+    "orders": {
       "filters": { "status": "completed" },
       "conditions": [{ "field": "total", "method": "isGreater", "params": [50] }]
     }
   },
-  "joins": {
-    "order": {
+  "joinMultiple": {
+    "orders": {
       "filters": { "status": "completed" },
-      "conditions": [{ "field": "total", "method": "isGreater", "params": [50] }]
+      "selection": "id,total,status"
     }
   },
-  "joinGroups": {
-    "order": {
+  "joinGroup": {
+    "orders": {
       "aggregations": {
         "by": "status",
         "sum": ["total"],
@@ -278,20 +285,29 @@ Search with filters, advanced conditions, pagination, ordering, joins, and aggre
         "count": ["id"],
         "distinctCount": ["status"]
       },
-      "filters": { "status": "completed" },
-      "conditions": [{ "field": "total", "method": "isGreater", "params": [0] }]
+      "filters": { "status": "completed" }
     }
+  },
+  "joinLeft": {
+    "creator": { "selection": "id,name,email" }
   }
 }
 ```
 
 - **`filters`** — equality-based, flat key/value. Supports schema fields + `extraFilters`.
 - **`conditions`** — array of `{ field, method, params }`. Methods: `isEqual`, `isNotEqual`, `isGreater`, `isGreaterOrEqual`, `isLess`, `isLessOrEqual`, `isLike`, `isILike`, `isIn`, `isNotIn`, `isBetween`, `isNotBetween`, `isNull`, `isNotNull`.
-- **`joinFilters`** — EXISTS-based filtering: "main rows where at least one related row matches". Accepts `{ filters, conditions }` (both optional). Only tables in `allowedReadJoins`.
-- **`joins`** — fetch related records (virtual join via separate query). Accepts `{ filters, conditions }`.
-- **`joinGroups`** — aggregations on related tables. Supports `sum`, `min`, `max`, `avg`, `count`, `distinctCount`, and optional `by` for GROUP BY. Accepts `{ filters, conditions }` inside the subquery.
+- **`joinMustExist`** — EXISTS-based filter: "main rows where at least one related row matches". Accepts `{ filters, conditions }` (both optional). Aliases must come from `allowedReadJoins` declarations with `unique: false`.
+- **`joinMultiple`** — fetches related child rows in a side query. Accepts `{ filters, conditions, selection }`. Same `unique: false` aliases.
+- **`joinGroup`** — aggregations on the related table. Supports `sum`, `min`, `max`, `avg`, `count`, `distinctCount`, and optional `by` for GROUP BY (a schema field name or a computed-field name declared on the join table — e.g. for date bucketing declare a computed using `db.dateTrunc('month', qiCol('orderDate'))`). Accepts `{ filters, conditions }`. Same `unique: false` aliases.
+- **`joinLeft`** — embeds an N:1 parent. Real `LEFT JOIN` is added on demand (only when the request has `filters`/`conditions` on the parent or uses 2-parti `orderBy` on this alias). Aliases must be declared with `unique: true`. Accepts `{ filters, conditions, selection }`.
+
+**Dot-notation in `orderBy` and `conditions`**:
 
-**Dot-notation in `conditions` and `orderBy`** — use `<joinTable>.<fn>.<field>` to filter/order the main rows by an aggregation value (HAVING-style). Example: `orderBy=order.sum.total DESC` or `conditions: [{ field: 'order.count.id', method: 'isGreaterOrEqual', params: [4] }]`. The joinGroup must be declared in the body.
+| Form | Source | Example |
+|------|--------|---------|
+| `<field>` | main schema | `orderBy=name ASC` |
+| `<alias>.<field>` | `joinLeft` aliases (`unique: true`) | `orderBy=creator.name ASC` |
+| `<alias>.<fn>.<field>` | `joinGroup` aliases declared in the same body | `orderBy=orders.sum.total DESC`, or `conditions: [{ field: 'orders.count.id', method: 'isGreaterOrEqual', params: [4] }]` |
 
 **Querystring** (optional): `orderBy`, `page`, `itemsPerPage`, `computeMin`, `computeMax`, `computeSum`, `computeAvg`
 
@@ -301,9 +317,10 @@ Search with filters, advanced conditions, pagination, ordering, joins, and aggre
 {
   "table": "customer",
   "main": [{ "id": 1, "name": "Mario", "email": "m@test.it" }],
-  "joins": { "order": [{ "id": 10, "customerId": 1, "total": 50 }] },
-  "joinGroups": {
-    "order": {
+  "joinLeft":     { "creator": [{ "id": 7, "name": "Alice", "email": "a@x.it" }] },
+  "joinMultiple": { "orders":  [{ "id": 10, "customerId": 1, "total": 50 }] },
+  "joinGroup": {
+    "orders": {
       "sum": { "total": 300 },
       "count": { "id": 2 },
       "rows": [{ "by": "completed", "sum_total": 300, "count_id": 2 }]
@@ -318,7 +335,7 @@ Search with filters, advanced conditions, pagination, ordering, joins, and aggre
 }
 ```
 
-`joins`, `joinGroups`, and `pagination` only appear when requested. A simple `{}` body returns `{ table, main }`. `pagination.computed` appears only if `computeMin`/`computeMax`/`computeSum`/`computeAvg` are used.
+`joinLeft`, `joinMultiple`, `joinGroup`, and `pagination` appear only when requested. A simple `{}` body returns `{ table, main }`. `pagination.computed` appears only if `computeMin`/`computeMax`/`computeSum`/`computeAvg` are used.
 
 ### GET /rest/{table}/:id
 
@@ -332,12 +349,12 @@ Returns `{ main: { ... } }` or 404.
 {
   "main": { "name": "Mario", "email": "m@test.it" },
   "secondaries": {
-    "order": [{ "total": 50, "status": "pending" }]
+    "orders": [{ "total": 50, "status": "pending" }]
   }
 }
 ```
 
-`secondaries` is optional. FK fields are auto-filled from the inserted main record.
+`secondaries` keys are the **alias** declared in `allowedWriteJoins`. FK fields are auto-filled from the inserted main record.
 
 **Response (201):** `{ main: { ... }, secondaries: { ... } }`
 
@@ -348,8 +365,8 @@ Returns `{ main: { ... } }` or 404.
 ```json
 {
   "main": { "id": 1, "name": "Updated Name" },
-  "secondaries": { "order": [{ "total": 75 }] },
-  "deletions": { "order": [{ "id": 10 }] }
+  "secondaries": { "orders": [{ "total": 75 }] },
+  "deletions":   { "orders": [{ "id": 10 }] }
 }
 ```
 
@@ -480,7 +497,9 @@ await app.register(async (instance) => {
 
 - **camelCase everywhere in the API** — requests, responses, `validate`, and all hooks (`beforeInsert`, `beforeUpdate`, `afterInsert`) use schema field names
 - **Conversion to DB column format is automatic** via `colMap` — supports both snake_case and camelCase DB columns (e.g. betterauth-style)
-- **Joins are virtual** — separate `SELECT ... WHERE fk IN (...)` queries, not SQL JOINs
+- **Aliases identify joins** — declared in `buildRelation({ alias })`, used as keys in request/response/`secondaries`/dotted notation
+- **`joinMustExist` / `joinMultiple` / `joinGroup`** are 1:N (child→main) and use side queries / EXISTS / correlated subqueries — no row duplication
+- **`joinLeft`** is N:1 (parent→main) and adds a real `LEFT JOIN` on demand (only when filtering/ordering by parent)
 - **All response fields are Optional** — response schemas use `Type.Partial` since `RETURNING *` may return any subset
 
 ## Re-exports
@@ -516,7 +535,9 @@ import type {
   ValidationError,        // [field, code] | [field, code, message]
   ValidatorFn,
   BulkValidatorFn,
+  JoinDefinition,
   JoinRefFilter,
+  JoinFetchRequest,
   JoinGroupRequest,
   SearchCondition,
   ConditionMethod,