Snowpark 実践ガイド

基礎から読む

• Snowparkのアーキテクチャと実行の仕組み ── 自分のPythonコードは、結局どこで動いているのか。クライアント・Snowflake・UDFという3つの実行場所を切り分けて説明します。
• Snowpark と Apache Spark の違い ── DataFrame APIの書き味はよく似ていますが、クラスタを自分で持つか持たないかで運用とコストの構造がまったく変わります。
• Snowpark と Polars の違い（総論） ── どちらも遅延評価を採用しているが、計算がどこで走るか（クラウドかローカルか）が根本的に異なります。使い分けの軸を整理します。
• Snowpark pandas API（pandas on Snowflake）の位置づけ ── pandasの書き方のままSnowflake上のデータを扱えるが、既存のSnowpark DataFrameやto_pandas()と何が違うのかを整理します。
• UDF・Vectorized UDF・UDTF・ストアドプロシージャの使い分け ── Snowflake上でカスタムロジックを実行する4つの手段を、入出力の形とSQLからの呼び出し方で整理します。
• 料金構造とウェアハウスのリソース消費 ── コストは何に対して発生するのか。標準ウェアハウスとSnowpark-Optimized Warehouseの違い、書き方で抑えられる部分を整理します。
• Snowpark ML の概要 ── Snowflake上で完結する機械学習ワークフロー。前処理・学習を担うModelingと、モデル管理を担うRegistryの2本柱です。
• Snowpark Container Services とは何か ── UDF・UDTF・ストアドプロシージャでは対応できない「任意の言語・ランタイム・ライブラリ」をSnowflake内で動かすための、一般提供済みのコンテナ実行基盤です。

射影・選択

列を選ぶ・落とす・作る・名前を変える

• select ── 列を選んで取り出します。両方とも遅延評価で、実際のクエリは後段のアクションまで発行されません。
• drop ── 指定した列を取り除きます。select の逆で、残す列でなく捨てる列を書きます。
• with_column / with_columns ── 既存の列はそのままに、新しい列を1つ（または複数）追加します。
• with_column_renamed / rename ── 列名を変更します。
• col ── 列を式として参照します。以降のメソッドチェーンの起点になる、両APIで最も頻出する関数です。
• lit ── 定数値を式として埋め込みます。
• alias ── 式の出力列に名前をつけます。
• columns / collect_schema().names() ── 現在の列名の一覧を取得します。
• schema / collect_schema() ── 列名と型の一覧（スキーマ）を取得します。

フィルタ・サンプリング

行を絞り込む・抜き出す

• filter / where ── 条件に合う行だけを残します。whereはfilterの別名で、書き方はどちらも同じです。
• limit ── 先頭から指定した行数だけを取得します。
• sample ── データの一部をランダムに抽出します。
• distinct / unique ── 重複行を取り除きます。メソッド名がSnowparkとPolarsで異なる点に注意してください。
• drop_duplicates ── 指定した列の値が一致する行を重複とみなして間引きます。
• between ── 値が指定した範囲内（両端を含む）にあるかを判定します。
• in_ / isin ── 値が指定したリストの中に含まれるかを判定します。

集約・構造変換

グループ化・集計・縦横の入れ替え

• group_by / groupBy ── 指定した列の値でグループ化します。集約する前段階として使います。
• agg ── group_byで作ったグループごとに、集約の計算をまとめて指定します。
• count ── 行数を数える。
• sum ── 列の値を合計します。
• avg / mean ── 列の値の平均を求める。
• min ── 列の最小値を求める。
• max ── 列の最大値を求める。
• pivot ── 行の値を列に展開します（縦持ちから横持ちへ）。
• unpivot ── pivotの逆です。複数列を1つの列にまとめます（横持ちから縦持ちへ）。
• array_agg ── グループ内の複数行の値を、1つの配列（リスト）にまとめます。
• listagg ── グループ内の複数行の文字列を、区切り文字でつないだ1つの文字列にまとめます。
• median / stddev ── 中央値と標準偏差を求めます（外れ値の影響を受けにくい代表値・散らばりの指標）。
• count_distinct / approx_count_distinct ── 重複を除いた値の種類数（ユニーク数）を求めます。近似版は誤差を許容する代わりに高速です。

結合・集合演算

複数のテーブルを1つにする

• join ── 2つのDataFrameを結合します。
• union ── 2つのDataFrameを縦に連結し、重複行を取り除きます。
• union_all / unionAll ── 2つのDataFrameを縦に連結します。重複行はそのまま残します。
• union_by_name / unionByName ── 列の並び順ではなく列名を基準に2つのDataFrameを連結します。
• intersect ── 2つのDataFrameの両方に存在する行だけを残します（積集合）。
• subtract / except_ ── 片方のDataFrameから、もう片方にも存在する行を取り除きます（差集合）。
• join の how（結合の種類） ── inner/left/full/semi/anti など、結合の種類を切り替えます。

ソート

並び順を決める

• order_by / sort ── 行を指定した列の値で並べ替えます。
• asc / desc ── 列に昇順・降順の方向を持たせます。
• nulls_first / nulls_last ── NULL値をソート結果の先頭・末尾どちらに置くかを指定します。

式評価・文字列・型変換

値を計算する・文字列を扱う・型を変える

• when / otherwise ── 条件に応じて異なる値を返します（複数分岐の条件式）。
• iff ── 条件が真か偽かで2つの値のどちらかを返します（2分岐専用のショートカット）。
• is_null / is_not_null ── 値がNULL（欠損）かどうかを判定します。
• coalesce ── 複数の列を左から順に見て、最初に見つかったNULLでない値を返します。
• cast ── 列の型を別の型に変換します。
• substring ── 文字列の一部を指定した位置から切り出します。
• concat（文字列連結） ── 複数の列・文字列を1つにつなげます。
• upper / lower ── 文字列を大文字・小文字に統一します。
• trim / ltrim / rtrim ── 文字列の前後にある空白（または指定した文字）を取り除きます。
• to_date ── 文字列を日付型に変換します。
• date_trunc ── 日付・時刻を指定した単位（月・年など）で切り捨てます。
• datediff ── 2つの日付・時刻の差を、指定した単位（日数など）で求めます。
• dateadd ── 日付・時刻に一定期間を加算（または減算）します。
• round ── 数値を指定した桁数で四捨五入します。
• regexp_replace ── 正規表現にマッチした部分を別の文字列に置き換えます。
• split ── 文字列を区切り文字で分割し、配列（リスト）にします。
• md5 / sha2 ── 文字列からハッシュ値を計算します（重複検知・疑似的な主キー生成などに使います）。
• length ── 文字列の長さ（文字数）を求めます。
• contains ── 文字列に指定した部分文字列が含まれているかを判定します。
• startswith / endswith ── 文字列が指定した文字列で始まる／終わるかを判定します。
• replace（文字列の置き換え） ── 文字列中の一致した部分を、別の文字列に置き換えます（正規表現ではない単純一致）。
• abs / ceil / floor ── 絶対値、切り上げ、切り下げを求める基本的な数値関数です。
• greatest / least ── 複数の列を横に比較し、行ごとの最大値・最小値を求めます。
• year / month / dayofmonth ── 日付・時刻から年・月・日の値だけを取り出します。
• lpad / rpad ── 文字列の左側・右側を指定した文字で埋め、一定の長さに揃えます。
• initcap ── 各単語の先頭だけを大文字にし、残りを小文字にします（タイトルケース化）。
• current_date / current_timestamp ── 現在の日付・日時を取得します。
• array_contains ── 配列の中に指定した値が含まれているかを判定します。
• parse_json / object_construct ── 文字列をJSON（半構造化データ）として解釈します／複数の値からJSONオブジェクトを組み立てます。
• sqrt / exp / ln ── 平方根、指数関数（eのべき乗）、自然対数を求めます。
• left / right ── 文字列の先頭・末尾から指定した文字数を取り出します。
• reverse ── 文字列の文字の並び順を反転させます。
• charindex ── 文字列の中で、指定した部分文字列が最初に現れる位置を求めます。
• to_decimal / to_varchar ── 文字列を指定した精度の数値に変換します／数値を文字列に変換します（書式指定つき）。

ウィンドウ関数

行をまたいだ計算（順位・累積・移動平均）

• Window.partition_by / Window.order_by ── グループ（パーティション）ごとに、行をまたいだ計算をするための土台を定義します。
• rank ── パーティション内で順位をつけます。同じ値には同じ順位がつき、その分だけ次の順位を飛ばします。
• dense_rank ── パーティション内で順位をつけます。同じ値には同じ順位がつきますが、次の順位は飛ばしません。
• row_number ── パーティション内で1から始まる連番をふります。同率でも必ず別の番号になります。
• lag ── パーティション内で、1つ前（過去）の行の値を取得します。
• lead ── パーティション内で、1つ後（未来）の行の値を取得します。
• ntile ── パーティション内の行を、指定した個数のグループに行数ができるだけ均等になるよう分割します。
• percent_rank / cume_dist ── パーティション内での相対的な順位を、0〜1の割合で表します。
• first_value / last_value ── パーティション内で並べ替えた順序の、先頭の値・末尾の値を各行に持たせます。

Null処理

欠損値の扱い方

• na.fill（fillna） ── NULL（欠損）を指定した値で埋めます。
• na.drop（dropna） ── 指定した列がNULLの行を取り除きます。
• na.replace ── 特定の値（NULLとは限らない）を、別の値に一括で置き換えます。

実行・アクション・IO

評価を起動する・結果を取り出す・保存する

• collect ── それまで積み上げた変換を実際に評価し、結果を手元に取得します。最も基本的なアクション。
• show ── 結果の先頭数行を、確認用に画面へ表示します。
• first ── 先頭の1行だけを取得します。
• take ── 指定した件数の行を取得します。
• to_pandas ── 結果をpandas DataFrameに変換します。
• to_local_iterator ── 結果を全件メモリに載せず、1行（またはチャンク）ずつ順番に処理します。
• cache_result ── それまでの計算結果を1度だけ確定させ、以降はその結果を使い回します。
• createOrReplaceView（create_or_replace_view） ── 今のDataFrameの定義を、他のSQLセッションからも参照できるビューとして登録します。
• createOrReplaceTempView（create_or_replace_temp_view） ── 今のセッション限定で有効な、一時的なビューを作ります。
• write.save_as_table ── 結果をテーブル（またはファイル）として書き出します。
• explain ── その時点までの変換が、実際にどう実行される予定かを表示します。