JavaScript API Docs

The iris namespace

The Deephaven Web API provides similar functionality as the client GUI. The following documentation details the available class types, methods, properties, and events. "namespace" here refers to the fact that using any of these objects requires an "iris." prefix.

Class Client

Simple client object used to connect to the Deephaven installation and interact with it.

Constructor

  • new iris.Client(websocketUrl) - Creates a connection to the given Deephaven webserver.

Methods

  • login(creds):Promise<void> - Username and password or other token to be supported by the current installation's auth server. The returned Promise will hold no value, and the request parameter will depend on how the installation is configured to handle auth. Optionally there may be an operateAs key in the credentials objects, allowing the authenticated user to see content as if they were another user, if they have permission to do so.
  • getKnownConfigs():QueryInfo[] - Get known Query Configs that this client is already aware of. It is possible that this list is empty right after connecting; ensure you are subscribed to the configadded and related events to get updates if necessary. For a simple view showing available Query Configs, you can get the known queries and subscribe to later changes, and then remove the event handler when the view goes away.
  • getServerConfigValues():Promise<ServerConfigValues> - Get the current configuration values for the server.
  • createAuthToken(String service):Promise<String> - Create an auth token for the given service. This is useful for creating tokens to be used in other contexts, such as when connecting to a Core+ query.
  • addEventListener(String type, function listener):Function - Listen for events on the main connection. Returns a convenience function to remove the event listener for you.
  • removeEventListener(String type, function listener) - Allow for manual "normal" event handler removal.
  • disconnect() - Log out and disconnect from the server.

Events

  • connect - Indicates that the initial connection has been established.
  • disconnect - Indicates that the connection was lost and some messages may be delayed until reconnect.
  • reconnect - Indicates that the client has automatically reconnected to the server.
  • configadded - event.detail is the new QueryInfo (see below).
  • configremoved - event.detail is the deleted QueryInfo.
  • configupdated - event.detail is the modified QueryInfo.
  • requestfailed - Indicates that there was an error communicating with the server.

Class QueryInfo

Describes a given persistent query configuration and its status.

Properties

  • String serial - Unique identifier for this configuration, intended for internal use.
  • String scriptLanguage - The language used to write the script that this configuration runs.
  • String configurationType - The type of this configuration (e.g., "Live Query (Script)", "Live Query Replay - (ReplayScript)", "Import - JDBC")
  • String name - Human readable name identifying this configuration.
  • String status - The current status of this configuration.
  • String[] tables - The unique, human-readable names of all tables in this query configuration.
  • String[] scheduling - Describes the schedule that this query is run on, if any.

Methods

  • getTable(String tableName):Promise<Table> - Load the named table, with columns and size information already fully populated.
  • getTableMap(String tableMapName):Promise<TableMap> - Load the named TableMap, with all keys that can be used to access underlying tables. Note that unlike tables, TableMap names are not published as part of the QueryInfo, so each use of the TableMap must either follow some naming convention from an existing table, or must already know the TableMap's name.

Events

  • requestfailed - Indicates that there was an error communicating with the worker for this query configuration.

Class Table

Provides access to data in a table. Note that several methods present their response through Promises. This allows the client to both avoid actually connecting to the server until necessary, and also will permit some changes not to inform the UI right away that they have taken place.

Properties

  • Column[] columns - Read-only. The columns that are present on this table. This is always all possible columns. If you specify fewer columns in .setViewport(), you will get only those columns in your ViewportData.
  • Number size - Read-only. The total count of rows in the table. The size can and will change; see the sizechanged event for details.
  • Number totalSize - Read-only. The total count of the rows in the table, excluding any filters. Unlike size, changes to this value will not result in any event.
  • Sort[] sort - Read-only. An ordered list of Sorts to apply to the table. To update, call applySort(). Note that this getter will return the new value immediately, even though it may take a little time to update on the server. You may listen for the sortchanged event to know when to update the UI.
  • FilterCondition[] filter - Read-only. An ordered list of Filters to apply to the table. To update, call applyFilter(). Note that this getter will return the new value immediately, even though it may take a little time to update on the server. You may listen for the filterchanged event to know when to update the UI.
  • String[] customColumns - Read-only. An ordered list of custom column formulas to add to the table, either adding new columns or replacing existing ones. To update, call applyCustomColumns().
  • boolean hasInputTable - Read-only. True if this table represents a user Input Table (created by InputTable.newInputTable). When true, you may call .inputTable() to add or remove data from the underlying table.
  • TotalsTableConfig totalsTableConfig - The default configuration to be used when building a TotalsTable for this table.

Methods

  • applySort(Sort[]):Sort[] - Replace the currently set sort on this table. Returns the previously set value. Note that the sort property will immediately return the new value, but you may receive update events using the old sort before the new sort is applied, and the sortchanged event fires. Reusing existing, applied sorts may enable this to perform better on the server. The updated event will also fire, but rowadded and rowremoved will not.
  • applyFilter(FilterCondition[]):FilterCondition[] - Replace the currently set filters on the table. Returns the previously set value. Note that the filter property will immediately return the new value, but you may receive update events using the old filter before the new one is applied, and the filterchanged event fires. Reusing existing, applied filters may enable this to perform better on the server. The updated event will also fire, but rowadded and rowremoved will not.
  • applyCustomColumns(String[]):String[] - Replace the current custom columns with a new set. These columns can be used when adding new filter and sort operations to the table, as long as they are present.
  • setViewport(Number firstRow, Number lastRow, Column[]= columns, Number= updateIntervalMs):TableViewportSubscription - If the columns parameter is not provided, all columns will be used. If the updateIntervalMs parameter is not provided, a default of one second will be used. Until this is called, no data will be available. Invoking this will result in events to be fired once data becomes available, starting with an updated event and a rowadded event per row in that range. The returned object allows the viewport to be closed when no longer needed.
  • subscribe(Column[] columns, Number= updateIntervalMs):TableSubscription - Creates a subscription to the specified columns, across all rows in the table. The optional parameter updateIntervalMs may be specified to indicate how often the server should send updates, defaulting to one second if omitted. Useful for charts or taking a snapshot of the table atomically. The initial snapshot will arrive in a single event, but later changes will be sent as updates. However, this may still be very expensive to run from a browser for very large tables. Each call to subscribe creates a new subscription, which must have close() called on it to stop it, and all events are fired from the TableSubscription instance.
  • getViewportData():Promise<ViewportData> - Gets the currently visible viewport. If the current set of operations has not yet resulted in data, it will not resolve until that data is ready.
  • copy():Promise<Table> - Creates a new copy of this table, so it can be sorted and filtered separately, and maintain a different viewport.
  • addEventListener(String type, function listener):Function - Listen for events on this table. Returns a cleanup function.
  • removeEventListener(String type, function listener) - Removes an event listener added to this table.
  • close() - Indicates that this Table instance will no longer be used, and its connection to the server can be cleaned up.
  • selectDistinct(Column[]):Promise<Table> - Returns a new table containing the distinct tuples of values from the given columns that are present in the original table. This table can be manipulated as any other table. Sorting is often desired as the default sort is the order of appearance of values from the original table.
  • findColumn(String named):Column - Retrieve a column by the given name. You should prefer to always retrieve a new Column instance instead of caching a returned value.
  • findColumns(String[] named):Column[] - Retrieve multiple columns specified by the given names.
  • inputTable():Promise<InputTable> - If .hasInputTable is true, you may call this method to gain access to an InputTable object which can be used to mutate the data within the table. If the table is not an Input Table, the promise will be immediately rejected.
  • getTotalsTable(TotalsTableConfig= config):Promise<TotalsTable> - Returns a promise that will resolve to a Totals Table of this table. This table will obey the configurations provided as a parameter, or will use the table's default if no parameter is provided, and be updated once per second as necessary. Note that multiple calls to this method will each produce a new TotalsTable which must have close() called on it when not in use.
  • getGrandTotalsTable(TotalsTableConfig= config):Promise<TotalsTable> - Returns a promise that will resolve to a Totals Table of this table, ignoring any filters. See getTotalsTable() above for more specifics.

Events

  • sizechanged - The table size has updated, so live scrollbars and the like can be updated accordingly.
  • updated - event.detail is the currently visible window, the same as if getViewportData() was called and resolved. Listening to this event removes the need to listen to the finer grained events below for data changes. In contrast, using the finer grained events may enable only updating the specific rows which saw a change.
  • rowadded - Finer grained visibility into data being added, rather than just seeing the currently visible viewport. Provides the row being added, and the offset it will exist at.
  • rowremoved - Finer grained visibility into data being removed, rather than just seeing the currently visible viewport. Provides the row being removed, and the offset it used to exist at.
  • rowupdated - Finer grained visibility into data being updated, rather than just seeing the currently visible viewport. Provides the row being updated and the offset it exists at.
  • sortchanged - Indicates that a sort has occurred, and that the UI should be replaced with the current viewport.
  • filterchanged - Indicates that a filter has occurred, and that the UI should be replaced with the current viewport.
  • customcolumnschanged - Indicates that columns for this table have changed, and column headers should be updated.
  • requestfailed - Indicates that an error occurred on this table on the server or while communicating with it. The message will provide more insight, but recent operations were likely unsuccessful and may need to be reapplied.

Class Column

Describes the structure of the column, and if desired can be used to get access to the data to be rendered in this column.

Methods

  • get(Row):Any - Returns the value for this column in the given row. Type will be consistent with the type of the Column.
  • filter():FilterValue - Creates a new value for use in filters based on this column. Used either as a parameter to another filter operation, or as a builder to create a filter operation.
  • sort():Sort - Creates a sort builder object, to be used when sorting by this column.

Properties

  • Number index - Internal index of the column in the table, to be used as a key on the Row.
  • String type - Type of the row data that can be found in this column.
  • String name - Label for this column.

Class Sort

Describes a Sort present on the table. No visible constructor, created through the use of Column.sort(), will be tied to that particular column data. Sort instances are immutable, and use a builder pattern to make modifications. All methods return a new Sort instance.

Methods

  • asc():Sort - Builds a Sort instance to sort values in ascending order.
  • desc():Sort - Builds a Sort instance to sort values in descending order.
  • abs():Sort - Builds a Sort instance which takes the absolute value before applying order.

Properties

  • Column column - The column which is sorted.
  • String direction - The direction of this sort, either ASC or DESC.
  • boolean isAbs - True if the absolute value of the column should be used when sorting; defaults to false.

Class FilterValue

Describes data that can be filtered, either a column reference or a literal value. Used this way, the type of a value can be specified so that values which are ambiguous or not well supported in JS will not be confused with Strings or imprecise numbers (e.g., nanosecond-precision date values). Additionally, once wrapped in this way, methods can be called on these value literal instances. These instances are immutable - any method called on them returns a new instance.

Static factory methods

  • ofString(?):FilterValue - Constructs a string for the filter API from the given parameter.
  • ofNumber(?):FilterValue - Constructs a number for the filter API from the given parameter. Can also be used on the values returned from Row.get for DateTime values.
  • ofDateTime(?):FilterValue - Constructs a datetime for the filter API from the given parameter (not yet supported).
  • ofBoolean(?):FilterValue - Constructs a boolean for the filter API from the given parameter.

Methods

  • eq(FilterValue):FilterCondition - Returns a filter condition checking if the current value is equal to the given parameter.
  • eqIgnoreCase(FilterValue):FilterCondition - Returns a filter condition checking if the current value is equal to the given parameter, ignoring differences of upper vs lower case.
  • notEq(FilterValue):FilterCondition - Returns a filter condition checking if the current value is not equal to the given parameter.
  • notEqIgnoreCase(FilterValue):FilterCondition - Returns a filter condition checking if the current value is not equal to the given parameter, ignoring differences of upper vs lower case.
  • greaterThan(FilterValue):FilterCondition - Returns a filter condition checking if the current value is greater than the given parameter.
  • lessThan(FilterValue):FilterCondition - Returns a filter condition checking if the current value is less than the given parameter.
  • greaterThanOrEqualTo(FilterValue):FilterCondition - Returns a filter condition checking if the current value is greater than or equal to the given parameter.
  • lessThanOrEqualTo(FilterValue):FilterCondition - Returns a filter condition checking if the current value is less than or equal to the given parameter.
  • in(FilterValue[]):FilterCondition - Returns a filter condition checking if the current value is in the given set of values.
  • inIgnoreCase(FilterValue[]):FilterCondition - Returns a filter condition checking if the current value is in the given set of values, ignoring differences of upper vs lower case.
  • notIn(FilterValue[]):FilterCondition - Returns a filter condition checking that the current value is not in the given set of values.
  • notInIgnoreCase(FilterValue[]):FilterCondition - Returns a filter condition checking that the current value is not in the given set of values, ignoring differences of upper vs lower case.
  • contains(FilterValue):FilterCondition - Returns a filter condition checking if the given value contains the given string value.
  • isTrue():FilterCondition - Returns a filter condition checking if the current value is a true boolean.
  • isFalse():FilterCondition - Returns a filter condition checking if the current value is a false boolean.
  • isNull():FilterCondition - Returns a filter condition checking if the current value is a null value.
  • invoke(String, ...?):FilterCondition - Returns a filter condition invoking the given method on the current value, with the given parameters. Currently supported functions that can be invoked on a String:
    • startsWith - Returns true if the current string value starts with the supplied string argument.
    • endsWith - Returns true if the current string value ends with the supplied string argument.
    • matches - Returns true if the current string value matches the supplied string argument used as a Java regular expression.
    • contains - Returns true if the current string value contains the supplied string argument. When invoking against a constant, this should be avoided in favor of FilterValue.contains.

Class FilterCondition

Describes a filter which can be applied to a table. Replacing these instances may be more expensive than reusing them. These instances are immutable - all operations that compose them to build bigger expressions return a new instance.

Methods

  • not():FilterCondition - Returns the opposite of this condition.
  • and(...FilterCondition):FilterCondition - Returns a condition representing the current condition logically ANDed with the other parameters.
  • or(...FilterCondition):FilterCondition - Returns a condition representing the current condition logically ORed with the other parameters.
  • toString():String - Returns a string suitable for debugging showing the details of this condition.

Properties

  • Column[] columns - The columns tested in some way by this filter (not yet supported).

Static functions

  • search(FilterValue):FilterCondition - Returns a filter condition which will check if the given value can be found in any supported column on whatever table this FilterCondition is passed to. This FilterCondition is somewhat unique in that it need not be given a column instance, but will adapt to any table. On numeric columns, with a value passed in which can be parsed as a number, the column will be filtered to numbers which equal, or can be "rounded" effectively to this number. On String columns, the given value will match any column which contains this string in a case-insensitive search.
  • invoke(String, ...FilterValue):FilterCondition - Returns a filter condition invoking a static function with the given parameters. Currently supported Deephaven static functions:
    • contains - Given two strings, yields true if the first string contains the second.
    • inRange - Given three comparable values, returns true if the first is less than the second but greater than the third.
    • isInf - Returns true if the given number is "infinity".
    • isNaN - Returns true if the given number is "not a number".
    • isNormal - Returns true if the given number is not null, is not infinity, and is not "not a number".
    • startsWith - Returns true if the first string starts with the second string.
    • endsWith - Returns true if the first string ends with the second string.
    • matches - Returns true if the first string argument matches the second string used as a Java regular expression.
    • contains - Returns true if the first string argument contains the second string as a substring.

Class ViewportData

Contains data in the current viewport. Also contains the offset to this data, so that the actual row number may be determined. Do not assume that the first row in rows is the first visible row, because extra rows may be provided for easier scrolling without going to the server.

Properties

  • Number offset - The index of the first returned row.
  • Row[] rows - An array of rows of data.
  • Column[] columns - A list of columns describing the data types in each row.

Class Row

This object may be pooled internally or discarded and not updated. Do not retain references to it. Instead, request the viewport again.

Methods

  • get(Column column):Any - Returns the data for the given column's cell.
  • getFormat(Column column):Format - Returns the format object for the given columns' cell.

Class Format

This object may be pooled internally or discarded and not updated. Do not retain references to it.

Properties

  • String color - Color to apply to the text, in #rrggbb format.
  • String backgroundColor - Color to apply to the cell's background, in #rrggbb format.
  • String numberFormat - Number format string() to apply to the value in this cell.

Class TableMap

Represents a set of Tables each corresponding to some key. The keys are available locally, but a call must be made to the server to get each Table. All tables will have the same structure.

The available TableMap instances are not listed in the QueryInfo object as tables are - the application must know the name of the TableMaps that will be available.

Note

Currently, keys can only be String values.

Methods

  • getKeys():String[] - The set of all currently known keys. This is kept up to date, so getting the list after adding an event listener for keyadded will ensure no keys are missed.
  • size():Number - The count of known keys.
  • close() - Indicates that this TableMap will no longer be used, removing subcriptions to updated keys, etc. This will not affect tables in use.
  • getTable(String):Promise<Table> - Fetches the table with the given key.

Events

  • keyadded - Indicates that a new key has been added to the array of keys, which can now be fetched with getTable.
  • requestfailed - Indicates that an error has occurred while communicating with the server.

Class InputTable

Represents a User Input Table, which can have data added to it from other sources.

You may add individual rows using dictionaries of key-value tuples (representing columns by name), or add whole tables at once. Custom actions and deletion of rows are not yet supported.

Each table has one or more key columns, where each unique combination of keys will appear at most once in the table.

To view the results of the Input Table, you should use standard table operations on the InputTable's source Table object.

Properties

  • String[] keys - A list of the key columns, by name.
  • Column[] keyColumns - A list of the key Column objects.
  • String[] values - A list of the value columns, by name.
  • Column[] valueColumns - A list of the value Column objects.
  • Table table - The source table for this Input Table.

Methods

  • addTable(Table from):Promise<InputTable> - Add an entire table to this Input Table. Only column names that match the definition of the input table will be copied, and all key columns must have values filled in. This only copies the current state of the source table; future updates to the source table will not be reflected in the Input Table. The returned promise will be resolved to the same InputTable instance this method was called upon once the server returns.
  • addRow(Object from):Promise<InputTable> - Adds a single row to the table. For each key or value column name in the Input Table, we retrieve that javascript property at that name and validate it can be put into the given column type; we then batch all addRow requests within the current event loop, and send them all at once to be inserted on the server. Only basic primitive types, strings and arrays thereof are supported at this time.

Class TotalsTable

A simplistic Table, providing access to aggregation of the table it is sourced from. This table is always automatically subscribed to its parent, and adopts changes automatically from it. This class has limited methods found on Table. Instances of this type always have a size of one when no groupBy is set on the config, but may potentially contain as few as zero rows, or as many as the parent table if each row gets its own group.

When using the groupBy feature, it may be desireable to also provide a row to the user with all values across all rows. To achieve this, request the same Totals Table again, but remove the groupBy setting.

Properties

  • TotalsTableConfig totalsTableConfig - Read-only. The configuration used when creating this Totals Table.
  • Column[] columns - Read-only. The columns present on this table. Note that this may not include all columns in the parent table, and in cases where a given column has more than one aggregation applied, the column name will have a suffix indicating the aggregation used. This suffixed name will be of the form columnName + '__' + aggregationName.
  • Number size - Read-only. The total number of rows in this table. This may change as the base table's configuration, filter, or contents change.
  • Sort[] sort - Read-only. An ordered list of Sorts to apply to the table. To update, call applySort(). Note that this getter will return the new value immediately, even though it may take a little time to update on the server. You may listen for the sortchanged event to know when to update the UI.
  • FilterCondition[] filter - Read-only. An ordered list of Filters to apply to the table. To update, call applyFilter(). Note that this getter will return the new value immediately, even though it may take a little time to update on the server. You may listen for the filterchanged event to know when to update the UI.
  • String[] customColumns - Read-only. An ordered list of custom column formulas to add to the table, either adding new columns or replacing existing ones. To update, call applyCustomColumns().

Methods

  • getViewportData():Promise<ViewportData> - Gets the currently visible viewport. If the current set of operations has not yet resulted in data, it will not resolve until that data is ready.
  • setViewport(Number firstRow, Number lastRow, Column[]= columns) - Specifies the range of items to pass to the client and update as they change. If the columns parameter is not provided, all columns will be used. Until this is called, no data will be available. Invoking this will result in events to be fired once data becomes available, starting with an updated event and one rowadded event per row in that range.
  • findColumn(String named):Column - Retrieve a column by the given name. You should prefer to always retrieve a new Column instance instead of caching a returned value.
  • findColumns(String[] named):Column[] - Retrieve multiple columns specified by the given names.
  • close() - Indicates that the table will no longer be used, and resources used to provide it can be freed up on the server.
  • applySort(Sort[]):Sort[] - Replace the currently set sort on this table. Returns the previously set value. Note that the sort property will immediately return the new value, but you may receive update events using the old sort before the new sort is applied, and the sortchanged event fires. Reusing existing, applied sorts may enable this to perform better on the server. The updated event will also fire, but rowadded and rowremoved will not.
  • applyFilter(FilterCondition[]):FilterCondition[] - Replace the currently set filters on the table. Returns the previously set value. Note that the filter property will immediately return the new value, but you may receive update events using the old filter before the new one is applied, and the filterchanged event fires. Reusing existing, applied filters may enable this to perform better on the server. The updated event will also fire, but rowadded and rowremoved will not.
  • applyCustomColumns(String[]):String[] - Replace the current custom columns with a new set. These columns can be used when adding new filter and sort operations to the table, as long as they are present.
  • addEventListener(String type, function listener):Function - Listen for events on the main connection. Returns a convenience function to remove the event listener.
  • removeEventListener(String type, function listener) - Allow for manual "normal" event handler removal as well.

Events

All events that can fire on a Table can also fire from a TotalsTable, and can be interacted with in the same way.

Class TotalsTableConfig

Describes how a Totals Table will be generated from its parent table. Each table has a default (which may be null) indicating how that table was configured when it was declared, and each Totals Table has a similar property describing how it was created. Both the Table.getTotalsTable and Table.getGrandTotalsTable methods take this config as an optional parameter - without it, the table's default will be used, or if null, a default instance of TotalsTableConfig will be supplied.

This class has a no-arg constructor, allowing an instance to be made with the default values provided. However, any JS object can be passed in to the methods which accept instances of this type, provided their values adhere to the expected formats.

Properties

  • boolean showTotalsByDefault - Specifies if a Totals Table should be expanded by default in the UI. Defaults to false.
  • boolean showGrandTotalsByDefault - Specifies if a Grand Totals Table should be expanded by default in the UI. Defaults to false.
  • String defaultOperation - Specifies the default operation for columns that do not have a specific operation applied; defaults to "Sum".
  • Object.<String[]> operationMap - Mapping from each column name to the aggregation(s) that should be applied to that column in the resulting Totals Table. If a column is omitted, the defaultOperation is used.
  • String[] groupBy - Groupings to use when generating the Totals Table. One row will exist for each unique set of values observed in these columns. See also Table.selectDistinct.

Constants

Constants are declared to provide the name of each supported aggregation type.

  • COUNT - The total number of values in the specified column. Can apply to any type.
  • MIN - The minimum value in the specified column. Can apply to any column type which is Comparable in Java.
  • MAX - The maximum value in the specified column. Can apply to any column type which is Comparable in Java.
  • SUM - The sum of all values in the specified column. Can only apply to numeric types.
  • VAR - The variance of all values in the specified column. Can only apply to numeric types.
  • AVG - The average of all values in the specified column. Can only apply to numeric types.
  • STD - The standard deviation of all values in the specified column. Can only apply to numeric types.
  • FIRST - The first value in the specified column. Can apply to any type.
  • LAST - The last value in the specified column. Can apply to any type.
  • SKIP - Indicates that this column should not be aggregated.

Class TreeTable

Similar to a table, a Tree Table provides access to subscribed viewport data on the current hierarchy. A different Row type is used within that viewport, showing the depth of that node within the tree and indicating details about whether or not it has children or is expanded. The Tree Table itself then provides the ability to change if a row is expanded or not. Methods used to control or check if a row should be expanded or not can be invoked on a TreeRow instance, or on the number of the row (thus allowing for expanding/collapsing rows which are not currently visible in the viewport).

Events and viewports are somewhat different than tables, due to the expense of computing the expanded/collapsed rows and count of children at each level of the hierarchy, and differences in the data that is available.

  • There is no totalSize property.
  • The viewport is not un-set when changes are made to filter or sort, but changes will continue to be streamed in. It is suggested that the viewport be changed to the desired position (usually the first N rows) after any filter/sort change is made. Likewise, getViewportData() will always return the most recent data, and will not wait if a new operation is pending.
  • Custom columns are not supported.
  • The totalsTableConfig property is instead a method, and returns a promise so the config can be fetched asynchronously.
  • Totals Tables for trees vary in behavior between hierarchical tables and Roll-up Tables. This behavior is based on the original flat table used to produce the Tree Table - for a hierarchical table (i.e. Table.treeTable in the query config), the totals will include non-leaf nodes (since they are themselves actual rows in the table), but in a Roll-up Table, the totals only include leaf nodes (as non-leaf nodes are generated through grouping the contents of the original table).

Properties

  • Number size - The current number of rows given the table's contents and the various expand/collapse states of each node. (No totalSize is provided at this time; its definition becomes unclear between Roll-up and Tree Tables, especially when considering collapse/expand states).
  • Sort[] sort - The current sort configuration of this Tree Table.
  • FilterCondition[] filter - The current filter configuration of this Tree Table.
  • Column[] columns - The columns that can be shown in this Tree Table.
  • TotalsTableConfig totalsTableConfig - The default Totals Table configuration for the base table which this Tree Table is based on.

Methods

  • expand(Number|TreeRow) - Expands the given node, so that its children are visible when they are in the viewport. The parameter can be the row index, or the row object itself. Equivalent to setExpanded(row, true).
  • collapse(Number|TreeRow) - Collapses the given node, so that its children and descendents are not visible in the size or the viewport. The parameter can be the row index, or the row object itself. Equivalent to setExpanded(row, false).
  • setExpanded(Number|TreeRow, Boolean) - Specifies if the given node should be expanded or collapsed. If this node has children, and the value is changed, the size of the table will change.
  • isExpanded(Number|TreeRow):Boolean - Returns true if the given row is expanded, false otherwise. Equivalent to TreeRow.isExpanded, if an instance of the row is available.
  • setViewport(Number firstRow, Number lastRow, Column[]= columns)
  • getViewportData():Promise<ViewportData>
  • close() - Indicates that the table will no longer be used, and server resources can be freed.
  • applySort(Sort[]):Sort[] - Applies the given sort to all levels of the tree. Returns the previous sort in use.
  • applyFilter(FilterCondition[]):FilterCondition[] - Applies the given filter to the contents of the tree in such a way that if any node is visible, then any parent node will be visible as well even if that parent node would not normally be visible due to the filter's condition. Returns the previous sort in use.
  • findColumn(String):Column - Returns a column with the given name, or throws an exception if it cannot be found.
  • findColumns(String[]):Column[] - Returns an array with all of the named columns in order, or throws an exception if one cannot be found.
  • getTotalsTableConfig():Promise<TotalsTableConfig> - Fetches the Totals config for the table that this Tree Table was based on, so that the content of the flat table can be aggregated.
  • getTotalsTable(TotalsTableConfig):Promise<TotalsTable> - Constructs a new Totals Table from the given config, based on the current filter status of this Tree Table. If null or not provided, the default config (see getTotalsTableConfig()) will be used.
  • getGrandTotalsTable(TotalsTableConfig):Promise<TotalsTable> - Constructs a new Totals Table from the given config, ignoring any filters set on this Tree Table. If null or not provided, the default config (see getTotalsTableConfig()) will be used.
  • addEventListener(String type, function listener):Function - Listen for events on this Tree Table. Returns a cleanup function.
  • removeEventListener(String type, function listener) - Removes an event listener from this Tree Table.

Events

  • updated - event.detail is the currently visible viewport data based on the active viewport configuration.

Class TreeRow extends Row

Like Row, TreeRow represents visible rows in the table, but with additional properties to reflect the tree structure.

Properties

  • Boolean isExpanded - True if this node is currently expanded to show its children; false otherwise. Those children will be the rows below this one with a greater depth than this one.
  • Boolean hasChildren - True if this node has children and can be expanded; false otherwise. Note that this value may change when the table updates, depending on the table's configuration.
  • Number depth - The number of levels above this node; zero for top level nodes. Generally used by the UI to indent the row and its expand/collapse icon.

Class RollupConfig

Like TotalsConfig, RollupConfig supports an operation map indicating how to aggregate the data, as well as an array of column names which will be the layers in the roll-up tree, grouped at each level. An additional optional value can be provided describing the strategy the engine should use when grouping the rows.

Properties

  • String defaultOperation - Specifies the default operation for columns that do not have a specific operation applied. Without a value provided, the default is "Sum".
  • Object.<String[]> operationMap - Mapping from each column name to aggregation(s) that should be applied to that column in the resulting Roll-up Table. If a column is omitted, the defaultOperation is used.
  • String[] columns - Ordered list of columns to group by to form the hierarchy of the resulting Roll-up Table.
  • String strategy - Optional parameter indicating how the roll-up should be performed in the engine. Permitted values are DEFAULT, LINEAR, LINEAR_GROUPS, USE_EXISTING_GROUPS, CREATE_GROUPS, USE_EXISTING_GROUPS_LINEAR_REFRESH, CREATE_GROUPS_LINEAR_REFRESH, USE_EXISTING_GROUPS_LINEAR_GROUP_REFRESH, and CREATE_GROUPS_LINEAR_GROUP_REFRESH. If not set, DEFAULT will be used.

Constants

Constants are declared to provide the name of each supported aggregation type.

  • COUNT - The total number of values in the specified column. Can apply to any type. String value is "Count".
  • MIN - The minimum value in the specified column. Can apply to any column type which is Comparable in Java. String value is "Min".
  • MAX - The maximum value in the specified column. Can apply to any column type which is Comparable in Java. String value is "Max".
  • SUM - The sum of all values in the specified column. Can only apply to numeric types. String value is "Sum".
  • VAR - The variance of all values in the specified column. Can only apply to numeric types. String value is "Var".
  • AVG - The average of all values in the specified column. Can only apply to numeric types. String value is "Avg".
  • STD - The standard deviation of all values in the specified column. Can only apply to numeric types. String value is "Std".
  • FIRST - The first value in the specified column. Can apply to any type. String value is "First".
  • LAST - The last value in the specified column. Can apply to any type. String value is "Last".
  • SKIP - Indicates that this column should not be aggregated. String value is "Skip".

Class TableViewportSubscription

This object serves as a "handle" to a subscription, allowing it to be acted on directly or canceled outright. If you retain an instance of this, you have two choices - either only use it to call close() on it to stop the table's viewport without creating a new one, or listen directly to this object instead of the table for data events, and always call close() when finished. Calling any method on this object other than close() will result in it continuing to live on after setViewport is called on the original table, or after the table is modified.

Methods

  • close() - Stops this viewport from running, stopping all events on itself and on the table that created it.
  • setViewport(Number firstRow, Number lastRow, Column[]= columns) - Changes the rows and columns set on this viewport. This cannot be used to change the update interval.
  • getViewportData():Promise<ViewportData> - Gets the data currently visible in this viewport.
  • addEventListener(String type, function listener):Function - Listens for events on this viewport subscription. Returns a cleanup function.
  • removeEventListener(String type, function listener) - Removes an event listener on this viewport subscription.

Class TableSubscription

Represents a subscription to the table on the server. Changes made to the table will not be reflected here - the subscription must be closed and a new one optioned to see those changes. The event model is slightly different from viewports to make it less expensive to compute for large tables.

Properties

  • Column[] columns - The columns that were subscribed to when this subscription was created.

Methods

  • close() - Stops the subscription on the server.
  • addEventListener(String type, function listener):Function - Listens for events on this table subscription. Returns a cleanup function.
  • removeEventListener(String type, function listener) - Removes an event listener on this table subscription.

Events

  • updated - Indicates that some new data is available on the client, either an initial snapshot or a delta update. The detail field of the event will contain a TableSubscriptionEventData detailing what has changed, or allowing access to the entire range of items currently in the subscribed columns.

Class TableSubscriptionEventData

This class supports two ways of reading the table - checking the changes made since the last update, and reading all data currently in the table. While it is more expensive to always iterate over every single row in the table, it may in some cases actually be cheaper than maintaining state separately and updating only the changes, though both options should be considered.

The RangeSet objects allow iterating over the LongWrapper indexes in the table. Note that these "indexes" are not necessarily contiguous and may be negative, and represent some internal state on the server, allowing it to keep track of data efficiently. Those LongWrapper objects can be passed to the various methods on this instance to read specific rows or cells out of the table.

Properties

  • Row[] rows - A lazily computed array of all rows in the entire table.
  • RangeSet added - The ordered set of row indexes added since the last update.
  • RangeSet removed - The ordered set of row indexes removed since the last update.
  • RangeSet updated - The ordered set of row indexes updated since the last update.

Methods

  • get(LongWrapper index):Row - Reads a row object from the table, from which any subscribed column can be read.
  • getData(LongWrapper index, Column column):Object - Reads a specific cell from the table, from the specified row and column.
  • getFormat(LongWrapper index, Column column):Format - Reads the Format to use for a cell from the specified row and column.

Class RangeSet

This class allows iteration over non-contiguous indexes. In the future, this will support the EcmaScript 2015 Iteration protocol, but for now has one method which returns an iterator, and also supports querying the size. Additionally, we may add support for creating RangeSet objects to better serve some use cases.

Properties

  • Number size - The total count of items contained in this collection. In some cases this can be expensive to compute, and generally should not be needed except for debugging purposes, or preallocating space (i.e., do not call this property each time through a loop).

Methods

  • iterator():Iterator<LongWrapper> - Returns a new iterator over all indexes in this collection.

Protocol Iterator<T>

This is part of EcmaScript 2015, documented here for completeness. It supports a single method, next(), which returns an object with a Boolean named done (true if there are no more items to return; false otherwise), and optionally some T instance, value, if there was at least one remaining item.

The iris.i18n namespace

Class NumberFormat

Utility class to parse and format numbers, using the same format patterns as are supported by the standard Java implementation used in the Deephaven server and swing client.

Constructor

  • new iris.i18n.NumberFormat(pattern) - Creates a new number format instance. This generally should be avoided in favor of the static getFormat function, which will create and cache an instance so that later calls share the same instance.

Methods

  • parse(String text):Number - Parses the given text using this instance's pattern into a JS Number.
  • format(Object number):String - Formats the specified number (or Java long value) using this instance's pattern.

Static functions

  • getFormat(String pattern):NumberFormat - Returns a number format instance matching the specified format. If this format has not been specified before, a new instance will be created and stored for later reuse.
  • parse(String pattern, String text):Number - Parses the given text using the cached format matching the given pattern.
  • format(String pattern, Object number):String - Formats the specified number (or Java long value) using the cached format matching the given pattern string.

Class DateTimeFormat

Utility class to parse and format various date/time values, using the same format patterns as are supported by the standard Java implementation used in the Deephaven server and swing client.

As Deephaven internally uses nanosecond precision to record dates, this API expects nanoseconds in most use cases, with the one exception of the JS Date type, which is not capable of more precision than milliseconds. Note, however, that when passing nanoseconds as a JS Number there is likely to be some loss of precision, though this is still supported for easier interoperability with other JS code. The values returned by parse() will be an opaque object wrapping the full precision of the specified date, However, this object supports toString() and valueOf() to return a string representation of that value, as well as a asNumber() to return a JS Number value and a asDate() to return a JS Date value.

Caveats:

  • The D format (for "day of year") is not supported by this implementation at this time.
  • The %t format for short timezone code is not supported by this implementation at this time, though z will work as expected in the browser to emit the user's own timezone.

Constructor

  • new iris.i18n.DateTimeFormat(String pattern) - Creates a new date/time format instance. This generally should be avoided in favor of the static getFormat function, which will create and cache an instance so that later calls share the same instance.

Methods

  • format(Object date):String - Takes a variety of objects to interpret as a date, and formats them using this instance's pattern. Inputs can include a String value of a number expressed in nanoseconds, a Number value expressed in nanoseconds, a JS Date object (necessarily in milliseconds), or a wrapped Java long value, expressed in nanoseconds.
  • parse(String text):Object - Parses the given string using this instance's pattern, and returns a wrapped Java long value in nanoseconds.
  • parseAsDate(String text):Date - Parses the given string using this instance's pattern, and returns a JS Date object in milliseconds.

Static functions

  • getFormat(String pattern):DateTimeFormat - Returns a date format instance matching the specified format. If this format has not been specified before, a new instance will be created and stored for later reuse.
  • format(String pattern, Object date):String - Accepts a variety of input objects to interpret as a date, and formats them using the specified pattern. See the instance method for more details on input objects.
  • parse(String pattern, String text):Object - Parses the given input string using the provided pattern, and returns a wrapped Java long value in nanoseconds.
  • parseAsDate(String pattern, String text):Date - Parses the given input string using the provided pattern, and returns a JS Date - object in milliseconds.