Available in versions: Dev (3.18) | Latest (3.17) | 3.16 | 3.15 | 3.14 | 3.13 | 3.12 | 3.11 | 3.10 | 3.9 | 3.8

This documentation is for the unreleased development version of jOOQ. Click on the above version links to get this documentation for a supported version of jOOQ.

jOOQ: Referencing the Step types

Applies to ✅ Open Source Edition   ✅ Express Edition   ✅ Professional Edition   ✅ Enterprise Edition

By convention, all of jOOQ's DSL API consists of interfaces whose name ends in Step, such as org.jooq.SelectFromStep, which is the step in the DSL API where users can append the FROM clause.

When writing dynamic SQL queries, users may be tempted to reference these types explicitly, such as

SelectConditionStep<?> c =
create.select(T.A, T.B)
      .from(T)
      .where(T.C.eq(1));
 
if (something)
    c = c.and(T.D.eq(2));
 
Result<?> result = c.fetch();

With this user-code, it is possible to add predicates dynamically to a query. But there are caveats:

  • In jOOQ 3.x, the DSL API is mostly mutable, but this may change in the future. Code that assumes mutability might break.
  • The DSL API guarantees source compatibility of methods between minor versions, but not of types, as set out in this section of the manual. In order to evolve the DSL, it is sometimes necessary to replace the type hierarchy that implements the DSL. If you chain your method calls to look like actual SQL, you will not notice these changes (as the method calls remain compatible). But if you assign the Step types to local variables, or pass them around in your API, then that code might break.

It is much better to use one of the approaches mentioned in the section about dynamic SQL. Also, this blog post elaborates more in detail on the topic of creating optional SQL clauses.

Feedback

Do you have any feedback about this page? We'd love to hear it!

The jOOQ Logo