Class VoltTable
- All Implemented Interfaces:
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");
-
Nested Class Summary
Modifier and TypeClassDescriptionstatic class
Object that represents the name and schema for aVoltTable
column. -
Field Summary
Modifier and TypeFieldDescriptionstatic final int
Size in bytes of the maximum length for a VoltDB tuple.static final String
String representation ofMAX_SERIALIZED_TABLE_LENGTH
.Fields inherited from class org.voltdb.VoltTableRow
MAX_TUPLE_LENGTH, MAX_TUPLE_LENGTH_STR
-
Constructor Summary
ConstructorDescriptionVoltTable
(VoltTable.ColumnInfo[] columns) Create an empty table from column schema given as an array.VoltTable
(VoltTable.ColumnInfo[] columns, int columnCount) Create an empty table from column schema.VoltTable
(VoltTable.ColumnInfo firstColumn, VoltTable.ColumnInfo... columns) Create an empty table from column schema. -
Method Summary
Modifier and TypeMethodDescriptionfinal void
add
(VoltTableRow row) Append arow
from anotherVoltTable
to this VoltTable instance.final void
Append a new row to the table using the supplied column values.void
Add all rows fromother
into this VoltTable.void
addTables
(Collection<VoltTable> tables) Add all rows fromtables
into this VoltTable.void
void
addTableWithLessColumns
(VoltTable other) final long
Tables containing a single row and a single integer column can be read using this convenience method.byte[]
final void
Delete all row data.final VoltTable
clone
(int extraBytes) Generates a duplicate of a table including the column schema.cloneRow()
Get a newVoltTableRow
instance with identical position as this table.final void
boolean
Deprecated.Exists for unit testing, but probably shouldn't be called.final VoltTableRow
fetchRow
(int index) Return aVoltTableRow
instance with the specified index.void
Serialize this table to a given ByteBuffer.static VoltTable
fromJSONObject
(org.json_voltpatches.JSONObject json) Construct a table from a JSON object.static VoltTable
fromJSONString
(String json) Construct a table from a JSON string.Directly access the table's underlyingByteBuffer
.final int
Returns the number of columns in the table schemafinal int
getColumnIndex
(String name) Return the index of the column with the specified column name.final String
getColumnName
(int index) Return the name of the column with the specified index.final VoltType
getColumnType
(int index) Return thetype
of the column with the specified index.static VoltTable
get a not fully constructed and validated VoltTable.final int
protected final int
int
Get the serialized size in bytes of this table.byte
Set the status code associated with this table.long
getTableCheckSum
(boolean includeHeader) Calculate a rudimentary checksum of the table.Get the schema of the table.int
hashCode()
Deprecated.This only throws.boolean
hasSameContents
(VoltTable other) Check to see if this table has the same contents as the provided table.boolean
hasSameContents
(VoltTable other, boolean ignoreOrder) void
setStatusCode
(byte code) Set the status code associated with this table.Return a "pretty print" representation of this table with column names.toFormattedString
(boolean includeColumnNames) Return a "pretty print" representation of this table with or without column names.Get a JSON representation of this table.org.json_voltpatches.JSONStringer
toJSONStringerV2
(org.json_voltpatches.JSONStringer js) Get a JSON /api/2.0/ representation of this table.toString()
Returns aString
representation of this table.static String
varbinaryToPrintableString
(byte[] bin) Make a printable, short string for a varbinary.Methods inherited from class org.voltdb.VoltTableRow
advanceRow, advanceToRow, get, get, get, getActiveRowIndex, getDecimalAsBigDecimal, getDecimalAsBigDecimal, getDouble, getDouble, getGeographyPointValue, getGeographyPointValue, getGeographyValue, getGeographyValue, getLong, getLong, getOffset, getRawRow, getRow, getRowObjects, getString, getString, getStringAsBytes, getStringAsBytes, getTimestampAsLong, getTimestampAsLong, getTimestampAsSqlTimestamp, getTimestampAsSqlTimestamp, getTimestampAsTimestamp, getTimestampAsTimestamp, getVarbinary, getVarbinary, getVarbinaryLen, resetRowPosition, wasNull
-
Field Details
-
MAX_SERIALIZED_TABLE_LENGTH
public static final int MAX_SERIALIZED_TABLE_LENGTHSize 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
String representation ofMAX_SERIALIZED_TABLE_LENGTH
.
-
-
Constructor Details
-
VoltTable
Create an empty table from column schema. WhileVoltTable(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
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
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
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 anVoltTable
. -
cloneRow
Get a newVoltTableRow
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 classVoltTableRow
- Returns:
- A new
VoltTableRow
instance with the same position as this table.
-
getColumnName
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
Description copied from class:VoltTableRow
Return thetype
of the column with the specified index.- Specified by:
getColumnType
in classVoltTableRow
- Parameters:
index
- Index of the column- Returns:
VoltType
of the column
-
getColumnIndex
Description copied from class:VoltTableRow
Return the index of the column with the specified column name.- Specified by:
getColumnIndex
in classVoltTableRow
- Parameters:
name
- Name of the column- Returns:
- Index of the column
-
fetchRow
Return aVoltTableRow
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
Append arow
from anotherVoltTable
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
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 isnull
. UseVoltTableRow.wasNull()
instead.- Returns:
- The integer row value.
-
addTable
Add all rows fromother
into this VoltTable. Both tables must have the exact same schema including column names.- Parameters:
other
-VoltTable
to add to this table- Throws:
IllegalArgumentException
- ifother
is not compatible with this table
-
addTableWithExtraColumns
-
addTableWithLessColumns
-
addTables
Add all rows fromtables
into this VoltTable. All tables must have the exact same schema including column names.- Parameters:
tables
-Collection
ofVoltTable
s to add to this table- Throws:
IllegalArgumentException
- if any table intables
is not compatible with this table
-
toString
Returns aString
representation of this table. Resulting string will contain schema and all data and will be formatted. -
varbinaryToPrintableString
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
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
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
Get a JSON representation of this table.- Specified by:
toJSONString
in interfaceorg.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
Check to see if this table has the same contents as the provided table. This is notObject.equals(Object)
because we don't want to provide all of the additional contractual requirements that go along with it, such as implementingObject.hashCode()
.- Parameters:
other
- Table to compare to.- Returns:
- Whether the tables have the same contents.
-
hasSameContents
-
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
isfalse
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
- Iftrue
the table header will be included in the checksum- Returns:
- checksum of table
-
equals
Deprecated.Exists for unit testing, but probably shouldn't be called.An unreliable version ofObject.equals(Object)
that should not be used. Only present for unit testing. -
hashCode
Deprecated.This only throws. Doesn't do anything.Also overridesObject.hashCode()
since we are overridingObject.equals(Object)
. Throws anUnsupportedOperationException
.- Overrides:
hashCode
in classObject
- Throws:
UnsupportedOperationException
- if called.
-
clone
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 ofrows
and strings.
-
getRowCount
public final int getRowCount() -
getRowStart
protected final int getRowStart() -
getColumnCount
public final int getColumnCount()Description copied from class:VoltTableRow
Returns the number of columns in the table schema- Specified by:
getColumnCount
in classVoltTableRow
- 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
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() -
convertToHeapBuffer
public final void convertToHeapBuffer() -
getBuffer
Directly access the table's underlyingByteBuffer
. 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
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.
-