---
title: JavaScript からの接続
description: npm の queria パッケージで、ブラウザから SQL を実行し、グラフと地図を描く手順
sidebar:
  label: JavaScript
---

npm の `queria` パッケージを使うと、Web ページの中で Queria のデータセットに SQL を実行し、結果をグラフや地図にできます。SQL はブラウザの DuckDB WASM で実行します。グラフと地図の下には、使ったデータセットの出典とライセンスを表示します。

```bash
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>` の要素が使えます。

```html
<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 />` です。

## 地図

```html
<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

```tsx
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` で列を指定します。

```tsx
<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

```ts
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 のリテラルにしてください。

```ts
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 のロゴを入れます。

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