qlik-load-script

Qlik Load Script Generator

概要

データ準備のために、Qlik Sense ロードスクリプト（.qvs ファイル）を作成します。ライブデータや Qlik Cloud 環境にはアクセスできません。Qlik エンジンに対してスクリプトを実行、プレビュー、検証することはできません。最小限の編集で実行できる、正確で読みやすく、コメントが充実したスクリプトを作成してください。

コーディングエージェント向けに設計されています。 このスキルは主に、Claude Code、Cursor、Windsurf など、ファイルシステムにアクセスできるエージェント型コーディングツールが、.qvs ファイルを含むプロジェクト内で作業することを想定しています。

• 編集前に、ファイル読み取りツールを使って既存のスクリプトをディスクから読み込みます。
• スクリプトをチャットに出力するだけでなく、プロジェクト内の .qvs ファイルを直接編集または作成します。
• タスクで変更を求められた箇所を除き、周囲のプロジェクト構成（他のタブ、接続、ファイル構成）はそのまま維持します。

ファイルにアクセスできないチャット専用環境（通常のウェブチャットなど）で使用する場合は、ユーザーがコピーして貼り付けられる完全なスクリプトブロックを出力してください。詳しくは応答形式を参照してください。

主な用途： Qlik Predict を使った ML 実験向けのデータ準備スクリプトです。ユーザーがベースデータを含む開始用スクリプトを提供します。特徴量を変換・生成し、トレーニング用とテスト用の QVD ファイルを出力します。

一般的な用途： 開始用コード、インラインコメント、ユーザーのプロンプトに基づいて、あらゆる Qlik ロードスクリプトを完成または拡張します。

重要なルール

1. これは Qlik ロードスクリプトであり、SQL ではありません。 構文は SQL に似ていますが、重要な違いがあります。不明な場合は、references/syntax-and-patterns.mdを読み、次のドキュメントを参照してください：https://help.qlik.com/en-US/cloud-services/Subsystems/Hub/Content/Sense_Hub/LoadData/script-syntax-functions.htm
2. 関数をでっち上げてはいけません。 組み込み関数が存在するかどうか確信が持てない場合は、その旨を伝え、確実に使用できる代替案を提示してください。
3. 実行してはいけません。 環境にかかわらず、Qlik Cloud に対してスクリプトを実行またはテストすることはできません。不確かな箇所には、ユーザーが確認できるように // TODO: verify コメントを付けてください。
4. ユーザーの開始用スクリプトを維持してください。 ユーザーが変更を依頼していない箇所を書き換えたり、構成し直したりしてはいけません。
5. 完全で実行可能なスクリプトを出力してください。 ユーザーが差分を明示的に求めている場合を除き、「...」による省略を含む部分的なスニペットを出力してはいけません。ファイルにアクセスできる場合は、完全なセクションを .qvs ファイルに書き戻します。チャットに出力する場合は、ユーザーが Qlik Cloud のスクリプトエディターにコピーして貼り付けます。

Qlik スクリプトを作成する前に、必ずreferences/syntax-and-patterns.mdを読み、構文の完全なリファレンス、よくある落とし穴、コードパターンを確認してください。 Qlik の構文には SQL との細かな違いが多く、SQL の感覚に頼ると、気づきにくいバグの原因になります。

---

ML データ準備のガイドライン

一般的なデータソース

開始用スクリプトでは通常、lib:// 接続を介して CSV または QVD ファイルを読み込みます。開始用スクリプトで使われているソース形式と lib パスに合わせてください。CSV ファイルを読み込む場合は、形式を必ず明示してください。

FROM [lib://DataFiles/data.csv] (txt, codepage is utf8, embedded labels, delimiter is ',');

特徴量エンジニアリングの考え方

データサイエンスと ML の知識を活用し、特定のユースケースで実際に予測に役立つ可能性が高い特徴量を生成してください。網羅性よりも効果を重視します。ノイズを増やすだけの膨大な特徴量行列より、十分な理由に基づく、的を絞った特徴量セットのほうが有効です。生成する特徴量を選ぶ際は、ドメインの文脈、文献で知られている要因、予測タスクの背景にあるビジネスロジックを考慮してください。

Qlik Predict の出力構成

Qlik Predict では、単一のフラットなテーブル形式のデータセットが必要です。

• 1 行は、定義された粒度（例：1 人の顧客、1 件のローン、1 つの月・地域）における 1 件の観測値です。
• 1 列はターゲット（予測対象）です。
• 残りの列は特徴量（モデルへの入力）です。
• 対応する出力形式：QVD（推奨）、CSV、XLSX、Parquet。

ターゲット列の要件

実験タイプ	ターゲットの要件
二値分類	固有値がちょうど2つ（例：Yes／No、1／0、Churn／Active）
多クラス分類	固有のカテゴリ値が3～10個
回帰	10個を超える固有値を持つ数値
時系列	数値ターゲット列＋日付インデックス列＋任意のグループ列（最大2列）

特徴量数とフィールド保持に関する指針

• 影響力のある特徴量を目指し、特徴量行列を複雑にしすぎないようにします。考えられる組み合わせをすべて網羅的に導出するのではなく、明確な予測シグナルを持つ特徴量に注力します。データサイエンスとMLの知識を活用し、特定のユースケースで重要となる可能性が高い特徴量を優先してください。
• ID／キー項目は必ず保持します（例：CustomerID、LoanID、PolicyNumber）。これらはトレーニング中に特徴量として使用されませんが、モデルのデプロイ後に予測を元のデータにひも付けるために不可欠です。Qlik Predictは高カーディナリティの識別子を自動的に無視するため、データセットに残しても問題ありません。
• ターゲットから直接導出された項目や、ターゲットの結果として生じた項目（リーク）を削除します。

日付形式の規則

Qlik環境全体で確実に扱えるよう、日付フィールドは YYYY-MM-DD 形式（ISO 8601）で保存してください。Qlik Predictは、日付としてプロファイルしたフィールドから日付ディメンション（年、月、曜日、四半期など）を自動的に導出するため、通常、年／月／日を別々の列に手動で分解する必要はありません。手動での日付特徴量エンジニアリングは、Qlik Predictが自動導出できない特徴量、つまり日付の差、期間、ドメイン固有の期間に注力してください。

// Format dates as YYYY-MM-DD for reliable interpretation
Date(Date#(RawDateField, 'DD/MM/YYYY'), 'YYYY-MM-DD') as EventDate,
// Manual date engineering — only for features Qlik Predict won't auto-derive
Today() - Date#(RawDateField, 'DD/MM/YYYY') as DaysSinceEvent

トレーニング／テストの分割方法

分割によって保留検証セットが作成されます。これは、モデルのトレーニングとデプロイ後に実際に発生する未知のデータをシミュレートするものであり、POCの信頼性に不可欠です。Qlik Predictはトレーニング中に独自の内部交差検証と評価指標を処理します。ここで作成するテストセットは、それとは別の外部検証用アセットです。ユースケースに合った方法を選択してください。

方法1 — ランダム分割（ほとんどのユースケースでのデフォルト）

// Random 80/20 split (non-deterministic across reloads)

WithSplit:
LOAD
    *,
    If(Rand() <= 0.8, 'Train', 'Test') as SplitFlag
RESIDENT FinalFeatures;

DROP TABLE FinalFeatures;

// Store separately
Training:
NoConcatenate
LOAD * RESIDENT WithSplit WHERE SplitFlag = 'Train';
DROP FIELD SplitFlag FROM Training;
STORE Training INTO [lib://DataFiles/training_data.qvd] (qvd);
DROP TABLE Training;

Testing:
NoConcatenate
LOAD * RESIDENT WithSplit WHERE SplitFlag = 'Test';
DROP FIELD SplitFlag FROM Testing;
STORE Testing INTO [lib://DataFiles/testing_data.qvd] (qvd);
DROP TABLE Testing;

DROP TABLE WithSplit;

方法2 — 時間ベースの分割（時間的な順序が重要な場合）

予測タスクが本質的に時間に依存する場合（例：予測、翌月の解約、季節性リスク）に使用します。時間で分割することで、将来のデータがトレーニングセットに漏れるのを防ぎ、本番環境の状況をより適切にシミュレートできます。

// Split on a date threshold — all data before cutoff = Train, after = Test
LET vCutoffDate = Num(MakeDate(2025, 1, 1));

Training:
NoConcatenate
LOAD * RESIDENT FinalFeatures
WHERE ObservationDate < $(vCutoffDate);
STORE Training INTO [lib://DataFiles/training_data.qvd] (qvd);
DROP TABLE Training;

Testing:
NoConcatenate
LOAD * RESIDENT FinalFeatures
WHERE ObservationDate >= $(vCutoffDate);
STORE Testing INTO [lib://DataFiles/testing_data.qvd] (qvd);
DROP TABLE Testing;

DROP TABLE FinalFeatures;

ターゲットリークのチェックリスト

ML準備スクリプトを最終確定する前に、次の点を確認してください。

• ターゲットの直接的な結果となるフィールドがないこと（例：解約を予測する場合の Cancellation_Date）。
• 予測対象のイベント後にのみ入力されるフィールドがないこと。
• ラグ／ウィンドウ特徴量に現在の行が含まれていないこと（オフセットは-1以前から開始）。
• 集計に将来のデータが誤って含まれていないこと。
• 次の点を確認してください。「予測を行う必要がある時点で、この値を知ることができるだろうか？」

クラス不均衡（二値分類）

少数クラスが行の20%未満の場合は、コメントでその旨を示し、次の方法を提案してください。

1. ターゲットの期間を再定義する（陽性クラスの定義範囲を広げる）。
2. Rand() を使用して多数クラスをアンダーサンプリングする。
3. CONCATENATE を使用して少数クラスをオーバーサンプリングする。
4. Qlik Predictのインテリジェント最適化に自動バランス調整を任せる（中程度の不均衡である5～20%に有効）。

最終クリーンアップのチェックリスト

最終スクリプトを出力する前に、次の点を確認してください。

• 一時テーブル／中間テーブルがすべて DROP されていること。
• 予測をソースデータにひも付けられるよう、ID／キー項目が保持されていること。一時的な補助列のみを削除してください。
• コメントでターゲット列が明確に示されていること。
• フィールド名が説明的であること（ドメイン標準でない限り、生の略語を使用しない）。
• 重要なフィールドのNULL処理が明示されていること。
• 開始スクリプトで異なるlib接続を使用していない限り、STOREパスのデフォルトが lib://DataFiles/... であること。開始スクリプトに合わせてください。
• 目的、ターゲットフィールド、粒度、生成日を含むヘッダーコメントブロックがスクリプトに含まれていること。

スクリプトテンプレート

新しい ML 準備スクリプトを最初から作成する場合は、次の構成を使用してください。

///$tab Main
/**
 * ML Data Preparation Script
 * Purpose:     [describe the prediction task]
 * Target:      [field name] ([binary/regression/multiclass/time series])
 * Grain:       One row per [entity]
 * Generated:   [date]
 * Source data: [describe inputs]
 */

///$tab Config
// ============================================================
// CONFIGURATION
// ============================================================
SET vOutputPath = 'lib://DataFiles';  // Default — use the lib path from the starting script if different
LET vToday = Today();
// LET vCutoffDate = Num(MakeDate(2025, 1, 1));  // Uncomment for time-based split

///$tab Source Data
// ============================================================
// LOAD SOURCE DATA
// ============================================================
// [Load base tables from QVDs or other sources]

///$tab Feature Engineering
// ============================================================
// FEATURE ENGINEERING
// ============================================================
// [Aggregation, derived fields, joins, enrichment]

///$tab Final Assembly
// ============================================================
// ASSEMBLE FINAL DATASET
// ============================================================
// [Combine all features into one flat table]
// [Drop helper tables]
// [Drop leaky or unnecessary fields]

///$tab Output
// ============================================================
// STORE OUTPUT
// ============================================================
// [Train/test split if applicable]
// [STORE to QVD]
// [DROP final tables]

///$tab コメントに関する注意： これらは Qlik スクリプトのセクションマーカーです。Qlik Cloud スクリプトエディターに名前付きタブを作成します。長いスクリプトを論理的なセクションに整理するために使用してください。

---

回答形式

ユーザーが開始用のスクリプトまたはプロンプトを提供した場合：

1. タスクを把握します。 予測対象、粒度、必要な主な変換を確認します。意図が曖昧な場合は、確認の質問をしてください。
2. スクリプトを作成します。 ファイルにアクセスできる場合（Claude Code、Cursor など）は、.qvs ファイルを直接編集または作成します。そうでない場合は、実行可能な Qlik ロードスクリプトのセクションをすべてチャットに出力します。コメントを十分に使用してください。
3. 不確かな点を明示します。 確信が持てない箇所には // TODO: verify — [reason] を付けてください。
4. 分かりにくいロジックを説明します。 スクリプトブロックの後に、複雑な Window() 呼び出し、扱いにくい結合、またはドメイン固有の選択について簡潔に説明します。
5. 改善案を提案します。 追加機能、NULL 値や外れ値の適切な処理、またはデータリークのリスクに関する改善の余地があれば、主な出力の後に記載してください。

---

例

ユーザーのプロンプト：

「lib://DataFiles/transactions.qvd（1 行につき 1 件のトランザクション：CustomerID、TransactionDate、Amount、ProductCategory、Returned）と lib://DataFiles/customers.qvd（1 行につき 1 人の顧客：CustomerID、SignupDate、Region``）があります。顧客が今後 90 日以内に解約するか（CancellationDate` に値が設定されているか）を予測する ML 準備スクリプトを作成してください。トレーニング用とテスト用の QVD を出力してください。」

期待される回答：

1. タスクを確認します。目的変数 = CancellationDate から導出する二値フラグ（導出後に削除するリーク項目）、粒度 = 顧客ごとに 1 行、ソース = 上記 2 つの QVD。
2. スクリプトテンプレートに従って、次の処理を行うスクリプトを作成します。両方の QVD をロードし、transactions を顧客粒度に集計し（TxnCount、TotalSpend、AvgSpend、Recency_Days、Count(DISTINCT ProductCategory)、返品率 — 特徴量エンジニアリングのパターンを参照）、customers に結合し、CancellationDate から Churn_Flag を導出してから CancellationDate 自体を削除し、トレーニング／テスト分割の方法にあるランダムな 80／20 分割を適用し、training_data.qvd／testing_data.qvd を保存します。
3. 不確かな関数呼び出しには // TODO: verify を付け、スクリプトの後にリークの確認（CancellationDate を削除済みであること）を明示します。

---

参考資料

• 構文とパターンのリファレンス： references/syntax-and-patterns.md — Qlik ロードスクリプトの構文全般、よくある落とし穴、特徴量エンジニアリングのコードパターン。スクリプトを作成する前に必ず読んでください。
• Qlik スクリプトの構文と関数： https://help.qlik.com/en-US/cloud-services/Subsystems/Hub/Content/Sense_Hub/LoadData/script-syntax-functions.htm
• Qlik Predict のドキュメント： https://help.qlik.com/en-US/cloud-services/Subsystems/Hub/Content/Sense_Hub/AutoML/home-automl.htm
• ウィンドウ関数のリファレンス： https://help.qlik.com/en-US/cloud-services/Subsystems/Hub/Content/Sense_Hub/LoadData/window-functions.htm