Develop a Python Client Query

Welcome to the Client APIs section of the crash course! So far, you've learned how to use Deephaven from the server itself. If you missed any of the previous sections, check out the links below:

This section of the crash course covers Deephaven Enterprise's client APIs. This guide discusses the Python client, which allows you to:

Create new workers
Interact with tables and objects on the server
Connect to existing Persistent Queries (PQs)
Create PQs
Run queries server-side
And more!

The Enterprise Python client is built on top of the Community Python client, giving you access to its rich feature set.

Installation

Install the Enterprise Python client from the wheel file available in your Deephaven Enterprise installation. If your system administrator has not given you the wheel file directly, you can copy it from the server to your local machine. It is found in the following location on every installation:

/usr/illumon/coreplus/latest/py/wheel/deephaven_coreplus_client-1.20240517.344-py3-none-any.whl

Deephaven always recommends the use of virtual environments for local development. Create and use a new virtual environment, and install the wheel with pip:

python -m venv .venv

./.venv/bin/pip install deephaven_coreplus_client-1.20240517.344-py3-none-any.whl

Alternatively, you may install the Deephaven Core+ client from PyPi:

python -m venv .venv

./.venv/bin/pip install deephaven_coreplus_client==1.20240517.344

Only certified builds are published to PyPi. If you are using a pre-release or candidate build, your version may not be available. In that case, you must install the package using the wheel from your Deephaven Core+ installation.

To use the client in Jupyter, also install jupyterlab and deephaven-ipywidgets:

python -m venv .venv

./.venv/bin/pip install "deephaven-ipywidgets[client]" jupyterlab deephaven_coreplus_client-1.20240517.344-py3-none-any.whl

Then activate your venv:

source .venv/bin/activate

For a list of Enterprise Python client requirements, see the file /usr/illumon/coreplus/latest/py/resources/frozen-requirements-client-1.20240517.344.txt on your Enterprise installation.

Create a session

The first and most important step when using the Python client is to create a session. A session is a connection to the Deephaven server that allows you to authenticate with the server, create tables, PQs, and more. A SessionManager creates a session. It requires one of the following two things to connect to the server:

A URL to a connection.json file
A JSON object with the connection details

All Deephaven servers expose a connection.json file. Connecting to a server via this file is simple:

from deephaven_enterprise.client.session_manager import SessionManager

connection_json = "https://deephaven-host:8000/iris/connection.json"

session_mgr = SessionManager(connection_json)

Note

This example uses port 8000. Your server may use a different port. Typically, the port is 8123 for servers without Envoy and 8000 for servers with Envoy.

Authenticate

You should already have login credentials for the server. Use them to authenticate with the server:

session_mgr.password("username", "password")

Now that you're logged in, you can start doing things with Deephaven!

Use the client

Create a new worker

A common use case for the client is to create a new worker and run queries on it. The following code connects to a new unnamed worker with 4GB of memory:

session = session_mgr.connect_to_new_worker(name=None, heap_size_gb=4.0)

Log readout after running the above query

Run queries on the worker

The Python client has some built-in methods, like ones to consume static and ticking tables:

static_table = session.historical_table(
    namespace="LearnDeephaven", table_name="StockTrades"
)

ticking_table = session.live_table(
    namespace="DbInternal", table_name="ProcessEventLog"
).tail(100)

print(f"Static table: {static_table}\n")
print(f"Ticking table: {ticking_table}")

Log readout from the above print statements

The client can also run queries on the server:

my_query = "\n".join(
    [
        "from deephaven import time_table",
        "from deephaven import empty_table",
        "static_table = db.historical_table(namespace='LearnDeephaven', table_name='StockTrades')",
        "ticking_table = db.live_table(namespace='DbInternal', table_name='ProcessEventLog').tail(100)",
    ]
)

session.run_script(my_query)

Workers should be closed once you're done with them:

session.close()

Connect to a PQ

Instead of creating a new temporary worker, you can also connect to an existing PQ:

pq_session = session_mgr.connect_to_persistent_query("MyPersistentQuery")

my_ticking_table = pq_session.open_table("ticking_table")
print(f"Ticking table has {my_ticking_table.size} rows.")

pq_session.close()

Close the `SessionManager` object

Once your Python code is done performing operations on PQs, close the SessionManager object:

session_mgr.close()

Jupyter

You can also use the Python client from Jupyter. To do so, follow all of the same steps presented in installation, but be sure also to install the deephaven-ipywidgets package, which allows you to display tables and other Deephaven objects in Jupyter.