[#1410] Add support for the Postgres "DISTINCT ON" clause

jOOQ-test/src/test/java/org/jooq/test/PostgresTest.java

@@ -1388,4 +1388,25 @@ public class PostgresTest extends jOOQAbstractTest<
         assertEquals(4, (int) record.value3());
         assertEquals(2, (int) record.value4());
     }
+
+    @Test
+    public void testPostgresDistinctOnTest() {
+        Result<Record2<Integer, Integer>> r1 =
+        create().selectDistinct(T_BOOK.ID, T_BOOK.AUTHOR_ID)
+                .on(T_BOOK.AUTHOR_ID)
+                .from(T_BOOK)
+                .orderBy(T_BOOK.AUTHOR_ID)
+                .fetch();
+
+        Result<Record2<Integer, Integer>> r2 =
+        create().select(T_BOOK.ID, T_BOOK.AUTHOR_ID)
+                .distinctOn(T_BOOK.AUTHOR_ID)
+                .from(T_BOOK)
+                .orderBy(T_BOOK.AUTHOR_ID)
+                .fetch();
+
+        assertEquals(r1, r2);
+        assertEquals(asList(1, 3), r1.getValues(T_BOOK.ID));
+        assertEquals(asList(1, 2), r1.getValues(T_BOOK.AUTHOR_ID));
+    }
 }

jOOQ/src/main/java/org/jooq/SelectDistinctOnStep.java

@@ -0,0 +1,124 @@
+/**
+ * Copyright (c) 2009-2014, Data Geekery GmbH (http://www.datageekery.com)
+ * All rights reserved.
+ *
+ * This work is dual-licensed
+ * - under the Apache Software License 2.0 (the "ASL")
+ * - under the jOOQ License and Maintenance Agreement (the "jOOQ License")
+ * =============================================================================
+ * You may choose which license applies to you:
+ *
+ * - If you're using this work with Open Source databases, you may choose
+ *   either ASL or jOOQ License.
+ * - If you're using this work with at least one commercial database, you must
+ *   choose jOOQ License
+ *
+ * For more information, please visit http://www.jooq.org/licenses
+ *
+ * Apache Software License 2.0:
+ * -----------------------------------------------------------------------------
+ * 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
+ *
+ *  http://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.
+ *
+ * jOOQ License and Maintenance Agreement:
+ * -----------------------------------------------------------------------------
+ * Data Geekery grants the Customer the non-exclusive, timely limited and
+ * non-transferable license to install and use the Software under the terms of
+ * the jOOQ License and Maintenance Agreement.
+ *
+ * This library is distributed with a LIMITED WARRANTY. See the jOOQ License
+ * and Maintenance Agreement for more details: http://www.jooq.org/licensing
+ */
+package org.jooq;
+
+import static org.jooq.SQLDialect.POSTGRES;
+
+import java.util.Collection;
+
+/**
+ * This type is used for the {@link Select}'s DSL API when selecting generic
+ * {@link Record} types.
+ * <p>
+ * Example: <code><pre>
+ * -- get all authors' first and last names, and the number
+ * -- of books they've written in German, if they have written
+ * -- more than five books in German in the last three years
+ * -- (from 2011), and sort those authors by last names
+ * -- limiting results to the second and third row
+ *
+ *   SELECT T_AUTHOR.FIRST_NAME, T_AUTHOR.LAST_NAME, COUNT(*)
+ *     FROM T_AUTHOR
+ *     JOIN T_BOOK ON T_AUTHOR.ID = T_BOOK.AUTHOR_ID
+ *    WHERE T_BOOK.LANGUAGE = 'DE'
+ *      AND T_BOOK.PUBLISHED > '2008-01-01'
+ * GROUP BY T_AUTHOR.FIRST_NAME, T_AUTHOR.LAST_NAME
+ *   HAVING COUNT(*) > 5
+ * ORDER BY T_AUTHOR.LAST_NAME ASC NULLS FIRST
+ *    LIMIT 2
+ *   OFFSET 1
+ *      FOR UPDATE
+ *       OF FIRST_NAME, LAST_NAME
+ *       NO WAIT
+ * </pre></code> Its equivalent in jOOQ <code><pre>
+ * create.select(TAuthor.FIRST_NAME, TAuthor.LAST_NAME, create.count())
+ *       .from(T_AUTHOR)
+ *       .join(T_BOOK).on(TBook.AUTHOR_ID.equal(TAuthor.ID))
+ *       .where(TBook.LANGUAGE.equal("DE"))
+ *       .and(TBook.PUBLISHED.greaterThan(parseDate('2008-01-01')))
+ *       .groupBy(TAuthor.FIRST_NAME, TAuthor.LAST_NAME)
+ *       .having(create.count().greaterThan(5))
+ *       .orderBy(TAuthor.LAST_NAME.asc().nullsFirst())
+ *       .limit(2)
+ *       .offset(1)
+ *       .forUpdate()
+ *       .of(TAuthor.FIRST_NAME, TAuthor.LAST_NAME)
+ *       .noWait();
+ * </pre></code> Refer to the manual for more details
+ *
+ * @author Lukas Eder
+ */
+public interface SelectDistinctOnStep<R extends Record> extends SelectIntoStep<R> {
+
+    /**
+     * Add the PostgreSQL-specific <code>ON(...)</code> clause to a
+     * <code>SELECT DISTINCT ON (...)</code> statement.
+     * <p>
+     * This implicitly enforces the <code>DISTINCT</code> clause, no matter if
+     * it is added explicitly via the jOOQ API.
+     */
+    @Support({ POSTGRES })
+    SelectIntoStep<R> on(Field<?>... fields);
+
+    /**
+     * Add the PostgreSQL-specific <code>ON(...)</code> clause to a
+     * <code>SELECT DISTINCT ON (...)</code> statement.
+     * <p>
+     * This implicitly enforces the <code>DISTINCT</code> clause, no matter if
+     * it is added explicitly via the jOOQ API.
+     */
+    @Support({ POSTGRES })
+    SelectIntoStep<R> on(Collection<? extends Field<?>> fields);
+
+    /**
+     * Add the PostgreSQL-specific <code>ON(...)</code> clause to a
+     * <code>SELECT DISTINCT ON (...)</code> statement.
+     */
+    @Support({ POSTGRES })
+    SelectIntoStep<R> distinctOn(Field<?>... fields);
+
+    /**
+     * Add the PostgreSQL-specific <code>ON(...)</code> clause to a
+     * <code>SELECT DISTINCT ON (...)</code> statement.
+     */
+    @Support({ POSTGRES })
+    SelectIntoStep<R> distinctOn(Collection<? extends Field<?>> fields);
+}

jOOQ/src/main/java/org/jooq/SelectQuery.java

@@ -95,6 +95,22 @@ public interface SelectQuery<R extends Record> extends Select<R>, ConditionProvi
     @Support
     void setDistinct(boolean distinct);
 
+    /**
+     * Add a PostgreSQL-specific <code>DISTINCT ON (fields...)</code> clause.
+     * <p>
+     * This also sets the <code>distinct</code> flag to <code>true</code>
+     */
+    @Support({ POSTGRES })
+    void addDistinctOn(Field<?>... fields);
+
+    /**
+     * Add a PostgreSQL-specific <code>DISTINCT ON (fields...)</code> clause.
+     * <p>
+     * This also sets the <code>distinct</code> flag to <code>true</code>
+     */
+    @Support({ POSTGRES })
+    void addDistinctOn(Collection<? extends Field<?>> fields);
+
     /**
      * Add <code>INTO</code> clause to the <code>SELECT</code> statement.
      */

jOOQ/src/main/java/org/jooq/SelectSelectStep.java

@@ -85,7 +85,7 @@ import java.util.Collection;
  *
  * @author Lukas Eder
  */
-public interface SelectSelectStep<R extends Record> extends SelectIntoStep<R> {
+public interface SelectSelectStep<R extends Record> extends SelectDistinctOnStep<R> {
 
     /**
      * Add additional fields to the <code>SELECT</code> clause of this query

jOOQ/src/main/java/org/jooq/impl/SelectImpl.java

@@ -77,6 +77,7 @@ import org.jooq.SelectConditionStep;
 import org.jooq.SelectConnectByConditionStep;
 import org.jooq.SelectForUpdateOfStep;
 import org.jooq.SelectHavingConditionStep;
+import org.jooq.SelectIntoStep;
 import org.jooq.SelectJoinStep;
 import org.jooq.SelectOffsetStep;
 import org.jooq.SelectOnConditionStep;
@@ -240,6 +241,28 @@ class SelectImpl<R extends Record, T1, T2, T3, T4, T5, T6, T7, T8, T9, T10, T11,
         return this;
     }
 
+    @Override
+    public final SelectIntoStep<R> on(Field<?>... fields) {
+        return distinctOn(Arrays.asList(fields));
+    }
+
+    @Override
+    public final SelectIntoStep<R> on(Collection<? extends Field<?>> fields) {
+        return distinctOn(fields);
+    }
+
+    @Override
+    public final SelectIntoStep<R> distinctOn(Field<?>... fields) {
+        getQuery().addDistinctOn(fields);
+        return this;
+    }
+
+    @Override
+    public final SelectIntoStep<R> distinctOn(Collection<? extends Field<?>> fields) {
+        getQuery().addDistinctOn(fields);
+        return this;
+    }
+
     @Override
     public final SelectImpl into(Table<?> table) {
         getQuery().setInto(table);

jOOQ/src/main/java/org/jooq/impl/SelectQueryImpl.java

@@ -139,6 +139,7 @@ class SelectQueryImpl<R extends Record> extends AbstractSelect<R> implements Sel
     private String                          hint;
     private String                          option;
     private boolean                         distinct;
+    private final QueryPartList<Field<?>>   distinctOn;
     private boolean                         forUpdate;
     private final QueryPartList<Field<?>>   forUpdateOf;
     private final TableList                 forUpdateOfTables;
@@ -177,6 +178,7 @@ class SelectQueryImpl<R extends Record> extends AbstractSelect<R> implements Sel
 
         this.with = with;
         this.distinct = distinct;
+        this.distinctOn = new QueryPartList<Field<?>>();
         this.select = new SelectFieldList();
         this.from = new TableList();
         this.condition = new ConditionProviderImpl();
@@ -620,7 +622,10 @@ class SelectQueryImpl<R extends Record> extends AbstractSelect<R> implements Sel
         x
         xx [/pro] */
 
-        if (distinct) {
+        if (!distinctOn.isEmpty()) {
+            context.keyword("distinct on").sql(" (").visit(distinctOn).sql(") ");
+        }
+        else if (distinct) {
             context.keyword("distinct").sql(" ");
         }
 
@@ -925,6 +930,16 @@ class SelectQueryImpl<R extends Record> extends AbstractSelect<R> implements Sel
         this.distinct = distinct;
     }
 
+    @Override
+    public final void addDistinctOn(Field<?>... fields) {
+        addDistinctOn(Arrays.asList(fields));
+    }
+
+    @Override
+    public final void addDistinctOn(Collection<? extends Field<?>> fields) {
+        this.distinctOn.addAll(fields);
+    }
+
     @Override
     public final void setInto(Table<?> into) {
         this.into = into;