JavaScript からの接続
npm の queria パッケージで、ブラウザから SQL を実行し、グラフと地図を描く手順
npm の queria パッケージを使うと、Web ページの中で Queria のデータセットに SQL を実行し、結果をグラフや地図にできます。SQL はブラウザの DuckDB WASM で実行します。グラフと地図の下には、使ったデータセットの出典とライセンスを表示します。
npm install queria
グラフを描くときは vega・vega-lite・vega-embed・vega-interpreter を、地図を描くときは maplibre-gl を追加でインストールします。使わない部品のライブラリは要りません。
パッケージはバージョン 0.x です。1.0 までは、どのリリースでも互換性のない変更が入ることがあります。
データセットの指定
読むデータセットを完全修飾名(queria/e_stat のような 持ち主/名前)で宣言します。SQL の中では名前の後半で参照します(e_stat.<スキーマ>.<テーブル>)。同じ名前のデータセットを 2 つ読むときは、{ a: "alice/e_stat", b: "bob/e_stat" } のように別名を付けます。
HTML
queria/elements/define を読み込むと、<queria-chart> と <queria-map> の要素が使えます。
<script type="module">import "queria/elements/define";</script>
<queria-chart
datasets="queria/e_stat"
spec='{"mark": "line", "encoding": {"x": {"field": "year"}, "y": {"field": "population", "type": "quantitative"}}}'
sql="SELECT year, any_value(value) AS population FROM e_stat.ssds.a_municipal_population
WHERE area = '13224' AND cat01 = 'A1101' GROUP BY year ORDER BY year"></queria-chart>
spec は Vega-Lite の仕様です。SQL の結果が data に入ります。
save-image を付けると、出典の行に「Save image」のボタンを表示します。押すと、グラフを 1200 × 630 ピクセルの PNG でダウンロードします。画像は chartPng() で作り、datasets のデータセットの出典とライセンスの行と Queria のロゴを入れます。色・フォント・数値の書き方は、表示しているグラフと同じにします。React では <Chart saveImage /> です。
地図
<queria-map
datasets="queria/e_stat"
layer='{"area": "city", "code": "lg_code", "color": "population", "label": "lg_code"}'
sql="SELECT area AS lg_code, any_value(value) AS population
FROM e_stat.ssds.a_municipal_population
WHERE area LIKE '13%' AND year = 2020 AND cat01 = 'A1101' GROUP BY area"></queria-map>
layer で行を地図に置く方法を指定します。
| 項目 | 内容 |
|---|---|
area・code |
地域コードで置くとき。area は prefecture・city・small_area のどれか、code は地域コードの列名 |
lng・lat |
経緯度で置くとき。経度と緯度の列名 |
color |
色を分ける列。数値は値の小さい順に薄い色から濃い色、それ以外は値ごとに 1 色 |
label |
マウスを重ねたときに表示する列 |
opacity |
不透明度(0〜1) |
ページに maplibre-gl の CSS を読み込んでください。地図の高さは CSS 変数 --queria-map-height(既定は 400px)で指定します。
React
import { Chart, DataMap, QueriaProvider, Table } from "queria/react";
<QueriaProvider datasets={["queria/e_stat"]}>
<Chart sql={sql} spec={spec} />
<DataMap sql={sql} layer={layer} />
<Table sql={sql} />
</QueriaProvider>;
Table は SQL の結果をテーブルで表示します。表示するのは既定で 100 行までで、limit で変更できます。HTML では <queria-table sql="...">、JavaScript では renderTable(el, rows) で同じテーブルを表示します。
Kpi は 1 つの数値を大きく表示し、その下に前年比を表示します。value で指定した列を最後の行から読み、1 つ前の行の値と比較します。年の順に並べた SQL なら前年からの増減になります。最後の行の別の列と比較するときは compare で列を指定します。
<Kpi sql={sql} value="population" label="人口" unit="人" />
1 万以上の数値は「139.4万」のように万・億で表示します(compact={false} で全桁)。unit が % のときは増減をポイント(pt)で表示します。比較の見出しは compareLabel で変更できます(既定は「前年比」)。HTML では <queria-kpi sql="..." value="population">、JavaScript では renderKpi(el, rows, { value }) で同じ表示になります。
行だけが必要なときは、QueriaProvider の中で useQuery(sql) を使います。status が loading・done・error のどれかで、done のときに rows を持ちます。
JavaScript
import { connect, renderChart } from "queria";
const q = connect({ datasets: ["queria/e_stat"] });
const rows = await q.sql(sql);
await renderChart(el, spec, rows);
connect() は sql() と sources() を持つ接続を返します。sql() は結果を行の配列で返し、SQL が参照するデータセットを最初の実行時に ATTACH します。sources() は出典の表示に使うデータセットの情報を返します。地図は renderMap(el, layer, rows) で描きます。
SQL の文字列に値を埋め込むときは、lit() で SQL のリテラルにしてください。
import { lit } from "queria";
const rows = await q.sql(`SELECT year, value FROM e_stat.ssds.a_municipal_population WHERE area = ${lit(code)}`);
ST_* の関数を使う SQL では、DuckDB の spatial 拡張を最初の実行時に読み込みます。
画像の書き出し
chartPng() はグラフを PNG の画像にします。SNS に投稿する画像を作るときに使います。画像は 1200 × 630 ピクセルで、背景を塗りつぶし、グラフの下に出典とライセンスの行と Queria のロゴを入れます。
import { chartPng, connect } from "queria";
const q = connect({ datasets: ["queria/e_stat"] });
const blob = await chartPng(spec, await q.sql(sql), { sources: await q.sources(sql) });
sources を省くと、出典の行とロゴの無いグラフだけの画像になります。そのほかのオプションは次のとおりです。
| 項目 | 内容 |
|---|---|
theme |
light(既定)か dark |
highlight |
紫で強調する値。renderChart() と同じ |
width・height |
画像の大きさ(CSS ピクセル、既定は 600 × 315、出典の行を含む) |
scale |
1 CSS ピクセルあたりのピクセル数(既定は 2) |
chartSvg() は同じオプションで、画像を SVG の文字列で返します。Node でも実行できるので、ビルド時やサーバーで画像を作るときに使います。画像の文字は、描く環境にインストールされているフォントで表示します。
非公開のデータセット
非公開のデータセットを読むときは、connect({ datasets, token }) にデータトークン(qd_ で始まる文字列)か、それを返す関数を渡します。トークンは Queria の API と、宣言したデータセットのホストにだけ送ります。
API トークン(qk_)は、公開するページの HTML や JavaScript に書かないでください。ページを開いた人がトークンを読み取れます。
