Deephaven Community Core Quickstart for the Python Client

Deephaven's Python client pydeephaven enables users to connect to a Deephaven server running anywhere in the world. This guide will walk you through installing pydeephaven, connecting to a server, and using the client to perform some real-time data tasks.

1. Install pydeephaven and connect to a running server

pydeephaven is easily installed with pip:

Now, fire up a Python session, and let's get started!

The Deephaven Python client creates and maintains a connection to the remote Deephaven server through a Session. To connect to a remote server with a Session, you must supply it with information about the remote server's hostname or URL, port, and authentication requirements. Here's an example:

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. It's used to run scripts on the server, create and fetch tables, and more. This functionality is facilitated by methods attached to the Session instance.

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. However, this is not the case - the Python client can only return references to tables on the server. These references are represented with a Table class, and that class has its own methods that mirror the table operations of a true Deephaven table.

3. Create tables and retrieve references

New tables are created directly on the server with the empty_table and time_table methods:

Tables created in this way do not yet have names on the server, so some Deephaven operations will not be possible. 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 will only accept an Arrow table, so you must make the conversion before calling import_table:

4. Table operations with the Python client

Table references represented as Tables have methods that mirror Deephaven table operations. In this way, table references can often be used as if they were tables.

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 seamlessly 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. Run scripts

The Python client can execute Python scripts on the 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:

The client-side table operations discussed above may be a more convenient way to perform such table operations.

6. 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.