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.

Note

This guide assumes that you already have a Deephaven server running. See the Quickstart or the detailed installation guides for Docker or pip to get Deephaven installed. The examples connect to a server on port 10000 that uses pre-shared key authentication, which is how the Quickstart starts Deephaven.

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 (default localhost), its port (default 10000), and its authentication settings (default anonymous). A server started with a pre-shared key, as in the Quickstart, needs auth_type and auth_token:

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 auth_type and auth_token arguments must match how the server authenticates clients:

  • "Anonymous" (the default): no token is needed. Use this for a server started with anonymous authentication.
  • "Basic": the token is a "user:password" string.
  • The class name of a server authentication handler, such as "io.deephaven.authentication.psk.PskAuthenticationHandler" for pre-shared key authentication: the token must match what that handler expects, which for pre-shared key authentication is the key itself.

Once the connection has been established, you're ready to start using the Deephaven Python client.

2. A brief overview of the Python client design

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 — a table that updates as new data arrives (see table types) — called t. It doesn't. Methods like time_table return references to tables on the server, not the data itself. These references are represented with the Table class, which has methods that 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 tables and retrieve references

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 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 you must make the conversion 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. In this way, table references can often be used as if they were tables.

Note

The table operations here are not intended to demonstrate a broad overview of what Deephaven offers. They are only for demonstrating how such operations are used in the Python client context. For a brief overview of table operations, check out the Quickstart. For more details, visit the table operations section of the Crash Course.

All of the methods that have been implemented can be found in the Pydocs. These include 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 agg_by and update_by to learn more.

Table operations that require other tables as arguments, like join, are supported:

Even Deephaven's time-series joins like aj and raj are supported:

Learn more about Deephaven's join operations in the exact join guide and inexact 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:

6. Run scripts

The Python client can execute Python scripts on a Python Deephaven server with the run_script method. These scripts can include all of the Deephaven functionality that the server-side Python API supports. They should be encapsulated in strings:

Tables created with scripts can then be used directly in downstream queries:

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

For operations like these, the client-side table operations from section 4 are often more convenient than run_script.

7. Stream data with input tables

The Python client can create input tables on the server with the input_table method and stream data to them with add. This is useful when your data source runs outside the Deephaven server. The following example uploads data with import_table from section 3, using pyarrow (imported there as pa):

For a complete guide on streaming patterns, memory management, and input table types, see Client input tables.

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: