Documentation

Author: jeffgbutler

CHANGELOG.md

@@ -18,6 +18,7 @@ If you have written your own set of functions to extend the library, you will no
 - Added the capability to specify a rendering strategy on a column to override the defaut rendering strategy for a statement. This will allow certain edge cases where a parameter marker needs to be formatted in a unique way (for example, "::jsonb" needs to be added to parameter markers for JSON fields in PostgreSQL) ([#200](https://github.com/mybatis/mybatis-dynamic-sql/issues/200))
 - Added the ability to write a function that will change the column data type ([#197](https://github.com/mybatis/mybatis-dynamic-sql/issues/197))
 - Added the `applyOperator` function to make it easy to use non-standard database operators in expressions ([#220](https://github.com/mybatis/mybatis-dynamic-sql/issues/220))
+- Added convenience methods for count(column) and count(distinct column)([#221](https://github.com/mybatis/mybatis-dynamic-sql/issues/221))
 
 ## Release 1.1.4 - November 23, 2019
 

src/site/markdown/docs/kotlinMyBatis3.md

@@ -80,7 +80,7 @@ A count query is a specialized select - it returns a single column - typically a
 
 Count method support enables the creation of methods that execute a count query allowing a user to specify a where clause at runtime, but abstracting away all other details.
 
-To use this support, we envision creating two methods - one standard mapper method, and one extension method. The first method is the standard MyBatis Dynamic SQL method that will execute a select:
+To use this support, we envision creating several methods - one standard mapper method, and other extension methods. The first method is the standard MyBatis Dynamic SQL method that will execute a select:
 
 ```kotlin
 @Mapper
@@ -90,14 +90,20 @@ interface PersonMapper {
 }
 ```
 
-This is a standard method for MyBatis Dynamic SQL that executes a query and returns a `Long`. The second method should be an extension maethod. It will reuse the abstract method and supply everything needed to build the select statement except the where clause:
+This is a standard method for MyBatis Dynamic SQL that executes a query and returns a `Long`. The other methods should be extension methods. They will reuse the abstract method and supply everything needed to build the select statement except the where clause:
 
 ```kotlin
-fun PersonMapper.count(completer: CountCompleter) =
+fun PersonMapper.count(completer: CountCompleter) = // count(*)
     countFrom(this::count, Person, completer)
+
+fun PersonMapper.count(column: BasicColumn, completer: CountCompleter) = // count(column)
+    count(this::count, column, Person, completer)
+
+fun PersonMapper.countDistinct(column: BasicColumn, completer: CountCompleter) = // count(distinct column)
+    countDistinct(this::count, column, Person, completer)
 ```
 
-This method shows the use of `CountCompleter` which is a Kotlin typealias for a function with a receiver that will allow a user to supply a where clause. This also shows use of the Kotlin `countFrom` method which is supplied by the library. That method will build and execute the select count statement with the supplied where clause. Clients can use the method as follows:
+These methods show the use of `CountCompleter` which is a Kotlin typealias for a function with a receiver that will allow a user to supply a where clause. This also shows use of the Kotlin `countFrom`, `count`, and `countDistinct` methods which are supplied by the library. Those methods will build and execute the select count statements with the supplied where clause. Clients can use the methods as follows:
 
 ```kotlin
 val rows = mapper.count {

src/site/markdown/docs/kotlinSpring.md

@@ -35,15 +35,34 @@ This object is a singleton containing the `SqlTable` and `SqlColumn` objects tha
 
 A count query is a specialized select - it returns a single column - typically a long - and supports joins and a where clause.
 
+The library supports three types of count statements:
+
+1. `count(*)` - counts the number of rows that match a where clause
+1. `count(column)` - counts the number of non-null column values that match a where clause
+1. `count(distinct column)` - counts the number of unique column values that match a where clause
+
 The DSL for count methods looks like this:
 
 ```kotlin
+    // count(*)
     val countStatement = countFrom(Person) {  // countStatement is a SelectStatementProvider
         where(id, isLessThan(4))
     }
+
+    // count(column)
+    val countStatement = countColumn(lastName).from(Person) {  // countStatement is a SelectStatementProvider
+        allRows()
+    }
+
+    // count(distinct column)
+    val countStatement = countDistinctColumn(lastName).from(Person) {  // countStatement is a SelectStatementProvider
+        allRows()
+    }
 ```
 
-This code creates a `SelectStatementProvider` that can be executed with an extension method for `NamedParameterJdbcTemplate` like this:
+Note the somewhat awkward method names `countColumn`, and `countDistinctColumn`. The methods are named this way to avoid a name collision with other methods in the `SqlBuilder`. This awkwardness can be avoided by using the one step method shown below.
+
+These methods create a `SelectStatementProvider` that can be executed with an extension method for `NamedParameterJdbcTemplate` like this:
 
 ```kotlin
     val template: NamedParameterJdbcTemplate = getTemplate() // not shown
@@ -56,6 +75,14 @@ This is the two step execution process. This can be combined into a single step
     val rows = template.countFrom(Person) {
         where(id, isLessThan(4))
     }
+
+    val rows = template.count(lastName).from(Person) {
+        where(id, isLessThan(4))
+    }
+
+    val rows = template.countDistinct(lastName).from(Person) {
+        where(id, isLessThan(4))
+    }
 ```
 
 There is also an extention method that can be used to count all rows in a table:

src/site/markdown/docs/mybatis3.md

@@ -9,22 +9,36 @@ With version 1.1.3, specialized interfaces and utilities were added that can fur
 
 The goal of count method support is to enable the creation of methods that execute a count query allowing a user to specify a where clause at runtime, but abstracting away all other details.
 
-To use this support, we envision creating two methods on a MyBatis mapper interface. The first method is the standard MyBatis Dynamic SQL method that will execute a select:
+To use this support, we envision creating several methods on a MyBatis mapper interface. The first method is the standard MyBatis Dynamic SQL method that will execute a select:
 
 ```java
 @SelectProvider(type=SqlProviderAdapter.class, method="select")
 long count(SelectStatementProvider selectStatement);
 ```
 
-This is a standard method for MyBatis Dynamic SQL that executes a query and returns a `long`. The second method will reuse this method and supply everything needed to build the select statement except the where clause:
+This is a standard method for MyBatis Dynamic SQL that executes a query and returns a `long`. The other methods will reuse this method and supply everything needed to build the select statement except the where clause. There are several varients of count queries that may be useful:
+
+1. `count(*)` - counts the number of rows that match a where clause
+1. `count(column)` - counts the number of non-null column values that match a where clause
+1. `count(distinct column)` - counts the number of unique column values that match a where clause
+
+Corresponding mapper methods are as follows:
 
 ```java
-default long count(CountDSLCompleter completer) {
+default long count(CountDSLCompleter completer) {  // count(*)
     return MyBatis3Utils.countFrom(this::count, person, completer);
 }
+
+default long count(BasicColumn column, CountDSLCompleter completer) { // count(column)
+    return MyBatis3Utils.count(this::count, column, person, completer);
+}
+
+default long countDistinct(BasicColumn column, CountDSLCompleter completer) { // count(distinct column)
+    return MyBatis3Utils.countDistinct(this::count, column, person, completer);
+}
 ```
 
-This method shows the use of `CountDSLCompleter` which is a specialization of a `java.util.Function` that will allow a user to supply a where clause. Clients can use the method as follows:
+These methods show the use of `CountDSLCompleter` which is a specialization of a `java.util.Function` that will allow a user to supply a where clause. Clients can use the method as follows:
 
 ```java
 long rows = mapper.count(c ->