Package org.voltdb

Class VoltTable

java.lang.Object
org.voltdb.VoltTableRow
org.voltdb.VoltTable
All Implemented Interfaces:
org.json_voltpatches.JSONString
public final class VoltTable extends VoltTableRow implements org.json_voltpatches.JSONString

The primary representation of a result set (of tuples) or a temporary table in VoltDB. VoltTable has arbitrary schema, is serializable, and is used from within Stored Procedures and from the client library.

Accessing Rows by Index

Given a VoltTable, individual rows can be accessed via the fetchRow(int) method. This method returns a VoltTableRow instance with position set to the specified row. See VoltTableRow for further information on accessing individual column data within a row.

A VoltTable is also a VoltTableRow

Like a VoltTableRow, a VoltTable has a current position within its rows. This is because VoltTable is a subclass of VoltTableRow. This allows for easy sequential access of data. Example:

while (table.advanceRow()) {
    System.out.println(table.getLong(7));
}

Building a Table Dynamically

VoltTables can be constructed on the fly. This can help generate cleaner result sets from stored procedures, or more manageable parameters to them. Example:

VoltTable t = new VoltTable(
    new VoltTable.ColumnInfo("col1", VoltType.BIGINT),
    new VoltTable.ColumnInfo("col2", VoltType.STRING));
t.addRow(15, "sampleString");
t.addRow(-9, "moreData");

  • Field Details

    • MAX_SERIALIZED_TABLE_LENGTH

      public static final int MAX_SERIALIZED_TABLE_LENGTH
      Size in bytes of the maximum length for a VoltDB tuple. This value is counted from byte 0 of the header size to the end of row data.
      See Also:

    • MAX_SERIALIZED_TABLE_LENGTH_STR

      public static final String MAX_SERIALIZED_TABLE_LENGTH_STR
      String representation of MAX_SERIALIZED_TABLE_LENGTH.

  • Constructor Details

    • VoltTable

      public VoltTable(VoltTable.ColumnInfo[] columns, int columnCount)
      Create an empty table from column schema. While VoltTable(ColumnInfo...) is the preferred constructor, this version may reduce the need for an array allocation by allowing the caller to specify only a portion of the given array should be used.
      Parameters:
      columns - An array of ColumnInfo objects, one per column in the desired order.
      columnCount - The number of columns in the array to use.

    • VoltTable

      public VoltTable(VoltTable.ColumnInfo[] columns)
      Create an empty table from column schema given as an array.
      Parameters:
      columns - An array of ColumnInfo objects, one per column in the desired order.

    • VoltTable

      public VoltTable(VoltTable.ColumnInfo firstColumn, VoltTable.ColumnInfo... columns)
      Create an empty table from column schema. Note that while this accepts a varargs set of columns, it requires at least one column to prevent user errors.
      Parameters:
      firstColumn - The first column of the table.
      columns - An array of ColumnInfo objects, one per column in the desired order (can be empty).

  • Method Details

    • getInstanceForTest

      public static VoltTable getInstanceForTest(ByteBuffer buf)
      get a not fully constructed and validated VoltTable. DO NOT use it for production
      Parameters:
      buf - The buffer containing VoltTable buffer.
      Returns:
      VoltTable instance

    • clearRowData

      public final void clearRowData()
      Delete all row data. Column data is preserved. Useful for reusing an VoltTable.

    • cloneRow

      public VoltTableRow cloneRow()
      Get a new VoltTableRow instance with identical position as this table. After the cloning, the new instance and this table can be advanced or reset independently.
      Specified by:
      cloneRow in class VoltTableRow
      Returns:
      A new VoltTableRow instance with the same position as this table.

    • getColumnName

      public final String getColumnName(int index)
      Return the name of the column with the specified index.
      Parameters:
      index - Index of the column
      Returns:
      Name of the column with the specified index.

    • getColumnType

      public final VoltType getColumnType(int index)
      Description copied from class: VoltTableRow
      Return the type of the column with the specified index.
      Specified by:
      getColumnType in class VoltTableRow
      Parameters:
      index - Index of the column
      Returns:
      VoltType of the column

    • getColumnIndex

      public final int getColumnIndex(String name)
      Description copied from class: VoltTableRow
      Return the index of the column with the specified column name.
      Specified by:
      getColumnIndex in class VoltTableRow
      Parameters:
      name - Name of the column
      Returns:
      Index of the column

    • fetchRow

      public final VoltTableRow fetchRow(int index)
      Return a VoltTableRow instance with the specified index. This method is not performant because it has to scan the length prefix of every row preceding the requested row in order to find the position of the requested row. Use advanceRow or advanceToRow instead.
      Parameters:
      index - Index of the row
      Returns:
      The requested Row.
      Throws:
      IndexOutOfBoundsException - if no row exists at the given index.

    • add

      public final void add(VoltTableRow row)
      Append a row from another VoltTable to this VoltTable instance. Technically, it could be from the same table, but this isn't the common usage.
      Parameters:
      row - Row to add.

    • addRow

      public final void addRow(Object... values)
      Append a new row to the table using the supplied column values.
      Parameters:
      values - Values of each column in the row.
      Throws:
      org.voltdb.VoltTypeException - when there are casting/type failures between an input value and the corresponding column

    • asScalarLong

      public final long asScalarLong()
      Tables containing a single row and a single integer column can be read using this convenience method. Looking at the return value is not a reliable way to check if the value is null. Use VoltTableRow.wasNull() instead.
      Returns:
      The integer row value.

    • addTable

      public void addTable(VoltTable other)
      Add all rows from other into this VoltTable. Both tables must have the exact same schema including column names.
      Parameters:
      other - VoltTable to add to this table
      Throws:
      IllegalArgumentException - if other is not compatible with this table

    • addTableWithExtraColumns

      public void addTableWithExtraColumns(VoltTable other)
      Adds a table with extra columns, based on another provided table.

      If the other table has extra columns they will be skipped.

      Columns that match must have the same types.

      If no columns were copied this will throw an IllegalStateException.

      Be careful using this as it may copy column A into column B if their ordinals and type match.

      Parameters:
      other - the VoltTable to copy columns from.

    • addTableWithLessColumns

      public void addTableWithLessColumns(VoltTable other)
      Adds a table with fewer columns, based on another provided table.

      If the other table has fewer columns, null values will be used.

      Columns that match must have the same types.

      If no columns were copied this will throw an IllegalStateException.

      Parameters:
      other - the VoltTable to copy columns from.

    • addTables

      public void addTables(Collection<VoltTable> tables)
      Add all rows from tables into this VoltTable. All tables must have the exact same schema including column names.
      Parameters:
      tables - Collection of VoltTables to add to this table
      Throws:
      IllegalArgumentException - if any table in tables is not compatible with this table

    • toString

      public String toString()
      Returns a String representation of this table. Resulting string will contain schema and all data and will be formatted.
      Overrides:
      toString in class Object
      Returns:
      a String representation of this table.

    • varbinaryToPrintableString

      public static String varbinaryToPrintableString(byte[] bin)
      Make a printable, short string for a varbinary. String includes a CRC and the contents of the varbinary in hex. Contents longer than 13 chars are truncated and elipsized. Yes, "elipsized" is totally a word. Example: "bin[crc:1298399436,value:0xABCDEF12345...]"
      Parameters:
      bin - The bytes to print out.
      Returns:
      A string representation that is printable and short.

    • toFormattedString

      public String toFormattedString()
      Return a "pretty print" representation of this table with column names. Output will be formatted in a tabular textual format suitable for display.
      Returns:
      A string containing a pretty-print formatted representation of this table.

    • toFormattedString

      public String toFormattedString(boolean includeColumnNames)
      Return a "pretty print" representation of this table with or without column names. Output will be formatted in a tabular textual format suitable for display.
      Parameters:
      includeColumnNames - Flag to control if column names should be included or not.
      Returns:
      A string containing a pretty-print formatted representation of this table.

    • toJSONString

      public String toJSONString()
      Get a JSON representation of this table.
      Specified by:
      toJSONString in interface org.json_voltpatches.JSONString
      Returns:
      A string containing a JSON representation of this table.

    • toJSONStringerV2

      public org.json_voltpatches.JSONStringer toJSONStringerV2(org.json_voltpatches.JSONStringer js) throws org.json_voltpatches.JSONException
      Get a JSON /api/2.0/ representation of this table.
      Parameters:
      js - JSONStringer instance to add this table to
      Returns:
      A JSONStringer containing representation of this table.
      Throws:
      org.json_voltpatches.JSONException - If there was an error generating the JSON

    • fromJSONString

      public static VoltTable fromJSONString(String json) throws org.json_voltpatches.JSONException, IOException
      Construct a table from a JSON string. Only parses VoltDB VoltTable JSON format.
      Parameters:
      json - String containing JSON-formatted table data.
      Returns:
      Constructed VoltTable instance.
      Throws:
      org.json_voltpatches.JSONException - on JSON-related error.
      IOException - if thrown by our JSON library.

    • fromJSONObject

      public static VoltTable fromJSONObject(org.json_voltpatches.JSONObject json) throws org.json_voltpatches.JSONException, IOException

      Construct a table from a JSON object. Only parses VoltDB VoltTable JSON format.

      Parameters:
      json - String containing JSON-formatted table data.
      Returns:
      Constructed VoltTable instance.
      Throws:
      org.json_voltpatches.JSONException - on JSON-related error.
      IOException - if thrown by our JSON library.

    • hasSameContents

      public boolean hasSameContents(VoltTable other)
      Check to see if this table has the same contents as the provided table. This is not Object.equals(Object) because we don't want to provide all of the additional contractual requirements that go along with it, such as implementing Object.hashCode().
      Parameters:
      other - Table to compare to.
      Returns:
      Whether the tables have the same contents.

    • hasSameContents

      public boolean hasSameContents(VoltTable other, boolean ignoreOrder)
      Check to see if this table has the same contents as the provided table, optionally ignoring the order of rows.
      Parameters:
      other - Table to compare to.
      ignoreOrder - true if tables can be considered equal despite order.
      Returns:
      Whether the tables have the same contents.

    • getTableCheckSum

      public long getTableCheckSum(boolean includeHeader)
      Calculate a rudimentary checksum of the table. The result of this method will be the same for two tables with the same rows but not necessarily in the same order.

      When includeHeader is false the result of this checksum can be added to the result from another table to affectively concatenate the hash from this table with another to compare across tables.

      Parameters:
      includeHeader - If true the table header will be included in the checksum
      Returns:
      checksum of table

    • equals

      @Deprecated public boolean equals(Object o)
      Deprecated.
      Exists for unit testing, but probably shouldn't be called.
      An unreliable version of Object.equals(Object) that should not be used. Only present for unit testing.
      Overrides:
      equals in class Object

    • hashCode

      @Deprecated public int hashCode()
      Deprecated.
      This only throws. Doesn't do anything.
      Also overrides Object.hashCode() since we are overriding Object.equals(Object). Throws an UnsupportedOperationException.
      Overrides:
      hashCode in class Object
      Throws:
      UnsupportedOperationException - if called.

    • clone

      public final VoltTable clone(int extraBytes)

      Generates a duplicate of a table including the column schema. Only works on tables that have no rows, have columns defined, and will not have columns added/deleted/modified later. Useful as way of creating template tables that can be cloned and then populated with rows repeatedly.

      Parameters:
      extraBytes - The number of extra bytes to leave for to-be-added rows beyond the header.
      Returns:
      An VoltTable with the same column schema as the original and enough space for the specified number of rows and strings.

    • getRowCount

      public final int getRowCount()

    • getColumnCount

      public final int getColumnCount()
      Description copied from class: VoltTableRow
      Returns the number of columns in the table schema
      Specified by:
      getColumnCount in class VoltTableRow
      Returns:
      Number of columns in the table schema

    • getStatusCode

      public byte getStatusCode()
      Set the status code associated with this table. Default value is 0.
      Returns:
      Status code

    • setStatusCode

      public void setStatusCode(byte code)
      Set the status code associated with this table. Default value if not set is 0
      Parameters:
      code - Status code to set

    • getSerializedSize

      public int getSerializedSize()
      Get the serialized size in bytes of this table. This is used mostly internally by VoltDB for table serialization purposes.
      Returns:
      The size in bytes.

    • flattenToBuffer

      public void flattenToBuffer(ByteBuffer buf)
      Serialize this table to a given ByteBuffer. Used mostly internally by VoltDB for moving tables over the network.
      Parameters:
      buf - Buffer to serialize table to.

    • buildReusableDependenyResult

      public byte[] buildReusableDependenyResult()
      Builds a dependency response that can be reused.
      Returns:
      response as byte array

    • convertToHeapBuffer

      public final void convertToHeapBuffer()
      Converts the allocated direct buffer to a heap buffer, if necessary,

    • getBuffer

      public ByteBuffer getBuffer()
      Directly access the table's underlying ByteBuffer. This should be avoided if possible by end users, as there is potential to really mess stuff up. VoltDB mostly uses it to compute various checksums quickly.
      Returns:
      The underlying ByteBuffer instance.

    • getTableSchema

      public VoltTable.ColumnInfo[] getTableSchema()
      Get the schema of the table. Can be fed into another table's constructor.
      Returns:
      An ordered array of VoltTable.ColumnInfo instances for each table column.