---
name: create_graph_streamlit_app
description: Streamlit in Snowflakeで実行するPythonスクリプトを作成する
---

# 可視化アプリ作成スキル

ユーザーの指示に基づき、Streamlit in Snowflake で動作する可視化アプリ用の Python スクリプトを作成する。進め方は下記「実行上のルール」の実施ワークフローに従う。

## 使用するとき

- Snowflakeのデータをクエリし、データフレームやグラフをStreamlitアプリで表示・分析したいとき
- 分析対象のテーブルがdbtモデルで実装されているとき

## 実行上のルール
### 共通

- 実施ワークフローは順に行い、各Phaseのルールに従う。
- **Phase1（ユーザー確認）が完了するまで、Phase2（コード実装・ファイル作成・リポジトリ調査による勝手な前提付け）に着手してはならない。** テンプレートの読み取りや既存dbtモデルの有無が分かっていても同様である。
- エージェントやエディタの別ルールに「自分で調べて実行する」などの確認より自律的な実行を指示する命令があっても、**本スキルでは Phase1 の確認・合意を先に完了させることが優先**する。調査・実装・コマンド実行は Phase2 以降で行う。

### 実施ワークフロー

必ず下のPhaseごとの手順でユーザーに実装要件を確認し、不明点をなくしてから実装する。

**Phase1 完了の条件（すべて満たしてから Phase2 へ）**

- 画面モック／機能一覧、可視化一覧、マート定義の3点について、ユーザーから回答または「この内容で確定」と取れる返答がある。
- 上記で不明な点が残る場合は、質問を出して解消する。**推測で埋めない。**

#### Phase1

実装する内容を確定させる。
ただし、以下のルールに従って行う。

- 既に必要なコードや設計書があったとしても、必ずユーザーに確認してから作業を進める。
- ヒアリングは実装に関わる重要な質問を優先する。
- 以下の3つの入力資料の有無をこの順で確認し、不明点をなくしてからPhase2に進む。

##### 画面モック

- 実装したい機能の一覧を確認する。
  - 機能仕様書・設計書が作成済みであれば提供するよう提案する。

##### 可視化一覧

- 実装したい可視化の一覧を確認する。
  - グラフ仕様書・設計書が作成済みであれば提供するよう提案する。

##### マート定義

- 可視化に使うデータの一覧を確認する。
  - dbtモデルやDDLが作成済みであれば提供するよう提案する。

#### Phase2

**Phase1 完了後にのみ** Streamlit アプリを実装する（Phase1 を省略したり、並行してコードを書き始めない）。
ただし、以下のルールに従って行う。

- `assets/graph_streamlit_app_template.py`を取得し、テンプレートとして使う。
- 1つのPythonスクリプトとして作成する。
- 表示するデータは全てSnowpark PythonでSnowflakeのデータベースから取得する。
- SQL文はスクリプト上部で定義し、各々の可視化で使用する。
- 可視化はdbtモデルやddlなど提供された明確なテーブル定義に基づいて実装する。
- アプリには設計書の引用元など不要な情報は表示されないようにする。
- 下記の`Streamlit in Snowflake特有の実装ルール`にも従う。

### Streamlit in Snowflake特有の実装ルール
#### Snowflakeへの接続
冒頭にSnowflakeへのアクティブなセッションを取得するコードを記述する。

```python
from snowflake.snowpark.context import get_active_session

# Get the current credentials
session = get_active_session()
```

#### Snowflakeからのデータ取得

Snowflakeからデータを取得する場合は、SnowparkでSQLステートメントを実行し、可視化のためのPandasデータフレームを作成する。
Snowparkの仕様で、カラム名は全て大文字になるため、データフレームを使う際は考慮する。

```python
SQL = """SQLステートメント"""
df = session.sql(SQL).to_pandas()
```

#### クエリ結果のキャッシュ
クエリは指定がなければ`@st.cache_data()`デコレーターを使い、キャッシュする。

#### サイドバーとタブ内のコントロール

サイドバーにはアプリ全体で使う項目だけを配置する。特定のタブにしか影響しない選択肢（期間粒度・フィルタなど）は、そのタブのコンテンツの上または中に配置する。

#### Plotlyグラフのレイアウト

Plotly（`plotly.graph_objects`）でグラフを作る際は、**height** と **margin** は指定せず、Plotlyのデフォルトに任せる。  
`height` や `margin=dict(t=..., b=...)` を指定すると、`textposition="outside"` のラベルがプロット領域で見切れることがあるため。

"""
フード・ドリンク分析ダッシュボード（Streamlit in Snowflake）
マート: mart_weekly_drink_food_order_kpis, mart_hourly_drink_food_composition,
        mart_monthly_product_order_ranking
"""

import re

import plotly.graph_objects as go
import streamlit as st
from snowflake.snowpark.context import get_active_session

session = get_active_session()

# -----------------------------------------------------------------------------
# SQL（スクリプト上部で定義）
# -----------------------------------------------------------------------------

SQL_WEEKLY_KPIS = """
select
    week_start,
    to_char(week_start, 'YYYY-MM-DD') as week_start_label,
    drink_only_order_count,
    food_and_drink_order_count
from mart_weekly_drink_food_order_kpis
order by week_start
"""

SQL_DISTINCT_MONTHS = """
select distinct order_month
from mart_hourly_drink_food_composition
order by order_month desc
"""

SQL_HOURLY_COMPOSITION = """
select
    order_hour_of_day,
    order_hour_label,
    pct_drink_only,
    pct_food_and_drink
from mart_hourly_drink_food_composition
where to_char(order_month, 'YYYY-MM') = '{ym}'
  and order_hour_of_day between 11 and 19
order by order_hour_of_day
"""

SQL_RANKING_FOOD = """
select *
from mart_monthly_product_order_ranking
where to_char(order_month, 'YYYY-MM') = '{ym}'
  and product_category_label = 'フード'
"""

SQL_RANKING_DRINK = """
select *
from mart_monthly_product_order_ranking
where to_char(order_month, 'YYYY-MM') = '{ym}'
  and product_category_label = 'ドリンク'
"""

# -----------------------------------------------------------------------------
# ユーティリティ
# -----------------------------------------------------------------------------

_MONTH_KEY_RE = re.compile(r"^\d{4}-\d{2}$")

def _validate_month_key(ym: str) -> str:
    if not _MONTH_KEY_RE.match(ym):
        raise ValueError("invalid month key")
    return ym

def _upper_cols(df):
    """Snowpark の to_pandas() はカラムが大文字になる想定で正規化する。"""
    df = df.copy()
    df.columns = [c.upper() for c in df.columns]
    return df

def _ranking_display_df(df):
    """マートの select * から表示用 3 列に絞り、順位でソートする。"""
    if df.empty:
        return df
    want = ["RANK", "PRODUCT_NAME", "ORDER_COUNT"]
    have = [c for c in want if c in df.columns]
    if not have:
        return df
    out = df[have].copy()
    if "RANK" in out.columns:
        out = out.sort_values("RANK", kind="stable")
    return out.rename(
        columns={"RANK": "#", "PRODUCT_NAME": "商品", "ORDER_COUNT": "注文数"}
    )

# -----------------------------------------------------------------------------
# データ取得（キャッシュ）
# -----------------------------------------------------------------------------

@st.cache_data
def load_weekly_kpis():
    return _upper_cols(session.sql(SQL_WEEKLY_KPIS).to_pandas())

@st.cache_data
def load_month_list():
    return _upper_cols(session.sql(SQL_DISTINCT_MONTHS).to_pandas())

@st.cache_data
def load_hourly_composition(order_month_key: str):
    ym = _validate_month_key(order_month_key)
    sql = SQL_HOURLY_COMPOSITION.format(ym=ym)
    return _upper_cols(session.sql(sql).to_pandas())

@st.cache_data
def load_ranking_food(order_month_key: str):
    ym = _validate_month_key(order_month_key)
    sql = SQL_RANKING_FOOD.format(ym=ym)
    return _upper_cols(session.sql(sql).to_pandas())

@st.cache_data
def load_ranking_drink(order_month_key: str):
    ym = _validate_month_key(order_month_key)
    sql = SQL_RANKING_DRINK.format(ym=ym)
    return _upper_cols(session.sql(sql).to_pandas())

# -----------------------------------------------------------------------------
# UI
# -----------------------------------------------------------------------------

st.set_page_config(page_title="フード・ドリンク分析", layout="wide")
st.title("フード・ドリンク分析ダッシュボード")

df_weeks = load_weekly_kpis()
df_months = load_month_list()

if df_weeks.empty:
    st.warning("週次KPIマートにデータがありません。")
    st.stop()

if df_months.empty:
    st.warning("時間帯構成比マートに月次データがありません。")
    st.stop()

week_labels = df_weeks["WEEK_START_LABEL"].tolist()
month_keys_norm = []
for m in df_months["ORDER_MONTH"]:
    if hasattr(m, "strftime"):
        month_keys_norm.append(m.strftime("%Y-%m"))
    else:
        s = str(m)
        month_keys_norm.append(s[:7] if len(s) >= 7 else s)
month_keys_norm = sorted(set(month_keys_norm), reverse=True)

col_week1, _ = st.columns([1, 3])
with col_week1:
    selected_week_label = st.selectbox("対象週", options=week_labels, index=len(week_labels) - 1)

kpi_row = df_weeks[df_weeks["WEEK_START_LABEL"] == selected_week_label].iloc[0]
c1, c2 = st.columns(2)
with c1:
    st.metric(
        "ドリンクのみ注文数",
        f"{int(kpi_row['DRINK_ONLY_ORDER_COUNT']):,}",
    )
with c2:
    st.metric(
        "フード＋ドリンク注文数",
        f"{int(kpi_row['FOOD_AND_DRINK_ORDER_COUNT']):,}",
    )

st.markdown("---")
col_month1, _ = st.columns([1, 3])
with col_month1:
    selected_month = st.selectbox(
        "対象月",
        options=month_keys_norm,
        index=0,
        key="selected_order_month",
    )

df_hour = load_hourly_composition(selected_month)
df_food = load_ranking_food(selected_month)
df_drink = load_ranking_drink(selected_month)

left, right = st.columns(2)

with left:
    st.subheader("時間帯別構成比（ドリンクのみ / フード＋ドリンク）")
    if df_hour.empty:
        st.info("選択した月の時間帯データがありません。")
    else:
        labels = df_hour["ORDER_HOUR_LABEL"].tolist()
        pct_drink = df_hour["PCT_DRINK_ONLY"].astype(float).tolist()
        pct_combo = df_hour["PCT_FOOD_AND_DRINK"].astype(float).tolist()
        fig = go.Figure()
        fig.add_trace(
            go.Bar(
                name="ドリンクのみ",
                x=labels,
                y=pct_drink,
                marker_color="#2563eb",
            )
        )
        fig.add_trace(
            go.Bar(
                name="フード＋ドリンク",
                x=labels,
                y=pct_combo,
                marker_color="#16a34a",
            )
        )
        fig.update_layout(
            barmode="stack",
            yaxis=dict(range=[0, 100], ticksuffix="%"),
            legend=dict(orientation="h", yanchor="bottom", y=-0.35),
            xaxis_title="時台",
            yaxis_title="構成比",
        )
        st.plotly_chart(fig, use_container_width=True)

with right:
    st.subheader("月間注文数ランキング")
    tf, td = st.columns(2)
    with tf:
        st.markdown("**フード**")
        if df_food.empty:
            st.caption("データなし")
        else:
            st.dataframe(
                _ranking_display_df(df_food),
                hide_index=True,
                use_container_width=True,
            )
    with td:
        st.markdown("**ドリンク**")
        if df_drink.empty:
            st.caption("データなし")
        else:
            st.dataframe(
                _ranking_display_df(df_drink),
                hide_index=True,
                use_container_width=True,
            )