Skip to content

Commit 06983bf

Browse files
jeffgbutlerjeffgbutler
committed
Docs
1 parent fa59817 commit 06983bf

File tree

5 files changed

+153
-61
lines changed

5 files changed

+153
-61
lines changed

‎CHANGELOG.md

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,13 @@ functions in the Kotlin DSL still only apply to the where clause.
3535

3636
The pull request for this change is ([#550](https://github.com/mybatis/mybatis-dynamic-sql/pull/550))
3737

38+
### Multi-Select Queries
39+
40+
A multi-select query is a special case of a union select statement. The difference is that it allows "order by" and
41+
paging clauses to be applied to the nested queries.
42+
43+
The pull request for this change is...TODO
44+
3845
### Other Changes
3946

4047
1. Added support for specifying "limit" and "order by" on the DELETE and UPDATE statements. Not all databases support

‎src/site/markdown/docs/kotlinMyBatis3.md

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -940,6 +940,14 @@ val records = mapper.select {
940940
}
941941
```
942942

943+
## Multi-Select Statement Support
944+
945+
Multi-select statements are a special case of select statement. All the above information about MyBatis mappers applies
946+
equally to multi-select statements.
947+
948+
The library does not provide a "one-step" shortcut for multi-select queries. You can execute a multi-select query
949+
with the two-step method using either a "selectMany" or "selectOne" mapper method as shown above.
950+
943951
## Update Method Support
944952

945953
### Two-Step Method

‎src/site/markdown/docs/kotlinOverview.md

Lines changed: 96 additions & 53 deletions
Original file line numberDiff line numberDiff line change
@@ -6,9 +6,9 @@ DSL. You certainly can use the Java DSL with Kotlin. However, using the more spe
66
benefits:
77

88
1. The Kotlin DSL generally masks the platform types that are inferred with the underlying Java DSL
9-
1. The Kotlin DSL accurately expresses the nullability expectations of the underlying Java DSL
10-
1. Using the Kotlin DSL will avoid some confusion with overloaded function names that are present in the Java DSL
11-
1. The Kotlin DSL makes extensive use of Kotlin DSL construction features. It more closely mimics actual SQL than the
9+
2. The Kotlin DSL accurately expresses the nullability expectations of the underlying Java DSL
10+
3. Using the Kotlin DSL will avoid some confusion with overloaded function names that are present in the Java DSL
11+
4. The Kotlin DSL makes extensive use of Kotlin DSL construction features. It more closely mimics actual SQL than the
1212
Java DSL and will likely feel more natural to Kotlin developers
1313

1414
We take the customary approach to DSL building in Kotlin in that we attempt to create a somewhat natural feel for SQL,
@@ -41,7 +41,7 @@ generated by the DSL. In general, the DSL can be used to generate the following
4141
users these objects can be considered intermediate objects and will not need to be accessed directly. However, if
4242
you want to implement a custom rendering strategy then you might need to work with "model" objects (this is an
4343
unusual use case)
44-
1. "Provider" objects have been rendered into a form that can be used with SQL execution engines
44+
2. "Provider" objects have been rendered into a form that can be used with SQL execution engines
4545
directly. Currently, the library supports rendering for MyBatis3 and Spring JDBC Template. Most users will interact
4646
with "provider" objects in some form or another
4747

@@ -87,7 +87,7 @@ import org.mybatis.dynamic.sql.util.kotlin.elements.column
8787
import java.util.Date
8888

8989
object PersonDynamicSqlSupport {
90-
val person: Person()
90+
val person = Person()
9191
val id = person.id
9292
val firstName = person.firstName
9393
val lastName = person.lastName
@@ -114,9 +114,9 @@ object PersonDynamicSqlSupport {
114114
Notes:
115115

116116
1. The outer object is a singleton containing the `SqlTable` and `SqlColumn` objects that map to the database table.
117-
1. The inner `SqlTable` is declared as a `class` rather than an `object` - this allows you to create additional
117+
2. The inner `SqlTable` is declared as a `class` rather than an `object` - this allows you to create additional
118118
instances for use in self-joins.
119-
1. Note the use of the `column` extension function. This function accepts different
119+
3. Note the use of the `column` extension function. This function accepts different
120120
parameters for the different attributes that can be assigned to a column (such as a MyBatis3 type handler, or a
121121
custom rendering strategy). We recommend using this extension function rather than the corresponding `column` and
122122
`withXXX` methods in the Java native DSL because the extension method will retain the non-nullable type information
@@ -132,15 +132,17 @@ The library supports the following types of statements:
132132

133133
1. Count statements of various types - these are specialized select statements that return a single Long column, Count
134134
statements support where clauses, joins, and subqueries.
135-
1. Delete statement with or without a where clause.
136-
1. Insert statements of various types:
135+
2. Delete statement with or without a where clause.
136+
3. Insert statements of various types:
137137
1. Single row insert - a statement where the insert values are obtained from a record class
138-
1. General insert - a statement where the insert values are set directly in the statement
139-
1. Multi-row Insert - a statement where the insert values are derived from a collection of records
140-
1. Batch insert - a set of insert statements appropriate for use as a JDBC batch
141-
1. Insert select - a statement where the insert values are obtained from a select statement
142-
1. Select statement that supports joins, subqueries, where clauses, order by clauses, group by clauses, etc.
143-
1. Update Statement with or without a where clause
138+
2. General insert - a statement where the insert values are set directly in the statement
139+
3. Multi-row Insert - a statement where the insert values are derived from a collection of records
140+
4. Batch insert - a set of insert statements appropriate for use as a JDBC batch
141+
5. Insert select - a statement where the insert values are obtained from a select statement
142+
4. Select statement that supports joins, subqueries, where clauses, order by clauses, group by clauses, etc.
143+
5. Multi-Select statements - multiple full select statements (including order by and paging clauses) merged together
144+
with "union" or "union all" operators
145+
6. Update Statement with or without a where clause
144146

145147
## Count Statements
146148

@@ -150,8 +152,8 @@ where clause.
150152
The library supports three types of count statements:
151153

152154
1. `count(*)` - counts the number of rows that match a where clause
153-
1. `count(column)` - counts the number of non-null column values that match a where clause
154-
1. `count(distinct column)` - counts the number of unique column values that match a where clause
155+
2. `count(column)` - counts the number of non-null column values that match a where clause
156+
3. `count(distinct column)` - counts the number of unique column values that match a where clause
155157

156158
The DSL for count statements looks like this:
157159

@@ -174,11 +176,11 @@ val countDistinctColumnStatement = countDistinct(lastName) {
174176

175177
These methods create models or providers depending on which package is used:
176178

177-
| Package | Resulting Object |
178-
|---|---|
179-
| org.mybatis.dynamic.sql.util.kotlin.model | org.mybatis.dynamic.sql.select.SelectModel |
179+
| Package | Resulting Object |
180+
|----------------------------------------------|---------------------------------------------------------------------------------------|
181+
| org.mybatis.dynamic.sql.util.kotlin.model | org.mybatis.dynamic.sql.select.SelectModel |
180182
| org.mybatis.dynamic.sql.util.kotlin.mybatis3 | org.mybatis.dynamic.sql.select.render.SelectStatementProvider (rendered for MyBatis3) |
181-
| org.mybatis.dynamic.sql.util.kotlin.spring | org.mybatis.dynamic.sql.select.render.SelectStatementProvider (rendered for Spring) |
183+
| org.mybatis.dynamic.sql.util.kotlin.spring | org.mybatis.dynamic.sql.select.render.SelectStatementProvider (rendered for Spring) |
182184

183185
## Delete Statement
184186

@@ -202,11 +204,11 @@ val rows = template.deleteFrom(person) {
202204

203205
This method creates models or providers depending on which package is used:
204206

205-
| Package | Resulting Object |
206-
|---|---|
207-
| org.mybatis.dynamic.sql.util.kotlin.model | org.mybatis.dynamic.sql.delete.DeleteModel |
207+
| Package | Resulting Object |
208+
|----------------------------------------------|---------------------------------------------------------------------------------------|
209+
| org.mybatis.dynamic.sql.util.kotlin.model | org.mybatis.dynamic.sql.delete.DeleteModel |
208210
| org.mybatis.dynamic.sql.util.kotlin.mybatis3 | org.mybatis.dynamic.sql.delete.render.DeleteStatementProvider (rendered for MyBatis3) |
209-
| org.mybatis.dynamic.sql.util.kotlin.spring | org.mybatis.dynamic.sql.delete.render.DeleteStatementProvider (rendered for Spring) |
211+
| org.mybatis.dynamic.sql.util.kotlin.spring | org.mybatis.dynamic.sql.delete.render.DeleteStatementProvider (rendered for Spring) |
210212

211213
## Single Row Insert Statement
212214

@@ -247,11 +249,11 @@ as shown above.
247249

248250
This method creates models or providers depending on which package is used:
249251

250-
| Package | Resulting Object |
251-
|---|---|
252-
| org.mybatis.dynamic.sql.util.kotlin.model | org.mybatis.dynamic.sql.insert.InsertModel |
252+
| Package | Resulting Object |
253+
|----------------------------------------------|---------------------------------------------------------------------------------------|
254+
| org.mybatis.dynamic.sql.util.kotlin.model | org.mybatis.dynamic.sql.insert.InsertModel |
253255
| org.mybatis.dynamic.sql.util.kotlin.mybatis3 | org.mybatis.dynamic.sql.insert.render.InsertStatementProvider (rendered for MyBatis3) |
254-
| org.mybatis.dynamic.sql.util.kotlin.spring | org.mybatis.dynamic.sql.insert.render.InsertStatementProvider (rendered for Spring) |
256+
| org.mybatis.dynamic.sql.util.kotlin.spring | org.mybatis.dynamic.sql.insert.render.InsertStatementProvider (rendered for Spring) |
255257

256258
## General Insert Statement
257259

@@ -274,11 +276,11 @@ val generalInsertStatement = insertInto(person) {
274276

275277
This method creates models or providers depending on which package is used:
276278

277-
| Package | Resulting Object |
278-
|---|---|
279-
| org.mybatis.dynamic.sql.util.kotlin.model | org.mybatis.dynamic.sql.insert.GeneralInsertModel |
279+
| Package | Resulting Object |
280+
|----------------------------------------------|----------------------------------------------------------------------------------------------|
281+
| org.mybatis.dynamic.sql.util.kotlin.model | org.mybatis.dynamic.sql.insert.GeneralInsertModel |
280282
| org.mybatis.dynamic.sql.util.kotlin.mybatis3 | org.mybatis.dynamic.sql.insert.render.GeneralInsertStatementProvider (rendered for MyBatis3) |
281-
| org.mybatis.dynamic.sql.util.kotlin.spring | org.mybatis.dynamic.sql.insert.render.GeneralInsertStatementProvider (rendered for Spring) |
283+
| org.mybatis.dynamic.sql.util.kotlin.spring | org.mybatis.dynamic.sql.insert.render.GeneralInsertStatementProvider (rendered for Spring) |
282284

283285
## Multi-Row Insert Statement
284286

@@ -324,11 +326,11 @@ the documentation pages for those utilities.
324326

325327
This method creates models or providers depending on which package is used:
326328

327-
| Package | Resulting Object |
328-
|---|---|
329-
| org.mybatis.dynamic.sql.util.kotlin.model | org.mybatis.dynamic.sql.insert.MultiRowInsertModel |
329+
| Package | Resulting Object |
330+
|----------------------------------------------|-----------------------------------------------------------------------------------------------|
331+
| org.mybatis.dynamic.sql.util.kotlin.model | org.mybatis.dynamic.sql.insert.MultiRowInsertModel |
330332
| org.mybatis.dynamic.sql.util.kotlin.mybatis3 | org.mybatis.dynamic.sql.insert.render.MultiRowInsertStatementProvider (rendered for MyBatis3) |
331-
| org.mybatis.dynamic.sql.util.kotlin.spring | org.mybatis.dynamic.sql.insert.render.MultiRowInsertStatementProvider (rendered for Spring) |
333+
| org.mybatis.dynamic.sql.util.kotlin.spring | org.mybatis.dynamic.sql.insert.render.MultiRowInsertStatementProvider (rendered for Spring) |
332334

333335
## Batch Insert Statement
334336

@@ -367,11 +369,11 @@ the documentation pages for those utilities.
367369

368370
This method creates models or providers depending on which package is used:
369371

370-
| Package | Resulting Object |
371-
|---|---|
372-
| org.mybatis.dynamic.sql.util.kotlin.model | org.mybatis.dynamic.sql.insert.BatchInsertModel |
372+
| Package | Resulting Object |
373+
|----------------------------------------------|---------------------------------------------------------------------------|
374+
| org.mybatis.dynamic.sql.util.kotlin.model | org.mybatis.dynamic.sql.insert.BatchInsertModel |
373375
| org.mybatis.dynamic.sql.util.kotlin.mybatis3 | org.mybatis.dynamic.sql.insert.render.BatchInsert (rendered for MyBatis3) |
374-
| org.mybatis.dynamic.sql.util.kotlin.spring | org.mybatis.dynamic.sql.insert.render.BatchInsert (rendered for Spring) |
376+
| org.mybatis.dynamic.sql.util.kotlin.spring | org.mybatis.dynamic.sql.insert.render.BatchInsert (rendered for Spring) |
375377

376378
## Insert Select Statement
377379

@@ -397,11 +399,11 @@ number of rows returned from the query.
397399

398400
This method creates models or providers depending on which package is used:
399401

400-
| Package | Resulting Object |
401-
|---|---|
402-
| org.mybatis.dynamic.sql.util.kotlin.model | org.mybatis.dynamic.sql.insert.InsertSelectModel |
402+
| Package | Resulting Object |
403+
|----------------------------------------------|---------------------------------------------------------------------------------------------|
404+
| org.mybatis.dynamic.sql.util.kotlin.model | org.mybatis.dynamic.sql.insert.InsertSelectModel |
403405
| org.mybatis.dynamic.sql.util.kotlin.mybatis3 | org.mybatis.dynamic.sql.insert.render.InsertSelectStatementProvider (rendered for MyBatis3) |
404-
| org.mybatis.dynamic.sql.util.kotlin.spring | org.mybatis.dynamic.sql.insert.render.InsertSelectStatementProvider (rendered for Spring) |
406+
| org.mybatis.dynamic.sql.util.kotlin.spring | org.mybatis.dynamic.sql.insert.render.InsertSelectStatementProvider (rendered for Spring) |
405407

406408
## Select Statement
407409

@@ -458,11 +460,52 @@ val selectStatement = selectDistinct(id, firstName, lastName, birthDate, employe
458460

459461
These methods create models or providers depending on which package is used:
460462

461-
| Package | Resulting Object |
462-
|---|---|
463-
| org.mybatis.dynamic.sql.util.kotlin.model | org.mybatis.dynamic.sql.select.SelectModel |
463+
| Package | Resulting Object |
464+
|----------------------------------------------|---------------------------------------------------------------------------------------|
465+
| org.mybatis.dynamic.sql.util.kotlin.model | org.mybatis.dynamic.sql.select.SelectModel |
464466
| org.mybatis.dynamic.sql.util.kotlin.mybatis3 | org.mybatis.dynamic.sql.select.render.SelectStatementProvider (rendered for MyBatis3) |
465-
| org.mybatis.dynamic.sql.util.kotlin.spring | org.mybatis.dynamic.sql.select.render.SelectStatementProvider (rendered for Spring) |
467+
| org.mybatis.dynamic.sql.util.kotlin.spring | org.mybatis.dynamic.sql.select.render.SelectStatementProvider (rendered for Spring) |
468+
469+
## Multi-Select Statement
470+
471+
A multi-select statement is a special case of a union query. In a multi-select statement, each select statement is
472+
wrapped with parentheses. This means that you can use "order by" and paging clauses on the select statements that are
473+
merged with a "union" or "union all" operator. You can also apply "order by" and paging clauses to the query as a whole.
474+
475+
The full DSL for multi-select statements looks like this:
476+
477+
```kotlin
478+
val selectStatement = multiSelect {
479+
selectDistinct(id, firstName, lastName, birthDate, employed, occupation, addressId) {
480+
from(person)
481+
where { id isLessThanOrEqualTo 2 }
482+
orderBy(id)
483+
limit(1)
484+
}
485+
unionAll {
486+
select(id, firstName, lastName, birthDate, employed, occupation, addressId) {
487+
from(person)
488+
where { id isGreaterThanOrEqualTo 4 }
489+
orderBy(id.descending())
490+
limit(1)
491+
}
492+
}
493+
orderBy(id)
494+
fetchFirst(1)
495+
offset(1)
496+
}
497+
```
498+
499+
Each nested select statement can be either "select" or "selectDistinct". They can be merged with either
500+
"union" or "unionAll". There is no limit to the number of statements that can be merged.
501+
502+
These methods create models or providers depending on which package is used:
503+
504+
| Package | Resulting Object |
505+
|----------------------------------------------|---------------------------------------------------------------------------------------|
506+
| org.mybatis.dynamic.sql.util.kotlin.model | org.mybatis.dynamic.sql.select.MultiSelectModel |
507+
| org.mybatis.dynamic.sql.util.kotlin.mybatis3 | org.mybatis.dynamic.sql.select.render.SelectStatementProvider (rendered for MyBatis3) |
508+
| org.mybatis.dynamic.sql.util.kotlin.spring | org.mybatis.dynamic.sql.select.render.SelectStatementProvider (rendered for Spring) |
466509

467510
## Update Statement
468511

@@ -482,8 +525,8 @@ If you omit the `where` clause, the statement will update every row in a table.
482525

483526
This method creates models or providers depending on which package is used:
484527

485-
| Package | Resulting Object |
486-
|---|---|
487-
| org.mybatis.dynamic.sql.util.kotlin.model | org.mybatis.dynamic.sql.update.UpdateModel |
528+
| Package | Resulting Object |
529+
|----------------------------------------------|---------------------------------------------------------------------------------------|
530+
| org.mybatis.dynamic.sql.util.kotlin.model | org.mybatis.dynamic.sql.update.UpdateModel |
488531
| org.mybatis.dynamic.sql.util.kotlin.mybatis3 | org.mybatis.dynamic.sql.update.render.UpdateStatementProvider (rendered for MyBatis3) |
489-
| org.mybatis.dynamic.sql.util.kotlin.spring | org.mybatis.dynamic.sql.update.render.UpdateStatementProvider (rendered for Spring) |
532+
| org.mybatis.dynamic.sql.util.kotlin.spring | org.mybatis.dynamic.sql.update.render.UpdateStatementProvider (rendered for Spring) |

‎src/site/markdown/docs/kotlinSpring.md

Lines changed: 10 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -24,13 +24,13 @@ For each operation, there are two different methods of executing SQL:
2424
1. The first method is a two-step method. With this method you build SQL provider objects as shown on the Kotlin
2525
overview page and then execute the generated SQL by passing the provider to an extension method
2626
on `NamedParameterJdbcTemplate`
27-
1. The second method is a one-step method that combines these operations into a single step
27+
2. The second method is a one-step method that combines these operations into a single step
2828

2929
We will illustrate both approaches below.
3030

3131
## Kotlin Dynamic SQL Support Objects
3232

33-
The pattern for the meta-model is the same as shown on the Kotlin overview page. We'll repeat it here to show some
33+
The pattern for the metamodel is the same as shown on the Kotlin overview page. We'll repeat it here to show some
3434
specifics for Spring.
3535

3636
```kotlin
@@ -580,6 +580,14 @@ val personRecord: List<PersonRecord> = template.selectDistinct(id, firstName, la
580580
}
581581
```
582582

583+
## Multi-Select Statement Support
584+
585+
Multi-select statements are a special case of select statement. All the above information about row mappers applies
586+
equally to multi-select statements.
587+
588+
The library does not provide a "one-step" shortcut for multi-select queries. You can execute a multi-select query
589+
with the two-step method using either the "selectList" or "selectOne" extension methods as shown above.
590+
583591
## Update Method Support
584592

585593
### Two-Step Method

0 commit comments

Comments
 (0)