Package com.tableau.hyperapi

# Class Inserter

java.lang.Object
com.tableau.hyperapi.Inserter

All Implemented Interfaces:
  `AutoCloseable`

public final class Inserter extends Object implements AutoCloseable
An inserter.

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.

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static final class`
  `Inserter.ColumnMapping`
  Maps an expression to a column

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `Inserter(Connection connection, TableDefinition tableDefinition)`
  Creates an inserter for an existing table.
  `Inserter(Connection connection, TableDefinition tableDefinition, String[] columns)`
  Creates an inserter for an existing table.
  `Inserter(Connection connection, TableDefinition tableDefinition, List<Inserter.ColumnMapping> columnMappings, List<TableDefinition.Column> inserterDefinition)`
  Creates an inserter for an existing table.
  `Inserter(Connection connection, TableName name)`
  Creates an inserter for an existing table.
  `Inserter(Connection connection, TableName name, String[] columns)`
  Creates an inserter for an existing table.
  `Inserter(Connection connection, TableName name, List<Inserter.ColumnMapping> columnMappings, List<TableDefinition.Column> inserterDefinition)`
  Creates an inserter for an existing table.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `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(double value)`
  Sets the current field to the given double value.
  `Inserter`
  `add(float value)`
  Sets the current field to the given float value.
  `Inserter`
  `add(int value)`
  Sets the current field to the given int value.
  `Inserter`
  `add(long value)`
  Sets the current field to the given long value.
  `Inserter`
  `add(short value)`
  Sets the current field to the given short value.
  `Inserter`
  `add(Interval value)`
  Sets the current INTERVAL field to the given value.
  `Inserter`
  `add(String value)`
  Sets the current field to the given String value.
  `Inserter`
  `add(BigDecimal value)`
  Sets the current field to the given BigDecimal value.
  `Inserter`
  `add(Instant value)`
  Sets the current TIMESTAMP or TIMESTAMPTZ field to the given Instant value.
  `Inserter`
  `add(LocalDate value)`
  Sets the current DATE field to the given LocalDate value.
  `Inserter`
  `add(LocalDateTime value)`
  Sets the current TIMESTAMP field to the given value.
  `Inserter`
  `add(LocalTime value)`
  Sets the current TIME field to the given value.
  `Inserter`
  `add(OffsetDateTime value)`
  Sets the current TIMESTAMPTZ field to the given value.
  `Inserter`
  `add(ZonedDateTime value)`
  Sets the current TIMESTAMPTZ field to the given value.
  `Inserter`
  `add(Date value)`
  Sets the current TIMESTAMP or TIMESTAMPTZ field to the given java.util.Date 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.

  ### Methods inherited from class java.lang.Object

  `equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Constructor Details

  - ### Inserter

    public Inserter(Connection connection, TableName name)
    Creates an inserter for an existing table.
    Parameters:
      `connection` - The connection to the Hyper instance containing the table.
      `name` - The name of the table.
    Throws:
      `HyperException` - When creating the inserter fails.

  - ### Inserter

    public Inserter(Connection connection, TableName name, String[] columns)
    Creates an inserter for an existing table.
    Parameters:
      `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.
    Throws:
      `HyperException` - When creating the inserter fails.

  - ### Inserter

    public Inserter(Connection connection, TableDefinition tableDefinition)
    Creates an inserter for an existing table.
    Parameters:
      `connection` - The connection to the Hyper instance containing the table.
      `tableDefinition` - The table definition for the table into which the data is inserted.
    Throws:
      `HyperException` - When creating the inserter fails.

  - ### Inserter

    public Inserter(Connection connection, TableDefinition tableDefinition, String[] columns)
    Creates an inserter for an existing table.
    Parameters:
      `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.
    Throws:
      `HyperException` - When creating the inserter fails.

  - ### Inserter

    public Inserter(Connection connection, TableName name, List<Inserter.ColumnMapping> columnMappings, List<TableDefinition.Column> inserterDefinition)
    Creates an inserter for an existing table. Note: SQL expression provided during insertion are used without any modification during insertion and hence vulnerable to SQL injection attacks. Applications must prevent end-users from providing expressions directly during insertion

    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)

    Parameters:
      `connection` - The connection to the Hyper instance containing the table.
      `name` - The name of the table into which 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`
    Throws:
      `HyperException` - When creating the inserter fails.

  - ### Inserter

    public Inserter(Connection connection, TableDefinition tableDefinition, List<Inserter.ColumnMapping> columnMappings, List<TableDefinition.Column> inserterDefinition)
    Creates an inserter for an existing table. Note: SQL expression provided during insertion are used without any modification during insertion and hence vulnerable to SQL injection attacks. Applications must prevent end-users from providing expressions directly during insertion

    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)

    Parameters:
      `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`.
    Throws:
      `HyperException` - When creating the inserter fails.

- ## Method Details

  - ### execute

    public void execute()
    Executes the insert, closes the inserter.

    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.

    Throws:
      `HyperException` - When the current row was not ended, sending data failed, or executing the insert failed.

  - ### close

    public void close()
    Closes the inserter and discards all data.

    This methods discards all data and cancels the insert if it was not yet executed (with `execute()`).

    Specified by:
      `close` in interface `AutoCloseable`

  - ### isOpen

    public boolean isOpen()
    Returns whether the inserter is open.
    Returns:
      Whether the inserter is open.

  - ### getTableDefinition

    public TableDefinition getTableDefinition()
    Gets the table definition.
    Returns:
      TableDefinition The table definition of the table being inserted.

  - ### addNull

    public Inserter addNull()
    Sets the current field to null. The field must be nullable.

    Calling the method advances the current field.

    Returns:
      Inserter For method chaining.
    Throws:
      `HyperException` - When column was not defined as nullable.

  - ### add

    public Inserter add(boolean value)
    Sets the current field to the given boolean value.

    Calling the method advances the current field.

    Parameters:
      `value` - The value.
    Returns:
      Inserter For method chaining.
    Throws:
      `HyperException` - If the column has an incompatible type, the row is complete, or the inserter is closed.

  - ### add

    public Inserter add(long value)
    Sets the current field to the given long value.

    Calling the method advances the current field.

    Parameters:
      `value` - The value.
    Returns:
      Inserter For method chaining.
    Throws:
      `HyperException` - If the column has an incompatible type, the row is complete, or the inserter is closed.

  - ### add

    public Inserter add(short value)
    Sets the current field to the given short value.

    Calling the method advances the current field.

    Parameters:
      `value` - The value.
    Returns:
      Inserter For method chaining.
    Throws:
      `HyperException` - If the column has an incompatible type, the row is complete, or the inserter is closed.

  - ### add

    public Inserter add(int value)
    Sets the current field to the given int value.

    Calling the method advances the current field.

    Parameters:
      `value` - The value.
    Returns:
      Inserter For method chaining.
    Throws:
      `HyperException` - If the column has an incompatible type, the row is complete, or the inserter is closed.

  - ### add

    public Inserter add(float value)
    Sets the current field to the given float value.

    Calling the method advances the current field.

    Parameters:
      `value` - The value.
    Returns:
      Inserter For method chaining.
    Throws:
      `HyperException` - If the column has an incompatible type, the row is complete, or the inserter is closed.

  - ### add

    public Inserter add(double value)
    Sets the current field to the given double value.

    Calling the method advances the current field.

    Parameters:
      `value` - The value.
    Returns:
      Inserter For method chaining.
    Throws:
      `HyperException` - If the column has an incompatible type, the row is complete, or the inserter is closed.

  - ### add

    public Inserter add(BigDecimal value)
    Sets the current field to the given BigDecimal value.

    Calling the method advances the current field.

    Parameters:
      `value` - The value.
    Returns:
      Inserter For method chaining.
    Throws:
      `HyperException` - If the column has an incompatible type, the row is complete, or the inserter is closed.

  - ### add

    public Inserter add(byte[] value)
    Sets the current field to the given byte array value.

    Calling the method advances the current field.

    Parameters:
      `value` - The value.
    Returns:
      Inserter For method chaining.
    Throws:
      `HyperException` - If the column has an incompatible type, the row is complete, or the inserter is closed.

  - ### add

    public Inserter add(String value)
    Sets the current field to the given 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.

    Parameters:
      `value` - The value.
    Returns:
      Inserter For method chaining.
    Throws:
      `HyperException` - If the column has an incompatible type, the row is complete, or the inserter is closed.

  - ### add

    public Inserter add(Instant value)
    Sets the current TIMESTAMP or TIMESTAMPTZ field to the given 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.

    Parameters:
      `value` - The value.
    Returns:
      Inserter For method chaining.
    Throws:
      `HyperException` - If the column has an incompatible type, the row is complete, or the inserter is closed.

  - ### add

    public Inserter add(LocalDate value)
    Sets the current DATE field to the given LocalDate value.

    The LocalDate represents a date without a time-zone in the ISO-8601 calendar system.

    Calling the method advances the current field.

    Parameters:
      `value` - The value.
    Returns:
      Inserter For method chaining.
    Throws:
      `HyperException` - If the column has an incompatible type, the row is complete, or the inserter is closed.

  - ### add

    public Inserter add(Date value)
    Sets the current TIMESTAMP or TIMESTAMPTZ field to the given 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.

    Parameters:
      `value` - The value.
    Returns:
      Inserter For method chaining.
    Throws:
      `HyperException` - If the column has an incompatible type, the row is complete, or the inserter is closed.

  - ### add

    public Inserter add(LocalDateTime value)
    Sets the current TIMESTAMP field to the given 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.

    Parameters:
      `value` - The value.
    Returns:
      Inserter For method chaining.
    Throws:
      `HyperException` - If the column has an incompatible type, the row is complete, or the inserter is closed.

  - ### add

    public Inserter add(OffsetDateTime value)
    Sets the current TIMESTAMPTZ field to the given 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.

    Parameters:
      `value` - The value.
    Returns:
      Inserter For method chaining.
    Throws:
      `HyperException` - If the column has an incompatible type, the row is complete, or the inserter is closed.

  - ### add

    public Inserter add(ZonedDateTime value)
    Sets the current TIMESTAMPTZ field to the given 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.

    Parameters:
      `value` - The value.
    Returns:
      Inserter For method chaining.
    Throws:
      `HyperException` - If the column has an incompatible type, the row is complete, or the inserter is closed.

  - ### add

    public Inserter add(LocalTime value)
    Sets the current TIME field to the given value.

    Calling the method advances the current field.

    Parameters:
      `value` - The value.
    Returns:
      Inserter For method chaining.
    Throws:
      `HyperException` - If the column has an incompatible type, the row is complete, or the inserter is closed.

  - ### add

    public Inserter add(Interval value)
    Sets the current INTERVAL field to the given value.

    Calling the method advances the current field.

    Parameters:
      `value` - The value.
    Returns:
      Inserter For method chaining.
    Throws:
      `HyperException` - If the column has an incompatible type, the row is complete, or the inserter is closed.

  - ### add

    public Inserter add(byte[] value, int offset, int length)
    Sets the current field to the given value.

    Calling the method advances the current field.

    Parameters:
      `value` - The value.
      `offset` - The offset in the byte array to start copying from.
      `length` - The amount of data from offset to insert.
    Returns:
      Inserter For method chaining.zm
    Throws:
      `HyperException` - If the column has an incompatible type, the row is complete, or the inserter is closed.

  - ### addDate

    public Inserter addDate(int year, int month, int day)
    Sets the current DATE field to the given value.

    Calling the method advances the current field.

    Parameters:
      `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.
    Returns:
      Inserter For method chaining.
    Throws:
      `HyperException` - If the column has an incompatible type, the row is complete, or the inserter is closed.

  - ### addInterval

    public 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.

    Calling the method advances the current field.

    Parameters:
      `years` - The years.
      `months` - The months.
      `days` - The days.
      `hours` - The hours.
      `minutes` - The minutes.
      `seconds` - The seconds.
      `microseconds` - The microseconds.
    Returns:
      Inserter For method chaining.
    Throws:
      `HyperException` - If the column has an incompatible type, the row is complete, or the inserter is closed.

  - ### addTime

    public Inserter addTime(int hour, int minute, int second, int microsecond)
    Sets the current TIME field to the given value.

    Calling the method advances the current field.

    Parameters:
      `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.
    Returns:
      Inserter For method chaining.
    Throws:
      `HyperException` - If the column has an incompatible type, the row is complete, or the inserter is closed.

  - ### addTime

    public Inserter addTime(int hour, int minute, int second)
    Sets the current TIME field to the given value.

    Calling the method advances the current field.

    Parameters:
      `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.
    Returns:
      Inserter For method chaining.
    Throws:
      `HyperException` - If the column has an incompatible type, the row is complete, or the inserter is closed.

  - ### addTimestamp

    public 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.

    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.

    Parameters:
      `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.
    Returns:
      Inserter For method chaining.
    Throws:
      `HyperException` - If the column has an incompatible type, the row is complete, or the inserter is closed.

  - ### endRow

    public Inserter endRow()
    Advances the inserter to the next row.

    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.

    Returns:
      Inserter For method chaining.
    Throws:
      `HyperException` - When a failure occurs sending the data to Hyper.