SemText

Reference · SemText · Data & tables

<sem-data-query>

SemText element

You write one query: pick columns, filter, sort, and limit. Joins are declared separately, and nothing can change the data. Readers see the results, and the query text stays visible.

A question asked of a data set, written in a small, safe SQL-like language. You write one query: pick columns, filter, sort, and limit. Joins are declared separately, and nothing can change the data. Readers see the results, and the query text stays visible. 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-query.html
source
1 <sem-data-visualizer id="dv-services">
2 <sem-data-source data-name="services" data-format="table">
3 | name | port | ready |
4 | :------ | ---: | :---- |
5 | api | 8443 | true |
6 | web | 8080 | true |
7 | metrics | 9090 | false |
8 </sem-data-source>
9 <sem-data-query>SELECT name, port FROM services WHERE ready = true ORDER BY port LIMIT 5</sem-data-query>
10 </sem-data-visualizer>
render

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

variant: SELECT * with ORDER BY … DESC

The whole-row form — `SELECT *` returns every column in bucket order and `ORDER BY port DESC` sorts the results table descending. No WHERE or LIMIT: both optional clauses are genuinely optional.

variant: SELECT * with ORDER BY … DESC
sem-data-query-star-order-desc.html
source
1 <sem-data-visualizer id="dv-services">
2 <sem-data-source data-name="services" data-format="table">
3 | name | port | ready | owner |
4 | :------ | ---: | :---- | :---- |
5 | api | 8443 | true | alice |
6 | web | 8080 | true | |
7 | metrics | 9090 | false | bob |
8 </sem-data-source>
9 <sem-data-query>SELECT * FROM services ORDER BY port DESC</sem-data-query>
10 </sem-data-visualizer>
render

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

variant: WHERE with AND and IS NULL

Conditions combine with AND / OR (AND binds tighter) and compare against boolean, numeric or string literals. `IS NULL` matches the empty cell, which no `=` comparison ever can.

variant: WHERE with AND and IS NULL
sem-data-query-where-clauses.html
source
1 <sem-data-visualizer id="dv-services">
2 <sem-data-source data-name="services" data-format="table">
3 | name | port | ready | owner |
4 | :------ | ---: | :---- | :---- |
5 | api | 8443 | true | alice |
6 | web | 8080 | true | |
7 | metrics | 9090 | false | bob |
8 </sem-data-source>
9 <sem-data-query>SELECT name, port FROM services WHERE owner IS NULL AND ready = true</sem-data-query>
10 </sem-data-visualizer>
render

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

variant: a query over a declarative join bucket

The grammar has no JOIN — a `sem-data-join` materializes an extra bucket a query then addresses by name. Here `user-orders` is the inner join of `users` and `orders` on `user-id`: carol (no orders) drops, alice appears twice.

variant: a query over a declarative join bucket
sem-data-query-join-bucket.html
source
1 <sem-data-visualizer id="dv-orders">
2 <sem-data-source data-name="users" data-format="table">
3 | user-id | name |
4 | :------ | :---- |
5 | 1 | alice |
6 | 2 | bob |
7 | 3 | carol |
8 </sem-data-source>
9 <sem-data-source data-name="orders" data-format="table">
10 | user-id | total |
11 | :------ | ----: |
12 | 1 | 120 |
13 | 1 | 80 |
14 | 3 | 200 |
15 </sem-data-source>
16 <sem-data-join name="user-orders" left="users" right="orders" on="user-id"></sem-data-join>
17 <sem-data-query>SELECT name, total FROM user-orders ORDER BY total DESC</sem-data-query>
18 </sem-data-visualizer>
render

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

variant: authoring error — a bucket that does not resolve

A query naming a bucket the visualizer does not declare renders an inline `role=alert` naming the miss; the authored statement is preserved. The same alert appears for an unknown column, a syntax error or a mutating statement.

variant: authoring error — a bucket that does not resolve
sem-data-query-unknown-bucket.html
source
1 <sem-data-visualizer id="dv-services">
2 <sem-data-source data-name="services" data-format="table">
3 | name | port |
4 | :--- | ---: |
5 | api | 8443 |
6 </sem-data-source>
7 <sem-data-query>SELECT name FROM hosts</sem-data-query>
8 </sem-data-visualizer>
render

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

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