Deephaven TableHandles
TableHandle.RdA TableHandle holds a reference to a Deephaven Table on the server, and provides methods for operating on that table.
Note that TableHandles should not be instantiated directly by user code, but rather by server calls accessible from
the Client class. See ?Client for more information.
Naming tables on the server
When a TableHandle is created, it is not automatically bound to a variable name on the server. This means that the TableHandle that gets created is the only reference to the table that's been created. Importantly, the variable name given to the TableHandle is purely a local variable, and has no relationship to that table's name on the server. For this reason, code like the following:
client <- Client$new(...)
df1 <- data.frame(x = 1:10, y = 11:20)
t1 <- client$import_table(df1)
client$run_script("t2 = t1.update('z = x + y')")will not run, because the table referenced by the local variable t1 is not named on the server at all. To
make the table referenced by t1 accessible by name on the server (e.g., from within query strings), you must
bind it to a variable with the method bind_to_variable(). We adopt the convention of calling local TableHandles
th1, th2, etc., and server-side tables t1, t2, etc., to help distinguish between the two. So, the above
code should be written as:
client <- Client$new(...)
df1 <- data.frame(x = 1:10, y = 11:20)
th1 <- client$import_table(df1)
th1$bind_to_variable("t1")
client$run_script("t2 = t1.update('z = x + y')")You can then create a local TableHandle to reference t2 as follows:
th2 <- client$open_table("t2")The above code is not best practice; calling update() directly on t1 would be preferred to running a script.
It is, however, more illustrative of the relationship between local TableHandles and server-side tables. The best
way to accomplish the above would be the following:
client <- Client$new(...)
df1 <- data.frame(x = 1:10, y = 11:20)
th1 <- client$import_table(df1)
th2 <- th1$update("z = x + y")
# this is necessary to access the tables from within query strings
th1$bind_to_variable("t1")
th2$bind_to_variable("t2")Methods
TableHandle$new()
Initializes a new TableHandle from an internal Deephaven TableHandle.
Usage
TableHandle$new(table_handle)TableHandle$is_static()
Determines whether the table referenced by this TableHandle is static or not.
TableHandle$bind_to_variable()
Binds the table referenced by this TableHandle to a variable on the server, so that it can be referenced by that name.
TableHandle$dim()
Gets the dimensions of the table referenced by this TableHandle. Equivalent to c(nrow, ncol).
TableHandle$merge()
Merges several tables into one table on the server. All tables must have the same schema as this table, and can be supplied as a list of TableHandles, any number of TableHandles, or a mix of both.
TableHandle$as_record_batch_reader()
Converts the table referenced by this TableHandle to an Arrow RecordBatchStreamReader.
TableHandle$select()
Creates a new in-memory table that includes one column for each formula. If no formula is specified, all columns will be included.
Usage
TableHandle$select(formulas = character())TableHandle$view()
Creates a new formula table that includes one column for each formula.
Usage
TableHandle$view(formulas = character())TableHandle$update()
Creates a new table containing a new, in-memory column for each formula.
Usage
TableHandle$update(formulas = character())TableHandle$update_view()
Creates a new table containing a new formula column for each formula.
Usage
TableHandle$update_view(formulas = character())TableHandle$drop_columns()
Creates a new table that has the same number of rows as this table,
but omits the columns specified in cols.
Usage
TableHandle$drop_columns(cols = character())TableHandle$group_by()
Creates a new table containing grouping columns and grouped data, with column content is grouped into arrays. If no group-by column is given, the content of each column is grouped into its own array.
Usage
TableHandle$group_by(by = character())TableHandle$ungroup()
Creates a new table in which array columns from the source table are unwrapped into separate rows. The ungroup columns should be of array types.
Usage
TableHandle$ungroup(by = character())TableHandle$update_by()
Creates a table with additional columns calculated from window-based aggregations of columns in this table.
The aggregations are defined by the provided operations, which support incremental aggregations over the
corresponding rows in the table. The aggregations will apply position or time-based windowing and compute the
results over the entire table or each row group as identified by the provided key columns.
See more detailed documentation here or run ?UpdateBy.
Usage
TableHandle$update_by(ops, by = character())TableHandle$agg_by()
Creates a new table containing grouping columns and grouped data. The resulting grouped data is defined by the
aggregation(s) specified. See more detailed documentation here or run ?AggBy.
Usage
TableHandle$agg_by(aggs, by = character())TableHandle$agg_all_by()
Creates a new table containing grouping columns and grouped data. The resulting grouped data is defined by the
aggregation(s) specified. See more detailed documentation here or run ?AggBy.
This method applies the aggregation to all non-grouping columns of the table, so it can only
accept one aggregation at a time.
Usage
TableHandle$agg_all_by(agg, by = character())TableHandle$first_by()
Creates a new table containing the first row of each group.
Usage
TableHandle$first_by(by = character())TableHandle$last_by()
Creates a new table containing the last row of each group.
Usage
TableHandle$last_by(by = character())TableHandle$head_by()
Creates a new table containing the first num_rows rows of each group.
Usage
TableHandle$head_by(num_rows, by = character())TableHandle$tail_by()
Creates a new table containing the last num_rows rows of each group.
Usage
TableHandle$tail_by(num_rows, by = character())TableHandle$min_by()
Creates a new table containing the column-wise minimum of each group.
Usage
TableHandle$min_by(by = character())TableHandle$max_by()
Creates a new table containing the column-wise maximum of each group.
Usage
TableHandle$max_by(by = character())TableHandle$sum_by()
Creates a new table containing the column-wise sum of each group.
Usage
TableHandle$sum_by(by = character())TableHandle$abs_sum_by()
Creates a new table containing the column-wise absolute sum of each group.
Usage
TableHandle$abs_sum_by(by = character())TableHandle$avg_by()
Creates a new table containing the column-wise average of each group.
Usage
TableHandle$avg_by(by = character())TableHandle$w_avg_by()
Creates a new table containing the column-wise weighted average of each group.
Usage
TableHandle$w_avg_by(wcol, by = character())TableHandle$median_by()
Creates a new table containing the column-wise median of each group.
Usage
TableHandle$median_by(by = character())TableHandle$var_by()
Creates a new table containing the column-wise variance of each group.
Usage
TableHandle$var_by(by = character())TableHandle$std_by()
Creates a new table containing the column-wise standard deviation of each group.
Usage
TableHandle$std_by(by = character())TableHandle$percentile_by()
Creates a new table containing the column-wise percentile of each group.
Usage
TableHandle$percentile_by(percentile, by = character())TableHandle$count_by()
Creates a new table containing the number of rows in each group.
Usage
TableHandle$count_by(col, by = character())TableHandle$join()
Creates a new table containing rows that have matching values in both tables. Rows that do not have matching criteria will not be included in the result. If there are multiple matches between a row from the left table and rows from the right table, all matching combinations will be included. If no columns to match (on) are specified, every combination of left and right table rows is included.
TableHandle$natural_join()
Creates a new table containing all the rows and columns of this table, plus additional columns containing data from the right table. For columns appended to the left table (joins), row values equal the row values from the right table where the key values in the left and right tables are equal. If there is no matching key in the right table, appended row values are NULL.
TableHandle$exact_join()
Creates a new table containing all the rows and columns of this table, plus additional columns containing data from the right table. For columns appended to the left table (joins), row values equal the row values from the right table where the key values in the left and right tables are equal.
TableHandle$sort()
Creates a new table containing all the rows and columns of this table, sorted by the specified columns.
Arguments
order_byString or list of strings denoting the names of the columns to sort by.
descendingBoolean or list of booleans denoting whether to sort in descending order. If a list is supplied, it must be the same length as
order_by.abs_sortBoolean or list of booleans denoting whether to sort by absolute value. If a list is supplied, it must be the same length as
order_by.
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, push it to the server, and retrieve a TableHandle referencing the new table
df <- data.frame(
timeCol = seq.POSIXt(as.POSIXct(Sys.Date()), as.POSIXct(Sys.Date() + 0.01), by = "1 sec")[1:50],
boolCol = sample(c(TRUE, FALSE), 50, TRUE),
col1 = sample(1000, size = 50, replace = TRUE),
col2 = sample(1000, size = 50, replace = TRUE),
col3 = 1:50
)
th <- client$import_table(df)
# get the dimension of the table
dim(th)
# get the last 10 rows of the table
th2 <- tail(th, 10)
as.data.frame(th2)
# create several new columns
th3 <- th$update(c("col4 = col1 + col2", "charCol = col3 % 2 == 0 ? `A` : `B`"))
as.data.frame(th3)
# filter based on parity of col3
th4 <- th3$where("charCol == `A`")
as.data.frame(th4)
# select a subset of columns
th5 <- th3$select(c("timeCol", "col1", "col4"))
as.data.frame(th5)
# drop timestamp column and get sum of remaining columns grouped by boolCol and charCol
th6 <- th3$
drop_columns("timeCol")$
sum_by(c("boolCol", "charCol"))
as.data.frame(th6)
client$close()
} # }