Type-specific table access

db.liveTable and db.historicalTable cover the common case of retrieving a table by namespace and table name. Some data sources support additional, source-specific options that don't fit those two methods — for example, pinning an Iceberg table to a specific snapshot, or replaying historical data as if it were ticking live.

db.as lets you "mix in" a type-specific accessor for these cases, while still applying the same access controls and audit logging as db.liveTable and db.historicalTable.

Note

db.as and the table access types described here are part of the Core+ (io.deephaven.enterprise.database.Database) API and are available from Groovy and Java only. Python's db.live_table and db.historical_table work as usual and automatically pick up type-specific sources such as Iceberg (see Iceberg's live and historical access), but the db.as(...) entry point itself does not yet have a Python wrapper.

Overview

db.as(factory) takes a TableAccessFactory and returns a DatabaseTableAccess, an accessor with a table(options)method that takes source-specific options instead of a bare namespace/table name pair:

myTypeSpecificAccessor = db.as(MyTypeSpecificAccessor.factory())
myTable = myTypeSpecificAccessor.table(myOptions)

Deephaven Enterprise ships two built-in accessors:

IcebergTableAccess — Iceberg-specific options such as a pinned snapshot or manual refresh control.
ReplayAccess — replay a single table (or another db.as(...) source) as historical data ticking in on a simulated clock, without a dedicated Replay Query.

Building a custom table access

Customers may implement their own TableAccess for a data source not covered by the built-in accessors, in support of one or both of:

Explicit, type-specific access via db.as(MyAccess.factory()).
Transparent access through the existing db.liveTable and db.historicalTable (and Python live_table/historical_table) calls, the same way Iceberg tables work today.

Extend DatabaseTableAccessAclBase, which applies Deephaven's access controls and audit logging around your table-fetching logic so you don't have to reimplement either:

public final class MyTableAccess
        extends DatabaseTableAccessAclBase<MyTableAccess.Options, MyPreAclTable, Table> {

    public static Database.TableAccessFactory<MyTableAccess> factory() {
        return MyTableAccess::new;
    }

    private MyTableAccess(final Database db) {
        super(db);
    }

    // extract namespace/tableName/isRefreshing/event from your own Options type
    @Override protected String namespace(Options options) { /*...*/ }
    @Override protected String tableName(Options options) { /*...*/ }
    @Override public boolean isRefreshing(Options options) { /*...*/ }
    @Override protected String event(Options options) { /*...*/ }

    // fetch the table before ACLs are applied
    @Override protected MyPreAclTable tableImpl(Options options) { /*...*/ }

    // return the table after ACLs have been applied (usually just intermediate.aclOrPre())
    @Override protected Table postAclTableApply(IntermediateResults<Options, MyPreAclTable> intermediate) { /*...*/ }
}

To make your accessor available transparently through db.liveTable/db.historicalTable, additionally implement Database.TableAccessAdapter.Provider and register it for discovery via ServiceLoader. Your provider's supports(Schema) method determines which schemas it applies to, and liveTableOptions/historicalTableOptions adapt a namespace, tableName, and TableOptions into your accessor's own options type.

Type-specific table access

Overview

Building a custom table access

Related documentation