Use the JS API

The Deephaven JS API connects a browser application to a Deephaven Community Core instance. It handles the connection and authentication to the server. It runs code in a server console session. It also subscribes to table data, so your page stays current as the data updates in real time. The Deephaven web IDE is built on the same JS API.

A Node.js application can use the JS API too. The @deephaven/jsapi-nodejs package downloads the JS API from the server and loads it into Node.js.

In this guide, you'll learn how to create a basic web page that uses the JS API to create a table in Deephaven and display it. Then you'll extend the page to show a ticking table that updates live.

Prerequisites

  • A Deephaven server running locally on port 10000 with the Python console. See Launch Deephaven from pre-built images.
  • A static file server to host the page. This guide uses Python's built-in http.server. JDK 18 and later include jwebserver, which also works.
  • The Deephaven server must use pre-shared key (PSK) authentication. The code in this guide uses the key very-secret-password. Either start the server with that key, or replace very-secret-password in the code with your server's key.
    • To set the key, start the server with -Dauthentication.psk=very-secret-password.
    • In Docker, pass that option through START_OPTS, as Set a pre-shared key shows.

Create a simple web page

Create a folder, add an empty index.html file, and start a server to host it:

Tip

To use jwebserver instead, run jwebserver -p 8000 from the same folder.

Open http://localhost:8000/ in a browser to view index.html from the file server. At first, the page is blank, because index.html is empty.

Open index.html for editing, and add the following:

Refresh the page, and it shows the "Table data" heading. The import statement downloads the Deephaven JS API and makes its namespace available locally as dh. The inline script doesn't have any actual code yet.

Let's add some code to make the page do something. Add all the code in the following sections to the inline script in the body element of the page.

Connect to the server

First, open a connection to the server with a CoreClient:

Next, authenticate with login. This example uses pre-shared key (PSK) authentication with the key very-secret-password from the Prerequisites:

The login type and token depend on how your server is configured:

After the client connects and authenticates, get its IdeConnection with getAsIdeConnection. An IdeConnection starts console sessions on the server with startSession. The session type must match the server's console language, so start a python session:

Create and retrieve a table

Run the code that creates the table with runCode. This code creates a static table called remote_table with 10 rows and three columns: I, J, and K. Because it's Python code, be careful with indentation when creating the template string.

Retrieve the table as a JS API Table object. getObject takes the variable's type and name:

Display the table

Create a table header element (thead) with the table columns:

A viewport is the set of rows and columns that the client asks the server to send. A viewport subscription keeps that data up to date as a ticking table changes. It stays open until you close it.

How the page uses its subscription depends on the table:

  • For a static table such as remote_table, the page reads the data once and then closes the subscription to release its resources.
  • For a ticking table, the page leaves the subscription open and rebuilds the table body each time the subscription fires its "updated" event. Display a ticking table shows how.

remote_table is static, so the following code reads it once:

  1. createViewportSubscription asks the server for rows 0 through 9 of every column. dh.RangeSet.ofRange includes both ends, so that's all 10 rows.
  2. getViewportData waits for the data and returns it.
  3. The loop builds one tr element per row.
  4. close ends the subscription.

Retrieve the table element on the page and append the header and body to it:

Refresh the page. After the table loads, the browser shows its 10 rows under the "Table data" heading. I counts from 0 to 9, J holds its square, and K alternates between Hello and World.

Congratulations! You've used the JS API to create a table in Deephaven and display it in the browser.

Display a ticking table

The static table above never changes. The JS API's real strength is live data. A viewport subscription to a ticking table sends the browser each update to the rows it covers.

To try it, add a second heading and table element to the body of index.html, after the first table:

Then add the following code to the end of the inline script. It creates a time table that adds a row every second. reverse puts the newest row first, so rows 0 through 9 are always the 10 newest rows.

Next, subscribe to the first 10 rows. This time, keep the subscription open:

  1. createViewportSubscription asks for rows 0 through 9, as before.
  2. addEventListener listens for the subscription's "updated" event. The event fires when the first data arrives and again each time the server sends an update.
  3. Each time, the listener rebuilds the table body from event.detail.rows, which holds every row now in the viewport.

Refresh the page. Under "Ticking data", a new row appears at the top every second. Each row shows its Timestamp and a counter, X, that grows by 1 with each new row. The JS API delivers Timestamp as a DateWrapper. Its text form is the number of nanoseconds since the epoch, which is hard to read. So the listener checks each column's type. For a java.time.Instant column such as Timestamp, it calls dh.i18n.DateTimeFormat.format to show the value as a date and time in the browser's time zone.

The table keeps updating until you close the browser tab. To stop the updates sooner, call close on tickingSubscription.

Final product

The complete index.html file, with both tables, looks like this:

Note

The server hosts more JS API examples at http://localhost:10000/jsapi. table_basic.html builds a page like this one, but with two differences: