Integrations5 min read

DuckDBによるSQLクエリ

SQLを使用してスプレッドシートデータと外部データベースを照会する

概要

ModelMonkeyにはDuckDBを搭載したSQLエンジンが内蔵されており、スプレッドシートデータに対して直接SQLクエリを実行できます。また、外部データベース（PostgreSQL、BigQuery）を照会したり、複数のソースにまたがるデータを結合したりすることも可能です。

この機能は、データ変換を正確に制御したい場合、複雑な集計を行いたい場合、または自然言語では明確に表現しにくい方法で異なるソースのデータを組み合わせたい場合に役立ちます。

Tip

SQLを自分で書く必要はありません。やりたいことを平易な言葉で説明するだけで、ModelMonkeyが適切なSQLクエリを生成して実行します。

SQLクエリが使用される場面

リクエストに以下の内容が含まれる場合、ModelMonkeyは自動的にSQLクエリを使用します。

複雑な集計
データのグループ化、合計・平均・件数などの統計演算を多数の行にわたって実行する。

フィルタリングと並び替え
複数の条件に基づいて特定のレコードを検索したり、大規模なデータセットをさまざまな条件で並び替えたりする。

データの結合
スプレッドシートのデータと外部データベースを組み合わせたり、複数のシートをマージしたりする。

データ変換
行ごとの処理が必要な方法でデータを再フォーマット、新しい列の計算、または再構成する。

特定の操作でSQLの精度を優先したい場合は、ModelMonkeyに「SQLを使用して」または「SQLクエリを実行して」と明示的に依頼することもできます。

スプレッドシートデータの照会

スプレッドシートのデータにはsheet_range()関数を通じてアクセスできます。この関数はA1表記の参照を受け取り、照会可能なテーブルとしてデータを返します。

重要な要件

指定範囲の最初の行には列ヘッダーが必要です
列名はヘッダー行から導出されます
ヘッダーが空の場合、列名は "column_1"、"column_2" などになります

サポートされる範囲形式

シート全体: sheet_range('Sheet1!A:Z')
特定の範囲: sheet_range('Sales!A1:D100')
特殊文字を含む名前付き範囲は自動的にエスケープされます

text

-- Query all data from a sheet
SELECT * FROM sheet_range('Sheet1!A1:D100')

-- Filter and aggregate
SELECT category, SUM(amount) as total
FROM sheet_range('Sales!A1:E500')
WHERE date >= '2024-01-01'
GROUP BY category

-- Sort by multiple columns
SELECT * FROM sheet_range('Customers!A:F')
ORDER BY region ASC, revenue DESC

スプレッドシートクエリの例

外部データベースの照会

外部データ接続が設定されている場合、接続名を使用して照会できます。

PostgreSQL
テーブルはconnection_name.schema.tableとして参照します。デフォルトスキーマは通常 "public" です。

BigQuery
テーブルはconnection_name.dataset.tableとして参照します。

外部データベースのクエリは標準SQLとまったく同じように機能します。結合、サブクエリ、ウィンドウ関数、CTEなど、DuckDBがサポートするすべての機能を使用できます。

Tip

照会する前に、まず「外部データ接続」パネルで外部接続を設定してください。

text

-- Query a PostgreSQL table
SELECT * FROM my_postgres.public.customers
WHERE country = 'USA'

-- Query a BigQuery table
SELECT event_date, COUNT(*) as events
FROM my_bigquery.analytics.page_views
GROUP BY event_date

-- Join PostgreSQL with BigQuery
SELECT p.name, b.total_events
FROM my_postgres.public.products p
JOIN my_bigquery.analytics.product_stats b
  ON p.id = b.product_id

外部データベースクエリの例

スプレッドシートとデータベースデータの結合

最も強力な機能の一つは、異なるソースにまたがるデータを結合できることです。スプレッドシートのデータと外部データベースを1つのクエリで組み合わせることができます。

一般的なユースケース

スプレッドシートのレコードをデータベースの顧客データで補完する
ローカルのトラッキングデータをデータウェアハウスと比較する
スプレッドシートのエントリを外部参照テーブルに対して検証する
シートの売上データとデータベースの商品カタログを組み合わせる

text

-- Join spreadsheet orders with database customers
SELECT
  s.order_id,
  s.order_date,
  s.amount,
  c.customer_name,
  c.email,
  c.tier
FROM sheet_range('Orders!A1:D500') s
JOIN my_postgres.public.customers c
  ON s.customer_id = c.id
WHERE s.amount > 1000

-- Cross-database aggregation
SELECT
  c.country,
  COUNT(*) as order_count,
  SUM(s.amount) as total_sales
FROM sheet_range('Sales!A1:C1000') s
JOIN my_postgres.public.customers c
  ON s.customer_id = c.id
GROUP BY c.country
ORDER BY total_sales DESC

クロスソース結合の例

クエリ出力オプション

クエリ結果は2つの方法で出力できます。

インライン結果（デフォルト）
結果はModelMonkeyに直接返され、分析と推論に使用されます。データをどう活用するか決める前にデータを理解したい探索的なクエリに役立ちます。

デフォルトで最大20行を返します（最大100行まで設定可能）
列の型とメタデータを含みます
クイックなデータ探索に最適です

シート出力
結果はスプレッドシートの新しいシートに直接書き込まれます。クエリ結果をその後の作業のために保持したい場合に役立ちます。

指定した名前で新しいシートを作成します
すべての行を含みます（行数制限なし）
ヘッダー行が自動的に追加されます
レポートの作成やデータのステージングに最適です

Tip

シート出力モードを使用するには、ModelMonkeyに「結果を新しいシートに保存して」または「Results というシートに出力を書き込んで」と依頼してください。

データ型の処理

ModelMonkeyはスプレッドシートのデータから列の型を自動的に推論します。

サポートされる型

数値: 整数と小数が検出され、数値型として扱われます
ブール値: TRUE/FALSE の値がブール値として認識されます
テキスト: それ以外はすべてテキスト（VARCHAR）として扱われます
日付: セル内の日付値は通常テキストとして処理されます。解析にはSQLの日付関数を使用してください

型推論のプロセス
ModelMonkeyはデータの最初の数行をサンプリングして各列の適切な型を決定します。列に複数の型が混在している場合、データの損失を防ぐためにテキストがデフォルトになります。

text

-- Parse date strings in queries
SELECT
  order_id,
  strptime(order_date, '%Y-%m-%d') as parsed_date,
  amount
FROM sheet_range('Orders!A1:C100')
WHERE strptime(order_date, '%Y-%m-%d') >= DATE '2024-01-01'

-- Cast numeric strings
SELECT
  product_name,
  CAST(price AS DOUBLE) as numeric_price
FROM sheet_range('Products!A1:B50')

データ型の操作

パフォーマンスに関する考慮事項

クエリの実行

クエリには30秒のタイムアウトがあります
安全のため、最大結果セットは16,384行です
大きなスプレッドシートの範囲はクエリのためにメモリに読み込まれます

ベストプラクティス

列全体ではなく正確な範囲を指定してください（例：A:Dの代わりにA1:D500）
WHERE句を使って早期にフィルタリングし、処理するデータを削減してください
非常に大きなデータセットの場合は、メモリの問題を避けるためにシート出力の使用を検討してください
結合を高速化するために、大きな外部データベーステーブルにインデックスを作成してください

キャッシュ
クエリ結果はリクエスト間でキャッシュされません。各クエリは現在のスプレッドシートデータを再読み込みするため、常に最新の値が取得できます。

Warning

非常に大きな範囲（数万行）はクエリの実行速度を低下させる可能性があります。大規模な分析には、データのフィルタリングまたは外部データベースの使用をご検討ください。

サポートされているSQL機能

ModelMonkeyはDuckDBを通じて幅広いSQL機能をサポートしています。

標準操作

SELECT、FROM、WHERE、ORDER BY、LIMIT
集計関数を使用したGROUP BY（SUM、COUNT、AVG、MIN、MAX など）
DISTINCT および HAVING 句
UNION、INTERSECT、EXCEPT

結合

INNER JOIN、LEFT JOIN、RIGHT JOIN、FULL OUTER JOIN
クロス結合と自己結合
複数テーブルの結合

高度な機能

サブクエリと CTE（WITH 句）
ウィンドウ関数（ROW_NUMBER、RANK、LAG、LEAD など）
CASE 式
文字列関数、日付関数、数学関数

サポート対象外

INSERT、UPDATE、DELETE（クエリは読み取り専用）
CREATE TABLE、ALTER TABLE（スキーマの変更不可）
ストアドプロシージャまたはユーザー定義関数

クエリの例

よく使われるSQLクエリの実用的な例を以下に示します。

text

-- Monthly sales summary
SELECT
  strftime(strptime(date, '%Y-%m-%d'), '%Y-%m') as month,
  COUNT(*) as num_orders,
  SUM(amount) as total_revenue,
  AVG(amount) as avg_order_value
FROM sheet_range('Orders!A1:D1000')
GROUP BY month
ORDER BY month DESC

-- Find duplicate entries
SELECT email, COUNT(*) as count
FROM sheet_range('Contacts!A1:E500')
GROUP BY email
HAVING COUNT(*) > 1

-- Top customers by spending
SELECT
  customer_id,
  SUM(amount) as total_spent,
  COUNT(*) as num_orders
FROM sheet_range('Orders!A1:D1000')
GROUP BY customer_id
ORDER BY total_spent DESC
LIMIT 10

-- Running total with window function
SELECT
  date,
  amount,
  SUM(amount) OVER (ORDER BY date) as running_total
FROM sheet_range('Transactions!A1:C100')

実用的なSQLクエリの例

トラブルシューティング

「列が見つかりません」エラー

ヘッダー行に期待する列名が含まれているか確認してください
列名は大文字と小文字を区別します
列名にスペースを含めることはできますが、複雑なクエリではクォートが必要な場合があります

「無効な範囲」エラー

シート名のスペルが正しいか確認してください
範囲が存在し、データが含まれていることを確認してください
エスケープが必要な特殊文字がシート名に含まれていないか確認してください

「クエリタイムアウト」エラー

クエリを簡略化するか、データ範囲を縮小してください
WHERE 句を追加してデータを早期にフィルタリングしてください
大きな結果セットにはシート出力の使用を検討してください

「接続が見つかりません」エラー

外部接続名が正しいか確認してください
「外部データ接続」パネルで接続がアクティブになっているか確認してください
外部データベースへのアクセス権限があることを確認してください

空または予期しない結果

データ型が WHERE 条件と一致しているか確認してください
日付形式がスプレッドシートの内容と一致しているか確認してください
テキストデータの先頭または末尾のスペースを確認してください