SemText

Reference · SemText · Data & tables

<sem-data-join>

SemText element

You name the two sources and the key column. The joined result becomes a new data set that queries can use. Nothing shows on the page by itself — it only feeds queries.

Combines two named data sets on one shared column, like a database join. You name the two sources and the key column. The joined result becomes a new data set that queries can use. Nothing shows on the page by itself — it only feeds queries. (alias `name`): required — bucket key of the join result; colliding with a source name is an authoring error. (alias `left`): required — the left-hand bucket to join, by `data-name` reference. (alias `right`): required — the other bucket to join, by `data-name` reference. (alias `on`): required — the named key column; must exist (case-insensitive) in both buckets. per the global attribute catalog (conventions.md §2) per the global attribute catalog (conventions.md §2) per the global attribute catalog (conventions.md §2)

Example

sem-data-join.html
source
1 <sem-data-visualizer id="dv-user-orders">
2 <sem-data-source data-name="Users" data-format="table">
3 | user-id | name | plan |
4 | :------ | :--- | :--- |
5 | u1 | Ada | team |
6 | u2 | Bao | free |
7 | u3 | Cleo | team |
8 </sem-data-source>
9 <sem-data-source data-name="Orders" data-format="table">
10 | order | user-id | total |
11 | :---- | :------ | ----: |
12 | o-101 | u2 | 120 |
13 | o-102 | u1 | 80 |
14 | o-103 | u2 | 45 |
15 </sem-data-source>
16 <sem-data-join name="user-orders" left="Users" right="Orders" on="user-id">
17 </sem-data-join>
18 <sem-data-query>SELECT name, total FROM user-orders ORDER BY total DESC</sem-data-query>
19 </sem-data-visualizer>
render

Live render boots with JavaScript — the authored source is alongside.

variant: the bare declaration

The element itself, outside a working visualizer. It renders nothing in any tier — a declaration with nothing to read; the joined bucket surfaces only through a sem-data-query results table.

variant: the bare declaration
sem-data-join-declaration-only.html
source
1 <sem-data-join name="user-orders" left="Users" right="Orders" on="user-id">
2 </sem-data-join>
render
No shipped runtime for this element — the authored example renders as plain HTML.

variant: colliding right column is qualified

Orders also carries a name column — the product, not the person. The join exposes the right side as orders.name, so SELECT * shows both names side by side. u3 has no orders and drops (inner join).

variant: colliding right column is qualified
sem-data-join-column-collision.html
source
1 <sem-data-visualizer id="dv-qualified">
2 <sem-data-source data-name="Users">| user-id | name |
3 |---|---|
4 | u1 | Ada |
5 | u2 | Bao |
6 | u3 | Cleo |</sem-data-source>
7 <sem-data-source data-name="Orders">| order | user-id | name | total |
8 |---|---|---|---|
9 | o-101 | u2 | Desk lamp | 120 |
10 | o-102 | u1 | Footrest | 80 |</sem-data-source>
11 <sem-data-join name="user-orders" left="Users" right="Orders" on="user-id"></sem-data-join>
12 <sem-data-query>SELECT * FROM user-orders ORDER BY total DESC</sem-data-query>
13 </sem-data-visualizer>
render

Live render boots with JavaScript — the authored source is alongside.

variant: authoring error — unknown bucket

right names no bucket in the visualizer: the join renders .sem-data-error (role=alert), registers no bucket, and heals on its own when a late file or API source supplies the missing one.

variant: authoring error — unknown bucket
sem-data-join-unknown-bucket.html
source
1 <sem-data-visualizer id="dv-unknown">
2 <sem-data-source data-name="Users">| user-id | name |
3 |---|---|
4 | u1 | Ada |</sem-data-source>
5 <sem-data-join name="user-orders" left="Users" right="Ordres" on="user-id"></sem-data-join>
6 </sem-data-visualizer>
render

Live render boots with JavaScript — the authored source is alongside.

variant: authoring error — key column missing

on names a column neither bucket declares: the same alert treatment, with the message naming the offending bucket and the key.

variant: authoring error — key column missing
sem-data-join-missing-key.html
source
1 <sem-data-visualizer id="dv-missing-key">
2 <sem-data-source data-name="Users">| user-id | name |
3 |---|---|
4 | u1 | Ada |</sem-data-source>
5 <sem-data-source data-name="Orders">| order | user-id | total |
6 |---|---|---|
7 | o-101 | u1 | 80 |</sem-data-source>
8 <sem-data-join name="user-orders" left="Users" right="Orders" on="account-id"></sem-data-join>
9 </sem-data-visualizer>
render

Live render boots with JavaScript — the authored source is alongside.

variant: authoring error — join name shadows a source

A result bucket must not overwrite a source bucket: name colliding with an existing data-name is an authoring error, never a silent rebind.

variant: authoring error — join name shadows a source
sem-data-join-shadowed-name.html
source
1 <sem-data-visualizer id="dv-shadowed">
2 <sem-data-source data-name="Users">| user-id | name |
3 |---|---|
4 | u1 | Ada |</sem-data-source>
5 <sem-data-join name="Users" left="Users" right="Users" on="user-id"></sem-data-join>
6 </sem-data-visualizer>
render

Live render boots with JavaScript — the authored source is alongside.

Source: spec/schema/sem-data-join.md