frappe-syntax-reports

レポート：クエリ、スクリプト、レポートビルダー

クイックリファレンス

レポートの種類の概要

種類	コードが必要	用途	権限
レポートビルダー	なし	フィルターやグループ化に対応した、単一の DocType のシンプルな一覧	すべてのユーザー
クエリレポート	SQL のみ	直接 SQL クエリを実行する場合、従来の列形式	システムマネージャー
スクリプトレポート（標準）	Python + JS	複雑なロジック、グラフ、概要、ツリー	管理者 + 開発者モード
スクリプトレポート（カスタム）	UI 内の Python	アプリのデプロイなしで手早くカスタムレポートを作成	システムマネージャー

スクリプトレポートの execute() 戻り値

def execute(filters=None):
    columns = [...]   # List of dicts
    data = [...]      # List of dicts or lists
    message = "..."   # Optional: HTML message above report
    chart = {...}     # Optional: chart configuration
    report_summary = [...]  # Optional: summary cards
    skip_total_row = False  # Optional: suppress auto-total
    return columns, data, message, chart, report_summary, skip_total_row

列の定義（Dict 形式）

columns = [
    {
        "fieldname": "customer",
        "label": _("Customer"),
        "fieldtype": "Link",
        "options": "Customer",
        "width": 200
    },
    {
        "fieldname": "amount",
        "label": _("Amount"),
        "fieldtype": "Currency",
        "options": "currency",  # field in row holding currency code
        "width": 120
    }
]

クエリレポートの列形式（レガシー文字列）

SELECT
  name as "Sales Order:Link/Sales Order:200",
  customer as "Customer:Link/Customer:180",
  grand_total as "Total:Currency:120",
  transaction_date as "Date:Date:100"
FROM `tabSales Order`
WHERE docstatus = 1

形式："Label:Fieldtype/Options:Width" — Link、Dynamic Link、Currency の場合のみ Options が必要です。

フィルターの定義（JS）

frappe.query_reports["My Report"] = {
    filters: [
        {
            fieldname: "company",
            label: __("Company"),
            fieldtype: "Link",
            options: "Company",
            default: frappe.defaults.get_user_default("company"),
            reqd: 1
        },
        {
            fieldname: "from_date",
            label: __("From Date"),
            fieldtype: "Date",
            default: frappe.datetime.add_months(frappe.datetime.get_today(), -1)
        },
        {
            fieldname: "status",
            label: __("Status"),
            fieldtype: "Select",
            options: "\nDraft\nSubmitted\nCancelled"
        }
    ]
};

選択フロー：レポートの種類を選ぶ

Need a report?
├─ Simple list/group of one DocType → Report Builder
│   (no code, UI-only, supports Group By with Count/Sum/Avg)
├─ Direct SQL query, no Python logic needed → Query Report
│   (SQL in Report doc, column format in aliases)
├─ Complex logic, calculations, charts → Script Report (Standard)
│   (Python .py + JS .js files, requires Developer Mode)
└─ Quick one-off with Python but no app deploy → Script Report (Custom)
    (Python in Report doc UI, System Manager can create)

Script Report returns what?
├─ Just data → return columns, data
├─ Data + chart → return columns, data, None, chart
├─ Data + summary → return columns, data, None, None, report_summary
├─ Data + message → return columns, data, message
└─ Everything → return columns, data, message, chart, report_summary, skip_total_row

列でサポートされる Fieldtype

Fieldtype	Options が必要	備考
Data	いいえ	プレーンテキスト
Link	DocType 名	ドキュメントへのクリック可能なリンク
Dynamic Link	DocType を保持するフィールド名	DocType を含む列と組み合わせます
Currency	通貨フィールドまたはコード	通貨を保持する行内のフィールド名
Float	いいえ	小数
Int	いいえ	整数
Percent	いいえ	パーセントバーを表示
Date	いいえ	日付表示
Datetime	いいえ	日付 + 時刻
Check	いいえ	ブール値のチェックボックス
Select	いいえ	ドロップダウンの値
Text	いいえ	長文テキスト
HTML	いいえ	生の HTML をレンダリング

サポートされるフィルターの Fieldtype

Fieldtype	Options	動作
Link	DocType 名	DocType からのオートコンプリート
Select	改行区切りの値	固定オプションのドロップダウン
Date	—	日付ピッカー
DateRange	—	[from_date, to_date] のリストを返します
Check	—	ブール値の切り替え
Dynamic Link	Link フィルターのフィールド名	別のフィルター値に応じて変わります
Data	—	自由形式のテキスト入力
Int	—	数値入力
MultiSelectList	DocType 名	複数の値を選択

グラフデータ形式

chart = {
    "data": {
        "labels": ["Jan", "Feb", "Mar", "Apr"],
        "datasets": [
            {"name": _("Revenue"), "values": [100, 200, 150, 300]},
            {"name": _("Expense"), "values": [80, 150, 120, 250]}
        ]
    },
    "type": "bar",        # bar, line, pie, donut, percentage
    "fieldtype": "Currency",
    "options": "currency",
    "currency": "USD",
    "colors": ["#5e64ff", "#ffa00a"]  # Optional custom colors
}

レポートの概要形式

report_summary = [
    {
        "value": total_revenue,
        "label": _("Total Revenue"),
        "datatype": "Currency",
        "currency": "USD",
        "indicator": "Green"   # Green, Blue, Orange, Red
    },
    {
        "value": total_count,
        "label": _("Total Orders"),
        "datatype": "Int",
        "indicator": "Blue"
    }
]

準備済みレポート

大規模なデータセットを処理するレポートでは、非同期で実行するために 準備済みレポート を有効にします。

1. Report ドキュメントで prepared_report = 1 を設定します
2. ユーザーが「新しいレポートを生成」をクリックすると、enqueue() によりバックグラウンドで実行されます
3. 結果はファイルに保存され、準備ができたらユーザーがダウンロードまたは表示できます
4. 10 万行を超えるデータをクエリするレポート、または完了までに 30 秒以上かかるレポートでは、必ず使用してください

数値カード

ソースの種類	必須フィールド	動作
ドキュメントタイプ	document_type、function、aggregate_function_based_on	DocType に対する SQL 集計
レポート	report_name、report_field、function	レポート列から値を取得
カスタムメソッド	method	許可リストに登録された Python メソッドを呼び出します

カスタムメソッドのシグネチャ：

@frappe.whitelist()
def get_total_active_users(filters=None):
    return frappe.db.count("User", {"enabled": 1})

ダッシュボードチャート

ソース	設定	データ形式
レポート	chart_type = "Report" を設定し、レポートを選択します	レポートのチャートデータを使用します
カスタム	chart_type = "Custom" を設定し、source を定義します	フックは {"labels": [...], "datasets": [...]} を返します
グループ化	chart_type = "Group By" を設定し、フィールドを選択します	フィールドごとに自動集計します

hooks.py のダッシュボードチャートソースフック：

dashboard_chart_source = [
    "myapp.dashboard_chart_source.get_chart_data"
]

重要なルール

• 必ず、fieldname、label、fieldtypeを含む辞書のリストとして列を定義してください。従来の文字列形式を使用できるのは、Query ReportのSQLエイリアスだけです。
• execute()でcolumnsまたはdataにNoneを決して返さないでください。必ず空のリスト[]を返してください。
• 列とreport_summaryの翻訳可能なラベルには、必ず_(...)を使用してください。
• ユーザーが指定したフィルター値をf文字列に直接埋め込んで、frappe.db.sqlを決して使用しないでください。必ずパラメーターとして渡してください：frappe.db.sql(query, filters, as_dict=True)。
• Reportドキュメントには、必ずReference DocTypeを設定してください。これはユーザーアクセス権限を制御します。
• 列定義でwidthを決して省略しないでください。幅を指定していない列は、適切に表示されません。
• チャートデータでは、datasets[].valuesの長さをlabelsの長さに必ず合わせてください。長さが一致しないと、チャートの描画エラーが発生します。

関連項目

• references/query-report.md — Query Report APIの全容
• references/script-report.md — Script ReportのJS API
• references/examples.md — 動作するレポートの例
• references/anti-patterns.md — よくあるレポートの誤り
• references/dashboard.md — Number Cards、Dashboard Charts