You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Observable Framework includes built-in support for client-side SQL powered by [DuckDB](./lib/duckdb). You can use SQL to query data from [CSV](./lib/csv), [TSV](./lib/csv), [JSON](./javascript/files#json), [Apache Arrow](./lib/arrow), and [Apache Parquet](./lib/arrow#apache-parquet) files, which can either be static or generated by [data loaders](./loaders).
9
+
10
+
To use SQL, first register the desired tables in the page’s [front matter](./markdown#front-matter) using the **sql** option. Each key is a table name, and each value is the path to the corresponding data file. For example, to register a table named `gaia` from a Parquet file:
11
+
12
+
```yaml
13
+
---
14
+
sql:
15
+
gaia: ./lib/gaia-sample.parquet
16
+
---
17
+
```
18
+
19
+
## SQL code blocks
20
+
21
+
To run SQL queries, create a SQL fenced code block (<code>```sql</code>). For example, to query the first 10 rows from the `gaia` table:
22
+
23
+
````md
24
+
```sql
25
+
SELECT * FROM gaia ORDER BY phot_g_mean_mag LIMIT 10
26
+
```
27
+
````
28
+
29
+
This produces a table:
30
+
31
+
```sql
32
+
SELECT*FROM gaia ORDER BY phot_g_mean_mag LIMIT10
33
+
```
34
+
35
+
To refer to the results of a query in JavaScript, use the `id` directive. For example, to refer to the results of the previous query as `top10`:
36
+
37
+
````md
38
+
```sql id=top10
39
+
SELECT * FROM gaia ORDER BY phot_g_mean_mag LIMIT 10
40
+
```
41
+
````
42
+
43
+
```sql id=top10
44
+
SELECT*FROM gaia ORDER BY phot_g_mean_mag LIMIT10
45
+
```
46
+
47
+
This returns an array of 10 rows, inspected here:
48
+
49
+
```js echo
50
+
top10
51
+
```
52
+
53
+
When a SQL code block uses the `id` directive, the results are not displayed by default. You can display them by adding the `display` directive, which produces the table shown above.
54
+
55
+
````md
56
+
```sql id=top10 display
57
+
SELECT * FROM gaia ORDER BY phot_g_mean_mag LIMIT 10
58
+
```
59
+
````
60
+
61
+
The `id` directive is often a simple identifier such as `top10` above, but it supports [destructuring assignment](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Destructuring_assignment), so you can refer to individual rows and columns using array and object patterns. For example, to pull out the top row:
62
+
63
+
````md
64
+
```sql id=[top]
65
+
SELECT * FROM gaia ORDER BY phot_g_mean_mag LIMIT 1
66
+
```
67
+
````
68
+
69
+
```sql id=[top]
70
+
SELECT*FROM gaia ORDER BY phot_g_mean_mag LIMIT1
71
+
```
72
+
73
+
```js echo
74
+
top
75
+
```
76
+
77
+
Or to pull out the minimum value of the `phot_g_mean_mag` column:
78
+
79
+
````md
80
+
```sql id=[{min}]
81
+
SELECT MIN(phot_g_mean_mag) AS min FROM gaia
82
+
```
83
+
````
84
+
85
+
```sql id=[{min}]
86
+
SELECTMIN(phot_g_mean_mag) AS min FROM gaia
87
+
```
88
+
89
+
```js echo
90
+
min
91
+
```
92
+
93
+
<divclass="tip">
94
+
95
+
For complex destructuring patterns, you may need to quote the `id` directive. For example, to pull out the column named `min(phot_g_mean_mag)` to the variable named `min`, say <codestyle="white-space: nowrap;">id="[{'min(phot_g_mean_mag)': min}]"</code>. Or to pull out the `min` and `max` columns, say <codestyle="white-space: nowrap;">id="[{min, max}]"</code>.
96
+
97
+
</div>
98
+
99
+
For dynamic or interactive queries that respond to user input, you can interpolate values into SQL queries using inline expressions `${…}`. For example, to show the stars around a given brightness:
SELECT*FROM gaia WHERE phot_g_mean_mag BETWEEN ${mag -0.1} AND ${mag +0.1};
107
+
```
108
+
109
+
The value of a SQL code block is an [Apache Arrow](./lib/arrow) table. This format is supported by [Observable Plot](./lib/plot), so you can use SQL and Plot together to visualize data. For example, below we count the number of stars in each 2°×2° bin of the sky (where `ra` is [right ascension](https://en.wikipedia.org/wiki/Right_ascension) and `dec` is [declination](https://en.wikipedia.org/wiki/Declination), representing a point on the celestial sphere in the equatorial coordinate system), and then visualize the resulting heatmap using a [raster mark](https://observablehq.com/plot/marks/raster).
110
+
111
+
```sql id=bins echo
112
+
SELECT
113
+
floor(ra /2) *2+1AS ra,
114
+
floor(dec /2) *2+1AS dec,
115
+
count() AS count
116
+
FROM
117
+
gaia
118
+
GROUP BY
119
+
1,
120
+
2
121
+
```
122
+
123
+
```js echo
124
+
Plot.plot({
125
+
aspectRatio:1,
126
+
x: {domain: [0, 360]},
127
+
y: {domain: [-90, 90]},
128
+
marks: [
129
+
Plot.frame({fill:0}),
130
+
Plot.raster(bins, {
131
+
x:"ra",
132
+
y:"dec",
133
+
fill:"count",
134
+
width:360/2,
135
+
height:180/2,
136
+
imageRendering:"pixelated"
137
+
})
138
+
]
139
+
})
140
+
```
141
+
142
+
## SQL literals
143
+
144
+
SQL fenced code blocks are shorthand for the `sql` tagged template literal. You can invoke the `sql` tagged template literal directly like so:
145
+
146
+
```js echo
147
+
constrows=awaitsql`SELECT random() AS random`;
148
+
```
149
+
150
+
```js echo
151
+
rows[0].random
152
+
```
153
+
154
+
The `sql` tagged template literal is available by default in Markdown, but you can also import it explicitly as:
0 commit comments