deephaven_enterprise.client.controller

class ControllerClient(host=None, port=None, rpc_timeout_seconds=120, channel=None)

Bases: object

The ControllerClient connects to the Deephaven PersistentQueryController process.

You may subscribe to the state of Persistent Queries as well as create and modify them.

This class operates on the deephaven_enterprise.proto.persistent_query_pb2 structures.

Connect to the persistent query controller.

Parameters:

• host (Optional[str]) – the host to connect to, requires port

• port (Optional[int]) – the port to connect to, requires host

• rpc_timeout_seconds (int) – the timeout period in seconds for RPCs. Defaults to 120 if not provided.

• channel (Optional[Channel]) – an already configured gRPC channel (exclusive with host and port)

add_query(query_config)

Add a persistent query. A successful call to authenticate should have happened before this call.

Parameters:

query_config (PersistentQueryConfigMessage) – the configuration of the query to add.

Return type:

int

Returns:

the serial number of the created query

authenticate(token, timeout=None)

Authenticate to the controller using a token obtained from the AuthClient get_token method.

Parameters:

token (Token) – the token to use for authentication, must have a service of “PersistentQueryController”

Return type:

None

close()

Invalidate the clients cookie so that further operations do not take place with this client.

Return type:

None

delete_query(serial)

Delete a query. A successful call to authenticate should have happened before this call.

Parameters:

serial (int) – the serial number to delete

Return type:

None

get(serial, timeout_seconds=0)

Get a query from the map. If the query does not exist, throws a KeyError. A successful call to subscribe should have happened before this call.

The timeout_seconds parameter can be specified to wait for the query to exist before failing with KeyError. This is useful when you have just created the query, know it’s serial, but the controller has not yet published the state to you.

Parameters:

• serial (int) –

• timeout_seconds (float) –

Return type:

PersistentQueryInfoMessage

Returns:

the PersistentQueryInfoMessage associated with the serial number

static is_running(status)

Is the status from the query info running?

If not running and not terminal, then the query is in the initialization process.

static is_terminal(status)

Is the status from the query info terminal?

If not running and not terminal, then the query is in the initialization process.

make_temporary_config(name, heap_size_gb, server=None, extra_jvm_args=None, extra_environment_vars=None, engine='DeephavenCommunity', auto_delete_timeout=600, admin_groups=None, viewer_groups=None)

Create a configuration suitable for use as a temporary InteractiveConsole query. The worker uses the default DeephavenCommunity engine. This kind of query enables a client to use the controller to create workers for general use, in the same way Enterprise clients would have used the dispatcher. For options that are not represented in the arguments, the returned PersistentQueryConfigMessage can be modified before adding it to the controller.

Parameters:

• name (str) – the name of the persistent query. Defaults to None, which means a name based on the current time is used

• heap_size_gb (float) – the heap size of the worker

• server (Optional[str]) – the server to connect to. Defaults to None, which means the first available server

• extra_jvm_args (Optional[List[str]]) – extra JVM arguments for starting the worker. Defaults to None.

• extra_environment_vars (Optional[List[str]]) – extra Environment variables for the worker. Defaults to None.

• engine (str) – which engine (worker kind) to use for the backend worker. Defaults to None, which means “DeephavenCommunity”

• auto_delete_timeout (Optional[int]) – after how many seconds should the query be automatically deleted after inactivity. Defaults to ten minutes. If none, auto-delete is disabled. If zero, the query is deleted immediately after a client connection is lost

• admin_groups (Optional[List[str]]) – list of groups that may administer the query. Defaults to None, which means only the current user may administer the query.

• viewer_groups (Optional[List[str]]) – list of groups that may view the query. Defaults to None, which means only the current user may view the query.

Return type:

PersistentQueryConfigMessage

Returns:

a configuration suitable for passing to add_query.

map()

Retrieve a copy of the current persistent query state. A successful call to subscribe should have happened before this call.

Return type:

Dict[int, PersistentQueryInfoMessage]

Returns:

a map from serial number to persistent query info

ping()

Ping the controller and refresh our cookie. :return: True if the ping was sent, False if we had no cookie

restart_query(serials)

Restart one or more queries. A successful call to authenticate should have happened before this call.

Parameters:

serials (Union[Iterable[int], int]) – a query serial number, or an iterable of serial numbers

Return type:

None

set_auth_client(auth_client)

Authenticate using the given authentication client, which is stored as a local variable. If a controller operation fails with a gRPC unauthenticated exception; then we attempt to use the authentication client to create a new controller session. If the authentication client cannot produce tokens, then we cannot proceed.

subscribe()

Subscribe to persistent query state, and wait for the initial query state snapshot to be populated. A successful call to authenticate should have happened before this call.

After the subscription is complete, you may call the map method to retrieve the complete map or the get method to fetch a specific query by serial number.

Return type:

None