- All Superinterfaces:
LoaderSourceStep<R>
Loader
API is used for configuring data loads.
Add options to for the loading behaviour. For performance reasons, you can fine-tune three different types of measures:
- The bulk statement size. This specifies how many rows
will be inserted in a single bulk statement / multi-row
INSERT
statement. - The batch statement size. This specifies how many bulk statements will be sent to the server as a single JDBC batch statement.
- The commit size. This specifies how many batch statements will be committed in a single transaction.
Referencing XYZ*Step
types directly from client code
It is usually not recommended to reference any XYZ*Step
types
directly from client code, or assign them to local variables. When writing
dynamic SQL, creating a statement's components dynamically, and passing them
to the DSL API statically is usually a better choice. See the manual's
section about dynamic SQL for details: https://www.jooq.org/doc/latest/manual/sql-building/dynamic-sql.
Drawbacks of referencing the XYZ*Step
types directly:
- They're operating on mutable implementations (as of jOOQ 3.x)
- They're less composable and not easy to get right when dynamic SQL gets complex
- They're less readable
- They might have binary incompatible changes between minor releases
- Author:
- Lukas Eder
-
Method Summary
Modifier and TypeMethodDescription@NotNull LoaderOptionsStep
<R> batchAfter
(int number) Batch a given number of bulk statements together.@NotNull LoaderOptionsStep
<R> batchAll()
Batch all bulk statements in one JDBC batch statement.@NotNull LoaderOptionsStep
<R> Do not batch bulk statements together.@NotNull LoaderOptionsStep
<R> bulkAfter
(int number) Bulk-insert a given number of statements in a single multi-row bulk statement.@NotNull LoaderOptionsStep
<R> bulkAll()
Bulk-insert all rows in a single multi-row bulk statement.@NotNull LoaderOptionsStep
<R> bulkNone()
Do not bulk-insert rows in multi-row bulk statements.@NotNull LoaderOptionsStep
<R> commitAfter
(int number) Commit after a certain number of batches.@NotNull LoaderOptionsStep
<R> Commit only after inserting all batches.@NotNull LoaderOptionsStep
<R> Commit each batch.@NotNull LoaderOptionsStep
<R> Leave committing / rollbacking up to client code.@NotNull LoaderOptionsStep
<R> Instruct theLoader
to cause an error in loading if there are any duplicate records.@NotNull LoaderOptionsStep
<R> Instruct theLoader
to skip duplicate records if any of the unique keys' values are already in the database.@NotNull LoaderOptionsStep
<R> Instruct theLoader
to update duplicate records if any of the unique keys' values are already in the database.@NotNull LoaderOptionsStep
<R> Instruct theLoader
to abort loading after the first error that might occur when inserting a record.@NotNull LoaderOptionsStep
<R> Instruct theLoader
to ignore any errors that might occur when inserting a record.Methods inherited from interface org.jooq.LoaderSourceStep
loadArrays, loadArrays, loadArrays, loadArrays, loadCSV, loadCSV, loadCSV, loadCSV, loadCSV, loadCSV, loadCSV, loadCSV, loadCSV, loadCSV, loadCSV, loadJSON, loadJSON, loadJSON, loadJSON, loadJSON, loadJSON, loadJSON, loadJSON, loadJSON, loadJSON, loadJSON, loadRecords, loadRecords, loadRecords, loadRecords, loadXML, loadXML, loadXML, loadXML, loadXML, loadXML, loadXML, loadXML, loadXML, loadXML, loadXML, loadXML
-
Method Details
-
onDuplicateKeyUpdate
@NotNull @CheckReturnValue @Support({AURORA_MYSQL,AURORA_POSTGRES,COCKROACHDB,CUBRID,DB2,DERBY,DUCKDB,EXASOL,FIREBIRD_3_0,H2,HANA,HSQLDB,INFORMIX,MARIADB,MEMSQL,MYSQL,ORACLE,POSTGRES_9_5,SNOWFLAKE,SQLITE,SQLSERVER,SYBASE,TERADATA,YUGABYTEDB}) @NotNull LoaderOptionsStep<R> onDuplicateKeyUpdate()Instruct theLoader
to update duplicate records if any of the unique keys' values are already in the database. This is only supported ifInsertQuery.onDuplicateKeyUpdate(boolean)
is supported, too.If the loaded table does not have any unqiue keys, then all records are inserted and this clause behaves like
onDuplicateKeyIgnore()
If you don't specify a behaviour,
onDuplicateKeyError()
will be the default. This cannot be combined withonDuplicateKeyError()
oronDuplicateKeyIgnore()
-
onDuplicateKeyIgnore
Instruct theLoader
to skip duplicate records if any of the unique keys' values are already in the database.If the loaded table does not have any unique keys, then all records are inserted. This may influence the JDBC driver's outcome on
Connection.getWarnings()
, depending on your JDBC driver's implementationIf you don't specify a behaviour,
onDuplicateKeyError()
will be the default. This cannot be combined withonDuplicateKeyError()
oronDuplicateKeyUpdate()
-
onDuplicateKeyError
Instruct theLoader
to cause an error in loading if there are any duplicate records.If this is combined with
onErrorAbort()
andcommitAll()
in a later step ofLoader
, then loading is rollbacked on abort.If you don't specify a behaviour, this will be the default. This cannot be combined with
onDuplicateKeyIgnore()
oronDuplicateKeyUpdate()
-
onErrorIgnore
Instruct theLoader
to ignore any errors that might occur when inserting a record. TheLoader
will then skip the record and try inserting the next one. After loading, you can access errors withLoader.errors()
If you don't specify a behaviour,
onErrorAbort()
will be the default. This cannot be combined withonErrorAbort()
-
onErrorAbort
Instruct theLoader
to abort loading after the first error that might occur when inserting a record. After loading, you can access errors withLoader.errors()
If this is combined with
commitAll()
in a later step ofLoader
, then loading is rollbacked on abort.If you don't specify a behaviour, this will be the default. This cannot be combined with
onErrorIgnore()
-
commitEach
Commit each batch.This is the same as calling
commitAfter(int)
with1
as parameter.With this clause, errors will never result in a rollback, even when you specify
onDuplicateKeyError()
oronErrorAbort()
The COMMIT OPTIONS might be useful for fine-tuning performance behaviour in some RDBMS, where large commits lead to a high level of concurrency in the database. Use this on fresh transactions only. Commits/Rollbacks are executed directly upon the connection returned by
Configuration.connectionProvider()
. This might not work with container-managed transactions, or whenConnection.getAutoCommit()
is set to true.If you don't specify a COMMIT OPTION,
commitNone()
will be the default, leaving transaction handling up to you. -
commitAfter
Commit after a certain number of batches.With this clause, errors will never result in a rollback, even when you specify
onDuplicateKeyError()
oronErrorAbort()
The COMMIT OPTIONS might be useful for fine-tuning performance behaviour in some RDBMS, where large commits lead to a high level of concurrency in the database. Use this on fresh transactions only. Commits/Rollbacks are executed directly upon the connection returned by
Configuration.connectionProvider()
. This might not work with container-managed transactions, or whenConnection.getAutoCommit()
is set to true.If you don't specify a COMMIT OPTION,
commitNone()
will be the default, leaving transaction handling up to you.- Parameters:
number
- The number of records that are committed together.
-
commitAll
Commit only after inserting all batches. If this is used together withonDuplicateKeyError()
oronErrorAbort()
, an abort will result in a rollback of previously loaded records.The COMMIT OPTIONS might be useful for fine-tuning performance behaviour in some RDBMS, where large commits lead to a high level of concurrency in the database. Use this on fresh transactions only. Commits/Rollbacks are executed directly upon the connection returned by
Configuration.connectionProvider()
. This might not work with container-managed transactions, or whenConnection.getAutoCommit()
is set to true.If you don't specify a COMMIT OPTION,
commitNone()
will be the default, leaving transaction handling up to you. -
commitNone
Leave committing / rollbacking up to client code.The COMMIT OPTIONS might be useful for fine-tuning performance behaviour in some RDBMS, where large commits lead to a high level of concurrency in the database.
If you don't specify a COMMIT OPTION, this will be the default, leaving transaction handling up to you. This should be your choice, when you use container-managed transactions, too, or your
Connection.getAutoCommit()
value is set to true. -
batchAll
Batch all bulk statements in one JDBC batch statement.If
commitEach()
orcommitAfter(int)
are set, this will force theCOMMIT
option tocommitAll()
. -
batchNone
Do not batch bulk statements together.If you don't specify a BATCH OPTION, this will be the default.
-
batchAfter
Batch a given number of bulk statements together.- Parameters:
number
- The number of records that are batched together.
-
bulkAll
Bulk-insert all rows in a single multi-row bulk statement.If
commitEach()
orcommitAfter(int)
are set, this will force theCOMMIT
option tocommitAll()
. -
bulkNone
Do not bulk-insert rows in multi-row bulk statements.If you don't specify a BULK OPTION, this will be the default.
-
bulkAfter
Bulk-insert a given number of statements in a single multi-row bulk statement.If
commitEach()
is set, each bulk statement will be committed. IfcommitAfter(int)
is set, the given number of bulk statements are committed.- Parameters:
number
- The number of records that are put together in one bulk statement.
-