| Title: | Relational Data Management Blocks for 'blockr' |
|---|---|
| Description: | Blocks for working with relational data in 'blockr.core' boards, built on the 'dm' package. Combine data frames into a data model, set primary and foreign keys, select, pull and flatten tables, and filter across linked tables with cascading through foreign keys. A crossfilter block shows linked counts for any column of any table and filters them in the browser. |
| Authors: | Christoph Sax [aut, cre], Square, Inc. [cph] (crossfilter2 JavaScript library), Mike Bostock [cph] (crossfilter2 JavaScript library), crossfilter contributors [cph] (crossfilter2 JavaScript library), The Dart project authors [cph] (quicksort implementation in crossfilter2) |
| Maintainer: | Christoph Sax <[email protected]> |
| License: | GPL (>= 3) |
| Version: | 0.0.104 |
| Built: | 2026-11-19 08:16:06 UTC |
| Source: | https://github.com/BristolMyersSquibb/blockr.dm |
Displays dm structure as an interactive diagram showing tables and relationships.
## S3 method for class 'dm_add_keys_block' block_output(x, result, session) ## S3 method for class 'dm_block' block_output(x, result, session)## S3 method for class 'dm_add_keys_block' block_output(x, result, session) ## S3 method for class 'dm_block' block_output(x, result, session)
x |
The block object |
result |
The dm result |
session |
Shiny session |
Override transform_block's render trigger which tries to access board options that may not be set. dm blocks don't need pagination.
## S3 method for class 'dm_block' block_render_trigger(x, session = blockr.core::get_session())## S3 method for class 'dm_block' block_render_trigger(x, session = blockr.core::get_session())
x |
The block object |
session |
Shiny session |
Custom UI for dm blocks
## S3 method for class 'dm_add_keys_block' block_ui(id, x, ...) ## S3 method for class 'dm_block' block_ui(id, x, ...)## S3 method for class 'dm_add_keys_block' block_ui(id, x, ...) ## S3 method for class 'dm_block' block_ui(id, x, ...)
id |
Namespace ID |
x |
The block object |
... |
Additional arguments |
The order a column's levels take wherever they are listed: in the
crossfilter's group definition, in the stamped Group column and in the
tables built on it. A factor gives the levels that occur, in levels()
order. Anything else gives its distinct non-missing values, sorted.
crossfilter_level_order(x)crossfilter_level_order(x)
x |
A vector. |
A character vector of levels.
crossfilter_level_order(factor(c("b", "a"), levels = c("c", "b", "a"))) crossfilter_level_order(c("b", NA, "a", "b"))crossfilter_level_order(factor(c("b", "a"), levels = c("c", "b", "a"))) crossfilter_level_order(c("b", NA, "a", "b"))
The record of which filters produced a table, carried on the data itself as
a blockr_filters attribute so that any downstream consumer (a chart
caption, a table footnote, a download) can print what was applied without
knowing anything about the board.
trail_key(), trail_expr() and provenance() are deprecated and will
stop being exported. They stay for blocks written against blockr.dm 0.0.95
and log a warning the first time each is called in a session. A block
passes its module namespace (session$ns("")) as the key to
add_filter_trail(), wraps its expression in that call itself, and reads
the blockr_provenance attribute of a table.
filter_trail(x, tables = NULL) add_filter_trail(x, key, clause, tables = NULL) trail_key(session = shiny::getDefaultReactiveDomain()) trail_expr( inner, key = NULL, clause = NULL, data = quote(data), table = NULL, tables = NULL, count = FALSE ) provenance(x)filter_trail(x, tables = NULL) add_filter_trail(x, key, clause, tables = NULL) trail_key(session = shiny::getDefaultReactiveDomain()) trail_expr( inner, key = NULL, clause = NULL, data = quote(data), table = NULL, tables = NULL, count = FALSE ) provenance(x)
x |
A data frame or a |
tables |
For a |
key |
Name the clause is stored under, unique to the block that writes it. |
clause |
What the block filtered, e.g. |
session |
The block server's Shiny session. |
inner |
The expression the block would otherwise return. |
data, count
|
Accepted and ignored: the trail upstream rides through on the tables, and the trail no longer counts subjects. |
table |
The one table a filter narrowed without cascading. Same as
|
The trail is a named character vector, keyed by block. A filter block writes its clause under its own key, so two branches meeting at a fan-in collapse to one entry per block, and a consumer can map a clause back to the block that set it.
filter_trail() returns a named character vector, or NULL when
nothing is recorded. On a dm it is the union of the tables' trails in
the order the clauses were added. add_filter_trail() returns x with
the clause added. The deprecated trail_key() returns a string,
trail_expr() a call, and provenance() a list or NULL.
On a data frame the attribute sits on the frame. On a dm it sits on the
tables, not on the dm object: every dm verb (dm::dm_filter(), zooming,
key edits) rebuilds the dm and drops attributes set on it, but keeps the
attributes of its tables, and dm::pull_tbl() and dm::dm_flatten_to_tbl()
hand a table's attributes on to the frame they return (a flatten keeps the
start table's). So a trail written onto the tables reaches every frame cut
from the dm with no further code, the way dplyr keeps a data frame's
attributes through filter(), mutate() and joins.
Which tables a clause goes on says which tables the filter narrowed.
dm::dm_filter() cascades over the keys, so a filter written against orders
narrows customers and through it every other table: by default the clause goes
on every table. A filter that narrows one table without cascading passes
that table as tables, and a frame pulled from another table does not
carry the clause.
dplyr::summarise() and tidyr::pivot_wider() do not keep attributes, so a
block that aggregates has to copy the trail across itself.
d <- data.frame(x = 1:3) d <- add_filter_trail(d, "segment", "segment = Consumer") filter_trail(d)d <- data.frame(x = 1:3) d <- add_filter_trail(d, "segment", "segment = Consumer") filter_trail(d)
Client-side crossfilter using crossfilter2.js. R builds lookup tables and ships them to the browser; all filtering, counting, and UI updates happen in JavaScript for instant responsiveness. Accepts either a data frame or a dm object.
new_crossfilter_block( active_dims = list(), filters = list(), range_filters = list(), measure = NULL, agg_func = NULL, featured = character(), pinned = NULL, groups = list(), subgroup = NULL, group_none = FALSE, ... )new_crossfilter_block( active_dims = list(), filters = list(), range_filters = list(), measure = NULL, agg_func = NULL, featured = character(), pinned = NULL, groups = list(), subgroup = NULL, group_none = FALSE, ... )
active_dims |
Named list of per-table active filter columns.
E.g., |
filters |
Named list of per-table categorical filters.
E.g., |
range_filters |
Named list of per-table range filters.
E.g., |
measure |
Measure column as |
agg_func |
Aggregation function: |
featured |
Columns worth showing up front: they get a pill each above
the cards, rank first in the search, and are the columns |
pinned |
The single column the block reports as the board's group,
chosen in the |
groups |
Group definitions for the pinned column and the subgroup,
edited under the |
subgroup |
A second column the board is split by, under |
group_none |
Whether the |
... |
Forwarded to |
A blockr transform block with client-side crossfiltering
This block adds primary and foreign key relationships to a dm object. It allows selecting a table and column to set as primary key, and optionally link it as a foreign key from one or more other tables.
new_dm_add_keys_block( pk_table = "", pk_column = "", fk_tables = character(0), fk_column = "", ... )new_dm_add_keys_block( pk_table = "", pk_column = "", fk_tables = character(0), fk_column = "", ... )
pk_table |
Character, the table to add primary key to. Default "". |
pk_column |
Character, the column to use as primary key. Default "". |
fk_tables |
Character vector, tables containing the foreign key.
Default |
fk_column |
Character, the column to use as foreign key. Default "". |
... |
Forwarded to |
Primary keys uniquely identify rows in a table. Foreign keys reference the primary key of another table, establishing relationships.
In a customer and orders model, customer_id is typically the primary
key in customers and a foreign key in orders.
A block object for adding keys to dm objects
# Add customer_id as key linking customers to orders new_dm_add_keys_block( pk_table = "customers", pk_column = "customer_id", fk_tables = "orders", fk_column = "customer_id" )# Add customer_id as key linking customers to orders new_dm_add_keys_block( pk_table = "customers", pk_column = "customer_id", fk_tables = "orders", fk_column = "customer_id" )
This block combines multiple data frames and/or dm objects into a single dm (data model) object.
new_dm_block(infer_keys = TRUE, ...)new_dm_block(infer_keys = TRUE, ...)
infer_keys |
Logical, whether to automatically infer primary and foreign
key relationships from columns with matching names. Default is |
... |
Forwarded to |
Inputs can be data frames or existing dm objects:
Data frames are added as new tables in the dm
Existing dm objects have their tables merged into the result
If table names conflict, later inputs overwrite earlier ones
A block object for creating dm objects
# Create a dm block new_dm_block() # Create a dm block with auto-inferred relationships new_dm_block(infer_keys = TRUE) if (interactive()) { library(blockr.core) library(blockr.dm) # Combine multiple tables into a dm serve( new_board( blocks = list( airlines = new_dataset_block( dataset = "airlines", package = "nycflights13" ), flights = new_dataset_block( dataset = "flights", package = "nycflights13" ), dm_obj = new_dm_block() ), links = c( new_link("airlines", "dm_obj", "1"), new_link("flights", "dm_obj", "2") ) ) ) }# Create a dm block new_dm_block() # Create a dm block with auto-inferred relationships new_dm_block(infer_keys = TRUE) if (interactive()) { library(blockr.core) library(blockr.dm) # Combine multiple tables into a dm serve( new_board( blocks = list( airlines = new_dataset_block( dataset = "airlines", package = "nycflights13" ), flights = new_dataset_block( dataset = "flights", package = "nycflights13" ), dm_obj = new_dm_block() ), links = c( new_link("airlines", "dm_obj", "1"), new_link("flights", "dm_obj", "2") ) ) ) }
A data block that provides ready-to-use dm objects from a built-in catalog of example datasets. The dropdown shows only datasets whose required packages are installed. A built-in BI star schema is always available.
new_dm_example_block(dataset = "bi_star_schema", ...)new_dm_example_block(dataset = "bi_star_schema", ...)
dataset |
Character, the ID of the dm example to load. Defaults to
|
... |
Forwarded to |
To add a new dataset, add an expression builder function (e.g.,
my_data_expr()) and wire it into dm_example_choices() and
dm_example_expr().
A data block of class c("dm_example_block", "dm_block").
if (interactive()) { library(blockr.core) library(blockr.dm) serve(new_dm_example_block()) }if (interactive()) { library(blockr.core) library(blockr.dm) serve(new_dm_example_block()) }
Filters a dm object by applying one or more conditions to a selected
table. The filter cascades to related tables via semi-joins on foreign
key relationships (handled by dm::dm_filter()), keeping only rows that
match across the data model.
new_dm_filter_block( table = "", state = list(conditions = list(), operator = "&"), ... )new_dm_filter_block( table = "", state = list(conditions = list(), operator = "&"), ... )
table |
Name of the dm table to filter. Default |
state |
Filter state as used by blockr.dplyr's filter block — a list
with |
... |
Forwarded to |
The condition UI is reused from blockr.dplyr's filter block: each
condition is type-aware (categorical multi-select, numeric operator +
value, or free R expression) and conditions are combined with & or |.
A single table picker above the conditions selects which table in the dm
the conditions apply to. Changing the table clears existing conditions.
A block object for filtering dm objects.
# Keep the customers in the "Consumer" segment, and the orders that follow new_dm_filter_block( table = "customers", state = list( conditions = list(list( type = "values", column = "segment", values = list("Consumer"), mode = "include" )), operator = "&" ) )# Keep the customers in the "Consumer" segment, and the orders that follow new_dm_filter_block( table = "customers", state = list( conditions = list(list( type = "values", column = "segment", values = list("Consumer"), mode = "include" )), operator = "&" ) )
This block flattens a dm object into a single data frame by joining all related tables based on their foreign key relationships.
new_dm_flatten_block( start_table = "", include_tables = character(), join_type = "left", recursive = TRUE, ... )new_dm_flatten_block( start_table = "", include_tables = character(), join_type = "left", recursive = TRUE, ... )
start_table |
Character, the table to start flattening from. Default "". |
include_tables |
Character vector, specific tables to include in the join. If empty, all reachable tables are included. |
join_type |
Character, type of join to use: "left", "inner", "full", "right". Default "left". |
recursive |
Logical, whether to recursively join all related tables. Default TRUE. |
... |
Forwarded to |
The starting table determines the base of the join. Related tables are
joined based on their foreign key relationships. With recursive = TRUE,
all transitively related tables are included.
Use include_tables to limit which tables are joined - useful when you
want to flatten only specific relationships (e.g., join orders with
customers but not products).
A block object for flattening dm objects
new_dm_flatten_block(start_table = "flights", recursive = TRUE) new_dm_flatten_block( start_table = "orders", include_tables = c("customers"), join_type = "inner" )new_dm_flatten_block(start_table = "flights", recursive = TRUE) new_dm_flatten_block( start_table = "orders", include_tables = c("customers"), join_type = "inner" )
This block extracts a single table from a dm object as a regular data frame. Use this after filtering to get a specific table for further analysis or visualization.
new_dm_pull_block(table = "", ...)new_dm_pull_block(table = "", ...)
table |
Character, the name of the table to extract. Default |
... |
Forwarded to |
A block object for extracting tables from dm objects
table is externally controllable (see
blockr.core::external_ctrl_vars()): a board update or an assistant can
switch the pulled table with a mod delta, and the picker follows.
new_dm_pull_block(table = "flights")new_dm_pull_block(table = "flights")
A block for selecting a subset of tables from a dm (data model) object.
Uses dm::dm_select_tbl() to keep only the specified tables.
new_dm_select_block(tables = character(), ...)new_dm_select_block(tables = character(), ...)
tables |
Character vector. Names of tables to keep. If empty, all tables are kept (no filtering). |
... |
Forwarded to |
A blockr transform block that filters tables from a dm object
tables is externally controllable (see
blockr.core::external_ctrl_vars()): a board update or an assistant can
change the kept set with a mod delta, and the picker follows.
if (interactive()) { library(blockr.core) library(blockr.dm) serve(new_dm_select_block()) }if (interactive()) { library(blockr.core) library(blockr.dm) serve(new_dm_select_block()) }
The destination for cross-block drill claims: a new_value_filter_block()
that senders can find without being told, and that resolves a claimed
column to a table in its own dm.
new_drill_filter_block(state = list(columns = list()), ...)new_drill_filter_block(state = list(columns = list()), ...)
state |
List with |
... |
Additional arguments forwarded to |
Put one on a board together with blockr.viz::new_ctrl_bridge_extension().
The two go together: the bridge opens the control channel and this block is
what the channel writes into, so a board with a bridge and no drill filter
has senders with nowhere to send, and a drill filter without a bridge is
just a value filter.
A block object.
A sender resolves its target by class and takes it only when there is exactly one candidate, so a second drill filter turns the drill back off rather than picking a winner. Use plain value filter blocks for every other filtering job on the board; they are not candidates and do not interfere.
A claim is a list of list(name=, mode=, values=) entries pushed into the
block's state over the control channel. On a dm input each entry needs a
table as well, and this block fills it in:
exactly one table carries the column: that table.
several carry it (an id such as customer_id is in several tables): the table where it
is the PRIMARY KEY, because dm::dm_filter() cascades along foreign keys,
so restricting the parent restricts the children too.
no table carries it: nothing is filtered and the block says which column it could not place. This means the sender claimed a column it DERIVED, and the fix belongs at the sender.
An entry that already names a valid table is left alone, so a sender that
does set ctrl_table keeps working unchanged.
On a plain data frame input there are no tables to resolve and this block behaves exactly like a value filter.
if (interactive()) { library(blockr.core) library(blockr.dm) serve( new_drill_filter_block(), data = list(data = datasets::iris) ) }if (interactive()) { library(blockr.core) library(blockr.dm) serve( new_drill_filter_block(), data = list(data = datasets::iris) ) }
Minimal value filter for data frames or dm objects. The columns to filter
on are chosen behind the gear icon (top-right of the block). Each column
can be toggled between single-select (always constrains — auto-picks first
value) and multi-select (empty selection passes through).
new_value_filter_block(state = list(columns = list()), ...)new_value_filter_block(state = list(columns = list()), ...)
state |
List with |
... |
Additional arguments forwarded to |
When the upstream input is a dm, the gear popover gains a table selector
so columns can be picked from any of the dm's tables. The emitted filter
goes through dm::dm_filter(), so the restriction cascades through foreign
keys to related tables.
Gear/popover UX, select widget, and click-through pill styling are reused
from blockr.dplyr to match the look-and-feel of the crossfilter and dplyr
transform blocks.
This is the value-selection member of the relational filter family,
alongside new_dm_filter_block() (expression-style) and
new_crossfilter_block(). It lives in blockr.dm because its dm
path depends on dm; it is fully usable in a dashboard by composing it
onto a board.
if (interactive()) { library(blockr.core) library(blockr.dm) serve( new_value_filter_block( state = list( columns = list( list(name = "Species", mode = "single", values = "setosa") ) ) ), data = list(data = iris) ) }if (interactive()) { library(blockr.core) library(blockr.dm) serve( new_value_filter_block( state = list( columns = list( list(name = "Species", mode = "single", values = "setosa") ) ) ), data = list(data = iris) ) }
Registers the dm blocks with blockr.
register_dm_blocks()register_dm_blocks()