コンテンツにスキップ
Queria Docs
Esc
↑↓移動↵開く⌘Jプレビュー
このページの内容

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 に書かないでください。ページを開いた人がトークンを読み取れます。

このページは役に立ちましたか?