---
title: Core+ R client
---

The R client allows you to:

- Create new workers.
- Interact with tables and objects on the server.
- Connect to existing [Persistent Queries (PQs)](../query-management/pq-overview.md).
- Run queries server-side.
- And more.

The Core+ R client is built on top of the [Community R client](https://docs.deephaven.io/core/client-api/r/). This guide covers basic R client usage and troubleshooting. For a crash course in the R client, see [Develop an R client query](../crash-course/develop-client-query/develop-r-query.md).

## Test the installation

The following R code loads the client and connects to a running Deephaven Enterprise server. It then creates a temporary PQ with a simple query, and displays the resultant ticking table.

```r
# These variables should be changed to match your server's configuration
# Note: The port number below is 8000 if your server uses Envoy, and 8123 otherwise
base_dhe_url = "https://your-deephaven-server.com:8000/iris"
dhe_user = "username"
dhe_password = "password"
new_pq_name = "PqForRClientTest"

library("rdnd")

sm <- SessionManager$new(descriptive_name="Core+ session manager", source=paste0(base_dhe_url, "/connection.json"))
sm$password_authentication(dhe_user, dhe_password, dhe_user)

pq_config_builder <- sm$make_temp_pq_config_builder(new_pq_name)
pq_config_builder$set_max_heap_size_gb(4)
client <- sm$add_query_and_connect(pq_config_builder)
client$run_script("from deephaven import time_table; my_table = time_table(\"PT0.1S\")")
my_table = client$open_table("my_table")

Sys.sleep(2)
df = my_table$as_data_frame()
print(df)
```

## Built-in R documentation

You can get more information about the Deephaven R client by consulting the built-in R documentation. In R, you can access the documentation for any function or package by using the `?` operator. To do this, simply type `?` followed by the name of the function or package you want to learn about.

You can try this:

```r
library("rdnd")
library("rdeephaven")

?rdnd
?rdeephaven
?SessionManager
?PqConfigBuilder
?DndClient
?Client
?Table
```

Additionally, you can use the `ls` method to list all the methods and fields on an object.

```r
library("rdnd")
library("rdeephaven")

connection_json <- "https://host.mydomain.com:8000/iris/connection.json"

sm <- SessionManager$new(
        descriptive_name=paste0("R session manager pid=", Sys.getpid()),
        source=connection_json)

new_pq_name <- "my_new_pq"

pq_config_builder <- sm$make_temp_pq_config_builder(new_pq_name)
pq_config_builder$set_max_heap_size_gb(4);
pq_config_builder$set_script_code("python")

session <- sm$add_query_and_connect(pq_config_builder$build());

t <- session$historical_table("LearnDeephaven", "StockTrades")

ls(sm)
ls(pq_config_builder)
ls(session)
ls(t)
```

## Troubleshooting

### Logging

The R client uses the C++ implementation of gRPC to exchange messages with a Deephaven server. gRPC has an internal logging component that can be configured to log detailed information about connection state and messages exchanged between client and server to stderr. To enable detailed logging, set the `GRPC_VERBOSITY` environment variable to `DEBUG` before starting R:

```bash
export GRPC_VERBOSITY=DEBUG
```

### Timeouts

During the creation of the `SessionManager` object, three network connections are made in the order indicated below.

1. Download the `connection.json` file from the provided URL. (This is a temporary connection that only lives while getting the file.)
2. Connect to the Deephaven Enterprise Authentication service.
3. Connect to the Deephaven Enterprise Controller service.

The connections to Authentication and Controller are made based on the information downloaded from `connection.json`. These two connections are maintained for as long as the `SessionManager` object is valid.

All three operations must succeed for `SessionManager` to be properly initialized or an error results. When experiencing connectivity issues, or if the information contained in the `connection.json` file downloaded is wrong, you may see an error similar to:

```text
Error: std::string deephaven_enterprise::utility::GetUrl(const string&)@/opt/deephaven/src/iris/DhcInDhe/cpp-client/utility/src/net.cc:121: Timeout was reached
```

Deephaven clients use [gRPC](https://grpc.io/), an open-source RPC framework from Google, to communicate with Deephaven servers. gRPC treats network errors as potentially temporary and uses a timeout model for network failures. This means that if the host address is incorrect or the server is down, the connection attempt does not fail immediately. Instead, gRPC [keeps trying to connect](https://github.com/grpc/grpc/blob/master/doc/connection-backoff.md), assuming that a new host name registration may appear or the server may restart and make the port available.

If the network issue is not resolved before the timeout window expires, the connection attempt fails and an error is returned.

Treating network connectivity issues as potentially temporary failures helps make the deployed infrastructure, clients, and servers more resilient. However, from a user's perspective, if there is a network failure, it may appear that the client is unresponsive for two minutes before an error occurs.

> [!IMPORTANT]
> The default timeout used by Deephaven in its clients is 2 minutes.

> [!TIP]
> To help debug network and connectivity issues, set the `GRPC_VERBOSITY` environment variable before starting an R session. The possible values are `info` and `debug`, with `debug` providing more detailed, but noisier, output.
>
> Setting `GRPC_VERBOSITY` will print details of the `gRPC` connection establishment, including SSL authentication and certificate validation, to the standard output.

## Related documentation

- [Install the Core+ R client](./install-r-client.md)
- [Install the Core+ C++ client](./install-cpp-client.md)
- [The R Project for Statistical Computing](https://www.r-project.org/)
- [Develop an R Client Query](../crash-course/develop-client-query/develop-r-query.md)
- [Core R API](/core/client-api/r/)
- [Overview of the Deephaven Core R Client](/core/client-api/r/articles/rdeephaven.html)
- [Aggregations with agg_by](/core/client-api/r/articles/agg_by.html)
- [Moving Operations with update_by](/core/client-api/r/articles/update_by.html)