Module org.jooq

Package org.jooq

Interface Query

All Superinterfaces:

Attachable, AutoCloseable, QueryPart, Serializable, Statement

All Known Subinterfaces:

AlterDatabaseFinalStep, AlterDomainDropConstraintCascadeStep, AlterDomainFinalStep, AlterIndexFinalStep, AlterSchemaFinalStep, AlterSequenceFinalStep, AlterSequenceFlagsStep, AlterSequenceStep<T>, AlterTableAddStep, AlterTableDropStep, AlterTableFinalStep, AlterTableUsingIndexStep, AlterTypeFinalStep, AlterViewFinalStep, Block, CommentOnFinalStep, CreateDatabaseFinalStep, CreateDomainConstraintStep, CreateDomainDefaultStep<T>, CreateDomainFinalStep, CreateIndexFinalStep, CreateIndexIncludeStep, CreateIndexWhereStep, CreateSchemaFinalStep, CreateSequenceFinalStep, CreateSequenceFlagsStep, CreateTableColumnStep, CreateTableCommentStep, CreateTableConstraintStep, CreateTableFinalStep, CreateTableIndexStep, CreateTableOnCommitStep, CreateTableStorageStep, CreateTableWithDataStep, CreateTypeFinalStep, CreateViewFinalStep, DDLQuery, Delete<R>, DeleteConditionStep<R>, DeleteFinalStep<R>, DeleteLimitStep<R>, DeleteOrderByStep<R>, DeleteQuery<R>, DeleteResultStep<R>, DeleteReturningStep<R>, DeleteUsingStep<R>, DeleteWhereStep<R>, DropDatabaseFinalStep, DropDomainCascadeStep, DropDomainFinalStep, DropIndexCascadeStep, DropIndexFinalStep, DropIndexOnStep, DropSchemaFinalStep, DropSchemaStep, DropSequenceFinalStep, DropTableFinalStep, DropTableStep, DropTypeFinalStep, DropTypeStep, DropViewFinalStep, GrantFinalStep, GrantWithGrantOptionStep, Insert<R>, InsertFinalStep<R>, InsertOnConflictConditionStep<R>, InsertOnConflictWhereStep<R>, InsertOnDuplicateSetMoreStep<R>, InsertOnDuplicateStep<R>, InsertQuery<R>, InsertResultStep<R>, InsertReturningStep<R>, InsertSetMoreStep<R>, InsertValuesStep1<R,T1>, InsertValuesStep10<R,T1,T2,T3,T4,T5,T6,T7,T8,T9,T10>, InsertValuesStep11<R,T1,T2,T3,T4,T5,T6,T7,T8,T9,T10,T11>, InsertValuesStep12<R,T1,T2,T3,T4,T5,T6,T7,T8,T9,T10,T11,T12>, InsertValuesStep13<R,T1,T2,T3,T4,T5,T6,T7,T8,T9,T10,T11,T12,T13>, InsertValuesStep14<R,T1,T2,T3,T4,T5,T6,T7,T8,T9,T10,T11,T12,T13,T14>, InsertValuesStep15<R,T1,T2,T3,T4,T5,T6,T7,T8,T9,T10,T11,T12,T13,T14,T15>, InsertValuesStep16<R,T1,T2,T3,T4,T5,T6,T7,T8,T9,T10,T11,T12,T13,T14,T15,T16>, InsertValuesStep17<R,T1,T2,T3,T4,T5,T6,T7,T8,T9,T10,T11,T12,T13,T14,T15,T16,T17>, InsertValuesStep18<R,T1,T2,T3,T4,T5,T6,T7,T8,T9,T10,T11,T12,T13,T14,T15,T16,T17,T18>, InsertValuesStep19<R,T1,T2,T3,T4,T5,T6,T7,T8,T9,T10,T11,T12,T13,T14,T15,T16,T17,T18,T19>, InsertValuesStep2<R,T1,T2>, InsertValuesStep20<R,T1,T2,T3,T4,T5,T6,T7,T8,T9,T10,T11,T12,T13,T14,T15,T16,T17,T18,T19,T20>, InsertValuesStep21<R,T1,T2,T3,T4,T5,T6,T7,T8,T9,T10,T11,T12,T13,T14,T15,T16,T17,T18,T19,T20,T21>, InsertValuesStep22<R,T1,T2,T3,T4,T5,T6,T7,T8,T9,T10,T11,T12,T13,T14,T15,T16,T17,T18,T19,T20,T21,T22>, InsertValuesStep3<R,T1,T2,T3>, InsertValuesStep4<R,T1,T2,T3,T4>, InsertValuesStep5<R,T1,T2,T3,T4,T5>, InsertValuesStep6<R,T1,T2,T3,T4,T5,T6>, InsertValuesStep7<R,T1,T2,T3,T4,T5,T6,T7>, InsertValuesStep8<R,T1,T2,T3,T4,T5,T6,T7,T8>, InsertValuesStep9<R,T1,T2,T3,T4,T5,T6,T7,T8,T9>, InsertValuesStepN<R>, Merge<R>, MergeFinalStep<R>, MergeMatchedDeleteStep<R>, MergeMatchedSetMoreStep<R>, MergeMatchedStep<R>, MergeMatchedWhereStep<R>, MergeNotMatchedSetMoreStep<R>, MergeNotMatchedStep<R>, MergeNotMatchedWhereStep<R>, MergeOnConditionStep<R>, ResultQuery<R>, RevokeFinalStep, RowCountQuery, Select<R>, SelectConditionStep<R>, SelectConnectByAfterStartWithConditionStep<R>, SelectConnectByConditionStep<R>, SelectConnectByStep<R>, SelectCorrelatedSubqueryStep<R>, SelectDistinctOnStep<R>, SelectFinalStep<R>, SelectForJSONCommonDirectivesStep<R>, SelectForStep<R>, SelectForUpdateOfStep<R>, SelectForUpdateStep<R>, SelectForUpdateWaitStep<R>, SelectForXMLCommonDirectivesStep<R>, SelectForXMLPathDirectivesStep<R>, SelectForXMLRawDirectivesStep<R>, SelectFromStep<R>, SelectGroupByStep<R>, SelectHavingConditionStep<R>, SelectHavingStep<R>, SelectIntoStep<R>, SelectJoinStep<R>, SelectLimitAfterOffsetStep<R>, SelectLimitPercentAfterOffsetStep<R>, SelectLimitPercentStep<R>, SelectLimitStep<R>, SelectOffsetStep<R>, SelectOnConditionStep<R>, SelectOptionalOnStep<R>, SelectOptionStep<R>, SelectOrderByStep<R>, SelectQualifyConditionStep<R>, SelectQualifyStep<R>, SelectQuery<R>, SelectSeekLimitStep<R>, SelectSeekStep1<R,T1>, SelectSeekStep10<R,T1,T2,T3,T4,T5,T6,T7,T8,T9,T10>, SelectSeekStep11<R,T1,T2,T3,T4,T5,T6,T7,T8,T9,T10,T11>, SelectSeekStep12<R,T1,T2,T3,T4,T5,T6,T7,T8,T9,T10,T11,T12>, SelectSeekStep13<R,T1,T2,T3,T4,T5,T6,T7,T8,T9,T10,T11,T12,T13>, SelectSeekStep14<R,T1,T2,T3,T4,T5,T6,T7,T8,T9,T10,T11,T12,T13,T14>, SelectSeekStep15<R,T1,T2,T3,T4,T5,T6,T7,T8,T9,T10,T11,T12,T13,T14,T15>, SelectSeekStep16<R,T1,T2,T3,T4,T5,T6,T7,T8,T9,T10,T11,T12,T13,T14,T15,T16>, SelectSeekStep17<R,T1,T2,T3,T4,T5,T6,T7,T8,T9,T10,T11,T12,T13,T14,T15,T16,T17>, SelectSeekStep18<R,T1,T2,T3,T4,T5,T6,T7,T8,T9,T10,T11,T12,T13,T14,T15,T16,T17,T18>, SelectSeekStep19<R,T1,T2,T3,T4,T5,T6,T7,T8,T9,T10,T11,T12,T13,T14,T15,T16,T17,T18,T19>, SelectSeekStep2<R,T1,T2>, SelectSeekStep20<R,T1,T2,T3,T4,T5,T6,T7,T8,T9,T10,T11,T12,T13,T14,T15,T16,T17,T18,T19,T20>, SelectSeekStep21<R,T1,T2,T3,T4,T5,T6,T7,T8,T9,T10,T11,T12,T13,T14,T15,T16,T17,T18,T19,T20,T21>, SelectSeekStep22<R,T1,T2,T3,T4,T5,T6,T7,T8,T9,T10,T11,T12,T13,T14,T15,T16,T17,T18,T19,T20,T21,T22>, SelectSeekStep3<R,T1,T2,T3>, SelectSeekStep4<R,T1,T2,T3,T4>, SelectSeekStep5<R,T1,T2,T3,T4,T5>, SelectSeekStep6<R,T1,T2,T3,T4,T5,T6>, SelectSeekStep7<R,T1,T2,T3,T4,T5,T6,T7>, SelectSeekStep8<R,T1,T2,T3,T4,T5,T6,T7,T8>, SelectSeekStep9<R,T1,T2,T3,T4,T5,T6,T7,T8,T9>, SelectSeekStepN<R>, SelectSelectStep<R>, SelectStartWithStep<R>, SelectUnionStep<R>, SelectWhereStep<R>, SelectWindowStep<R>, SelectWithTiesAfterOffsetStep<R>, SelectWithTiesStep<R>, StoreQuery<R>, Truncate<R>, TruncateCascadeStep<R>, TruncateFinalStep<R>, TruncateIdentityStep<R>, Update<R>, UpdateConditionStep<R>, UpdateFinalStep<R>, UpdateFromStep<R>, UpdateLimitStep<R>, UpdateOrderByStep<R>, UpdateQuery<R>, UpdateResultStep<R>, UpdateReturningStep<R>, UpdateSetMoreStep<R>, UpdateWhereStep<R>

public interface Query
extends Statement, Attachable, AutoCloseable

Any query.

Instances can be created using DSL.query(String) and overloads, or by creating a subtype.

Author:

Lukas Eder

Method Summary

Modifier and Type	Method	Description
@NotNull Query	bind(int index, Object value)	Bind a new value to an indexed parameter.
@NotNull Query	bind(String param, Object value)	Bind a new value to a named parameter.
void	cancel()	Cancel the underlying statement.
void	close()	Close the underlying statement.
int	execute()	Execute the query, if it has been created with a proper configuration.
@NotNull CompletionStage<Integer>	executeAsync()	Execute the query in a new CompletionStage.
@NotNull CompletionStage<Integer>	executeAsync(Executor executor)	Execute the query in a new CompletionStage that is asynchronously completed by a task running in the given executor.
@NotNull List<Object>	getBindValues()	Retrieve the bind values that will be bound by this Query.
@Nullable Param<?>	getParam(String name)	Get a named parameter from the Query, provided its name.
@NotNull Map<String,Param<?>>	getParams()	Get a Map of named parameters.
@NotNull String	getSQL()	Retrieve the SQL code rendered by this Query.
@NotNull String	getSQL(boolean inline)	Deprecated. - [#2414] - 3.1.0 - Use getSQL(ParamType) instead
@NotNull String	getSQL(ParamType paramType)	Retrieve the SQL code rendered by this Query.
boolean	isExecutable()	Whether this query is executable in its current state.
@NotNull Query	keepStatement(boolean keepStatement)	Keep the query's underlying statement open after execution.
@NotNull Query	poolable(boolean poolable)	Specify whether any JDBC Statement created by this query should be Statement.setPoolable(boolean).
@NotNull Query	queryTimeout(int seconds)	Specify the query timeout in number of seconds for the underlying JDBC Statement.

Methods inherited from interface org.jooq.Attachable

attach, configuration, detach

Methods inherited from interface org.jooq.QueryPart

equals, hashCode, toString

Method Detail

execute

int execute()
     throws DataAccessException

Execute the query, if it has been created with a proper configuration.

Returns:

A result value, depending on the concrete implementation of Query:

• Delete : the number of deleted records
• Insert : the number of inserted records
• Merge : the result may have no meaning
• Select : the number of resulting records
• Truncate : the result may have no meaning
• Update : the number of updated records

Throws:

DataAccessException - If anything goes wrong in the database

executeAsync

@NotNull
@NotNull CompletionStage<Integer> executeAsync()

Execute the query in a new CompletionStage.

The result is asynchronously completed by a task running in an Executor provided by the underlying Configuration.executorProvider().

Returns:

A result value, depending on the concrete implementation of Query:

• Delete : the number of deleted records
• Insert : the number of inserted records
• Merge : the result may have no meaning
• Select : the number of resulting records
• Truncate : the result may have no meaning
• Update : the number of updated records

executeAsync

@NotNull
@NotNull CompletionStage<Integer> executeAsync(Executor executor)

Execute the query in a new CompletionStage that is asynchronously completed by a task running in the given executor.

Returns:

A result value, depending on the concrete implementation of Query:

• Delete : the number of deleted records
• Insert : the number of inserted records
• Merge : the result may have no meaning
• Select : the number of resulting records
• Truncate : the result may have no meaning
• Update : the number of updated records

isExecutable

boolean isExecutable()

Whether this query is executable in its current state.

DML queries may be incomplete in structure and thus not executable. Calling execute() on such queries has no effect, but beware that getSQL() may not render valid SQL!

getSQL

@NotNull
@NotNull String getSQL()

Retrieve the SQL code rendered by this Query.

Use this method, when you want to use jOOQ for object oriented query creation, but execute the query with some other technology, such as

• JDBC
• Spring Templates
• JPA native queries
• etc...

Note, this is the same as calling getSQL(boolean). The boolean parameter will depend on your DSLContext's Settings:

StatementType	boolean parameter	effect
StatementType.PREPARED_STATEMENT	false (default)	This will render bind variables to be used with a JDBC PreparedStatement. You can extract bind values from this Query using getBindValues()
StatementType.STATIC_STATEMENT	true	This will inline all bind variables in a statement to be used with a JDBC Statement

[#1520] Note that the query actually being executed might not contain any bind variables, in case the number of bind variables exceeds your SQL dialect's maximum number of supported bind variables. This is not reflected by this method, which will only use the Settings to decide whether to render bind values.

See Also:

getSQL(boolean)

getSQL

@NotNull
@Deprecated
@NotNull String getSQL(boolean inline)

Deprecated.

- [#2414] - 3.1.0 - Use getSQL(ParamType) instead

Retrieve the SQL code rendered by this Query.

[#1520] Note that the query actually being executed might not contain any bind variables, in case the number of bind variables exceeds your SQL dialect's maximum number of supported bind variables. This is not reflected by this method, which will only use inline argument to decide whether to render bind values.

See getSQL() for more details.

Parameters:

inline - Whether to inline bind variables. This overrides values in Settings.getStatementType()

Returns:

The generated SQL

getSQL

@NotNull
@NotNull String getSQL(ParamType paramType)

Retrieve the SQL code rendered by this Query.

[#1520] Note that the query actually being executed might not contain any bind variables, in case the number of bind variables exceeds your SQL dialect's maximum number of supported bind variables. This is not reflected by this method, which will only use paramType argument to decide whether to render bind values.

See getSQL() for more details.

Parameters:

paramType - How to render parameters. This overrides values in Settings.getStatementType()

Returns:

The generated SQL

getBindValues

@NotNull
@NotNull List<Object> getBindValues()

Retrieve the bind values that will be bound by this Query. This List cannot be modified. To modify bind values, use getParams() instead.

Unlike getParams(), which returns also inlined parameters, this returns only actual bind values that will render an actual bind value as a question mark "?"

See Also:

DSLContext.extractBindValues(QueryPart)

getParams

@NotNull
@NotNull Map<String,Param<?>> getParams()

Get a Map of named parameters. The Map itself cannot be modified, but the Param elements allow for modifying bind values on an existing Query.

Bind values created with DSL.val(Object) will have their bind index as name.

See Also:

Param, DSL.param(String, Object), DSLContext.extractParams(QueryPart)

getParam

@Nullable
@Nullable Param<?> getParam(String name)

Get a named parameter from the Query, provided its name.

Bind values created with DSL.val(Object) will have their bind index as name.

See Also:

Param, DSL.param(String, Object), DSLContext.extractParam(QueryPart, String)

bind

@NotNull
@NotNull Query bind(String param,
                    Object value)
             throws IllegalArgumentException,
                    DataTypeException

Bind a new value to a named parameter.

[#1886] If the bind value with name param is inlined ( Param.isInline()) or if this query was created with StatementType.STATIC_STATEMENT and there is an underlying PreparedStatement kept open because of keepStatement(boolean), the underlying PreparedStatement will be closed automatically in order for new bind values to have an effect.

Parameters:

param - The named parameter name. If this is a number, then this is the same as calling bind(int, Object)

value - The new bind value.

Throws:

IllegalArgumentException - if there is no parameter by the given parameter name or index.

DataTypeException - if value cannot be converted into the parameter's data type

bind

@NotNull
@NotNull Query bind(int index,
                    Object value)
             throws IllegalArgumentException,
                    DataTypeException

Bind a new value to an indexed parameter.

[#1886] If the bind value at index is inlined ( Param.isInline()) or if this query was created with StatementType.STATIC_STATEMENT and there is an underlying PreparedStatement kept open because of keepStatement(boolean), the underlying PreparedStatement will be closed automatically in order for new bind values to have an effect.

Parameters:

index - The parameter index, starting with 1

value - The new bind value.

Throws:

IllegalArgumentException - if there is no parameter by the given parameter index.

DataTypeException - if value cannot be converted into the parameter's data type

poolable

@NotNull
@NotNull Query poolable(boolean poolable)

Specify whether any JDBC Statement created by this query should be Statement.setPoolable(boolean).

If this method is not called on jOOQ types, then jOOQ will not specify the flag on JDBC either, resulting in JDBC's default behaviour.

See Also:

Statement.setPoolable(boolean)

queryTimeout

@NotNull
@NotNull Query queryTimeout(int seconds)

Specify the query timeout in number of seconds for the underlying JDBC Statement.

See Also:

Statement.setQueryTimeout(int)

keepStatement

@NotNull
@NotNull Query keepStatement(boolean keepStatement)

Keep the query's underlying statement open after execution.

This indicates to jOOQ that the query's underlying Statement or PreparedStatement should be kept open after execution. If it is kept open, client code is responsible for properly closing it using close()

Parameters:

keepStatement - Whether to keep the underlying statement open

close

void close()
    throws DataAccessException

Close the underlying statement.

This closes the query's underlying Statement or PreparedStatement if a previous call to keepStatement(boolean) indicated that jOOQ should keep statements open after query execution. If there is no underlying open statement, this call is simply ignored.

Specified by:

close in interface AutoCloseable

Throws:

DataAccessException - If something went wrong closing the statement

See Also:

Statement.close()

cancel

void cancel()
     throws DataAccessException

Cancel the underlying statement.

This cancels the query's underlying Statement or PreparedStatement. If there is no underlying open and running statement, this call is simply ignored.

Throws:

DataAccessException - If something went wrong cancelling the statement

See Also:

Statement.cancel()