recon_gen.common.tree.fields
Field-well leaf nodes — Dim + Measure typed wrappers.
Every visual’s field wells contain a mix of DimensionField and
MeasureField entries (source / target columns, group-by fields,
aggregated values). These tree nodes wrap them with typed factories
(Dim.date(...), Measure.sum(...)) so construction-time typing
drives what the visual gets, rather than hand-wiring the underlying
models every time.
Auto field_id (L.1.16): both Dim and Measure accept an
optional field_id keyword. When omitted, the App walker assigns
f-{visual_kind}-s{sheet_idx}-v{visual_idx}-{role}{slot_idx} at
emit time. Authors typically pass Dim(ds, "column_name") and
reference the leaf via Python variable for sort / drill plumbing
(both accept Dim / Measure object refs in addition to bare
field-id strings).
Functions
|
Read the resolved field_id off a Dim / Measure / bare string. |
|
Convention name for the literal-1 CalcField backing |
Classes
|
One dimension field-well entry — typed wrapper that emits a |
|
One value field-well entry — typed wrapper that emits a |
- class recon_gen.common.tree.fields.Dim(dataset, column, kind='categorical', *, date_granularity=None, field_id=AUTO, currency=False)[source]
Bases:
objectOne dimension field-well entry — typed wrapper that emits a
DimensionFieldof the appropriate kind.datasetis aDatasetobject ref — the locked L.1.7 hard switch. The dataset must be registered on the parentApp(viaapp.add_dataset()) for the analysis to emit.columnaccepts either a barestr(a real column on the dataset) or aCalcFieldobject ref (an analysis-level calculated field). The CalcField ref carries the calc-field identity through the type checker — the App’s emit-time validation catches references to unregistered calc fields.Default kind is
categorical(the most common); use thedate()/numerical()classmethods for the other variants.field_idis keyword-only and Optional (L.1.16 auto-ID). When omitted, the App walker assigns one based on the leaf’s tree position. Pass an explicitfield_id="..."only when external consumers (browser e2e selectors, etc.) need a stable id — cross-reference plumbing (sort_by, drill writes) accepts the leaf object directly.Identity-keyed (
eq=False) so the auto-id resolver can mutate the field_id at emit time. Dim leaves stay hashable via the default object identity hash, which lets the dependency graph set-membership check work.- Parameters:
- calc_field()[source]
The CalcField this Dim references, or None if it points at a real dataset column. Used by the dependency-graph walk.
- Return type:
CalcField|None
- currency: bool = False
- classmethod date(dataset, column, *, date_granularity='DAY', field_id=AUTO)[source]
Date dimension.
date_granularitydefaults to"DAY"— QuickSight’s most common bucket for daily series. PassNoneto omit the granularity (the renderer falls back to its default, which can shift bucketing on day-vs-month dashboards).
- date_granularity: Literal['YEAR', 'QUARTER', 'MONTH', 'WEEK', 'DAY', 'HOUR', 'MINUTE', 'SECOND', 'MILLISECOND'] | None = None
- emit_unaggregated_field()[source]
Emit the raw
UnaggregatedFielddict shape used insideTableUnaggregatedFieldWells.Values. The model layer types that field aslist[dict[str, Any]]rather than a typed union, so the tree emits it as a dict directly.Q.1.a.7 — When
currency=Trueis set on a numerical Dim, the same USDFormatConfigurationthatemit()wires onto a NumericalDimensionField is also folded into the unaggregated field shape so table cells render with “$” + thousands separator + 2 decimals. Without this, currency=True only took effect when the Dim was used as a chart axis or KPI value, not when it was used as a table column (the by-far common case).- Return type:
dict[str,object]
- field_id: str | Literal[_AutoSentinel.AUTO] = 'auto'
- kind: Literal['categorical', 'date', 'numerical'] = 'categorical'
- class recon_gen.common.tree.fields.Measure(dataset, column, kind, *, field_id=AUTO, currency=False, decimals=None)[source]
Bases:
objectOne value field-well entry — typed wrapper that emits a
MeasureFieldwith the appropriate aggregation shape.datasetis aDatasetobject ref (L.1.7 hard switch). The dataset must be registered on the parentAppfor the analysis to emit.field_idis keyword-only and Optional (L.1.16 auto-ID). When omitted, the App walker assigns one based on the leaf’s tree position.Use the classmethod factories for ergonomic construction:
Measure.sum(...),Measure.distinct_count(...), etc. Aggregation kind determines which underlying model class is emitted (numerical aggregations on numeric columns, categorical on count-style aggregations).- Parameters:
- calc_field()[source]
The CalcField this Measure references, or None if it points at a real dataset column.
- Return type:
CalcField|None
- currency: bool = False
- decimals: int | None = None
- field_id: str | Literal[_AutoSentinel.AUTO] = 'auto'
- kind: Literal['sum', 'max', 'min', 'average', 'count', 'distinct_count']
- recon_gen.common.tree.fields.resolve_field_id(ref)[source]
Read the resolved field_id off a Dim / Measure / bare string.
- recon_gen.common.tree.fields.row_one_calc_name(dataset)[source]
Convention name for the literal-1 CalcField backing
Measure.kind == "count"row-count semantics ondataset.Returns
"_row_one_<sanitized-dataset-id>". Dashes in the dataset identifier are replaced with underscores so the name is QS-safe (QS calc field names accept underscores; dashes are allowed too but underscores stay closer to convention).- Return type:
str- Parameters:
dataset (Dataset)