The Deephaven Client

A Client is the entry point for interacting with the Deephaven server. It is used to create new tables, import data to and export data from the server, and run queries on the server.

Methods

Public methods

• Client$new()

• Client$initialize_for_xptr()

• Client$initialize_for_target()

• Client$empty_table()

• Client$time_table()

• Client$open_table()

• Client$import_table()

• Client$ticket_to_table()

• Client$run_script()

• Client$close()

---

Method new()

Calls initialize_for_xptr() if the first argument is an external pointer, and initialize_for_target() if the first argument is a string. In the latter case, the remaining keyword arguments are passed to initialize_for_target().

Usage

Client$new(...)

Arguments

...

Either an external pointer to an existing client connection, or a string denoting the address of a running Deephaven server followed by keyword arguments to initialize_from_target().

---

Method initialize_for_xptr()

Initializes a Client object using a pointer to an existing client connection.

Usage

Client$initialize_for_xptr(xptr)

Arguments

xptr

External pointer to an existing client connection.

---

Method initialize_for_target()

Initializes a Client object and connects to a Deephaven server.

Usage

Client$initialize_for_target(
  target,
  auth_type = "anonymous",
  username = "",
  password = "",
  auth_token = "",
  session_type = "python",
  use_tls = FALSE,
  tls_root_certs = "",
  int_options = list(),
  string_options = list(),
  extra_headers = list()
)

Arguments

target

String denoting the address of a Deephaven server, formatted as "ip:port".

auth_type

String denoting the authentication type. Can be "anonymous", "basic", "psk", or any custom-built authenticator supported by the server. Default is "anonymous".

username

String denoting the username, which only applies if auth_type is "basic". Username and password should not be used in conjunction with auth_token. Defaults to an empty string.

password

String denoting the password, which only applies if auth_type is "basic". Username and password should not be used in conjunction with auth_token. Defaults to an empty string.

auth_token

String denoting the authentication token. When auth_type is "anonymous", it will be ignored; when auth_type is "basic", it must be "user:password" or left blank; when auth_type "psk", it must be the pre-shared key, when auth_type is a custom-built authenticator, it must conform to the specific requirement of that authenticator. This should not be used in conjunction with username and password. Defaults to an empty string.

session_type

String denoting the session type supported on the server. Currently, "python" and "groovy" are supported. Defaults to "python".

use_tls

Whether or not to use a TLS connection. Defaults to FALSE.

tls_root_certs

String denoting PEM encoded root certificates to use for TLS connection, or "" to use system defaults. Only used if use_tls == TRUE. Defaults to system defaults.

int_options

List of name-value pairs for int-valued options to the underlying grpc channel creation. Defaults to an empty list, which implies not using any channel options.

string_options

List of name-value pairs for string-valued options to the underlying grpc channel creation. Defaults to an empty list, which implies not using any channel options.

extra_headers

List of name-value pairs for additional headers and values to add to server requests. Defaults to an empty list, which implies not using any extra headers.

---

Method empty_table()

Creates an empty table on the server with size rows and no columns.

Usage

Client$empty_table(size)

Arguments

size

Non-negative integer specifying the number of rows for the new table.

Returns

TableHandle reference to the new table.

---

Method time_table()

Creates a ticking table on the server.

Usage

Client$time_table(period, start_time = "now")

Arguments

period

ISO-8601-formatted string specifying the update frequency of the new table.

start_time

Optional ISO-8601-formatted string specifying the start time of the table. Defaults to now.

Returns

TableHandle reference to the new table.

---

Method open_table()

Retrieves a reference to a named table on the server using its name.

Usage

Client$open_table(name)

Arguments

name

String denoting the name of the table to retrieve.

Returns

TableHandle reference to the named table.

---

Method import_table()

Imports a new table to the Deephaven server. Note that this new table is not automatically bound to a variable name on the server. See ?TableHandle for more information.

Usage

Client$import_table(table_object)

Arguments

table_object

R Data Frame, dplyr Tibble, Arrow Table, Arrow RecordBatchReader, or other supported table containing the data to import to the server.

Returns

TableHandle reference to the new table.

---

Method ticket_to_table()

Retrieves a reference to a named table in the server using its Arrow Flight ticket.

Usage

Client$ticket_to_table(ticket)

Arguments

ticket

String denoting the Arrow Flight ticket.

Returns

TableHandle reference to the table.

---

Method run_script()

Runs a script on the server. The script must be in the language that the server console was started with.

Usage

Client$run_script(script)

Arguments

script

String containing the code to be executed on the server.

---

Method close()

Closes the client connection. After this method is called, any further server calls will be undefined and will likely result in an error.

Usage

Client$close()

Examples

if (FALSE) { # \dontrun{
library(rdeephaven)

# connecting to Deephaven server
client <- Client$new("localhost:10000", auth_type = "psk", auth_token = "my_secret_token")

# create a data frame and push it to the server, retrieve a reference to it as a TableHandle
df <- data.frame(
  col1 = c(1, 2, 3),
  col2 = c("a", "b", "c"),
  col3 = c(TRUE, FALSE, TRUE)
)
th1 <- client$import_table(df)
as.data.frame(th1)

# give table referenced by 'th' a name on the server
th1$bind_to_variable("server_table")

# use client to execute script
client$run_script('server_table_new = server_table.update("col4 = col1 + 1")')

# retrieve reference to new table on the server
th2 <- client$open_table("server_table_new")
as.data.frame(th2)

# create table on server directly with table API and retrieve a reference to it as a TableHandle
th3 <- client$empty_table(10)$update("col1 = i")
as.data.frame(th3)

# create ticking table on the server and retrieve a reference to it as a TableHandle
th4 <- client$time_table("PT1S")$update("col1 = i")
Sys.sleep(5)
as.data.frame(th4)
Sys.sleep(5)
as.data.frame(th4)
Sys.sleep(5)
as.data.frame(th4)

# close client connection
client$close()
} # }