Skip to content

Commit 0df46f8

Browse files
ez-pluginsez-plugins
committed
docs: split query and dialect docs into per-type submenu pages
Queries (nav_order 3, has_children): - queries/select.md — SELECT builder (was query-builder.md) - queries/insert.md — InsertBuilder - queries/update.md — UpdateBuilder - queries/delete.md — DeleteBuilder - queries/create.md — CreateBuilder (replaces query-builder.md + dml-builders.md) SQL Dialects (nav_order 6, has_children): - dialects/standard.md — ANSI / no quoting - dialects/mysql.md — back-tick quoting, DELETE LIMIT - dialects/sqlite.md — double-quote quoting, DELETE LIMIT - dialects/postgresql.md — double-quote, ILIKE, RETURNING (replaces sql-dialects.md) - Remove query-builder.md, dml-builders.md, sql-dialects.md - Shift nav_order of conditions (5→4), subqueries (6→5), configuration (8→7), in-memory (9→8), exceptions (10→9), api-reference (11→10) - Update docs/index.md table links to new paths
1 parent 030fc0d commit 0df46f8

19 files changed

Lines changed: 967 additions & 411 deletions

‎docs/api-reference.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
title: API Reference
3-
nav_order: 11
3+
nav_order: 10
44
description: "Complete public method tables for every class and interface in JavaQueryBuilder"
55
---
66

‎docs/conditions.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
title: Conditions
3-
nav_order: 5
3+
nav_order: 4
44
description: "Operators, Condition, ConditionEntry, Connector AND/OR, and the orWhere* pattern"
55
---
66

‎docs/configuration.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
title: Configuration
3-
nav_order: 8
3+
nav_order: 7
44
description: "QueryBuilderDefaults: global and per-query preset for dialect, columns, limit, offset, and LIKE wrapping"
55
---
66

docs/sql-dialects.md renamed to docs/dialects/index.md

Lines changed: 22 additions & 86 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,9 @@
11
---
22
title: SQL Dialects
3-
nav_order: 7
4-
description: "SqlDialect, SqlResult, AbstractSqlDialect, and the dialect matrix"
3+
nav_order: 6
4+
has_children: true
5+
permalink: /sql-dialects/
6+
description: "SqlDialect, SqlResult, AbstractSqlDialect, and the dialect comparison matrix"
57
---
68

79
# SQL Dialects
@@ -18,52 +20,31 @@ description: "SqlDialect, SqlResult, AbstractSqlDialect, and the dialect matrix"
1820
## Overview
1921

2022
`SqlDialect` is a strategy interface that converts a `Query` object into a
21-
parameterized `SqlResult`. Three built-in dialects are provided as constants
23+
parameterized `SqlResult`. Four built-in dialects are provided as constants
2224
on the interface:
2325

24-
| Constant | Identifier quoting | DELETE LIMIT | ILIKE | RETURNING |
25-
|----------|--------------------|--------------| ------|----------|
26-
| `SqlDialect.STANDARD` | None (ANSI) | Not supported | No | No |
27-
| `SqlDialect.MYSQL` | Back-tick `` ` `` | Supported | No | No |
28-
| `SqlDialect.SQLITE` | Double-quote `"` | Supported | No | No |
29-
| `SqlDialect.POSTGRESQL` | Double-quote `"` | Not supported | Yes | Yes (DELETE) |
26+
| Constant | Page | Identifier quoting | DELETE LIMIT | ILIKE | RETURNING |
27+
|----------|------|--------------------|--------------|-------|-----------|
28+
| `SqlDialect.STANDARD` | [STANDARD]({{ site.baseurl }}/sql-dialects/standard/) | None (ANSI) | No | No | No |
29+
| `SqlDialect.MYSQL` | [MySQL]({{ site.baseurl }}/sql-dialects/mysql/) | Back-tick `` ` `` | Yes | No | No |
30+
| `SqlDialect.SQLITE` | [SQLite]({{ site.baseurl }}/sql-dialects/sqlite/) | Double-quote `"` | Yes | No | No |
31+
| `SqlDialect.POSTGRESQL` | [PostgreSQL]({{ site.baseurl }}/sql-dialects/postgresql/) | Double-quote `"` | No | Yes | Yes (DELETE) |
3032

3133
---
3234

33-
## Using a dialect
35+
## Dialect matrix
3436

35-
Pass a dialect to `buildSql()` on the builder:
37+
The same `Query` produces different SQL across dialects due to identifier
38+
quoting:
3639

37-
```java
38-
// Standard ANSI
39-
SqlResult r1 = new QueryBuilder()
40-
.from("users")
41-
.whereEquals("id", 1)
42-
.buildSql();
43-
// → SELECT * FROM users WHERE id = ?
44-
45-
// MySQL: back-tick quoted identifiers
46-
SqlResult r2 = new QueryBuilder()
47-
.from("users")
48-
.whereEquals("id", 1)
49-
.buildSql(SqlDialect.MYSQL);
50-
// → SELECT * FROM `users` WHERE `id` = ?
51-
52-
// SQLite: double-quoted identifiers
53-
SqlResult r3 = new QueryBuilder()
54-
.from("users")
55-
.whereEquals("id", 1)
56-
.buildSql(SqlDialect.SQLITE);
57-
// → SELECT * FROM "users" WHERE "id" = ?
58-
59-
// PostgreSQL: double-quoted identifiers + ILIKE support
60-
SqlResult r4 = new QueryBuilder()
61-
.from("users")
62-
.whereILike("email", "alice")
63-
.buildSql(SqlDialect.POSTGRESQL);
64-
// → SELECT * FROM "users" WHERE "email" ILIKE ?
65-
// Parameters: ["%alice%"]
66-
```
40+
| Feature | STANDARD | MYSQL | SQLITE | POSTGRESQL |
41+
|---------|----------|-------|--------|------------|
42+
| Table quoting | `users` | `` `users` `` | `"users"` | `"users"` |
43+
| Column quoting | `id` | `` `id` `` | `"id"` | `"id"` |
44+
| DELETE LIMIT | No | Yes | Yes | No |
45+
| ILIKE / NOT ILIKE | No | No | No | Yes |
46+
| RETURNING on DELETE | No | No | No | Yes |
47+
| Parameter syntax | `?` | `?` | `?` | `?` |
6748

6849
---
6950

@@ -93,51 +74,6 @@ List<Object> params = result.getParameters();
9374

9475
---
9576

96-
## Rendering DELETE statements
97-
98-
Use `renderDelete(Query)` on a dialect instance to produce `DELETE FROM ...`
99-
statements. This respects the `LIMIT` clause on dialects that support it and
100-
the `RETURNING` clause on PostgreSQL.
101-
102-
```java
103-
Query q = new QueryBuilder()
104-
.from("sessions")
105-
.whereEquals("expired", true)
106-
.limit(500)
107-
.build();
108-
109-
// Standard: LIMIT ignored
110-
SqlResult std = SqlDialect.STANDARD.renderDelete(q);
111-
// → DELETE FROM sessions WHERE expired = ?
112-
113-
// MySQL: LIMIT honored
114-
SqlResult my = SqlDialect.MYSQL.renderDelete(q);
115-
// → DELETE FROM `sessions` WHERE `expired` = ? LIMIT 500
116-
117-
// SQLite: LIMIT honored
118-
SqlResult sq = SqlDialect.SQLITE.renderDelete(q);
119-
// → DELETE FROM "sessions" WHERE "expired" = ? LIMIT 500
120-
```
121-
122-
For PostgreSQL `RETURNING`, use `DeleteBuilder.returning()` — see [DML Builders](dml-builders#returning-clause-postgresql).
123-
124-
---
125-
126-
## Dialect matrix
127-
128-
The same `Query` produces different SQL across dialects due to identifier quoting:
129-
130-
| Feature | STANDARD | MYSQL | SQLITE | POSTGRESQL |
131-
|---------|----------|-------|--------|------------|
132-
| Table quoting | `users` | `` `users` `` | `"users"` | `"users"` |
133-
| Column quoting | `id` | `` `id` `` | `"id"` | `"id"` |
134-
| DELETE LIMIT | No | Yes | Yes | No |
135-
| ILIKE / NOT ILIKE | No | No | No | Yes |
136-
| RETURNING on DELETE | No | No | No | Yes |
137-
| Parameter syntax | `?` | `?` | `?` | `?` |
138-
139-
---
140-
14177
## AbstractSqlDialect
14278

14379
`AbstractSqlDialect` implements the shared rendering logic for SELECT and DELETE

‎docs/dialects/mysql.md‎

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
---
2+
title: MySQL
3+
parent: SQL Dialects
4+
nav_order: 2
5+
permalink: /sql-dialects/mysql/
6+
description: "MySQL dialect — back-tick identifier quoting and DELETE LIMIT support"
7+
---
8+
9+
# MySQL Dialect
10+
{: .no_toc }
11+
12+
## Table of contents
13+
{: .no_toc .text-delta }
14+
15+
1. TOC
16+
{:toc}
17+
18+
---
19+
20+
## Overview
21+
22+
`SqlDialect.MYSQL` wraps all table and column identifiers in back-ticks
23+
(`` ` ``). It also supports the `LIMIT` clause on `DELETE` statements.
24+
Quoting is applied to SELECT and DELETE queries rendered through this dialect.
25+
26+
| Feature | Value |
27+
|---------|-------|
28+
| Identifier quoting | Back-tick `` ` `` |
29+
| DELETE LIMIT | Supported |
30+
| ILIKE | Not supported |
31+
| RETURNING on DELETE | Not supported |
32+
33+
---
34+
35+
## SELECT
36+
37+
```java
38+
SqlResult r = new QueryBuilder()
39+
.from("users")
40+
.select("id", "name", "email")
41+
.whereEquals("status", "active")
42+
.orderBy("name", true)
43+
.buildSql(SqlDialect.MYSQL);
44+
// → SELECT `id`, `name`, `email` FROM `users` WHERE `status` = ? ORDER BY `name` ASC
45+
// Parameters: ["active"]
46+
```
47+
48+
---
49+
50+
## DELETE with LIMIT
51+
52+
```java
53+
Query q = new QueryBuilder()
54+
.from("logs")
55+
.whereLessThan("created_at", "2025-01-01")
56+
.limit(1000)
57+
.build();
58+
59+
SqlResult result = SqlDialect.MYSQL.renderDelete(q);
60+
// → DELETE FROM `logs` WHERE `created_at` < ? LIMIT 1000
61+
// Parameters: ["2025-01-01"]
62+
```
63+
64+
Or via `DeleteBuilder`:
65+
66+
```java
67+
SqlResult result = QueryBuilder.deleteFrom("sessions")
68+
.whereEquals("expired", true)
69+
.build(SqlDialect.MYSQL);
70+
// → DELETE FROM `sessions` WHERE `expired` = ?
71+
```
72+
73+
---
74+
75+
## Identifier quoting coverage
76+
77+
Back-tick quoting is applied by the dialect to identifiers in SELECT and DELETE
78+
statements. INSERT and UPDATE builders render their own SQL and do not apply
79+
dialect quoting to column or table names.
80+
81+
---
82+
83+
## When to use
84+
85+
- MySQL and MariaDB
86+
- Any database that uses back-tick quoting convention
87+
- When `DELETE … LIMIT` batching is needed

0 commit comments

Comments
 (0)