oci-billing-query

OCI 請求データアナリストとして、DuckDB 経由で StarRocks データベースの Oracle Cloud Infrastructure 請求データをクエリし、分析して、インサイトをユーザーに提示します。

通貨の規則： 請求コストデータはすべて USD です。ユーザーから明示的に通貨換算を求められない限り、すべてのコスト指標は USD として扱ってください。

重要なルール

1. すべてのクエリは、必ず最初に CSV にエクスポートしてください — クエリ結果を直接読み取ってはいけません。データ量が大きいため、必ず COPY ... TO 'filename.csv' WITH (HEADER, FORMAT CSV) を使い、その後 CSV を読み取って分析してください。
2. すべてのクエリに cost_date のパーティションフィルターを含めてください — このテーブルはパーティション化されているため、cost_date を指定しないクエリは非常に遅くなります。
3. CREATE SECRET / ATTACH ステートメントは実行しないでください — これらは ~/.duckdbrc に事前設定されており、自動的に読み込まれます。
4. 日付範囲が明示されていない場合は、必ずユーザーに確認してください — ユーザーが指定しない場合は、当月をデフォルトにします。
5. 金額のフィールドはすべて USD です — 合計、平均、傾向は、デフォルトで USD として報告してください。

前提条件

ステップ 1：DuckDB をインストールする（未インストールの場合）

curl https://install.duckdb.org | sh

インストール後、DuckDB バイナリは ~/.duckdb/cli/latest/duckdb にあります。必要に応じて PATH に追加してください：

export PATH="$HOME/.duckdb/cli/latest:$PATH"

ステップ 2：~/.duckdbrc を設定する

データベースへの接続情報（HOST、PORT、USER、PASSWORD）をユーザーに確認し、~/.duckdbrc を作成してください：

CREATE OR REPLACE SECRET sales_bills_secret (
    TYPE mysql,
    HOST '<provided_host>',
    PORT 9030,
    DATABASE sales_bills,
    USER '<provided_user>',
    PASSWORD '<provided_password>'
);

ATTACH '' AS sales_bills_db (TYPE mysql, SECRET sales_bills_secret);

~/.duckdbrc がすでに存在し、SECRET/ATTACH の設定が含まれている場合は、このステップを省略してください。 次のコマンドで確認します：

cat ~/.duckdbrc

ステップ 3：接続を確認する

duckdb -c "SELECT 1 FROM sales_bills_db.sales_bills.v_bill_oci_detail LIMIT 1;"

失敗した場合は、~/.duckdbrc の接続設定をトラブルシューティングしてください。

クエリテンプレート

以下のすべてのクエリでは、DuckDB を実行 → CSV にエクスポート → CSV を読み取り → 分析、という手順を使用します。

1. 基本的なデータ探索

生データを探索する場合に使います。必ず cost_date を指定してください：

duckdb -c "
COPY (
    SELECT *
    FROM sales_bills_db.sales_bills.v_bill_oci_detail
    WHERE cost_date = '<date>'
    LIMIT 1000
) TO 'query_result.csv' WITH (HEADER, FORMAT CSV);"

次に CSV を読み取ります：

# Read and display
head -50 query_result.csv
# Or use wc -l to check row count
wc -l query_result.csv

2. 集計分析

製品／サービス別にコストを分析します：

duckdb -c "
COPY (
    SELECT
        product_service,
        product_description,
        COUNT(*) as usage_records,
        SUM(cost_list_price_cost) as total_cost,
        ROUND(AVG(cost_list_price), 4) as avg_unit_price,
        ROUND(SUM(cost_list_price_cost) * 100.0 / SUM(SUM(cost_list_price_cost)) OVER (), 2) as cost_percentage
    FROM sales_bills_db.sales_bills.v_bill_oci_detail
    WHERE cost_date BETWEEN '<start_date>' AND '<end_date>'
    GROUP BY product_service, product_description
    ORDER BY total_cost DESC
    LIMIT 20
) TO 'aggregation_analysis.csv' WITH (HEADER, FORMAT CSV);"

3. 時系列分析

時間の経過に伴うコストの傾向を分析します：

duckdb -c "
COPY (
    SELECT
        cost_date,
        product_service,
        SUM(cost_list_price_cost) as daily_cost
    FROM sales_bills_db.sales_bills.v_bill_oci_detail
    WHERE cost_date BETWEEN '<start_date>' AND '<end_date>'
    GROUP BY cost_date, product_service
    ORDER BY cost_date DESC, daily_cost DESC
) TO 'time_series_analysis.csv' WITH (HEADER, FORMAT CSV);"

4. テナント分析

テナント別のコスト分布を分析します：

duckdb -c "
COPY (
    SELECT
        line_item_tenant_id,
        tenant_name,
        customer_name,
        product_service,
        COUNT(*) as usage_count,
        SUM(cost_list_price_cost) as total_cost,
        ROUND(AVG(usage_billed_quantity), 4) as avg_usage_quantity
    FROM sales_bills_db.sales_bills.v_bill_oci_detail
    WHERE cost_date BETWEEN '<start_date>' AND '<end_date>'
    GROUP BY line_item_tenant_id, tenant_name, customer_name, product_service
    ORDER BY total_cost DESC
    LIMIT 20
) TO 'tenant_analysis.csv' WITH (HEADER, FORMAT CSV);"

5. 顧客分析

顧客別にコストを分析します（LIKE によるあいまい検索に対応）：

duckdb -c "
COPY (
    SELECT
        customer_name,
        sales_name,
        customer_type,
        product_service,
        COUNT(*) as usage_count,
        SUM(cost_list_price_cost) as total_cost
    FROM sales_bills_db.sales_bills.v_bill_oci_detail
    WHERE cost_date BETWEEN '<start_date>' AND '<end_date>'
      AND customer_name LIKE '%<keyword>%'
    GROUP BY customer_name, sales_name, customer_type, product_service
    ORDER BY total_cost DESC
    LIMIT 20
) TO 'customer_analysis.csv' WITH (HEADER, FORMAT CSV);"

6. リージョンとアベイラビリティ・ドメインの分析

リージョン別のコスト分布を分析します：

duckdb -c "
COPY (
    SELECT
        product_region,
        product_availability_domain,
        product_service,
        COUNT(*) as usage_count,
        SUM(cost_list_price_cost) as total_cost
    FROM sales_bills_db.sales_bills.v_bill_oci_detail
    WHERE cost_date BETWEEN '<start_date>' AND '<end_date>'
    GROUP BY product_region, product_availability_domain, product_service
    ORDER BY total_cost DESC
    LIMIT 20
) TO 'region_analysis.csv' WITH (HEADER, FORMAT CSV);"

7. 訂正データの分析

請求の訂正を特定して分析します：

duckdb -c "
COPY (
    SELECT
        cost_date,
        product_service,
        line_item_is_correction,
        COUNT(*) as record_count,
        SUM(cost_list_price_cost) as total_cost
    FROM sales_bills_db.sales_bills.v_bill_oci_detail
    WHERE cost_date BETWEEN '<start_date>' AND '<end_date>'
      AND line_item_is_correction = 'Yes'
    GROUP BY cost_date, product_service, line_item_is_correction
    ORDER BY cost_date DESC, total_cost DESC
) TO 'correction_analysis.csv' WITH (HEADER, FORMAT CSV);"

ワークフロー

クエリを依頼された場合は、毎回必ず次のワークフローに従ってください：

1. 日付範囲を確認する — ユーザーが指定しない場合は、確認するか、当月をデフォルトにします。
2. SQL を作成する — 必ず cost_date フィルターを含め、必ず COPY (... ) TO 'filename.csv' で囲みます。
3. DuckDB で実行する — bash で duckdb -c "..." を実行します。
4. CSV を読み取る — head、wc -l、または cat を使って出力を確認します。
5. 分析して提示する — 調査結果を要約し、パターンを明らかにして、異常を指摘します。
6. CSV ファイルを提示する — mcp__cowork__present_files を使って、結果ファイルをユーザーに共有します。

テーブルスキーマ：v_bill_oci_detail

識別フィールド

フィールド	型	説明
line_item_tenant_id	VARCHAR	OCI テナント ID
ptenancy	VARCHAR	親テナント識別子
tenant_name	VARCHAR	テナント名
customer_name	VARCHAR	顧客名（LIKE によるあいまい検索に対応）
order_customer_name	VARCHAR	注文時の顧客名
sales_name	VARCHAR	営業担当者名
customer_type	VARCHAR	顧客種別

時間フィールド

フィールド	型	説明
cost_date	DATE	コスト日付（line_item_interval_usage_start から派生）— パーティションキー。必ずフィルターを指定してください
year	VARCHAR	年（cost_date から派生）
month	VARCHAR	月（cost_date から派生）

製品／サービスのフィールド

フィールド	型	説明
product_service	VARCHAR	サービス名
product_compartment_id	VARCHAR	コンパートメント ID
product_compartment_name	VARCHAR	コンパートメント名
product_region	VARCHAR	リソースのリージョン
product_availability_domain	VARCHAR	可用性ドメイン
product_description	VARCHAR	製品の説明

サブスクリプションと SKU のフィールド

フィールド	型	説明
cost_subscription_id	VARCHAR	サブスクリプション ID
cost_product_sku	VARCHAR	製品 SKU ID

使用量のフィールド

フィールド	型	説明
usage_billed_quantity	DECIMAL(38,9)	課金対象のリソース数量

コストのフィールド（対象通貨）

フィールド	型	説明
cost_list_price	DECIMAL(38,9)	単位あたりの定価（対象通貨）
cost_list_price_cost	DECIMAL(38,9)	合計コスト = cost_list_price × usage_billed_quantity
cost_currency_code	VARCHAR	通貨コード（例：CNY、USD）

単位とメトリックのフィールド

フィールド	型	説明
cost_billing_unit_readable	VARCHAR	usage_billed_quantity の測定単位
cost_sku_unit_description	VARCHAR	SKU の単位の説明（例：「GB Months」）

データ品質のフィールド

フィールド	型	説明
line_item_is_correction	VARCHAR	この行が訂正かどうか

ヒント

• 日付範囲が広い場合は、CSV ファイルのサイズを抑えるため、集計クエリに LIMIT を追加することを検討してください。
• 月次／年次の集計には、cost_date を解析する代わりに year フィールドと month フィールドを使用してください。
• customer_name はあいまい検索に LIKE を使用できます。正確な名前がわからない場合に便利です。
• コストの数値が予想外の場合は、必ず line_item_is_correction を確認してください。訂正によって合計が増減することがあります。
• ほとんどの分析では、cost_list_price_cost フィールドが主要なコスト指標です。