PySpark のアップグレード#

PySpark 3.5 から 4.0 へのアップグレード#

Spark 4.0 では、PySpark で Python 3.8 のサポートが廃止されました。
Spark 4.0 では、PySpark でサポートされる Pandas の最小バージョンが 1.0.5 から 2.0.0 に引き上げられました。
Spark 4.0 では、PySpark でサポートされる Numpy の最小バージョンが 1.15 から 1.21 に引き上げられました。
Spark 4.0 では、PySpark でサポートされる PyArrow の最小バージョンが 4.0.0 から 11.0.0 に引き上げられました。
Spark 4.0 では、Spark 上の pandas API から Int64Index および Float64Index が削除され、直接 Index を使用する必要があります。
Spark 4.0 では、Spark 上の pandas API から DataFrame.iteritems が削除され、代わりに DataFrame.items を使用してください。
Spark 4.0 では、Spark 上の pandas API から Series.iteritems が削除され、代わりに Series.items を使用してください。
Spark 4.0 では、Spark 上の pandas API から DataFrame.append が削除され、代わりに ps.concat を使用してください。
Spark 4.0 では、Spark 上の pandas API から Series.append が削除され、代わりに ps.concat を使用してください。
Spark 4.0 では、Spark 上の pandas API から DataFrame.mad が削除されました。
Spark 4.0 では、Spark 上の pandas API から Series.mad が削除されました。
Spark 4.0 では、Spark 上の pandas API から Index.factorize および Series.factorize の na_sentinel パラメータが削除され、代わりに use_na_sentinel を使用してください。
Spark 4.0 では、Spark 上の pandas API から Categorical.add_categories, Categorical.remove_categories, Categorical.set_categories, Categorical.rename_categories, Categorical.reorder_categories, Categorical.as_ordered, Categorical.as_unordered の inplace パラメータが削除されました。
Spark 4.0 では、Spark 上の pandas API から CategoricalIndex.add_categories, CategoricalIndex.remove_categories, CategoricalIndex.remove_unused_categories, CategoricalIndex.set_categories, CategoricalIndex.rename_categories, CategoricalIndex.reorder_categories, CategoricalIndex.as_ordered, CategoricalIndex.as_unordered の inplace パラメータが削除されました。
Spark 4.0 では、Spark 上の pandas API から ps.date_range の closed パラメータが削除されました。
Spark 4.0 では、Spark 上の pandas API から DataFrame.between_time の include_start および include_end パラメータが削除され、代わりに inclusive を使用してください。
Spark 4.0 では、Spark 上の pandas API から Series.between_time の include_start および include_end パラメータが削除され、代わりに inclusive を使用してください。
Spark 4.0 では、Spark 上の pandas API から DatetimeIndex の各種日時属性（day, month, year など）が int64 ではなく int32 になりました。
Spark 4.0 では、Spark 上の pandas API から DataFrame.plot および Series.plot の sort_columns パラメータが削除されました。
Spark 4.0 では、Spark 上の pandas API から Series.str.replace の regex パラメータのデフォルト値が True から False に変更されました。さらに、regex=True を指定した単一文字の pat は、文字列リテラルではなく正規表現として扱われるようになりました。
Spark 4.0 では、Spark 上の pandas API から、value_counts の結果の名前はすべて 'count'（normalize=True が渡された場合は 'proportion'）に設定され、インデックスは元のオブジェクトの名前になります。
Spark 4.0 では、Spark 上の pandas API から ps.read_csv および ps.read_excel の squeeze パラメータが削除されました。
Spark 4.0 では、Spark 上の pandas API から DataFrame.info の null_counts パラメータが削除され、代わりに show_counts を使用してください。
Spark 4.0 では、Spark 上の pandas API から、MultiIndex.append の結果はインデックス名を保持しなくなりました。
Spark 4.0 では、Spark 上の pandas API から、as_index=False を尊重したリストでの DataFrameGroupBy.agg がサポートされます。
Spark 4.0 では、Spark 上の pandas API から、DataFrame.stack は既存の列を辞書順にソートするのではなく、その順序を保証するようになりました。
Spark 4.0 では、Spark 上の pandas API から、Series.between の inclusive パラメータへの True または False の指定が削除され、それぞれ both または neither を使用してください。
Spark 4.0 では、Spark 上の pandas API から Index.asi8 が削除され、代わりに Index.astype を使用してください。
Spark 4.0 では、Spark 上の pandas API から Index.is_type_compatible が削除され、代わりに Index.isin を使用してください。
Spark 4.0 では、Spark 上の pandas API から DataFrame.to_latex および Series.to_latex の col_space パラメータが削除されました。
Spark 4.0 では、Spark 上の pandas API から DataFrame.to_spark_io が削除され、代わりに DataFrame.spark.to_spark_io を使用してください。
Spark 4.0 では、Spark 上の pandas API から Series.is_monotonic および Index.is_monotonic が削除され、それぞれ Series.is_monotonic_increasing または Index.is_monotonic_increasing を使用してください。
Spark 4.0 では、Spark 上の pandas API から DataFrame.get_dtype_counts が削除され、代わりに DataFrame.dtypes.value_counts() を使用してください。
Spark 4.0 では、Spark 上の pandas API から DataFrame.to_excel および Series.to_excel の encoding パラメータが削除されました。
Spark 4.0 では、Spark 上の pandas API から DataFrame.to_excel および Series.to_excel の verbose パラメータが削除されました。
Spark 4.0 では、Spark 上の pandas API から read_csv の mangle_dupe_cols パラメータが削除されました。
Spark 4.0 では、Spark 上の pandas API から DataFrameGroupBy.backfill が削除され、代わりに DataFrameGroupBy.bfill を使用してください。
Spark 4.0 では、Spark 上の pandas API から DataFrameGroupBy.pad が削除され、代わりに DataFrameGroupBy.ffill を使用してください。
Spark 4.0 では、Spark 上の pandas API から Index.is_all_dates が削除されました。
Spark 4.0 では、Spark 上の pandas API から read_excel の convert_float パラメータが削除されました。
Spark 4.0 では、Spark 上の pandas API から read_excel の mangle_dupe_cols パラメータが削除されました。
Spark 4.0 では、Spark 上の pandas API から DataFrame.koalas が削除され、代わりに DataFrame.pandas_on_spark を使用してください。
Spark 4.0 では、PySpark から DataFrame.to_koalas が削除され、代わりに DataFrame.pandas_api を使用してください。
Spark 4.0 では、PySpark から DataFrame.to_pandas_on_spark が削除され、代わりに DataFrame.pandas_api を使用してください。
Spark 4.0 では、Pandas on Spark API から DatatimeIndex.week および DatatimeIndex.weekofyear が削除され、代わりに DatetimeIndex.isocalendar().week を使用してください。
Spark 4.0 では、Pandas on Spark API から Series.dt.week および Series.dt.weekofyear が削除され、代わりに Series.dt.isocalendar().week を使用してください。
Spark 4.0 では、Decimal 型オブジェクトに astype を適用した場合、既存の欠損値は Pandas on Spark API では False ではなく True に変更されます。
Spark 4.0 では、Pandas on Spark API から pyspark.testing.assertPandasOnSparkEqual が削除され、代わりに pyspark.pandas.testing.assert_frame_equal を使用してください。
Spark 4.0 では、Pandas on Spark API からエイリアス Y, M, H, T, S が非推奨となり、それぞれ YE, ME, h, min, s を使用してください。
Spark 4.0 では、マップ列のスキーマは、マップ内のすべてのペアのスキーマをマージすることによって推論されます。スキーマが最初の非ヌルペアからのみ推論される以前の動作を復元するには、spark.sql.pyspark.legacy.inferMapTypeFromFirstPair.enabled を true に設定できます。
Spark 4.0 では、compute.ops_on_diff_frames がデフォルトで有効になっています。以前の動作を復元するには、compute.ops_on_diff_frames を false に設定してください。
Spark 4.0 では、DataFrame.collect のデータ型 YearMonthIntervalType は、基になる整数を返さなくなりました。以前の動作を復元するには、環境変数 PYSPARK_YM_INTERVAL_LEGACY を 1 に設定してください。
Spark 4.0 では、from pyspark.sql.functions import * のワイルドカードインポートから、関数以外の項目（DataFrame, Column, StructType など）が削除されました。これらの項目は適切なモジュールからインポートする必要があります（例: from pyspark.sql import DataFrame, Column, from pyspark.sql.types import StructType）。
Spark 4.0 では、pandas API on Spark は、ANSI モードが有効になっている（デフォルトで有効）Spark が基盤にある場合、例外を発生させます。これは ANSI モードでは正常に機能しないためです。機能させるには、spark.sql.ansi.enabled を false に設定して明示的に ANSI モードを無効にする必要があります。または、pandas-on-spark オプション compute.fail_on_ansi_mode を False に設定して強制的に機能させることもできますが、予期しない動作を引き起こす可能性があります。

PySpark 3.3 から 3.4 へのアップグレード#

Spark 3.4 では、配列列のスキーマは、配列内のすべての要素のスキーマをマージすることによって推論されます。スキーマが最初の要素からのみ推論される以前の動作を復元するには、spark.sql.pyspark.legacy.inferArrayTypeFromFirstElement.enabled を true に設定できます。
Spark 3.4 では、Pandas on Spark API の Groupby.apply の func パラメータの戻り値の型が指定されておらず、compute.shortcut_limit が 0 に設定されている場合、スキーマ推論が正確になるように、サンプリング行は 2（サンプリング行が常に 2 以上であることを保証）に設定されます。
Spark 3.4 では、Pandas on Spark API の Index.insert が範囲外の場合、index {} is out of bounds for axis 0 with size {} という IndexError を発生させ、pandas 1.4 の動作に従います。
Spark 3.4 では、pandas 1.4 の動作に従うために、Pandas on Spark API の Series.mode でシリーズ名が保持されるようになります。
Spark 3.4 では、Pandas on Spark API の Index.__setitem__ は、value の型が Column 型であるかを最初にチェックし、is_list_like で Cannot convert column into bool: please use '&' for 'and', '|' for 'or', '~' for 'not' when building DataFrame boolean expressions. のような予期しない ValueError の発生を回避します。
Spark 3.4 では、Pandas on Spark API の astype('category') は、元のデータの dtype に従って categories.dtype も更新し、pandas 1.4 の動作に従います。
Spark 3.4 では、Pandas on Spark API は pandas 1.4 に従い、GroupBy.head および GroupBy.tail で groupby 位置インデックスをサポートします。負の引数が正しく機能し、各グループの末尾および先頭からの範囲を返します。以前は、負の引数は空のフレームを返していました。
Spark 3.4 では、Pandas on Spark の groupby.apply のスキーマ推論プロセスは、まず pandas の型を推論し、pandas の dtype の精度を可能な限り保証します。
Spark 3.4 では、pandas 1.4 の動作に従い、Series.concat の sort パラメータが尊重されます。
Spark 3.4 では、pandas 1.4 の動作に従い、DataFrame.__setitem__ はコピーを作成し、既存の配列を上書きせずに置き換えます。
Spark 3.4 では、SparkSession.sql および Pandas on Spark API の sql に、名前付きパラメータを SQL リテラルにバインドする新しいパラメータ args が追加されました。
Spark 3.4 では、Pandas API on Spark は pandas 2.0 に準拠しており、Spark 3.4 では pandas 2.0 の変更に従って一部の API が非推奨または削除されました。詳細については、[pandas のリリースノート](https://pandas.dokyumento.jp/docs/dev/whatsnew/) を参照してください。
Spark 3.4 では、collections.namedtuple のカスタムモンキーパッチが削除され、デフォルトで cloudpickle が使用されるようになりました。collections.namedtuple の関連するピッキング問題の以前の動作を復元するには、環境変数 PYSPARK_ENABLE_NAMEDTUPLE_PATCH を 1 に設定してください。

PySpark 3.2 から 3.3 へのアップグレード#

Spark 3.3 では、pyspark.pandas.sql メソッドは [標準の Python 文字列フォーマッタ](https://docs.python.org/3/library/string.html#format-string-syntax) に従います。以前の動作を復元するには、環境変数 PYSPARK_PANDAS_SQL_LEGACY を 1 に設定してください。
Spark 3.3 では、Spark 上の pandas API の drop メソッドが index による行の削除をサポートし、デフォルトで列ではなくインデックスによる削除を設定します。
Spark 3.3 では、PySpark は Pandas のバージョンをアップグレードしました。新しい最小必須バージョンは 0.23.2 から 1.0.5 に変更されました。
Spark 3.3 では、SQL データ型の repr の戻り値が変更され、eval に渡されたときに同じ値を持つオブジェクトを生成するようになりました。

PySpark 3.1 から 3.2 へのアップグレード#

Spark 3.2 では、sql, ml, spark_on_pandas モジュールの PySpark メソッドは、不適切な型のパラメータに適用された場合、ValueError の代わりに TypeError を発生させます。
Spark 3.2 では、Python UDF、pandas UDF、および pandas 関数 API からのトレースバックは、デフォルトで内部 Python ワーカーからのトレースバックなしで簡略化されます。Spark 3.1 以前では、Python ワーカーからのトレースバックが出力されていました。Spark 3.2 より前の動作を復元するには、spark.sql.execution.pyspark.udf.simplifiedTraceback.enabled を false に設定できます。
Spark 3.2 では、デフォルトでピン留めスレッドモードが有効になり、各 Python スレッドが対応する JVM スレッドにマッピングされます。以前は、1 つの JVM スレッドが複数の Python スレッドで再利用される可能性があり、1 つの JVM スレッドローカルが複数の Python スレッドに共有される結果となっていました。また、JVM スレッド内のローカルプロパティなどの継承可能な属性を正しく継承し、潜在的なリソースリークの問題を回避するために、Python スレッドで pyspark.InheritableThread または pyspark.inheritable_thread_target を一緒に使用することが推奨されることに注意してください。Spark 3.2 より前の動作を復元するには、環境変数 PYSPARK_PIN_THREAD を false に設定できます。

PySpark 2.4 から 3.0 へのアップグレード#

Spark 3.0 では、PySpark は pandas 関連の機能（toPandas、pandas DataFrame からの createDataFrame など）を使用するために pandas バージョン 0.23.2 以上を必要とします。
Spark 3.0 では、PySpark は PyArrow 関連の機能（pandas_udf、toPandas、および "spark.sql.execution.arrow.enabled=true" を使用した createDataFrame など）を使用するために PyArrow バージョン 0.12.1 以上を必要とします。
PySpark では、SparkSession.builder.getOrCreate() で SparkSession を作成する際に、既存の SparkContext が存在する場合、ビルダーはビルダーに指定された構成で既存の SparkContext の SparkConf を更新しようとしました。しかし、SparkContext はすべての SparkSession で共有されるため、更新すべきではありません。3.0 では、ビルダーは構成を更新しなくなりました。これは 2.3 以降の Java/Scala API と同じ動作です。構成を更新したい場合は、SparkSession を作成する前に更新する必要があります。

PySpark では、Arrow 最適化が有効になっている場合、Arrow バージョンが 0.11.0 より大きい場合、シリアライズ中に pandas.Series を Arrow 配列に変換する際に Arrow は安全な型変換を実行できます。Arrow は、オーバーフローのような安全でない型変換を検出するとエラーを発生させます。spark.sql.execution.pandas.convertToArrowArraySafely を true に設定することで有効にできます。デフォルト設定は false です。Arrow バージョンに対する PySpark の動作を次の表に示します。

PyArrow バージョン

整数オーバーフロー

浮動小数点数切り捨て

0.11.0 以下

エラーを発生させる

サイレントに許可する

> 0.11.0, arrowSafeTypeConversion=false

サイレントオーバーフロー

サイレントに許可する

> 0.11.0, arrowSafeTypeConversion=true

エラーを発生させる

エラーを発生させる

Spark 3.0 では、PySpark で createDataFrame(..., verifySchema=True) も LongType を検証します。以前は、LongType は検証されず、値がオーバーフローした場合に None が返されていました。この動作を復元するには、verifySchema を False に設定して検証を無効にできます。
Spark 3.0 以降、Python 3.6 以降のバージョンでは、Row のフィールド名は名前付き引数で構成する際にアルファベット順にソートされなくなり、フィールドの順序は入力された順序と一致します。Spark 2.4 のようにデフォルトでフィールドをソートするには、executor および driver の両方で環境変数 PYSPARK_ROW_FIELD_SORTING_ENABLED を true に設定してください。この環境変数はすべての executor および driver で一貫している必要があります。そうしないと、失敗または誤った結果を招く可能性があります。Python バージョン 3.6 未満では、フィールド名はアルファベット順にソートされるのが唯一のオプションです。
Spark 3.0 では、pyspark.ml.param.shared.Has* ミキシンは set*(self, value) セッターメソッドを提供しなくなりました。代わりに、それぞれの self.set(self.*, value) を使用してください。詳細は [SPARK-29093](SPARK-29093) を参照してください。

PyArrow バージョン	整数オーバーフロー	浮動小数点数切り捨て
0.11.0 以下	エラーを発生させる	サイレントに許可する
> 0.11.0, arrowSafeTypeConversion=false	サイレントオーバーフロー	サイレントに許可する
> 0.11.0, arrowSafeTypeConversion=true	エラーを発生させる	エラーを発生させる

PySpark 2.3 から 2.4 へのアップグレード#

PySpark では、Arrow 最適化が有効になっている場合、以前は toPandas は Arrow 最適化が使用できない場合に単に失敗していましたが、pandas DataFrame からの createDataFrame は非最適化へのフォールバックを許可していました。現在では、toPandas および pandas DataFrame からの createDataFrame の両方で、デフォルトでフォールバックが許可されており、spark.sql.execution.arrow.fallback.enabled で無効にできます。

PySpark 2.3.0 から 2.3.1 以降へのアップグレード#

バージョン 2.3.1 以降、pandas_udf および toPandas()/createDataFrame() （spark.sql.execution.arrow.enabled が True に設定されている場合）を含む Arrow 機能は実験的なものとしてマークされています。これらはまだ進化中であり、現在、本番環境での使用は推奨されていません。

PySpark 2.2 から 2.3 へのアップグレード#

PySpark では、toPandas、pandas DataFrame からの createDataFrame などの pandas 関連機能を使用するには、Pandas 0.19.2 以上が必要になりました。
PySpark では、pandas 関連機能のタイムスタンプ値の動作が、セッションタイムゾーンを尊重するように変更されました。古い動作を使用したい場合は、設定 spark.sql.execution.pandas.respectSessionTimeZone を False に設定する必要があります。[SPARK-22395](SPARK-22395) を参照してください。
PySpark では、na.fill() または fillna もブール値を受け入れ、null をブール値で置き換えます。以前の Spark バージョンでは、PySpark はそれを無視して元の Dataset/DataFrame を返していました。
PySpark では、df.replace は to_replace が辞書でない場合に値を省略することを許可しませんでした。以前は、他のケースで値を省略でき、デフォルトで None になっていましたが、これは直感的ではなくエラーが発生しやすかったです。

PySpark 1.4 から 1.5 へのアップグレード#

Python での文字列から列への解決は、ドット（.）を使用して列を修飾したり、ネストされた値にアクセスしたりできるようになりました。例: df['table.column.nestedField']。ただし、これは列名にドットが含まれている場合は、バッククォート（例: table.`column.with.dots`.nested）を使用してエスケープする必要があることを意味します。
PySpark の DataFrame.withColumn メソッドは、新しい列を追加したり、同じ名前の既存の列を置き換えたりすることをサポートします。

PySpark 1.0-1.2 から 1.3 へのアップグレード#

Python で DataTypes を使用する場合、シングルトンを参照するのではなく、それらを構築（例: StringType()）する必要があります。