QGISでのQDuckDBプラグイン活用ガイド

:::note info 
これは MIERUNE Advent Calendar 2024 21日目の記事です! 
昨日は@shiori2436さんによる[「Pythonで雪の結晶を描いてみよう」](https://qiita.com/shiori0436/items/b113f7ffa179b28c6dc7)でした。 :snowflake:
:::

# はじめに
Bonjour！
クリスマスが近づいてきましたね。
フランスでは、クリスマスは美味しい料理を楽しむ時期です。
ローストチキンだけでなく、オイスターやスモークサーモンやフォアグラも食卓に並びます。
でも、私が一番好きなのは[鴨のマグレ](https://www.wine-and-food.site/foie-gras-magret-andre-daguin-000821/)。マグレと聞いただけで、美味しさが口の中に感じます。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/168196/5c618130-53a5-def2-c5c1-c8c59619409a.png)
GPTが作ってもらった「鴨のマグレ」の画像

お皿で鴨肉が楽しめるなら、QGISではDuckDBが楽しめます！
QGISでDuckDBを活用できるプラグイン「QDuckDB」が公開されて、この記事ではその使い方をご紹介します。

# DuckDBとは
DuckDBは、高速で組み込み可能な分析向けデータベース管理システム（DBMS）です。
その強みと活用方法について詳しくは、こちらの記事をご覧ください。

https://qiita.com/Kanahiro/items/7b4a3eb2f0ae68f16ddb

# QDuckDBとは

QDuckDBは、公開されているQGISプラグインです。このプラグインを使用すると、DuckDBデータベース内のテーブルからジオメトリを読み込み、QGIS上に直接表示することができます。

https://plugins.qgis.org/plugins/qduckdb/

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/168196/cf0c17d9-8a0f-6922-cf16-21c3b7f694e7.png)




# 事前準備

:::note warn
 現時点では、このプラグインはWindowsでのみ使用可能です。
LinuxやMacOSの場合は、[事前インストール手順](https://oslandia.gitlab.io/qgis/qduckdb/usage/installation.html)に従う必要があります。
:::

### 0. MacOS環境での事前準備
QGISアップ自体内でduckDBをインストールするべきです。

- MacのApplicationsフォルダーにQGISアップのファイル名を確認
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/168196/adafa3f0-023d-5f5b-edfe-87304d7050eb.png)

- Terminalを開き、確認したQGISのアプリ名に合わせて以下のコマンドを実行
```bash
# QGIS.appの場合
/Applications/QGIS.app/Contents/MacOS/bin/python3.9 -m pip install "duckdb==1.1.3"

# QGIS-LTR.appの場合
/Applications/QGIS-LTR.app/Contents/MacOS/bin/python3.9 -m pip install "duckdb==1.1.3"
```

MacOSでQDuckDBを使えるようにしました。

### 1. QDuckDBプラグインのインストール
メニューバー -> プラグイン -> プラグインを管理とインストールを選択
![Capture d’écran 2024-12-07 à 16.26.24.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/168196/d2d64f16-2a48-644a-15c8-cdb3e5fb6087.png)

`QDuckDB`を検索して`インストール`
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/168196/e316924c-a6d9-894d-9743-51538225ef33.png)

### 2. DuckDBのデータベースを設置

インストール後、QGISのツールバーにあるDuckDBアイコンをクリックすると、UIが表示されます。
インターフェイスを確認すると、データベースのファイルを指定しないと操作を進められないようになっています。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/168196/64258fe8-a86c-073b-8591-473f2ec5dbb0.png)

- DuckDBをインストールしていない場合、以下のコマンドを実行してDuckDBをインストールします：
```bash
brew install duckdb
```

- 以下のコマンドを実行してデータベースを作成します。
```bash
duckdb /path/to/your/database/20241214_duckdb/canard.duckdb
```
データベースが作成されました！次はテーブルを入力してみましょう！

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/168196/99422093-690e-7623-1971-728b96fdec04.png)

> ちなみに、「canard」（カナール）はフランス語で「鴨」を意味します。そのため、先ほど記載した「鴨のマグレ」という料理名は、フランス語では「マグレ・ド・カナール」（Magret de Canard）となります。:baby_chick:

### 3. Shapefileをデータベースに入力
Terminalで引き続きデータベースにアクセスし、SQLクエリを実行できます。
- Spatialをインストールしていない場合は、以下のコマンドを実行
```sql
INSTALL spatial;
LOAD spatial;
```

:::note warn
DuckDBでは、コマンドの末尾に必ず `;` を付けないと実行されませんので、ご注意ください。
:::

- [国土数値情報からダウンロードした](https://nlftp.mlit.go.jp/ksj/gml/datalist/KsjTmplt-N03-v2_3.html)都道府県のShapefileを入力クエリ
```sql
CREATE TABLE japan_pref AS SELECT * FROM '/your_path/.../N03-20240101_prefecture.shp';
```

- 以下のクエリで確認して無事に入力できました！これからQDuckDBで読み込んでみましょう。

```sql
SELECT * FROM japan_pref;
  
┌─────────┬─────────┬─────────┬─────────┬─────────┬─────────┬──────────────────────────────────────┐
│ N03_001 │ N03_002 │ N03_003 │ N03_004 │ N03_005 │ N03_007 │                 geom                 │
│ varchar │ varchar │ varchar │ varchar │ varchar │ varchar │               geometry               │
├─────────┼─────────┼─────────┼─────────┼─────────┼─────────┼──────────────────────────────────────┤
│ 北海道  │         │         │         │         │ 01000   │ POLYGON ((141.941187782 45.5214575…  │
│ 北海道  │         │         │         │         │ 01000   │ POLYGON ((148.75263496800002 45.55…  │
│ 北海道  │         │         │         │         │ 01000   │ POLYGON ((146.16670147900004 44.51…  │
│ 北海道  │         │         │         │         │ 01000   │ POLYGON ((146.83198749700003 43.88…  │
│ 北海道  │         │         │         │         │ 01000   │ POLYGON ((141.199192218 45.2588213…  │
```

:::note warn
DuckDBでデータベースにアクセス中はロックがかかり、QGISで使用できなくなるため注意が必要です。
入力作業が終わったら、以下のコマンドでデータベースを終了してください
```
.exit
```
:::

# QDuckDBでデータの読み込み
QGISに戻り、QDuckDBの設定を進めましょう。
- `canard.duckdb`データベースを指定すると、テーブルを正常に認識し、操作できるようになります。
- `Add Layer`をクリックすると都道府県が無事に表示されます！

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/168196/1cff594b-e399-b13f-f830-d4f0ee41d241.png)

### カスタムクエリでも行えます

`Custom SQL query`を使用すれば、特定の条件でデータを絞り込むことができます。
例えば、以下のクエリを使うと`北海道`だけをフィルタリングできます。
```sql
SELECT * FROM japan_pref WHERE N03_001 = '北海道'
```
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/168196/0bebe1fa-6eca-dae2-a799-9f54e1eeccfc.png)

# データに編集について
### QGIS側で編集できない

`japan_pref`のデータを編集しようとして`UPDATE`を記入したのですが、実行できませんでした。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/168196/78fb0c79-45b6-bcfd-4c57-e1f1da938668.png)



そのため、ターミナルでDuckDBに戻り、UPDATEクエリを実行します。

:::note warn
ただし、データベースにアクセスするとQGISでロックがかかり使用できなくなるため、UPDATEクエリを実行する際は一度QGISを閉じる必要があります。
:::

```bash
duckdb /.../20241214_duckdb/canard.duckdb
Error: unable to open database "/.../20241214_duckdb/canard.duckdb": 
IO Error: Could not set lock on file "/.../20241214_duckdb/canard.duckdb": 
Conflicting lock is held in /Applications/QGIS-LTR.app/Contents/MacOS/QGIS (PID 34286) by user bordoray. 
However, you would be able to open this database in read-only mode, 
e.g. by using the -readonly parameter in the CLI. 
See also https://duckdb.org/docs/connect/concurrency
```

### DuckDB側で編集

QGISを閉じた後、Terminal上で以下のクエリを実行することで、無事に編集を行うことができました。

```sql
UPDATE japan_pref SET N03_001 = '蝦夷' WHERE N03_001 = '北海道';
SELECT * FROM japan_pref;
┌─────────┬─────────┬─────────┬─────────┬─────────┬─────────┬──────────────────────────────────────┐
│ N03_001 │ N03_002 │ N03_003 │ N03_004 │ N03_005 │ N03_007 │                 geom                 │
│ varchar │ varchar │ varchar │ varchar │ varchar │ varchar │               geometry               │
├─────────┼─────────┼─────────┼─────────┼─────────┼─────────┼──────────────────────────────────────┤
│ 蝦夷    │         │         │         │         │ 01000   │ \x02\x04\x00\x00\x00\x00\x00\x00\x…  │
│ 蝦夷    │         │         │         │         │ 01000   │ \x02\x04\x00\x00\x00\x00\x00\x00\x…  │
│ 蝦夷    │         │         │         │         │ 01000   │ \x02\x04\x00\x00\x00\x00\x00\x00\x…  │
│ 蝦夷    │         │         │         │         │ 01000   │ \x02\x04\x00\x00\x00\x00\x00\x00\x…  │
│ 蝦夷    │         │         │         │         │ 01000   │ \x02\x04\x00\x00\x00\x00\x00\x00x …  │
│ 蝦夷    │         │         │         │         │ 01000   │ \x02\x04\x00\x00\x00\x00\x00\x00\x…  │
│ 蝦夷    │         │         │         │         │ 01000   │ \x02\x04\x00\x00\x00\x00\x00\x00F\…  │
│ 蝦夷    │         │         │         │         │ 01000   │ \x02\x04\x00\x00\x00\x00\x00\x00\x…  │
│ 蝦夷    │         │         │         │         │ 01000   │ \x02\x04\x00\x00\x00\x00\x00\x00\x…  │

```

- 編集後は、忘れずに`exit`で終了してください。


# おまけ：Overture Mapsデータの読み込み
以下の記事では、`Geoparquet Downloader`のQGISプラグインを使ってOverture Mapsを簡単に取得する方法を紹介していますが、MacOSの場合は事前インストールが必要です。

https://qiita.com/bordoray/items/81777963edaba2697e94#1-qduckdb%E3%83%97%E3%83%A9%E3%82%B0%E3%82%A4%E3%83%B3%E3%81%AE%E3%82%A4%E3%83%B3%E3%82%B9%E3%83%88%E3%83%BC%E3%83%AB

本記事ではMacOS環境で`QDuckDB`をインストールすることができましたが、`Geoparquet Downloader`を利用するには、Geoparquetを読み込むためのライブラリも必要です。

ただし、`QDuckDB`とデータベースがあれば、SQLでS3に直接アクセスしてOverture Mapsを取得することも可能です。

参考

https://docs.overturemaps.org/getting-data/duckdb/

領域に合わせて以下のクエリを記入することで、Overture Mapsを無事に取得できました！

```sql
SELECT
       id,
       names.primary as name,
       confidence AS confidence,
       CAST(socials AS JSON) as socials,    
       geometry                             
    FROM read_parquet('s3://overturemaps-us-west-2/release/2024-12-18.0/theme=places/type=place/*', filename=true, hive_partitioning=1)
    WHERE bbox.xmin BETWEEN 140.06 AND 140.167 
    AND bbox.ymin BETWEEN 36.387 AND 36.526
```

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/168196/e7b0cbfb-d8cf-f605-673a-892f646e3fb6.png)




# おわりに
QDuckDBでは、DuckDBのデータベースを簡単にQGISで表示できます。ただし、データの編集ができないの点には注意が必要です。
また、クエリを使ってOverture Mapsのデータを取得することも可能でありがたいです。
ぜひ、QDuckDB（と美味しい鴨肉）を楽しんでください！

:::note info 
明日は@chizutodesignさんによる記事です！お楽しみに！！ 
:::