diff --git a/jOOQ-website/src/main/resources/manual-3.0.xml b/jOOQ-website/src/main/resources/manual-3.0.xml index b3ca7f5d5f..373da0a0d3 100644 --- a/jOOQ-website/src/main/resources/manual-3.0.xml +++ b/jOOQ-website/src/main/resources/manual-3.0.xml @@ -1124,7 +1124,7 @@ Result result = select.fetch();]]> * Add an Oracle-specific CONNECT BY clause to the query */ @Support({ SQLDialect.CUBRID, SQLDialect.ORACLE }) -SelectConnectByConditionStep connectBy(Condition condition);]]> +SelectConnectByConditionStep connectBy(Condition condition);]]>

jOOQ API methods which are not annotated with the annotation, or which are annotated with the Support annotation, but without any SQL dialects can be safely used in all SQL dialects. An example for this is the factory method: @@ -1133,7 +1133,7 @@ SelectConnectByConditionStep connectBy(Condition condition);]]> * Create a new DSL select statement. */ @Support -SelectSelectStep select(Field... fields);]]> +SelectSelectStep select(Field... fields);]]>

jOOQ's SQL clause simulation capabilities

@@ -2712,6 +2712,28 @@ create.insertInto(AUTHOR, AUTHOR.FIRST_NAME, AUTHOR.LAST_NAME)

The above row value expressions usages are completely typesafe.

+ +

UPDATE .. RETURNING

+

+ The Firebird and Postgres databases support a RETURNING clause on their UPDATE statements, similar as the RETURNING clause in . This is useful to fetch trigger-generated values in one go. An example is given here: +

+ + + + + + +

+ The UPDATE .. RETURNING clause is currently not simulated for other databases. Future versions might execute an additional to fetch results. +

@@ -2881,13 +2903,72 @@ create.select() .orderBy(b.TITLE);]]>

- As you can see in the above example, calling as() on generated tables returns an object of the same type as the table. This means that the resulting object can be used to dereference fields from the aliased table. This is quite powerful in terms of having your Java compiler check the syntax of your SQL statements. If you remove a column from a table, dereferencing that column from that table alias will cause compilation errors. + As you can see in the above example, calling as() on generated tables returns an object of the same type as the table. This means that the resulting object can be used to dereference fields from the aliased table. This is quite powerful in terms of having your Java compiler check the syntax of your SQL statements. If you remove a column from a table, dereferencing that column from that table alias will cause compilation errors.

Dereferencing columns from other table expressions

- TODO document this + Only few table expressions provide the SQL syntax typesafety as shown above, where generated tables are used. Most tables, however, expose their fields through field() methods:

+ + a = AUTHOR.as("a"); + +// Get fields from a: +Field id = a.field("ID"); +Field firstName = a.field("FIRST_NAME");]]> + +

Derived column lists

+

+ The SQL standard specifies how a table can be renamed / aliased in one go along with its columns. It references the term "derived column list" for the following syntax (as supported by Postgres, for instance): +

+ + + +

+ This feature is useful in various use-cases where column names are not known in advance (but the table's degree is!). An example for this are , or the : +

+ + + +

+ Only few databaes really support such a syntax, but fortunately, jOOQ can simulate it easily using UNION ALL and an empty dummy record specifying the new column names. The two statements are equivalent: +

+ + +

+ In jOOQ, you would simply specify a varargs list of column aliases as such: +

+ + @@ -2947,6 +3028,10 @@ Table naturalRightOuterJoin(TableLike)]]> +
+ The VALUES() table constructor +
+
Nested SELECTs @@ -4238,6 +4323,11 @@ public static RowN row(Object... values) { ... }]]>

The also supports a variant where row value expressions are updated, rather than single columns. See the relevant section for more details

+ +

Higher-degree row value expressions

+

+ jOOQ chose to explicitly support degrees up to {max-row-degree} to match Scala's typesafe tuple, function and product support. Unlike Scala, however, jOOQ also supports higher degrees without the additional typesafety. +

@@ -6039,6 +6129,11 @@ System.out.println("Published in: " + book.getPublishedIn());]]> T1 value1(); T2 value2(); }]]> + +

Higher-degree records

+

+ jOOQ chose to explicitly support degrees up to {max-row-degree} to match Scala's typesafe tuple, function and product support. Unlike Scala, however, jOOQ also supports higher degrees without the additional typesafety. +

@@ -6614,6 +6709,59 @@ for (BookRecord book : create.selectFrom(BOOK).fetch()) {

+ +
+ Interning data + +

+ SQL result tables are not optimal in terms of used memory as they are not designed to represent hierarchical data as produced by JOIN operations. Specifically, FOREIGN KEY values may repeat themselves unnecessarily: +

+ ++----+-----------+--------------+ +| ID | AUTHOR_ID | TITLE | ++----+-----------+--------------+ +| 1 | 1 | 1984 | +| 2 | 1 | Animal Farm | +| 3 | 2 | O Alquimista | +| 4 | 2 | Brida | ++----+-----------+--------------+ + +

+ Now, if you have millions of records with only few distinct values for AUTHOR_ID, you may not want to hold references to distinct (but equal) objects. This is specifically true for IDs of type or string representations thereof. jOOQ allows you to "intern" those values: +

+ + r1 = create.select(BOOK.ID, BOOK.AUTHOR_ID, BOOK.TITLE) + .from(BOOK) + .join(AUTHOR).on(BOOK.AUTHOR_ID.eq(AUTHOR.ID)) + .fetch() + .intern(BOOK.AUTHOR_ID); + +// Interning data while fetching +Result r1 = create.select(BOOK.ID, BOOK.AUTHOR_ID, BOOK.TITLE) + .from(BOOK) + .join(AUTHOR).on(BOOK.AUTHOR_ID.eq(AUTHOR.ID)) + .intern(BOOK.AUTHOR_ID) + .fetch();]]> + +

+ You can specify as many fields as you want for interning. The above has the following effect: +

+ +
    +
  • If the interned Field is of type , then is called upon each string
    • +
  • If the interned Field is of any other type, then the call is ignored
    • +
+ +

+ Future versions of jOOQ will implement interning of data for non-String data types by collecting values in , removing duplicate instances. +

+ +

+ Note, that jOOQ will not use interned data for identity comparisons: string1 == string2. Interning is used only to reduce the memory footprint of objects. +

+ +
@@ -7425,6 +7573,10 @@ for (BookRecord book : create.fetch(BOOK, BOOK.PUBLISHED_IN.equal(1948))) { +
+ Records' internal flags +
+
IDENTITY values @@ -7899,6 +8051,10 @@ public class PrettyPrinter extends DefaultExecuteListener {
+
+ Database meta data +
+
Logging @@ -9559,9 +9715,14 @@ Condition condition = BOOK.ID.equalAny(create.select(BOOK.ID).from(BOOK)); QuantifiedSelect> subselect = any(select(BOOK.ID).from(BOOK)); Condition condition = BOOK.ID.equal(subselect);]]> +

FieldProvider

+

+ The FieldProvider marker interface was removed. Its methods still exist on FieldProvider subtypes. Note, they have changed names from getField() to field() and from getIndex() to indexOf() +

+

GroupField

- GroupField has been introduced as a DSL marker interface to denote fields that can be passed to GROUP BY clauses. This includes all org.jooq.Field types. However, fields obtained from ROLLUP(), CUBE(), and GROUPING SETS() functions no longer implement Field. Instead, they only implement GroupField. An example: + GroupField has been introduced as a DSL marker interface to denote fields that can be passed to GROUP BY clauses. This includes all org.jooq.Field types. However, fields obtained from ROLLUP(), CUBE(), and GROUPING SETS() functions no longer implement Field. Instead, they only implement GroupField. An example: