Create and use input tables

Input tables allow users to enter new data into tables in two ways: programmatically and manually through the UI.

In the first case, you add data with the add method of the table's InputTableUpdater, which works similarly to merge. In the second case, you click cells in the UI and type their contents, as in a spreadsheet program like Microsoft Excel.

Input tables come in two flavors:

• append-only
  • An append-only input table puts any entered data at the bottom. It is an append-only table.
• keyed
  • A keyed input table has one or more key columns whose values identify each row. You can replace or delete existing rows by key.

This guide shows how to create and use both types.

Create an input table

Append-only input tables use the AppendOnlyArrayBackedInputTable class, and keyed input tables use the KeyedArrayBackedInputTable class. To create an append-only input table, first import AppendOnlyArrayBackedInputTable:

You can create an input table from a pre-existing table or from a set of column definitions. Either source also works for a keyed input table. A key column holds values that identify each row, so no two rows share the same key value. With several key columns, no two rows share the same combination of values. The next two sections create append-only input tables, and Create a keyed input table shows how to add key columns.

From a pre-existing table

Here, we create an input table from a table that already exists in memory. The example creates that source table with emptyTable.

From column definitions

Here, we create an input table from a set of column definitions. Pass the columns as a TableDefinition built from ColumnDefinition objects.

The resulting table is initially empty and ready to receive data.

Create a keyed input table

To create a keyed input table, import KeyedArrayBackedInputTable and call make with a source table or a TableDefinition, followed by one or more key column names.

Let's first specify one key column.

In the case of multiple key columns, pass each column name as a separate argument.

When you create a keyed input table from a pre-existing table, the input table keeps one row per key. If several rows of the initial table share a key, the input table keeps the values from the last of those rows. With multiple key columns, a key is a combination of values. Take, for instance, the following table:

No two rows share the same combination of X and Y values, so a keyed input table with X and Y as key columns keeps all 10 rows:

Sym and Marker together take only four distinct combinations of values, so a keyed input table with Sym and Marker as key columns has four rows. Each row holds the values from the last source row with that combination:

Add data to the table

Programmatically

To add data to an input table programmatically, get its InputTableUpdater with InputTableUpdater.from(table). This object adds data to and removes data from the input table.

An append-only input table adds new rows to the end of the table. In a keyed input table, an added row whose key already exists replaces the existing row with that key, and the other added rows become new rows.

add blocks until Deephaven finishes adding the data. To add data without blocking, use addAsync.

addAsync takes an InputTableStatusListener, which Deephaven notifies when the queued addition succeeds or fails. InputTableStatusListener.DEFAULT does nothing on success and logs the failure to the server log. Problems that Deephaven detects before it queues the addition, such as a table whose column names or types don't match the input table, throw an exception from addAsync immediately instead of reaching the listener.

Deephaven processes asynchronous calls from the same thread in the order you make them, but it doesn't guarantee an order across threads. The following code block asynchronously adds a row with a new key, Jjj, and replaces the row with the existing key Aaa:

Manually

To manually add data to an input table, click the cell in which you wish to enter data, type the value, and press Enter.

A KeyedArrayBackedInputTable allows you to edit existing rows, while an AppendOnlyArrayBackedInputTable only allows you to add new rows. In a keyed input table, adding a row whose key already exists replaces the existing row with that key.

Here are some things to consider when manually entering data into an input table:

• Data added manually to a table must be of the correct type for its column. For instance, attempting to add a string value to an int column fails.
• Entering data in between populated cells and pressing Enter adds the data to the bottom of the column.

Delete data from a table

You can delete data only from a keyed input table. Calling delete or deleteAsync on an append-only input table throws an UnsupportedOperationException. To delete data from a keyed input table, use one of the following InputTableUpdater methods:

• delete: Synchronous deletion.
• deleteAsync: Asynchronous deletion.

To delete table data, supply a table that contains only the key columns, with the key values of the rows you wish to delete. For instance, the example in Programmatically creates a keyed input table whose key column is Strings, and gets its updater. The following code deletes the row with the key value Bbb:

To delete data asynchronously, use deleteAsync, which takes an InputTableStatusListener and follows the same ordering rules as addAsync. The following code block asynchronously deletes the row with the key value Ccc:

Enter clickable links in an input table

Input tables are a convenient way to try out clickable links, because you can type links directly into their cells. Any string column in Deephaven can contain a clickable link if the string is formatted correctly. See Add clickable links for examples of strings that are and aren't displayed as links.

Let's create an input table that we can add links to manually:

Related documentation

• Input table reference
• emptyTable
• Table types
• Add clickable links
• InputTableUpdater Javadoc