public final class Inserter
extends java.lang.Object
implements java.lang.AutoCloseable
Used to insert data into existing tables in hyper. The insertion happens row by row. Inside one row, all the columns have to be added sequentially in the right order. Note: While this resource is open, the connection is busy.
Use the add methods such as add(int)
to set values for all the columns of a row. After inserting a
complete row, call endRow()
. After ending the last row, call execute()
to finalize
the insert. Calling close()
instead discards all inserted data.
This is an AutoCloseable
class since it maintains native resources. The inserter must always be
closed when it is no longer needed. The best way to guarantee this is to use a try-with-resources block.
Modifier and Type | Class and Description |
---|---|
static class |
Inserter.ColumnMapping
Maps an expression to a column
|
Constructor and Description |
---|
Inserter(Connection connection,
TableDefinition tableDefinition)
Creates an inserter for an existing table.
|
Inserter(Connection connection,
TableDefinition tableDefinition,
java.util.List<Inserter.ColumnMapping> columnMappings,
java.util.List<TableDefinition.Column> inserterDefinition)
Creates an inserter for an existing table.
|
Inserter(Connection connection,
TableDefinition tableDefinition,
java.lang.String[] columns)
Creates an inserter for an existing table.
|
Inserter(Connection connection,
TableName name)
Creates an inserter for an existing table.
|
Inserter(Connection connection,
TableName name,
java.util.List<Inserter.ColumnMapping> columnMappings,
java.util.List<TableDefinition.Column> inserterDefinition)
Creates an inserter for an existing table.
|
Inserter(Connection connection,
TableName name,
java.lang.String[] columns)
Creates an inserter for an existing table.
|
Modifier and Type | Method and Description |
---|---|
Inserter |
add(java.math.BigDecimal value)
Sets the current field to the given BigDecimal value.
|
Inserter |
add(boolean value)
Sets the current field to the given boolean value.
|
Inserter |
add(byte[] value)
Sets the current field to the given byte array value.
|
Inserter |
add(byte[] value,
int offset,
int length)
Sets the current field to the given value.
|
Inserter |
add(java.util.Date value)
Sets the current TIMESTAMP or TIMESTAMPTZ field to the given java.util.Date value.
|
Inserter |
add(double value)
Sets the current field to the given double value.
|
Inserter |
add(java.time.Instant value)
Sets the current TIMESTAMP or TIMESTAMPTZ field to the given Instant value.
|
Inserter |
add(int value)
Sets the current field to the given int value.
|
Inserter |
add(Interval value)
Sets the current INTERVAL field to the given value.
|
Inserter |
add(java.time.LocalDate value)
Sets the current DATE field to the given LocalDate value.
|
Inserter |
add(java.time.LocalDateTime value)
Sets the current TIMESTAMP field to the given value.
|
Inserter |
add(java.time.LocalTime value)
Sets the current TIME field to the given value.
|
Inserter |
add(long value)
Sets the current field to the given long value.
|
Inserter |
add(java.time.OffsetDateTime value)
Sets the current TIMESTAMPTZ field to the given value.
|
Inserter |
add(short value)
Sets the current field to the given short value.
|
Inserter |
add(java.lang.String value)
Sets the current field to the given String value.
|
Inserter |
add(java.time.ZonedDateTime value)
Sets the current TIMESTAMPTZ field to the given value.
|
Inserter |
addDate(int year,
int month,
int day)
Sets the current DATE field to the given value.
|
Inserter |
addInterval(int years,
int months,
int days,
int hours,
int minutes,
int seconds,
int microseconds)
Sets the current INTERVAL field to the given value.
|
Inserter |
addNull()
Sets the current field to null.
|
Inserter |
addTime(int hour,
int minute,
int second)
Sets the current TIME field to the given value.
|
Inserter |
addTime(int hour,
int minute,
int second,
int microsecond)
Sets the current TIME field to the given value.
|
Inserter |
addTimestamp(int year,
int month,
int day,
int hour,
int minute,
int second,
int microsecond)
Sets the current TIMESTAMP or TIMESTAMPTZ field to the given value.
|
void |
close()
Closes the inserter and discards all data.
|
Inserter |
endRow()
Advances the inserter to the next row.
|
void |
execute()
Executes the insert, closes the inserter.
|
TableDefinition |
getTableDefinition()
Gets the table definition.
|
boolean |
isOpen()
Returns whether the inserter is open.
|
public Inserter(Connection connection, TableName name)
connection
- The connection to the Hyper instance containing the table.name
- The name of the table.HyperException
- When creating the inserter fails.public Inserter(Connection connection, TableName name, java.lang.String[] columns)
connection
- The connection to the Hyper instance containing the table.name
- The table name.columns
- The set of columns in which to insert. All other columns will be set to their default value.HyperException
- When creating the inserter fails.public Inserter(Connection connection, TableDefinition tableDefinition)
connection
- The connection to the Hyper instance containing the table.tableDefinition
- The table definition for the table into which the data is inserted.HyperException
- When creating the inserter fails.public Inserter(Connection connection, TableDefinition tableDefinition, java.lang.String[] columns)
connection
- The connection to the Hyper instance containing the table.tableDefinition
- The table definition for the table into which the data is inserted.columns
- The set of columns in which to insert. All other columns will be set to their default
value. The columns have to be contained in the tableDefinition.HyperException
- When creating the inserter fails.public Inserter(Connection connection, TableName name, java.util.List<Inserter.ColumnMapping> columnMappings, java.util.List<TableDefinition.Column> inserterDefinition)
Consider the following pseudo-code on how to transform or compute values on the fly during insertion: TableDefinition : [TableName="example", Columns=["ColumnA" as INT, "ColumnB" as BIG_INT]] ColumnMapping : [[Name: "ColumnA"], [Name:"ColumnB", Expression:"ColumnA"*"ColumnC"]] InserterDefinition : ["ColumnA" integer, "ColumnC" integer]
Notice that "ColumnA" does not specify an expression and "ColumnB" is a product of "ColumnA" and "ColumnC", but "ColumnC" is not part of the table. The InserterDefinition contains "ColumnA" and "ColumnC" "ColumnA" since it is not computed on the fly and has to be provided to the inserter "ColumnC" since it is specified in the SQL expression that computes "ColumnB" on the fly
try (Inserter inserter(conn, "example", columnMapping, inserterDefinition)) { inserter.add(2).add(3).endRow(); inserter.execute(); } The insertion code snippet above inserts 2 into "ColumnA" and 6 into "ColumnB" (product of 2 and 3)
connection
- The connection to the Hyper instance containing the table.name
- The name of the table into which data is insertedcolumnMappings
- The set of columns in which to insert. The columns have to exist in the table. The
columnMappings cannot be empty. Columns not present in columMappings will be set to
their default value. A columnMapping can optionally contain a valid SQL expression. The
SQL expression specified for the column is used to transform or compute values on the
fly during insertion. The SQL expression can depend on columns that exist in the table.
The SQL expression can also depend on values or columns that do not exist in the table,
but must be specified in the `inserterDefinition`.inserterDefinition
- The definition of columns to which values are provided. The column definition for all
the columns without SQL expression must be specified in `inserterDefinition` For a
column without SQL expression the column definition provided in `inserterDefinition`
must match the actual definition of the column in the table All columns that SQL
expressions specified in `columnMappings` must be in `inserterDefinition`HyperException
- When creating the inserter fails.public Inserter(Connection connection, TableDefinition tableDefinition, java.util.List<Inserter.ColumnMapping> columnMappings, java.util.List<TableDefinition.Column> inserterDefinition)
Consider the following pseudo-code on how to transform or compute values on the fly during insertion: TableDefinition : [TableName="example", Columns=["ColumnA" as INT, "ColumnB" as BIG_INT]] ColumnMapping : [[Name: "ColumnA"], [Name:"ColumnB", Expression:"ColumnA"*"ColumnC"]] InserterDefinition : ["ColumnA" integer, "ColumnC" integer]
Notice that "ColumnA" does not specify an expression and "ColumnB" is a product of "ColumnA" and "ColumnC", but "ColumnC" is not part of the table. The InserterDefinition contains "ColumnA" and "ColumnC" "ColumnA" since it is not computed on the fly and has to be provided to the inserter "ColumnC" since it is specified in the SQL expression that computes "ColumnB" on the fly
try (Inserter inserter(conn, "example", columnMapping, inserterDefinition)) { inserter.add(2).add(3).endRow(); inserter.execute(); } The insertion code snippet above inserts 2 into "ColumnA" and 6 into "ColumnB" (product of 2 and 3)
connection
- The connection to the Hyper instance containing the table.tableDefinition
- The table definition for the table into which the data is inserted.columnMappings
- The set of columns in which to insert. The columns have to exist in the table. The
columnMappings cannot be empty. Columns not present in columMappings will be set to
their default value. A columnMapping can optionally contain a valid SQL expression. The
SQL expression specified for the column is used to transform or compute values on the
fly during insertion. The SQL expression can depend on columns that exist in the table.
The SQL expression can also depend on values or columns that do not exist in the table,
but must be specified in the `inserterDefinition`.inserterDefinition
- The definition of columns to which values are provided. The column definition for all
the columns without SQL expression must be specified in `inserterDefinition`. For a
column without SQL expression the column definition provided in `inserterDefinition`
must match the actual definition of the column in the table. All columns that SQL
expressions specified in `columnMappings` must be in `inserterDefinition`.HyperException
- When creating the inserter fails.public void execute()
If this method throws, the result will not be inserted; it will be discarded and the inserter will be closed. In either way, the inserter will be closed once this method completes.
HyperException
- When the current row was not ended, sending data failed, or executing the insert failed.public void close()
This methods discards all data and cancels the insert if it was not yet executed (with execute()
).
close
in interface java.lang.AutoCloseable
public boolean isOpen()
public TableDefinition getTableDefinition()
public Inserter addNull()
Calling the method advances the current field.
HyperException
- When column was not defined as nullable.public Inserter add(boolean value)
Calling the method advances the current field.
value
- The value.HyperException
- If the column has an incompatible type, the row is complete, or the inserter is closed.public Inserter add(long value)
Calling the method advances the current field.
value
- The value.HyperException
- If the column has an incompatible type, the row is complete, or the inserter is closed.public Inserter add(short value)
Calling the method advances the current field.
value
- The value.HyperException
- If the column has an incompatible type, the row is complete, or the inserter is closed.public Inserter add(int value)
Calling the method advances the current field.
value
- The value.HyperException
- If the column has an incompatible type, the row is complete, or the inserter is closed.public Inserter add(double value)
Calling the method advances the current field.
value
- The value.HyperException
- If the column has an incompatible type, the row is complete, or the inserter is closed.public Inserter add(java.math.BigDecimal value)
Calling the method advances the current field.
value
- The value.HyperException
- If the column has an incompatible type, the row is complete, or the inserter is closed.public Inserter add(byte[] value)
Calling the method advances the current field.
value
- The value.HyperException
- If the column has an incompatible type, the row is complete, or the inserter is closed.public Inserter add(java.lang.String value)
The string is converted to a UTF-8 string. If using a static string, convert it to a UTF-8 byte array and use the
addUTF8 method instead. e.g., yourString.getBytes(StandardCharsets.UTF_8)
.
Calling the method advances the current field.
value
- The value.HyperException
- If the column has an incompatible type, the row is complete, or the inserter is closed.public Inserter add(java.time.Instant value)
An Instant represents an instantaneous point on the time-line in the UTC time-scale. The value is stored as is for TIMESTAMP columns and stored as UTC for TIMESTAMPTZ columns.
Calling the method advances the current field.
value
- The value.HyperException
- If the column has an incompatible type, the row is complete, or the inserter is closed.public Inserter add(java.time.LocalDate value)
The LocalDate represents a date without a time-zone in the ISO-8601 calendar system.
Calling the method advances the current field.
value
- The value.HyperException
- If the column has an incompatible type, the row is complete, or the inserter is closed.public Inserter add(java.util.Date value)
java.util.Date represents an instant in UTC. The value is stored as is for TIMESTAMP columns and stored as UTC for TIMESTAMPTZ columns.
Calling the method advances the current field.
value
- The value.HyperException
- If the column has an incompatible type, the row is complete, or the inserter is closed.public Inserter add(java.time.LocalDateTime value)
The LocalDateTime represents a date-time without a time-zone in the ISO-8601 calendar system. The value is stored as is in the TIMESTAMP column.
Calling the method advances the current field.
value
- The value.HyperException
- If the column has an incompatible type, the row is complete, or the inserter is closed.public Inserter add(java.time.OffsetDateTime value)
An OffsetDateTime is a date-time with an offset from UTC/Greenwich in the ISO-8601 calendar system. The value is converted to UTC and stored in the TIMESTAMPTZ column.
Calling the method advances the current field.
value
- The value.HyperException
- If the column has an incompatible type, the row is complete, or the inserter is closed.public Inserter add(java.time.ZonedDateTime value)
A ZonedDateTime is a date-time with a time-zone in the ISO-8601 calendar system. The value is converted to UTC and stored in the TIMESTAMPTZ column.
Calling the method advances the current field.
value
- The value.HyperException
- If the column has an incompatible type, the row is complete, or the inserter is closed.public Inserter add(java.time.LocalTime value)
Calling the method advances the current field.
value
- The value.HyperException
- If the column has an incompatible type, the row is complete, or the inserter is closed.public Inserter add(Interval value)
Calling the method advances the current field.
value
- The value.HyperException
- If the column has an incompatible type, the row is complete, or the inserter is closed.public Inserter add(byte[] value, int offset, int length)
Calling the method advances the current field.
value
- The value.offset
- The offset in the byte array to start copying from.length
- The amount of data from offset to insert.HyperException
- If the column has an incompatible type, the row is complete, or the inserter is closed.public Inserter addDate(int year, int month, int day)
Calling the method advances the current field.
year
- The year. To specify BC dates, you must convert the BC year to a negative year (e.g., 10 BC = -9).month
- The month, must be between 1 and 12.day
- The day, must be between 1 and 31.HyperException
- If the column has an incompatible type, the row is complete, or the inserter is closed.public Inserter addInterval(int years, int months, int days, int hours, int minutes, int seconds, int microseconds)
Calling the method advances the current field.
years
- The years.months
- The months.days
- The days.hours
- The hours.minutes
- The minutes.seconds
- The seconds.microseconds
- The microseconds.HyperException
- If the column has an incompatible type, the row is complete, or the inserter is closed.public Inserter addTime(int hour, int minute, int second, int microsecond)
Calling the method advances the current field.
hour
- The hour, must be between 0 and 23.minute
- The minute, must be between 0 and 59.second
- The second, must be between 0 and 59.microsecond
- The microsecond, must be smaller than 1'000'000.HyperException
- If the column has an incompatible type, the row is complete, or the inserter is closed.public Inserter addTime(int hour, int minute, int second)
Calling the method advances the current field.
hour
- The hour, must be between 0 and 23.minute
- The minute, must be between 0 and 59.second
- The second, must be between 0 and 59.HyperException
- If the column has an incompatible type, the row is complete, or the inserter is closed.public Inserter addTimestamp(int year, int month, int day, int hour, int minute, int second, int microsecond)
The arguments specify a date-time in UTC. The value is stored as is for TIMESTAMP columns and stored as UTC for TIMESTAMPTZ columns.
Calling the method advances the current field.
year
- The year. To specify BC dates, you must convert the BC year to a negative year (e.g., 10 BC =
-9).month
- The month, must be between 1 and 12.day
- The day, must be between 1 and 31.hour
- The hour, must be between 0 and 23.minute
- The minute, must be between 0 and 59.second
- The second, must be between 0 and 59.microsecond
- The microsecond, must be smaller than 1'000'000.HyperException
- If the column has an incompatible type, the row is complete, or the inserter is closed.public Inserter endRow()
May cause the inserter to send data over the connection. You must call this, even for the last row before closing the inserter; otherwise, close() will throw an exception.
HyperException
- When a failure occurs sending the data to Hyper.