Deephaven Community Core Quickstart for the Python Client

Deephaven's Python client pydeephaven connects to a Deephaven server from any Python process, whether the server runs on your own machine or on a remote host. This guide walks you through installing pydeephaven, connecting to a server, creating and querying tables on the server, retrieving data, running scripts, and streaming data to the server.

1. Install pydeephaven and connect to a running server

pydeephaven requires Python 3.9 or later. Install it with pip, ideally inside a Python virtual environment to isolate it and its dependencies from other Python installs:

Now, start a Python interpreter, and let's get started!

The Deephaven Python client creates and maintains a connection to the server through a Session. A Session takes the server's hostname or IP address, its port, and its authentication settings. The hostname and port each have a default:

• host: the DH_HOST environment variable if it's set, otherwise localhost.
• port: the DH_PORT environment variable if it's set, otherwise 10000.

The auth_type and auth_token arguments must match how the server authenticates clients:

• "Anonymous" (the default): the server doesn't need a token. Use this for a server started with anonymous authentication.
• "Basic": the token is a "user:password" string. Use this for a server started with username/password authentication.
• A handler class name: the token must match what that handler expects. For example, "io.deephaven.authentication.psk.PskAuthenticationHandler" selects pre-shared key authentication, and its token is the key itself.

A server started with a pre-shared key, as in the Quickstart, needs the PSK handler class name and the key:

Replace deephaven.local with your server's hostname — localhost if the server runs on your machine. Replace YOUR_PASSWORD_HERE with the pre-shared key you set when you started the server (see the Quickstart).

The Session constructor connects to the server immediately, so you're ready to start using the Deephaven Python client.

2. Python client tables are references to server tables

The Session instance created above is the client's main line of communication with the server. Its methods run scripts on the server, create and fetch tables, and more.

Many of these methods appear to return tables. Take, for example, the time_table method:

This code appears to create a new ticking table called t. A ticking table updates as new data arrives. The code does create one on the server, but t doesn't hold that table's data. Methods like time_table return references to tables on the server, not the data itself. The Table class represents these references, and its methods mirror the table operations of a server-side Deephaven table. To pull a table's data into your Python process, see Retrieve data from the server.

3. Create, name, open, and import tables

The empty_table and time_table methods create new tables directly on the server. Section 2 already created the ticking table t with time_table. The following code creates a static table with empty_table and adds a column to each table:

Tables created in this way have no names on the server, so you can't open them by name, use them in server-side scripts, or see them in the Deephaven web IDE. To name them, use the bind_table method:

Use the open_table method to retrieve a reference to a named table:

If you have a local Python data structure that you want to convert to a Deephaven table on the server, use the import_table method. This method accepts only an Arrow table, so convert your data to one before calling import_table:

4. Table operations with the Python client

As described in section 2, Table objects have methods that mirror Deephaven table operations. As a result, you can often use table references as if they were tables.

The Table Pydocs list every method the class supports, including basic table operations like update, view, where, and sort:

To learn more about these table operations, see the guides on choosing a select method, filtering, and sorting.

The agg_by and update_by operations work with the functions from the pydeephaven.agg and pydeephaven.updateby Python modules:

Check out the guides on combined aggregations and rolling aggregations to learn more.

The client also supports table operations that take other tables as arguments, such as join:

The client even supports Deephaven's time-series joins, such as aj and raj:

Learn more about Deephaven's join operations in the exact join guide and time-series join guide.

5. Retrieve data from the server

Table references don't hold data. To pull a table's data into your Python process, use the to_arrow method, which takes a snapshot of the table and returns it as a pyarrow.Table. For a ticking table, the snapshot reflects the table at the moment you call to_arrow. The following example snapshots the group_stats aggregation from section 4:

6. Run scripts

The run_script method runs Python scripts on a Deephaven server that uses Python. These scripts can include all of the Deephaven functionality that the server-side Python API supports. For table operations that the Table class already supports, the client-side methods from section 4 are usually more convenient; run_script is for server-side Python that the client API doesn't cover. Pass each script to run_script as a string:

Later scripts can refer by name to tables that earlier scripts created:

Then, retrieve a reference to the resulting table with the open_table method:

7. Stream data with input tables

An input table is a table on the server that you can add rows to. Keyed input tables also let you update and delete rows by key. Input tables are useful when your data source runs outside the Deephaven server.

The Python client creates input tables with the input_table method and streams data to them with add. The following example builds its data with the pa module that section 3 imported. It uploads that data with import_table:

For a complete guide on streaming patterns, memory management, and input table types, see Send data to Deephaven from a Python client.

8. Close the session

When you're done, close the session with the close method:

You can also create a Session in a with statement, which closes the session automatically when the block exits:

9. What to do next

Now that you've gotten a brief introduction to the Deephaven Python client, we suggest heading to the Crash Course in Deephaven to learn more about Deephaven's real-time data platform. To go further with the Python client, see:

• Send data to Deephaven from a Python client for more input table patterns.
• Capture Python client tables with Barrage to subscribe to server tables from another Deephaven server.
• pydeephaven Pydocs for the full client API.