JavaScript

Deephaven's Open API provides an interface for external applications to access and present data, both through creating new queries or using existing ones. This guide describes how to use the JavaScript API to connect to Deephaven, discover tables, display data, and apply operations like sorting and filtering.

For a hands-on introduction with a complete, runnable example, see the JavaScript Crash Course. For detailed API reference, see the JavaScript API docs.

Key concepts

Before working with the Deephaven JavaScript API, you should understand some foundational web development concepts and how Deephaven's architecture works.

Web development prerequisites

The Deephaven JavaScript API relies on standard web technologies:

Promise — A fluent callback API in modern browsers. Most Deephaven API methods that communicate with the server return Promises, allowing you to handle asynchronous operations with .then() or async/await.
WebSocket — An outgoing TCP socket connection that can be created by JavaScript code in modern browsers. Deephaven uses WebSockets for real-time communication between your application and the server.
Web Worker — A distinct JavaScript process without access to the DOM, allowing work to be done in the background. The Deephaven API uses Web Workers to handle server messages without blocking your UI.

Deephaven architecture

A Deephaven Enterprise installation consists of several servers that your JavaScript client interacts with:

Authentication server — Handles authentication and authorization.
PQ Controller — Manages Persistent Queries and their configuration.
Configuration server — Manages most Deephaven server configuration.
Remote Query Dispatcher — Manages workers as needed.
Remote Query Processor (worker) — Performs queries as requested by Persistent Queries or client consoles.
Web API Service — Serves the Web IDE, hosts connection.json for service discovery, and proxies Web IDE connections to backend services.

When you connect via the JavaScript API, you authenticate once, and the API automatically manages Auth Tokens for connections to other servers. You don't need to manually handle token exchanges between servers.

How tables work

Deephaven tables have some important characteristics:

Table configuration is immutable — Sorting, filtering, or adjusting columns creates a new table rather than modifying the existing one. The API handles this transparently.
Viewport-based data loading — Table metadata (size, columns, sorts, filters) is kept up to date automatically, but actual table data only loads when you call setViewport.
Two table types — Preemptive tables always send all contents to the client. Non-preemptive tables let you specify which rows and columns you want updates for.

Column types

Each column in a Deephaven table has a type property indicating the Java type of its data. When you read values with row.get(column), the API converts them to appropriate JavaScript types:

String — Returned as JavaScript strings.
Number types (int, long, double, etc.) — Returned as JavaScript numbers. Note that JavaScript numbers have limited precision, so very large long values may lose precision.
Boolean — Returned as JavaScript booleans.
DateTime — Deephaven uses nanosecond precision internally. Values are returned as opaque wrapper objects that support toString, valueOf, asNumber (nanoseconds), and asDate (JavaScript Date in milliseconds).

When creating filter values, use the appropriate factory method to ensure type correctness:

FilterValue.ofString(value) — For string comparisons.
FilterValue.ofNumber(value) — For numeric comparisons, including DateTime values.
FilterValue.ofBoolean(value) — For boolean comparisons.

Connection and reconnection

The API provides events to monitor connection state:

connect — Fired when the initial connection is established.
disconnect — Fired when the connection is lost. Some messages may be delayed until reconnection.
reconnect — Fired when the client automatically reconnects to the server.

The API handles reconnection automatically. You don't need to manually reconnect, but you should listen for these events to update your UI appropriately (for example, showing a "reconnecting" indicator).

Error handling

Errors are communicated through requestfailed events on various objects:

Client — Errors communicating with the main server.
QueryInfo — Errors communicating with a specific worker.
Table — Errors during table operations. Recent operations may have failed and need to be reapplied.

Listen for these events to handle errors gracefully:

client.addEventListener("requestfailed", (e) => {
  console.error("Server communication error:", e.detail);
});

table.addEventListener("requestfailed", (e) => {
  console.error("Table operation failed:", e.detail);
  // Consider reapplying recent operations
});

Performance considerations

To keep your application responsive and minimize server load:

Reuse sort and filter objects — When possible, reuse existing Sort and FilterCondition instances rather than creating new ones. The server can optimize operations when it recognizes previously applied sorts and filters.
Close unused tables — Call table.close() when you're done with a table to free server resources.
Don't retain Row objects — Row objects may be pooled or discarded internally. Always request fresh viewport data rather than caching rows.
Size viewport appropriately — Request only the rows you need to display. You can specify an updateIntervalMs parameter to control how often the server sends updates (default is one second).
Use subscriptions carefully — Full table subscriptions via table.subscribe can be expensive for large tables. Prefer viewport-based access with setViewport when possible.

Deephaven glossary

Auth Token — An identifier from the Authentication server that allows a client to connect to a server and make requests. Tokens are single-use and expire after a configurable period (default is 5 minutes).
Open API — Allows access to Deephaven data without using Deephaven's own client.
Persistent Query — A scripted query running on a worker, available to multiple users, and manageable through the PQ Controller.
Query Config — Describes a Persistent Query, the script running on it, and the tables it makes available to users.
Reconnection Token — A signed identifier that allows a client to reconnect without providing credentials again. Must be periodically refreshed.
Table Definition — Metadata for a table, describing the columns and their types.

Loading the library

The JavaScript library is tied to the version of the server it connects to, so you typically load it from the server itself. The library resides at /irisapi/irisapi.nocache.js on the web server.

Include this script tag in your HTML file, replacing https://your-deephaven-server/ with your actual server URL:

<script
  src="https://your-deephaven-server/irisapi/irisapi.nocache.js"
  type="text/javascript"
></script>

Connecting and authenticating

To connect to Deephaven, create a dh.Client instance, wait for the connect event, then call login. The following example uses password authentication. Deephaven supports multiple authentication methods — see Authentication for other options like SAML and LDAP.

class MyApp {
  constructor() {
    // Connect to the server using WebSocket Secure (wss) for HTTPS servers.
    // Replace with your actual server URL.
    this.client = new dh.Client("wss://your-deephaven-server/socket");

    // Wait for the WebSocket connection before logging in
    this.client.addEventListener("connect", () => this.onConnect());

    // Handle disconnection and reconnection
    this.client.addEventListener("disconnect", () => {
      console.log("Disconnected from server");
    });
    this.client.addEventListener("reconnect", () => {
      console.log("Reconnected to server");
    });
  }

  onConnect() {
    // Login after the connection is established.
    // The 'type' specifies the authentication method (e.g., 'password', or custom handlers).
    this.client
      .login({
        username: "your-username",
        token: "your-password",
        type: "password",
      })
      .then(
        () => this.startApp(),
        (error) => console.error("Login failed:", error),
      );
  }

  startApp() {
    // After successful authentication, you can:
    // - Discover and subscribe to Persistent Queries
    // - Open tables and display their data
    // - Apply sorts, filters, and other operations
    console.log("Successfully connected and authenticated!");
  }
}

new MyApp();

The login method takes an object with three properties:

username — Your Deephaven username.
token — Your authentication credential (password, SSO token, etc.).
type — The authentication method to use. This must match an auth handler configured on your server.

After authentication, the API automatically manages WebSocket connections and token refreshes. You only need to add callbacks to Promises as needed.

Discovering Persistent Queries

Persistent Queries are collections of tables running on workers. You can discover available queries and subscribe to changes as they're added, removed, or updated.

The following example shows how to retrieve all known Persistent Queries and listen for changes:

startApp() {
  // Subscribe to Persistent Query lifecycle events
  this.client.addEventListener('configadded', (e) => {
    console.log('Query added:', e.detail.name);
    this.addQuery(e.detail);
  });
  this.client.addEventListener('configremoved', (e) => {
    console.log('Query removed:', e.detail.name);
    this.removeQuery(e.detail);
  });
  this.client.addEventListener('configupdated', (e) => {
    console.log('Query updated:', e.detail.name);
    this.updateQuery(e.detail);
  });

  // Fetch all currently known Persistent Queries
  this.client.getKnownConfigs().forEach((queryInfo) => this.addQuery(queryInfo));
}

addQuery(queryInfo) {
  console.log(`Processing query: ${queryInfo.name} [serial: ${queryInfo.serial}]`);

  // queryInfo.designated may be undefined if the query is not currently running
  const designated = queryInfo.designated;
  if (!designated) {
    console.log('  (no designated replica; query is not running)');
    return;
  }

  // Derive table names from designated.objects, filtering to Table/TreeTable types
  const objects = designated.objects || [];
  for (const obj of objects) {
    if (obj && (obj.type === 'Table' || obj.type === 'TreeTable')) {
      console.log(`  - Table: ${obj.name}`);
      this.addTable(queryInfo, obj.name);
    }
  }
}

removeQuery(queryInfo) {
  console.log(`Removing query: ${queryInfo.name}`);
  // Clean up any UI elements or references for this query
}

updateQuery(queryInfo) {
  console.log(`Updating query: ${queryInfo.name}`);
  // Handle query configuration changes
}

addTable(queryInfo, name) {
  // Create a TableSelector for this table (defined in the next section)
  // For Core+ support, use: new TableSelector(this.client, queryInfo, name)
  const selector = new TableSelector(queryInfo, name);
  // Wire up UI - when user clicks, load and display the table
  // For example: button.addEventListener('click', () => selector.onClick());
}

The queryInfo object contains:

name — The Persistent Query's display name.
serial — A unique identifier for this query instance.
designated — The designated replica (undefined if the query is not running).
designated.objects — An array of objects with name and type properties (e.g., Table, TreeTable, Figure).
designated.getTable(name) — A method to retrieve a specific table.

Opening and displaying tables

Connecting to a table can be expensive, so the API uses a lazy loading pattern. The TableSelector class (used by addTable above) stores a reference to the query and table name, then loads the table only when the user clicks. Once loaded, it creates a TableView to display the data.

The following example shows the TableSelector and TableView classes that complete the flow:

class TableSelector {
  constructor(queryInfo, tableName) {
    this.queryInfo = queryInfo;
    this.tableName = tableName;
  }

  // Returns a Promise that resolves to the table, or rejects if unavailable
  _loadTable() {
    if (!this.queryInfo.designated) {
      return Promise.reject(
        new Error(
          "No designated replica available for this query; cannot load table '"
            + this.tableName
            + "'.",
        ),
      );
    }
    return this.queryInfo.designated.getTable(this.tableName);
  }

  onClick() {
    // Load the table when user clicks, then display it
    this._loadTable()
      .then((table) => {
        const view = new TableView(this.tableName, table);
        view.render();
      })
      .catch((error) => {
        console.error("Failed to load table:", error.message);
      });
  }
}

class TableView {
  constructor(name, table) {
    this.name = name;
    this.table = table;
    this.viewport = null;
    this.sorts = [];
    this.filters = [];
  }

  render() {
    // Subscribe to the 'updated' event to receive data when the viewport changes
    // addEventListener returns a cleanup function for easy removal later
    this._cleanup = this.table.addEventListener("updated", (e) => {
      this.viewport = e.detail;
      this.drawViewport();
    });

    // Request the first 100 rows. This triggers the 'updated' event above.
    // Replace 0 and 99 with your desired row range.
    this.table.setViewport(0, 99, this.table.columns);
  }

  drawViewport() {
    if (!this.viewport) return;

    let rowNumber = this.viewport.offset;
    this.viewport.rows.forEach((row) => {
      this.drawRow(rowNumber++, row);
    });
  }

  drawRow(rowNumber, row) {
    // Iterate through columns to render each cell
    this.table.columns.forEach((column) => {
      const cellValue = row.get(column);
      // Render the cell using your preferred method
      console.log(`Row ${rowNumber}, ${column.name}: ${cellValue}`);
    });
  }

  dispose() {
    // Stop listening for updates (guard in case render() wasn't called)
    if (this._cleanup) {
      this._cleanup();
    }

    // Close the table if it won't be used again
    this.table.close();
  }
}

Key points:

setViewport(startRow, endRow, columns) — Tells the server which rows and columns you want. Data arrives via the updated event.
addEventListener — Returns a cleanup function. Call it to stop receiving updates.
table.columns — Contains column metadata including names and types.
row.get(column) — Retrieves the value for a specific column in a row.

Sorting and filtering

You can extend the TableView class (defined above) with methods to sort and filter data. The table's applySort and applyFilter methods apply the new configuration and return the previously applied sorts or filters (not Promises). The actual data update happens asynchronously — listen for sortchanged, filterchanged, or updated events, or call getViewportData() to wait for new data.

Add these methods to your TableView class:

class TableView {
  // ... constructor and render methods from above (sorts/filters already initialized) ...

  // Apply one or more sort operations
  // Example: view.setSort(table.columns[0].sort().asc())
  setSort(...sortOperations) {
    this.sorts = sortOperations;
    return this.table.applySort(this.sorts);
  }

  // Add a sort to existing sorts
  addSort(sortOperation) {
    this.sorts.push(sortOperation);
    return this.table.applySort(this.sorts);
  }

  // Apply one or more filter conditions
  // Example: view.setFilter(table.columns[0].filter().eq(dh.FilterValue.ofString('value')))
  setFilter(...filterConditions) {
    this.filters = filterConditions;
    return this.table.applyFilter(this.filters);
  }

  // Add a filter to existing filters
  addFilter(filterCondition) {
    this.filters.push(filterCondition);
    return this.table.applyFilter(this.filters);
  }

  // Create a copy of this table to apply independent sorts/filters
  // Each copy maintains its own viewport and event subscriptions
  async clone(newName) {
    const cloneName = newName || `${this.name}_clone`;
    const clonedTable = await this.table.copy();
    return new TableView(cloneName, clonedTable);
  }
}

Example usage

// Assuming 'table' has columns: Symbol (String), Price (Number), Timestamp (Date)
const view = new TableView("MyTable", table);
const symbolColumn = table.columns.find((c) => c.name === "Symbol");
const priceColumn = table.columns.find((c) => c.name === "Price");

// Sort by Symbol ascending (returns previous sorts, not a Promise)
view.setSort(symbolColumn.sort().asc());

// Filter for prices greater than 100 (use FilterValue for type correctness)
view.setFilter(priceColumn.filter().greaterThan(dh.FilterValue.ofNumber(100)));

// After changing sort or filter, set a new viewport and wait for data
table.setViewport(0, 99, table.columns);

// Option 1: Listen for the updated event (set up earlier in your code)
table.addEventListener("updated", (e) => {
  console.log("New data available:", e.detail);
});

// Option 2: Use getViewportData() to get a Promise for the next update
table.getViewportData().then((viewportData) => {
  console.log("Viewport data:", viewportData);
});

Cloning tables

Use table.copy when you want to apply different sorts or filters without affecting the original table. Each copy:

Fires its own events.
Maintains its own viewport.
Must be closed independently with table.close().

Server operation order

The applySort, applyFilter, and setViewport methods are synchronous setters that queue operations to be processed on the server. The server processes these operations in order, but the methods return immediately — you may continue receiving updates with the old sort/filter until the server applies the change.

To know when a change has taken effect:

Events — Listen for sortchanged, filterchanged, or updated events.
Promise — Call getViewportData() to get a Promise that resolves with the next viewport update.

Caution

When you change the sort or filter, the current viewport is cleared. You must set a new viewport after each sort or filter change.

When applying a single change, set the viewport immediately after:

// Apply a sort, then set the viewport (lastRow is inclusive, so 0-99 = 100 rows)
table.applySort([nameColumn.sort().desc()]);
table.setViewport(0, lastRow, visibleColumns);

When applying multiple changes, set the viewport only after the last change:

// Apply filter first
table.applyFilter([
  nameColumn.filter().eqIgnoreCase(dh.FilterValue.ofString("FOO")).not(),
]);

// Don't set viewport yet — another change is coming

// Apply sort
table.applySort([nameColumn.sort().asc()]);

// Now set the viewport after both changes (lastRow is inclusive)
table.setViewport(0, lastRow, visibleColumns);

Connecting to Core+ queries

Core+ queries use a different protocol than standard Enterprise queries. To work with Core+ tables, you need to dynamically load the Core+ API and create a separate authenticated connection.

The following example shows an extended TableSelector that handles both Enterprise and Core+ queries. Use this version instead of the simpler TableSelector above if your deployment includes Core+ workers:

class TableSelector {
  constructor(enterpriseClient, queryInfo, tableName) {
    this.enterpriseClient = enterpriseClient; // The dh.Client instance
    this.queryInfo = queryInfo;
    this.tableName = tableName;
  }

  // Check if this query uses the Core+ protocol
  async isCorePlusQuery() {
    const { workerKinds } = await this.enterpriseClient.getServerConfigValues();
    const workerKind = workerKinds?.find(
      ({ name }) => name === this.queryInfo.workerKind,
    );
    return workerKind?.protocols?.includes("Community") ?? false;
  }

  // Load the Core+ API from the worker's URL
  async loadCorePlusApi() {
    if (!this.queryInfo.designated) {
      throw new Error(
        "No designated replica available; cannot load Core+ API.",
      );
    }
    const api = (await import(this.queryInfo.designated.jsApiUrl)).default;
    return api;
  }

  // Create an authenticated Core+ client
  async createCorePlusClient(api) {
    if (!this.queryInfo.designated) {
      throw new Error(
        "No designated replica available; cannot create Core+ client.",
      );
    }
    const { grpcUrl, envoyPrefix } = this.queryInfo.designated;

    // Configure client options for Envoy proxy if needed
    const clientOptions = envoyPrefix
      ? { headers: { "envoy-prefix": envoyPrefix } }
      : undefined;

    const corePlusClient = new api.CoreClient(grpcUrl, clientOptions);

    // Get an auth token from the Enterprise client and use it to authenticate
    const token = await this.enterpriseClient.createAuthToken(
      "RemoteQueryProcessor",
    );
    await corePlusClient.login({
      type: "io.deephaven.proto.auth.Token",
      token,
    });

    return corePlusClient;
  }

  // Get a table, automatically handling Core+ vs standard queries
  async getTable() {
    if (await this.isCorePlusQuery()) {
      // Core+ query: load API, authenticate, and get table
      const api = await this.loadCorePlusApi();
      const corePlusClient = await this.createCorePlusClient(api);
      const connection = await corePlusClient.getAsIdeConnection();
      return connection.getObject({ name: this.tableName, type: "Table" });
    } else {
      // Standard query: use the Enterprise API directly
      if (!this.queryInfo?.designated?.getTable) {
        throw new Error(
          "Cannot load table: query is not running or no designated replica is available.",
        );
      }
      return this.queryInfo.designated.getTable(this.tableName);
    }
  }

  async onClick() {
    const table = await this.getTable();
    const view = new TableView(this.tableName, table);
    view.render();
  }
}

The Core+ connection flow:

Check the protocol — Query workerKinds to see if the query supports the Community protocol.
Load the API — Dynamically import the Core+ API from queryInfo.designated.jsApiUrl.
Authenticate — Create an auth token via enterpriseClient.createAuthToken and use it to log in to the Core+ client.
Get the connection — Call getAsIdeConnection to get an IDE-like connection.
Fetch the table — Use connection.getObject with the table name and type.

API design principles

The Deephaven JavaScript API is designed to give web developers a familiar experience:

Automatic connection management — After logging in, Auth Tokens are maintained automatically. Connections to other servers happen transparently.
Mutable table interface — While tables are immutable on the server, the API lets you treat them as mutable objects. It tracks server-side tables internally and creates new ones as needed.
Simple size tracking — Total table size is exposed through a property rather than requiring you to track changes across messages.
Cell-level formatting — Format information is available as additional detail on each cell, not as hidden columns.
Non-blocking operations — Most server communication happens via Web Workers, keeping your UI responsive. Methods that communicate with the server return Promises or fire events.