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
10000with 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 includejwebserver, 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 replacevery-secret-passwordin 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.
- To set the key, start the server with
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:
- On a server with anonymous authentication, pass
{ type: dh.CoreClient.LOGIN_TYPE_ANONYMOUS }. - On a server with username/password authentication, pass
{ type: dh.CoreClient.LOGIN_TYPE_PASSWORD, username: "user", token: "password" }.
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:
createViewportSubscriptionasks the server for rows0through9of every column.dh.RangeSet.ofRangeincludes both ends, so that's all 10 rows.getViewportDatawaits for the data and returns it.- The loop builds one
trelement per row. closeends 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:
createViewportSubscriptionasks for rows0through9, as before.addEventListenerlistens for the subscription's"updated"event. The event fires when the first data arrives and again each time the server sends an update.- 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:
- It uses the deprecated
getTable,setViewport, andTable.getViewportDatacalls. This guide uses their replacements. - It logs in with anonymous authentication, so it runs only on a server that allows anonymous login.
Related documentation
- Table types
- Create a time table
- Launch Deephaven from pre-built images
- Pre-shared key authentication
- Anonymous authentication
- Username/password authentication
- Create an empty table
- JS API concepts
empty_tableupdate_viewtime_tablereverseempty_tablePydocupdate_viewPydoctime_tablePydocreversePydoc- JS API docs