Package com.tableau.hyperapi

Class Inserter

  • All Implemented Interfaces:
    java.lang.AutoCloseable
    public final class Inserter
extends java.lang.Object
implements java.lang.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 class  Inserter.ColumnMapping
      Maps an expression to a column

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      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​(java.lang.String value)
      Sets the current field to the given String value.
      Inserter add​(java.math.BigDecimal value)
      Sets the current field to the given BigDecimal value.
      Inserter add​(java.time.Instant value)
      Sets the current TIMESTAMP or TIMESTAMPTZ field to the given Instant 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​(java.time.OffsetDateTime value)
      Sets the current TIMESTAMPTZ field to the given value.
      Inserter add​(java.time.ZonedDateTime value)
      Sets the current TIMESTAMPTZ 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 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 Detail

      • 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,
                java.lang.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,
                java.lang.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,
                java.util.List<Inserter.ColumnMapping> columnMappings,
                java.util.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,
                java.util.List<Inserter.ColumnMapping> columnMappings,
                java.util.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 Detail

      • 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 java.lang.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​(java.math.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​(java.lang.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​(java.time.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​(java.time.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​(java.util.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​(java.time.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​(java.time.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​(java.time.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​(java.time.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.