ユーザーテーブルを利用する (Early access): ユーザーテーブルを利用する (Early access) | SORACOM Query

ユーザーテーブルは、お客様が用意した CSV ファイルを SORACOM Query に登録し、SQL クエリから参照できるようにする機能です。SORACOM に蓄積されたデータ (IoT SIM の通信統計や Harvest Data に保存されたセンサーデータなど) と、SORACOM が保持していないお客様側のデータを組み合わせて分析できます。

ユーザーテーブルには、以下の 2 つの特徴があります。

データは、SQL クエリを実行するたびに読み直されます。 CSV ファイルの中身は SORACOM Harvest Files に保存されたままで、SORACOM Query 側にコピーされることはありません。
スキーマは、登録したときに固定されます。 カラムの構成とデータ型は、登録時に決まった内容が使われ続けます。

ユーザーテーブルは Early access です

ユーザーテーブルは Free プランでは利用できません。Business プランまたは Enterprise プランを利用中のアカウントが対象です。
この機能を利用するには、ユーザーテーブル (Early access) への申し込みが必要です。
Early access の位置づけは用語集を参照してください。

ユーザーテーブルを利用すると SORACOM Harvest Files の料金が発生します

アップロードした CSV ファイルは SORACOM Harvest Files に保存されます。また、ユーザーテーブルを参照する SQL クエリは、実行のたびに Harvest Files からファイルを読み直します。この読み出しはお客様自身の認証情報で行われ、Harvest Files では書き込みと読み出しのそれぞれに料金が発生します。詳しくは、SORACOM Harvest Files の料金プランを参照してください。

ユーザーテーブルでできること

SORACOM Query のデータウェアハウスには、IoT SIM の通信統計やセッションイベント、Harvest Data に保存されたセンサーデータなどが収集されています。ただし、これらのデータで IoT SIM を識別する値は SIM ID や IMSI であり、その IoT SIM を搭載したデバイスの名称や機種、設置先の拠点名といった情報は SORACOM 側にはありません。

ユーザーテーブルを利用すると、こうしたお客様側のデータを保存した CSV ファイルをユーザーテーブルとして登録し、SQL クエリの中で SORACOM のデータと結合できます。

たとえば、SIM ID と設置先の拠点名、地域、機種、設置日を対応づけた site-master.csv という CSV ファイルを用意したとします。

sim_id,site_name,region,device_model,installed_on
8942310000000000001,Warehouse A,North,TH-200,2025-04-02
8942310000000000002,Warehouse B,North,TH-200,2025-04-09
8942310000000000003,Warehouse C,South,TH-200,2025-05-14
8942310000000000004,Factory East,East,TH-450,2025-06-01
8942310000000000005,Factory West,West,TH-450,2025-06-18
8942310000000000006,Depot North,North,TH-200,2025-07-02
8942310000000000007,Depot South,South,TH-450,2025-07-21
8942310000000000008,Head Office,Central,TH-450,2025-08-05

この CSV ファイルをユーザーテーブル HF_SITE_MASTER として登録すると、IoT SIM のデータ通信量を日ごとに集計した SIM_STATS_DAILY_SUMMARY テーブルと結合して、データ通信量を SIM ID ではなく拠点ごとに集計できます。

SELECT
    m.SITE_NAME,
    SUM(s.UPLINK_BYTES + s.DOWNLINK_BYTES) AS TOTAL_BYTES
FROM SIM_STATS_DAILY_SUMMARY AS s
JOIN HF_SITE_MASTER AS m
    ON s.SIM_ID = m.SIM_ID
GROUP BY m.SITE_NAME
ORDER BY TOTAL_BYTES DESC

SQL クエリの実行結果や SORACOM Lagoon の Dashboard に SIM ID が並ぶ代わりに、運用担当者がそのまま読める拠点名が表示されるため、分析結果を関係者と共有しやすくなります。

ユーザーテーブル (Early access) を申し込む

ユーザーテーブルは Free プランでは利用できません。Business プランまたは Enterprise プランを利用中のアカウントが対象です。プランについて詳しくは、SORACOM Query のプランを参照してください。

Business プランまたは Enterprise プランを利用中の場合でも、ユーザーテーブルは自動的には有効になりません。利用するには申し込みが必要です。

SORACOM サポートにお問い合わせください。有効化が完了すると、SORACOM Query Studio でユーザーテーブルを操作できるようになります。

SAM ユーザーでも操作できます

ユーザーテーブルの作成、説明の変更、削除は、ルートユーザーだけでなく SAM ユーザーでも行えます。SAM ユーザーで操作するには、Analysis:listUserTables、Analysis:previewUserTable、Analysis:registerUserTable、Analysis:updateUserTable、Analysis:deleteUserTable の各権限を許可してください。

あわせて、この画面が利用する SORACOM Harvest Files の権限も必要です。ファイルを一覧から選ぶには FileEntry:listFiles、CSV ファイルをアップロードするには FileEntry:getFileMetadata と FileEntry:putFile、ユーザーテーブルを参照する SQL クエリの実行時に CSV ファイルを読み出すには FileEntry:getFile を許可してください。

権限を設定する操作について詳しくは、SAM ユーザーの権限を設定するを参照してください。

ユーザーテーブルを作成する

操作を始める前に準備が必要です (クリックして確認してください)

ユーザーテーブル (Early access) の申し込みが完了し、SORACOM 側で有効化されていること
ユーザーテーブルとして登録する CSV ファイルが利用できる CSV ファイルの条件を満たしていること

準備完了

ユーザーテーブルの作成は、CSV ファイルを SORACOM Harvest Files にアップロードする操作と、アップロードした CSV ファイルをユーザーテーブルとして登録する操作の 2 つに分かれています。

SORACOM Query Studio をアドバンスドモードで表示します。
詳しくは、SORACOM Query Studio を表示するを参照してください。
[ユーザーテーブル] をクリックします。
登録済みのユーザーテーブルの一覧が表示されます。

登録できるユーザーテーブルの数はプランによって異なります
現在の登録数と上限は、ユーザーテーブルの一覧で確認できます。登録数が上限に達している場合は、新しいユーザーテーブルを登録できません。登録数がプランの上限を超えている間は、SQL クエリも実行できません。
[テーブル追加] をクリックします。
一覧から、登録する CSV ファイルをクリックします。
[Harvest ファイルパス] に、選択した CSV ファイルのパスが入力されます。
- [Harvest ファイルパス] にパスを直接入力することもできます。
- CSV ファイルをまだ Harvest Files にアップロードしていない場合は、[CSV をここにアップロード] をクリックします。CSV ファイルがアップロードされます。アップロード先に同じ名前の CSV ファイルがすでにある場合は、上書きするかどうかの確認が表示されます。上書きすると、そのファイルを参照している既存のユーザーテーブルのデータも入れ替わります。
[プレビュー] をクリックします。
CSV ファイルの先頭部分が読み込まれ、以下の情報が表示されます。
- CSV ファイルのファイル名から導出されたテーブル名とファイルパス
- カラム名とデータ型
- 最大 5 行のサンプルデータ
テーブル名は CSV ファイルのファイル名から自動的に決まります。登録時にも、登録後にも変更できません。テーブル名を変えたい場合は、CSV ファイルのファイル名を変更してアップロードし直してください。テーブル名の決まり方は、SQL クエリからユーザーテーブルを参照するを参照してください。

必要に応じて、以下の項目を変更します。

項目	説明
[CSV にヘッダー行がある]	デフォルトではオンです。この設定を変更すると、カラム名とデータ型が再度読み込まれます。
[名前]	自動的に決まったカラム名を変更できます。カラム名の決まり方は、カラム名の決まり方を参照してください。
[型]	自動的に判定されたデータ型を変更できます。`VARCHAR`、`INTEGER`、`FLOAT`、`NUMBER`、`BOOLEAN`、`DATE`、`TIMESTAMP`、`TIMESTAMP_NTZ` から選択できます。
[説明]	ユーザーテーブルの内容を説明する文章です。200 文字まで入力できます。この説明は SQL アシスタント (AI) にも渡されるため、生成される SQL クエリの精度に影響します。詳しくは、SQL アシスタント (AI) からユーザーテーブルを利用するを参照してください。

ユーザーテーブルの説明以外は登録後に変更できません

ユーザーテーブルを登録したあとに変更できるのは、説明だけです。[CSV にヘッダー行がある]、[名前]、[型] の設定を変更する場合は、ユーザーテーブルを削除して作成し直してください。

データ型を変更する例

SIM ID のように数字だけで構成されたカラムは、INTEGER と判定されます。SORACOM が提供するテーブルの SIM_ID は文字列のため、SIM ID で結合する場合は、登録する前に VARCHAR に変更してください。

[登録] をクリックします。
ユーザーテーブルが作成され、SQL クエリから参照できるようになります。

ユーザーテーブルに登録される情報

ユーザーテーブルとして登録されるのは、テーブル名、カラムの構成、参照する CSV ファイルの場所のようなメタ情報だけです。CSV ファイルの中身は Harvest Files に保存されたままで、SORACOM Query のデータウェアハウスにコピーされることはありません。

このため、動作は以下のようになります。

データは常に最新のものが参照されます。 SQL クエリを実行するたびに、その SQL クエリが参照するユーザーテーブルの登録に使用した CSV ファイルが Harvest Files から読み込まれます。Harvest Files 上の CSV ファイルを新しい内容で上書きすると、次に実行する SQL クエリから新しいデータが参照されます。ユーザーテーブルを登録し直す必要はありません。
スキーマは登録したときのまま固定されます。 カラムの構成とデータ型は、登録時に決まった内容が使われ続けます。カラムの構成が異なる CSV ファイルで上書きしても、ユーザーテーブルのスキーマは追随しません。カラムの構成やデータ型を変更する場合は、ユーザーテーブルを削除して作成し直してください。

ユーザーテーブルとして登録した CSV ファイルを削除しないでください

ユーザーテーブルとして登録した CSV ファイルを SORACOM Harvest Files から削除すると、そのユーザーテーブルを参照する SQL クエリは失敗します。CSV ファイルを削除しても、ユーザーテーブルの一覧には表示されたままです。

カラム名の決まり方

CSV ファイルにヘッダー行がある場合は、ヘッダー行の値を以下のように変換した文字列がカラム名になります。

前後の空白を取り除き、英字を大文字に変換します。
半角英数字とアンダースコア (_) 以外の文字を、アンダースコアに置き換えます。連続するアンダースコアは 1 つにまとめ、先頭と末尾のアンダースコアは取り除きます。
変換した結果が空になる場合は COLUMN にします。先頭が数字になる場合は、先頭に COL_ を付けます。

たとえば、site name は SITE_NAME になります。

変換した結果、同じカラム名が複数になる場合は、2 つ目以降に _2、_3 のような連番が付きます。エラーにはなりません。

ヘッダー行は半角英数字で記述してください

カラム名に使えるのは半角英数字とアンダースコアだけです。日本語のヘッダー行は、変換の結果すべての文字が失われるため、カラム名を判別できなくなります。

たとえば、拠点名,機種,設置日 というヘッダー行の CSV ファイルは、COLUMN、COLUMN_2、COLUMN_3 という 3 つのカラムになります。エラーにはならないため、そのまま登録できてしまいます。

すでにアップロードした CSV ファイルのヘッダー行が日本語の場合は、登録時にカラム名を手動で変更するか、CSV ファイルのヘッダー行を半角英数字に書き換えてアップロードし直してください。

CSV ファイルにヘッダー行がない場合は、左から順に COL_1、COL_2、... がカラム名になります。

データ型の判定について

データ型は、カラムごとに値を調べて自動的に判定されます。判定の対象になるのは CSV ファイルの先頭 100 行までです。空の値は判定に使われず、対象の範囲がすべて空のカラムは VARCHAR になります。

データ型は先頭 100 行だけで判定されます

101 行目以降にしか現れない値は、データ型の判定に反映されません。たとえば、先頭 100 行がすべて数値で、それより後の行に数値以外の値が含まれるカラムは INTEGER と判定されます。このユーザーテーブルを SQL クエリから参照すると、データの読み込み時に失敗します。

CSV ファイルの後半に異なる形式の値が含まれる可能性がある場合は、登録する前にデータ型を VARCHAR に変更してください。

利用できる CSV ファイルの条件

項目	条件
文字コード	UTF-8
区切り文字	カンマ (`,`) のみ
引用符	ダブルクォート (`"`)
ヘッダー行	任意。デフォルトではヘッダー行があるものとして扱われます。
ファイルサイズ	1 ファイルあたり最大 50 MiB
カラム数	最大 50

CSV ファイルのサイズには上限があります

1 つの CSV ファイルは、50 MiB 以下にしてください。50 MiB を超える CSV ファイルも SORACOM Harvest Files へアップロードできますが、ユーザーテーブルとして登録するとき、または SQL クエリを実行するときに失敗します。
1 つの SQL クエリで複数のユーザーテーブルを参照する場合は、ユーザーテーブルの登録に使用した CSV ファイルの合計サイズを 1.5 GiB 以下にしてください。1.5 GiB を超えると、SQL クエリの実行に失敗します。

データ行が 1 行もない CSV ファイルは登録できません。
CSV ファイルではないファイル (画像ファイルや実行ファイルなど) は、内容から判定され、登録が拒否されます。
空のセルは、NULL として読み込まれます。

SQL アシスタント (AI) からユーザーテーブルを利用する

登録したユーザーテーブルは、SORACOM が提供するテーブルと同じように、SQL アシスタント (AI) から利用できます。「拠点ごとの先月のデータ通信量を多い順に表示してください。」のように自然言語で問い合わせると、ユーザーテーブルを参照する SQL クエリが生成されます。SQL を自分で書く必要はありません。

このとき、ユーザーテーブルに登録した説明が SQL アシスタント (AI) に渡されます。説明は、SQL アシスタント (AI) がそのテーブルの内容を理解するための重要な手がかりです。カラム名だけでは、そのテーブルが何を表しているのか、どのテーブルと結合できるのかまではわかりません。

説明は具体的に書いてください

「デバイス一覧」や「CSV データ」のような説明では、SQL アシスタント (AI) はテーブルの使いどころを判断できません。以下のように、1 行が何を表すか、どのカラムが SORACOM のテーブルと対応するかまで書いてください。

「IoT SIM と設置先の対応表。1 行が 1 台のデバイスを表す。SIM_ID は SIM_STATS_DAILY_SUMMARY の SIM_ID と対応する。SITE_NAME は設置先の拠点名、REGION は拠点が属する地域、DEVICE_MODEL はデバイスの機種名、INSTALLED_ON は設置日」

説明は登録後にも変更できるため、SQL アシスタント (AI) が期待どおりの SQL クエリを生成しない場合は、説明を書き足してから試してください。

SQL アシスタント (AI) には、登録されているすべてのユーザーテーブルの情報が渡されます。SQL クエリで参照しているユーザーテーブルだけではありません。渡されるのは、テーブル名、テーブルの説明、各カラムの名前とデータ型です。CSV ファイルの中身が渡されることはありません。

ユーザーテーブルの情報は指示としては扱われません

ユーザーテーブルのテーブル名、カラムの定義、説明は、SORACOM が提供するテーブルのスキーマとは区別して SQL アシスタント (AI) に渡され、指示ではなくデータとして扱われます。これらの中に SQL アシスタント (AI) への指示のような文章が含まれていても、その指示には従いません。

エージェントモードでは SORACOM Harvest Files の料金が増えることがあります

[エージェントモード] を有効化すると、SQL アシスタント (AI) は生成した SQL クエリを自動的に実行し、必要に応じて調整して実行し直します。そのため、1 つの質問に答えるまでに SQL クエリを複数回実行することがあります。SQL クエリが実行される仕組みと、クエリ実行回数の数え方については、SQL アシスタント (AI) を参照してください。

SQL クエリを実行するたびに、その SQL クエリが参照するユーザーテーブルの登録に使用した CSV ファイルが SORACOM Harvest Files から読み直されます。そのため、1 つの質問で同じ CSV ファイルが何度も読み出されることがあります。読み出したファイルのサイズは、そのたびに Harvest Files の読み出し料金に加算されます。なお、SQL アシスタント (AI) がユーザーテーブルを参照するかどうかは、質問の内容によって異なります。

SQL クエリからユーザーテーブルを参照する

ユーザーテーブルのテーブル名は、CSV ファイルのファイル名から自動的に決まります。

ディレクトリを除いたファイル名から、拡張子 (.csv) を取り除きます。
英字を大文字に変換し、半角英数字とアンダースコア (_) 以外の文字をアンダースコアに置き換えます。連続するアンダースコアは 1 つにまとめ、先頭と末尾のアンダースコアは取り除きます。
先頭に HF_ を付けます。

たとえば、path/to/my-devices.csv をアップロードすると、テーブル名は HF_MY_DEVICES になります。

SQL クエリでは、データベース名やスキーマ名を付けずに、このテーブル名をそのまま指定します。

SELECT * FROM HF_MY_DEVICES

SIM_STATS_DAILY_SUMMARY などの SORACOM が提供するテーブルと同じように、JOIN で結合したり、WHERE で絞り込んだりできます。結合の例は、ユーザーテーブルでできることを参照してください。

テーブル名には必ず HF_ が付くため、SORACOM が提供するテーブルと名前が重複することはありません。

一方、ユーザーテーブル同士では名前が重複することがあります。テーブル名はディレクトリを除いたファイル名から決まるため、別のディレクトリにある同じ名前の CSV ファイルからは同じテーブル名が導出され、2 つ目のユーザーテーブルの登録に失敗します。

ユーザーテーブルを削除する

ユーザーテーブルを削除しても CSV ファイルは削除されません

ユーザーテーブルを削除すると、SQL クエリからそのテーブルを参照できなくなりますが、ユーザーテーブルとして登録した CSV ファイルは SORACOM Harvest Files に残ります。CSV ファイルも不要な場合は、Harvest Files から削除してください。詳しくは、SORACOM Harvest Files からファイルをダウンロード / 削除するを参照してください。

SORACOM Query Studio をアドバンスドモードで表示し、[ユーザーテーブル] をクリックします。
一覧から削除するユーザーテーブルを探し、行の右端にある削除アイコンをクリックします。
表示された内容を確認して、[ユーザーテーブルを削除] をクリックします。

ユーザーテーブルの登録が解除され、SQL クエリからそのテーブルを参照できなくなります。

同じテーブル名で登録し直せます

カラムの構成やデータ型、ヘッダー行の設定を変更する場合は、ユーザーテーブルを削除してから、同じ CSV ファイルを登録し直してください。削除したあとであれば、同じテーブル名で登録できます。

削除する前に登録し直そうとすると、テーブル名が重複するため登録に失敗します。

エラーが表示された場合

ユーザーテーブルの登録に失敗する

エラーメッセージ	原因と対処
`CSV からカラム型を推論できませんでした`	CSV ファイルとして読み取れないか、データ行が 1 行もありません。UTF-8 のカンマ区切りのファイルであること、ヘッダー行以外に 1 行以上のデータがあることを確認してください。
`Harvest ファイルのダウンロードに失敗しました`	CSV ファイルのパス、Harvest Files にファイルが存在すること、ファイルを読み出す権限があることを確認してください。CSV ファイルのサイズが 50 MiB を超えている場合も表示されます。その場合は、ファイルを分割するか、不要な行やカラムを減らしてからアップロードし直してください。
`カラム名が重複しています`	複数のカラムに同じカラム名を指定しています。登録する前にカラム名を変更してください。
`カラム数が多すぎます`	カラム数が上限 (50) を超えています。カラムを減らしてからアップロードし直してください。
`テーブル <テーブル名> は既に存在するか作成できませんでした`	同じテーブル名のユーザーテーブルがすでに登録されています。テーブル名は CSV ファイルのファイル名から決まるため、ファイル名を変更してアップロードし直すか、既存のユーザーテーブルを削除してください。
`お使いのプランのユーザーテーブル上限に達しました`	登録できるユーザーテーブルの数が上限に達しています (メッセージには上限の件数も表示されます)。不要なユーザーテーブルを削除してください。

SQL クエリの実行に失敗する

エラーメッセージ	原因と対処
`ユーザーテーブル <テーブル名> の Harvest Files のファイルが最大サイズ 52428800 バイトを超えています`	SQL クエリが参照しているユーザーテーブルの登録に使用した CSV ファイルが、50 MiB (52428800 バイト) を超えています。Harvest Files 上の CSV ファイルを小さくしてください。
`ユーザーテーブルが <件数> 件登録されていますが` で始まるメッセージ	登録されているユーザーテーブルの数が、プランで利用できる数を超えています。不要なユーザーテーブルを削除してから、SQL クエリを実行し直してください。

Soracom

Users