Multi Select Queries

CHANGELOG.md

@@ -35,6 +35,13 @@ functions in the Kotlin DSL still only apply to the where clause.
 
 The pull request for this change is ([#550](https://github.com/mybatis/mybatis-dynamic-sql/pull/550))
 
+### Multi-Select Queries
+
+A multi-select query is a special case of a union select statement. The difference is that it allows "order by" and
+paging clauses to be applied to the nested queries.
+
+The pull request for this change is ([#591](https://github.com/mybatis/mybatis-dynamic-sql/pull/591))
+
 ### Other Changes
 
 1. Added support for specifying "limit" and "order by" on the DELETE and UPDATE statements. Not all databases support

src/main/java/org/mybatis/dynamic/sql/SqlBuilder.java

@@ -30,6 +30,7 @@
 import org.mybatis.dynamic.sql.insert.MultiRowInsertDSL;
 import org.mybatis.dynamic.sql.select.ColumnSortSpecification;
 import org.mybatis.dynamic.sql.select.CountDSL;
+import org.mybatis.dynamic.sql.select.MultiSelectDSL;
 import org.mybatis.dynamic.sql.select.QueryExpressionDSL.FromGatherer;
 import org.mybatis.dynamic.sql.select.SelectDSL;
 import org.mybatis.dynamic.sql.select.SelectModel;
@@ -227,6 +228,10 @@ static FromGatherer<SelectModel> selectDistinct(Collection<BasicColumn> selectLi
         return SelectDSL.selectDistinct(selectList);
     }
 
+    static MultiSelectDSL multiSelect(Buildable<SelectModel> selectModelBuilder) {
+        return new MultiSelectDSL(selectModelBuilder);
+    }
+
     static UpdateDSL<UpdateModel> update(SqlTable table) {
         return UpdateDSL.update(table);
     }
@@ -496,8 +501,8 @@ static <T> Subtract<T> subtract(BindableColumn<T> firstColumn, BasicColumn secon
      * @param firstColumn first column
      * @param secondColumn second column
      * @param subsequentColumns subsequent columns
-     * @return a Concatenate instance
      * @param <T> type of column
+     * @return a Concatenate instance
      */
     static <T> Concatenate<T> concatenate(BindableColumn<T> firstColumn, BasicColumn secondColumn,
             BasicColumn... subsequentColumns) {
@@ -510,8 +515,8 @@ static <T> Concatenate<T> concatenate(BindableColumn<T> firstColumn, BasicColumn
      *
      * @param firstColumn first column
      * @param subsequentColumns subsequent columns
-     * @return a Concat instance
      * @param <T> type of column
+     * @return a Concat instance
      */
     static <T> Concat<T> concat(BindableColumn<T> firstColumn, BasicColumn... subsequentColumns) {
         return Concat.concat(firstColumn, subsequentColumns);

src/main/java/org/mybatis/dynamic/sql/select/MultiSelectDSL.java

@@ -0,0 +1,144 @@
+/*
+ *    Copyright 2016-2023 the original author or authors.
+ *
+ *    Licensed under the Apache License, Version 2.0 (the "License");
+ *    you may not use this file except in compliance with the License.
+ *    You may obtain a copy of the License at
+ *
+ *       https://www.apache.org/licenses/LICENSE-2.0
+ *
+ *    Unless required by applicable law or agreed to in writing, software
+ *    distributed under the License is distributed on an "AS IS" BASIS,
+ *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *    See the License for the specific language governing permissions and
+ *    limitations under the License.
+ */
+package org.mybatis.dynamic.sql.select;
+
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.Collection;
+import java.util.List;
+
+import org.jetbrains.annotations.NotNull;
+import org.mybatis.dynamic.sql.SortSpecification;
+import org.mybatis.dynamic.sql.common.OrderByModel;
+import org.mybatis.dynamic.sql.util.Buildable;
+
+public class MultiSelectDSL implements Buildable<MultiSelectModel> {
+    private final List<UnionQuery> unionQueries = new ArrayList<>();
+    private final SelectModel initialSelect;
+    private OrderByModel orderByModel;
+    private Long limit;
+    private Long offset;
+    private Long fetchFirstRows;
+
+    public MultiSelectDSL(Buildable<SelectModel> builder) {
+        initialSelect = builder.build();
+    }
+
+    public MultiSelectDSL union(Buildable<SelectModel> builder) {
+        unionQueries.add(new UnionQuery("union", builder.build())); //$NON-NLS-1$
+        return this;
+    }
+
+    public MultiSelectDSL unionAll(Buildable<SelectModel> builder) {
+        unionQueries.add(new UnionQuery("union all", builder.build())); //$NON-NLS-1$
+        return this;
+    }
+
+    public MultiSelectDSL orderBy(SortSpecification... columns) {
+        return orderBy(Arrays.asList(columns));
+    }
+
+    public MultiSelectDSL orderBy(Collection<SortSpecification> columns) {
+        orderByModel = OrderByModel.of(columns);
+        return this;
+    }
+
+    public LimitFinisher limit(long limit) {
+        this.limit = limit;
+        return new LimitFinisher();
+    }
+
+    public OffsetFirstFinisher offset(long offset) {
+        this.offset = offset;
+        return new OffsetFirstFinisher();
+    }
+
+    public FetchFirstFinisher fetchFirst(long fetchFirstRows) {
+        this.fetchFirstRows = fetchFirstRows;
+        return new FetchFirstFinisher();
+    }
+
+    @NotNull
+    @Override
+    public MultiSelectModel build() {
+        return new MultiSelectModel.Builder()
+                .withInitialSelect(initialSelect)
+                .withUnionQueries(unionQueries)
+                .withOrderByModel(orderByModel)
+                .withPagingModel(buildPagingModel())
+                .build();
+    }
+
+    private PagingModel buildPagingModel() {
+        if (limit == null && offset == null && fetchFirstRows == null) {
+            return null;
+        }
+
+        return new PagingModel.Builder()
+                .withLimit(limit)
+                .withOffset(offset)
+                .withFetchFirstRows(fetchFirstRows)
+                .build();
+    }
+
+    public class LimitFinisher implements Buildable<MultiSelectModel> {
+        public OffsetFinisher offset(long offset) {
+            MultiSelectDSL.this.offset(offset);
+            return new OffsetFinisher();
+        }
+
+        @NotNull
+        @Override
+        public MultiSelectModel build() {
+            return MultiSelectDSL.this.build();
+        }
+    }
+
+    public class OffsetFinisher implements Buildable<MultiSelectModel> {
+        @NotNull
+        @Override
+        public MultiSelectModel build() {
+            return MultiSelectDSL.this.build();
+        }
+    }
+
+    public class OffsetFirstFinisher implements Buildable<MultiSelectModel> {
+        public FetchFirstFinisher fetchFirst(long fetchFirstRows) {
+            MultiSelectDSL.this.fetchFirst(fetchFirstRows);
+            return new FetchFirstFinisher();
+        }
+
+        @NotNull
+        @Override
+        public MultiSelectModel build() {
+            return MultiSelectDSL.this.build();
+        }
+    }
+
+    public class FetchFirstFinisher {
+        public RowsOnlyFinisher rowsOnly() {
+            return new RowsOnlyFinisher();
+        }
+    }
+
+    public class RowsOnlyFinisher implements Buildable<MultiSelectModel> {
+        @NotNull
+        @Override
+        public MultiSelectModel build() {
+            return MultiSelectDSL.this.build();
+        }
+    }
+}

src/main/java/org/mybatis/dynamic/sql/select/MultiSelectModel.java

@@ -0,0 +1,104 @@
+/*
+ *    Copyright 2016-2023 the original author or authors.
+ *
+ *    Licensed under the Apache License, Version 2.0 (the "License");
+ *    you may not use this file except in compliance with the License.
+ *    You may obtain a copy of the License at
+ *
+ *       https://www.apache.org/licenses/LICENSE-2.0
+ *
+ *    Unless required by applicable law or agreed to in writing, software
+ *    distributed under the License is distributed on an "AS IS" BASIS,
+ *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *    See the License for the specific language governing permissions and
+ *    limitations under the License.
+ */
+package org.mybatis.dynamic.sql.select;
+
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Objects;
+import java.util.Optional;
+import java.util.function.Function;
+import java.util.stream.Stream;
+
+import org.jetbrains.annotations.NotNull;
+import org.mybatis.dynamic.sql.common.OrderByModel;
+import org.mybatis.dynamic.sql.exception.InvalidSqlException;
+import org.mybatis.dynamic.sql.render.RenderingStrategy;
+import org.mybatis.dynamic.sql.select.render.MultiSelectRenderer;
+import org.mybatis.dynamic.sql.select.render.SelectStatementProvider;
+import org.mybatis.dynamic.sql.util.Messages;
+
+public class MultiSelectModel {
+    private final SelectModel initialSelect;
+    private final List<UnionQuery> unionQueries;
+    private final OrderByModel orderByModel;
+    private final PagingModel pagingModel;
+
+    private MultiSelectModel(Builder builder) {
+        initialSelect = Objects.requireNonNull(builder.initialSelect);
+        unionQueries = builder.unionQueries;
+        orderByModel = builder.orderByModel;
+        pagingModel = builder.pagingModel;
+        if (unionQueries.isEmpty()) {
+            throw new InvalidSqlException(Messages.getString("ERROR.35")); //$NON-NLS-1$
+        }
+    }
+
+    public SelectModel initialSelect() {
+        return initialSelect;
+    }
+
+    public <R> Stream<R> mapUnionQueries(Function<UnionQuery, R> mapper) {
+        return unionQueries.stream().map(mapper);
+    }
+
+    public Optional<OrderByModel> orderByModel() {
+        return Optional.ofNullable(orderByModel);
+    }
+
+    public Optional<PagingModel> pagingModel() {
+        return Optional.ofNullable(pagingModel);
+    }
+
+    @NotNull
+    public SelectStatementProvider render(RenderingStrategy renderingStrategy) {
+        return new MultiSelectRenderer.Builder()
+                .withMultiSelectModel(this)
+                .withRenderingStrategy(renderingStrategy)
+                .build()
+                .render();
+    }
+
+    public static class Builder {
+        private SelectModel initialSelect;
+        private final List<UnionQuery> unionQueries = new ArrayList<>();
+        private OrderByModel orderByModel;
+        private PagingModel pagingModel;
+
+        public Builder withInitialSelect(SelectModel initialSelect) {
+            this.initialSelect = initialSelect;
+            return this;
+        }
+
+        public Builder withUnionQueries(List<UnionQuery> unionQueries) {
+            this.unionQueries.addAll(unionQueries);
+            return this;
+        }
+
+        public Builder withOrderByModel(OrderByModel orderByModel) {
+            this.orderByModel = orderByModel;
+            return this;
+        }
+
+        public Builder withPagingModel(PagingModel pagingModel) {
+            this.pagingModel = pagingModel;
+            return this;
+        }
+
+        public MultiSelectModel build() {
+            return new MultiSelectModel(this);
+        }
+    }
+}

src/main/java/org/mybatis/dynamic/sql/select/UnionQuery.java

@@ -0,0 +1,36 @@
+/*
+ *    Copyright 2016-2023 the original author or authors.
+ *
+ *    Licensed under the Apache License, Version 2.0 (the "License");
+ *    you may not use this file except in compliance with the License.
+ *    You may obtain a copy of the License at
+ *
+ *       https://www.apache.org/licenses/LICENSE-2.0
+ *
+ *    Unless required by applicable law or agreed to in writing, software
+ *    distributed under the License is distributed on an "AS IS" BASIS,
+ *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *    See the License for the specific language governing permissions and
+ *    limitations under the License.
+ */
+package org.mybatis.dynamic.sql.select;
+
+import java.util.Objects;
+
+public class UnionQuery {
+    private final String connector;
+    private final SelectModel selectModel;
+
+    public UnionQuery(String connector, SelectModel selectModel) {
+        this.connector = Objects.requireNonNull(connector);
+        this.selectModel = Objects.requireNonNull(selectModel);
+    }
+
+    public String connector() {
+        return connector;
+    }
+
+    public SelectModel selectModel() {
+        return selectModel;
+    }
+}