ref / select_all
ref is the single reference noun in GoFish, and it works in two positions:
- Inline in a layout —
ref("a")inside a.relate()clause,ref(token)anywhere — it resolves at layout time against the name tree, hygienically scoped (see scoping). - As chart data —
chart(ref("maxBar")).mark(text(...))— it resolves at build time against the named-layer registry to a list of one ref, the node registered under that name. Like all chart data it is a list; being singular is a check that exactly one node matched.
select_all(name) is the plural chart-data verb: it returns an array of refs, one per node a named mark produced (node-unit; aggregate or not, no flattening). Pass either form as the data argument to a second chart() call to build overlays and connectors.
Think of select_all as the DOM's querySelectorAll (always a collection) and ref(name)-as-data as querySelector (the one-or-bust singular).
from gofish import layer, chart, scatter, blank, select_all, line
layer([
# Step 1: name the mark
chart(catch_locations)
.flow(scatter(by="lake", x="x", y="y"))
.mark(blank().name("points")),
# Step 2: select_all those nodes as data for a connector
chart(select_all("points")).mark(line(stroke="coral", stroke_width=2)),
]).render(w=500, h=300, axes=True)Signature
ref(name: str) -> Ref # singular; as chart data, a list of exactly one ref
select_all(name: str) -> list[Ref] # one ref per matching nodeParameters
| Parameter | Type | Description |
|---|---|---|
name | str | The name of the layer to reference (registered via .name() on a mark) |
Singular as data: exactly one
When you pass ref(name) as chart data it must resolve to exactly one node:
- Zero matches → error. Nothing was registered under that name in scope.
- More than one match → error, with a hint to use
select_all(name)instead. A named mark that produced several nodes is a collection, and the singular reference refuses to silently pick one.
chart(ref("kpi")).mark(text(text="peak")) # a list of one ref; raises on 0 or >1 nodesNode-unit selection
select_all selects at node granularity: one ref per node the named mark produced, never flattened and never merged. Each ref points at a placed node, so overlay marks position themselves relative to it, and a ref's datum is that node's data bag.
bars = select_all("bars") # list[Ref]
bars[0].datum # the raw row-bag behind the first barThe bag is a list of rows — a 1-row list for a fully-split leaf, all the partition's rows for an auto-summed aggregate.
Why a ref, not a "selection"?
GoFish models a selection as a plain list of refs rather than a bespoke selection object, and this is deliberate:
- A ref is structurally a one-element selection.
ref(name)(one ref) andselect_all(a list of refs) are the singular/plural of the very same noun, so there is nothing new to learn — the ref you get from a selection behaves exactly like a ref you wrote by hand inline. - Geometry is decoupled from data. A ref points at a placed node; you read its placement off the ref (that is how
line/ribbondraw) and its bound datum via the ref'sdatum. Selecting does not flatten or reshape your data. - Batch operations live in
.flow, not on the noun. Unlike D3, where the selection object owns.data(),.attr(),.filter(), etc., GoFish keeps a selection inert. To partition, re-key, or re-encode a selection you run it through operators in.flow(e.g.group,spread) — see path-awarebybelow.
Hygienic scoping
Layer-name lookup is hygienic: a name registered via .name() is visible only within its scope and does not cross component boundaries. A name registered on a mark inside a mark component is internal to that component — it is not selectable from outside. This is the same component-boundary rule that string-name ref resolution always followed inline, so the inline-layout and chart-data lookup paths share one scoping rule.
Within that boundary, chart data follows the same widening rule as inline ref: the lookup starts at the scope the chart is built in, searches the scopes nested in it, nearest first, then widens one enclosing scope at a time. Every layer is a scope. The nearest scopes that have the name all contribute, so a mark repeated per row or per cell carries one name: a select_all outside a spread gathers every cell's marks, and one inside a cell finds its own. The singular form reports how many marks it matched when there is more than one. Inline, a string ref (and a .relate() operand) takes the nearest match to the layer that relates it; see the ref mark.
Inline select_all is not supported yet
select_all is a chart-data verb only. Using it inline inside a layout raises — pass it as the data argument to a chart() instead. (Inline plural references may arrive later; for now use a named layer + select_all as data.)
Connectors take select_all directly
line and ribbon consume a list of refs and read placed geometry off them, so feed them select_all:
chart(select_all("points")).mark(line(stroke="black"))When the connector traces a chart's own marks, chaining .layer() with a bare connector mark (or with by) is sugar for this two-chart select_all recipe — only reach for select_all by hand to connect another chart's marks.
Path-aware by after a selection
After select_all, the stream items are refs, not raw records. Operators' by option reads a ref through its datum rows, so you write the same bare field name you would on raw records:
chart(select_all("bars")) \
.flow(group(by="species")) \
.mark(ribbon(opacity=0.8)) # not by="datum.species"On a ref, a field resolves to a scalar only if every row in the ref's bag agrees on that field (homogeneity collapse — SQL's ONLY_FULL_GROUP_BY rule); otherwise it is None. So by="lake" works on lake-aggregate bars (all rows share a lake) but by="species" does not until you disaggregate. See spread → path-aware by for the full explanation.
pluck(source, path) — every value at a path
Where by's path projection collapses a row-bag to a single scalar (and goes None when the bag disagrees), pluck is its un-collapsed counterpart: it returns the full list of distinct values present at a path, in the order they first appear.
from gofish import pluck
pluck(ref, "species") # → ["Bass", "Trout", ...] (distinct across the bag)source may be a ref that a mark function received (pluck reads its datum bag), a list of rows, or a single row. path is a field name or a path ("a.b", "a[0]"), read as JS reads one; a list met along the path is read element by element, and a row that lacks the field, or holds None there, adds no value. Two values are one when JS counts them as one (1, 1.0 and "1"), so pluck answers what JS pluck answers. Reach for pluck when a field is multi-valued in the current bag and you want to enumerate its values rather than group by it — the case where by="field" would resolve to None.
pluck runs in Python, on the rows the mark function received, and returns plain Python values. Here it counts the species in each lake for a label:
def label(d):
species = pluck(d[0], "species")
return spread([text(text=f"{len(species)} spp"), d[0]],
dir="y", alignment="middle", spacing=10)
chart(seafood, axes=True) \
.flow(spread(by="lake", dir="x")) \
.mark(rect(h="count")) \
.layer(chart().flow(group(by="lake")).mark(label))project(source, path) — the single value at a path
project is the collapsing counterpart to pluck: it returns the one value at a path when the bag agrees on it (the same homogeneity collapse by performs), and None otherwise. Where pluck(ref, "site") gives you the whole multiset ["Morris"], project(ref, "site") gives you "Morris" directly — no indexing.
from gofish import project
project(ref, "site") # → "Morris" (None if the bag disagrees on "site")