Tree — Drill Actions¶
Drill is the typed action wrapper for click-driven navigation. Two
trigger flavors: DATA_POINT_CLICK (left-click) and DATA_POINT_MENU
(right-click context menu). Cross-sheet drills carry a Sheet object
ref as the target — never a string ID — so the tree validates the
destination at emit time.
actions ¶
Typed drill action wrapper (L.1.10).
A Drill is one custom action attached to a typed Visual — left-click
or right-click on a data point fires it. The drill navigates to a
target sheet (same-sheet or cross-sheet) and optionally sets parameter
values from the clicked data point.
The L.1.10 typed wrapper keeps K.2's shape-validated parameter writes
(DrillParam + DrillSourceField + ColumnShape) and adds:
target_sheetis a typedSheetobject ref, not aSheetIdstring. The App's emit-time validation catches "drill into a sheet that isn't on this analysis" the same way the dataset and calc-field walks catch unregistered references.action_idis Optional — the App walker assignsact-s{sheet_idx}-v{visual_idx}-{action_idx}at emit time.
Visual subtypes (KPI / Table / BarChart / Sankey) accept a typed
actions: list[Drill] field; their emit() passes the resolved
list into the underlying model's Actions slot.
__all__
module-attribute
¶
__all__ = ['Action', 'Drill', 'DrillParam', 'DrillSourceField', 'DrillResetSentinel', 'DrillStaticDateTime', 'SameSheetFilter']
DrillWriteSource
module-attribute
¶
DrillWriteSource = Union[Dim, Measure, DrillSourceField, DrillResetSentinel, DrillStaticDateTime]
DrillResetSentinel
dataclass
¶
Marker that a drill should reset a parameter to the sentinel value.
The destination calc-field filter recognizes the sentinel as PASS, so writing this clears the filter without needing an empty-string or null-value path that QuickSight's drill-action code path won't deliver to calc fields cleanly.
DrillSourceField
dataclass
¶
Source field on a drill action — visual field id + resolved shape.
Build via field_source(field_id, dataset_id, column_name) so the
shape is read from the dataset contract, not duplicated by hand.
DrillStaticDateTime
dataclass
¶
Marker that a drill should write a fixed ISO-8601 datetime literal
to a DateTimeParam destination.
Use case: cross-sheet drills where the destination sheet has a
universal date-range filter the source sheet doesn't share — e.g.
L1's Pending Aging → Transactions. The aging sheet is a
current-state view (rows can be arbitrarily old); the Transactions
sheet's universal-filter window defaults to last 7 days. Without
a date write the drill-target leg falls outside the destination's
window and the table renders empty. Writing
DrillStaticDateTime("1990-01-01T00:00:00.000Z") to the
destination's date-start param widens the window so the drill-
target row is always visible.
QuickSight has no "now" or "rolling" expression you can write via
SetParametersOperation — the only options are SourceField (column
ref) or static CustomValues. Pick the static value carefully so
the picker-shown date isn't misleading; the L1 app uses
"1990-01-01T..." for start and "2099-12-31T..." for end,
framing the explicit "all time" intent.
Format: ISO-8601 with millisecond precision and the trailing
Z, matching what the L2FT app already uses for its static
StaticValues defaults.
Drill
dataclass
¶
One custom action on a Visual.
target_sheet is the destination Sheet object ref. Two
binding modes:
- Cross-sheet drill — pass an explicit
target_sheet=sheet. The drill navigates to that sheet (and writes parameter values to it). - Same-sheet drill (the walk-the-flow / re-render-around-new-anchor
pattern) — leave
target_sheetasNone.App._resolve_auto_idsback-fills the field with the sheet that owns the visual carrying the drill, so the author never typestarget_sheet=this_sheetwhen wiring a drill inside the function that builds the sheet. Resolves the chicken-and-egg cycle (sheet doesn't exist yet when the drill is constructed insideSheet.add_visual(...)) without a back-fill loop at the call site.
writes is a list of (DrillParam, DrillSourceField | DrillResetSentinel)
tuples — same shape K.2 introduced. The DrillParam carries
its own ColumnShape; DrillSourceField.shape must match
or cross_sheet_drill raises (call-site shape validation).
trigger picks the click semantic — DATA_POINT_CLICK for
left-click, DATA_POINT_MENU for right-click context menu.
action_id is Optional — the App walker assigns one at emit
time when not specified.
name is the visible label QuickSight shows in the right-click
menu (for DATA_POINT_MENU triggers). For DATA_POINT_CLICK actions
the name doesn't surface in the UI but is still required by the
underlying model.
trigger
class-attribute
instance-attribute
¶
trigger: Literal['DATA_POINT_CLICK', 'DATA_POINT_MENU'] = 'DATA_POINT_CLICK'
__init__ ¶
__init__(writes: list[DrillWrite], name: str, trigger: Literal['DATA_POINT_CLICK', 'DATA_POINT_MENU'] = 'DATA_POINT_CLICK', action_id: str | AutoResolved = AUTO, target_sheet: 'Sheet | AutoResolved' = AUTO) -> None
SameSheetFilter
dataclass
¶
A click action that filters target visuals on the same sheet via ALL_FIELDS — the click-a-bar-to-narrow-the-table pattern.
target_visuals is a list of typed VisualLike object refs.
The action's emitted TargetVisuals field reads each visual's
(resolved) visual_id at emit time, so the action survives auto-
ID resolution and refactors that rename a visual.
Distinct from Drill — emits a FilterOperation rather than a
NavigationOperation + SetParametersOperation pair. Doesn't
cross sheets, doesn't write parameters.
trigger
class-attribute
instance-attribute
¶
trigger: Literal['DATA_POINT_CLICK', 'DATA_POINT_MENU'] = 'DATA_POINT_CLICK'
__init__ ¶
__init__(target_visuals: list['VisualLike'], name: str, trigger: Literal['DATA_POINT_CLICK', 'DATA_POINT_MENU'] = 'DATA_POINT_CLICK', action_id: str | AutoResolved = AUTO) -> None