SparkのSQLおよびスキーマエラーのトラブルシューティング

このガイドを使って、Microsoft Fabric SparkジョブにおけるSQLクエリ、スキーマ、メタデータのエラーを診断・解決します。分析例外、バージョン間の挙動変更、未解決のテーブルやビュー、Parquetスキーマ推論の失敗などが含まれます。 その他のSparkジョブエラーについては、Microsoft FabricのSparkエラー概要をご覧ください。

Sparkのバージョン間での動作の不一致

INCONSISTENT_BEHAVIOR_CROSS_VERSIONエラーは、Sparkアプリケーションがランタイムバージョン変更後に異なる結果を生み出したり、失敗したり、動作が変わっていることを示しています。 以前のバージョンで動作していたのと同じコードとデータによって、予期しない出力、エラー、またはパフォーマンスの低下が発生するようになりました。

Fabric ランタイム互換性マトリックス

コンポーネント ランタイム 1.2 ランタイム 1.3 ランタイム 2.0
Apache Spark 3.4 3.5 4.1
Java 11 11 21
Scala 2.12 2.12 2.13
Python 3.10 3.11 3.13
R 4.2 4.4 4.5
デルタ湖 2.4 3.2 4.2

一般的なカテゴリ

Category Examples
Datetime/Timestamp の非互換性 異なる解析、プロレプティックグレゴリオ暦とユリウス暦
クエリ結果の違い さまざまな行数、値、または列の順序
既存のコードの新しいエラー ClassNotFoundException、非推奨の API の削除
パフォーマンスの低下 同じジョブにかかる時間が大幅に長くなる
Delta Lake の互換性 InvalidProtocolVersionException
ライブラリ/依存関係の不一致 パッケージバージョンの変更Python、Scala/Java アップグレード

カテゴリ A — Datetime とタイムスタンプの非互換性

発生する理由: Spark 3.0 以降は、ハイブリッドジュリアン/グレゴリオ暦からプロレプティック グレゴリオ暦に切り替えました。 以前の動作で記述された Parquet INT96 形式と datetime 形式が誤って解釈される可能性があります。 レガシーのdatetime設定は高並行性モードで正しく伝播しない可能性があります。

手順 1: これが影響を受けるかどうかを特定します。 データ/ワークフローには以下が含まれますか。

  • 履歴の日付 (1900 より前か 1582 より前か)

  • 最近のアップグレードの前に作成された Parquet ファイル/テーブル

  • アップグレードされた環境またはコンカレンシーの高い環境でのみエラーが発生しますか?

  • INCONSISTENT_BEHAVIOR_CROSS_VERSIONまたはREAD_ANCIENT_DATETIMEを含むエラーログですか?

手順 2: datetime リベース モードの Spark 構成を設定します。

spark.conf.set("spark.sql.parquet.int96RebaseModeInRead", "CORRECTED")  
spark.conf.set("spark.sql.parquet.int96RebaseModeInWrite", "CORRECTED")  
spark.conf.set("spark.sql.parquet.datetimeRebaseModeInRead", "CORRECTED")  
spark.conf.set("spark.sql.parquet.datetimeRebaseModeInWrite", "CORRECTED")

Important

運用環境で使用する前に検証します。 CORRECTED モードを運用パイプラインに適用する前に、最初にサンプル データセットをテストします。 CORRECTED の動作で最初に書き込まれたデータに LEGACY を設定すると、過去の日付(1582 年以前)の日付値が気付かないうちにずれる可能性があります。 完全なパイプライン実行にコミットする前に、サンプルで SELECT MIN(date_col), MAX(date_col) FROM my_table を実行し、設定間で結果を比較します。 履歴の日付で結果が異なる場合は、既存のデータに LEGACY を使用し、新しいデータの CORRECTED への移行を計画します。

  • 環境間で新しい一貫性のある動作を行うには、"CORRECTED" を使用します (推奨)。

  • "LEGACY" は、アップグレード前のランタイムで書き込まれたデータが読み取りに失敗した場合にのみ使用します。

または、%%configureを介して:

%%configure  
{  
"conf": {  
"spark.sql.parquet.int96RebaseModeInRead": "CORRECTED",  
"spark.sql.parquet.int96RebaseModeInWrite": "CORRECTED",  
"spark.sql.parquet.datetimeRebaseModeInRead": "CORRECTED",  
"spark.sql.parquet.datetimeRebaseModeInWrite": "CORRECTED"  
}  
}

Important

高並行性モードでは、設定はノートブック/セッションレベルで適用する必要があります。環境設定やクラスター全体の設定が伝播しないことがあります。

手順 3: 検証:

  • 失敗したジョブ/ノートブックを再実行します。

  • 設定が有効になったかどうかを確認します。

print(spark.conf.get("spark.sql.parquet.datetimeRebaseModeInRead"))

カテゴリ B — Scala、Java、またはPythonバージョンの変更

Fabric ランタイム Spark Java Scala Python
ランタイム 1.2 3.4 11 2.12 3.10
ランタイム 1.3 3.5 11 2.12 3.11
ランタイム 2.0 4.1 21 2.13 3.13

対処方法:

  • 新しい Scala/Spark バージョンに対してカスタム JAR を再構築します。 Maven/SBT で Spark に指定されたスコープを使用します。

  • サードパーティ JAR を使用する ClassNotFoundException の場合は、JAR に正しい Scala サフィックス (例: _2.12) があることを確認します。

  • Python ModuleNotFoundError の場合は、不足しているパッケージを明示的にインストールします。

%pip install pandas==2.0.3

カテゴリ C — Delta Lake プロトコルの非互換性

発生する理由: Delta Lake では、プロトコル バージョンを使用してテーブル機能を追跡します。 プロトコルのアップグレードは元に戻すことができません。

シナリオ Result
ランタイム 1.2 での削除ベクトルの有効化、ランタイム 1.1 での読み取り 失敗: ランタイム 1.1 はプロトコルをサポートしていません
ランタイム 1.2 で TimestampNTZ を使用して作成されたテーブル リーダー バージョン 3 が必要: ランタイム 1.1 が読み取れない
ライター バージョン 6 で外部に書き込まれたテーブル Fabric Delta ランタイムでサポートされていない可能性があります

対処方法:

  • 前に進み、後方ではなく、プロトコルをサポートするランタイムを使用します。

  • 同じ Delta テーブルでランタイムを混在しないようにします。

  • 新しい機能を有効にする前にプロトコルを確認します。

DESCRIBE DETAIL my_table

カテゴリ D — Spark SQL の動作の変更

発生する理由: Spark バージョンでは、既定の動作 (ANSI モード、キャスト 規則、null 処理) が変更されます。

対処方法:

  • ANSI モードによりより厳密な動作が発生する場合:
spark.conf.set("spark.sql.ansi.enabled", "false")
  • 日付/時刻の解析の変更の場合:
spark.conf.set("spark.sql.legacy.timeParserPolicy", "LEGACY")
  • より厳密な INSERT 型チェックの場合:
spark.conf.set("spark.sql.storeAssignmentPolicy", "LEGACY")

レガシー設定は短期的な解決策です。 新しい動作のためにコードを更新することを計画します。

Spark での AnalysisException

AnalysisExceptionは、Spark のクエリ分析フェーズ中に、データが処理される前にスローされます。 Spark は、SQL または DataFrame クエリを検証し、参照されているすべてのテーブル、列、関数、および型が存在し、互換性があることを確認します。 何かがチェックアウトされない場合、Spark はすぐにクエリを拒否します。 これはほとんどの場合、ユーザー側の問題です。入力ミス、テーブルの不足、スキーマの不一致、サポートされていない操作などです。 早期に失敗するため、コンピューティング リソースは無駄にされません。

一般的なエラー パターン:

org.apache.spark.sql.AnalysisException: Table or view not found: my_table

org.apache.spark.sql.AnalysisException: [UNRESOLVED_COLUMN.WITH_SUGGESTION]  
A column or function parameter with name 'NotARealColumn' cannot be resolved.  
Did you mean one of the following? [Revenue, GrossRevenue, Rating, Branch, City]

org.apache.spark.sql.AnalysisException: Data type mismatch: ...

手順 1: エラー メッセージを注意深く読む

AnalysisException メッセージには、ほとんどの場合、次のものが含まれています。

  • 失敗した内容: テーブル、列、関数、または操作

  • 失敗した理由: 見つからない、型の不一致、あいまいな参照

  • 使用可能な内容: 有効な列、テーブル、または型の一覧

列名の入力ミスの例:

AnalysisException: cannot resolve '`salery`' given input columns:  
[employee.name, employee.salary, employee.dept]

このエラーは、列名は実際には "salary" なのに、"salery" と入力したことを示しています。

手順 2: エラーをシナリオに一致させる

エラーテキストを以下のシナリオと比較し、それに対応する修正を適用してください。

シナリオ A — テーブルまたはビューが見つかりません

Table or view not found: my_table
  • テーブル名にタイプミスがあります。スペルと大文字・小文字の区別を再確認してください。

  • 間違ったデータベースやスキーマ:完全に修飾された名前を使う:

spark.sql("SELECT * FROM my_catalog.my_schema.my_table")
  • 一時ビューの有効期限が切れた: セッションが再開された場合、ビューは失われます。 再作成します。
df.createOrReplaceTempView("my_table")
  • テーブルはまだ書き込まれていません。上流のノートブックまたはセルが完了していることを確認してください。

  • レイクハウスが接続されていません—Fabric で、レイクハウスがノートブックに接続されていることを確認してください。

シナリオ B — 列が見つかりません

[UNRESOLVED_COLUMN.WITH_SUGGESTION] A column or function parameter  
with name 'X' cannot be resolved.
  • 列名の誤植:誤りの中の提案と比較してください。

  • 列の名前が変更されたか、アップストリームから削除されました。スキーマを確認します。

df.printSchema()
  • 列は別の DataFrame に存在します。結合後、正しいソースを参照します。
df1.join(df2, df1.id == df2.id).select(df1.id, df2.name)

シナリオ C — あいまいな列参照

[AMBIGUOUS_REFERENCE] Reference 'Quantity' is ambiguous,  
could be: [a.Quantity, b.Quantity]

実行する操作: テーブルの別名を使用して列を修飾します。

# SQL  
spark.sql("""
  SELECT a.id, b.name  
  FROM table_a a JOIN table_b b ON a.id = b.id  
""")

# DataFrame API  
df1.alias("a").join(df2.alias("b"), col("a.id") == col("b.id")) \
  .select("a.id", "b.name")

使用可能な SQL 関数の完全な一覧については、「 Spark SQL 組み込み関数」を参照してください。

シナリオ D — データ型の不一致

Data type mismatch: differing types in '(col_a = col_b)': int vs string

実行する操作: 共通の型に明示的にキャストします。

from pyspark.sql.functions import col  
df = df1.join(df2, df1["id"].cast("string") == df2["id_str"])

シナリオ E — 関数が見つかりません

Undefined function: 'my_function'

対処方法:

  • 誤字:Spark SQL関数の参照を確認してください。

  • UDF が登録されていません:

spark.udf.register("my_function", my_function)
  • バージョン アップグレードで削除された関数: 移行ガイドを確認してください。

シナリオ F — 書き込み/INSERT でのスキーマの不一致

[_LEGACY_ERROR_TEMP_DELTA_0007] A schema mismatch detected  
when writing to the Delta table...

対処方法:

  • ターゲットが期待するものを確認します。
spark.sql("DESCRIBE my_table").show()
  • 記述内容を確認します。
df.printSchema()
  • 列と型を揃える:
df = df.select("col_a", "col_b", "col_c")  
df = df.withColumn("col_a", col("col_a").cast("int"))
  • Delta スキーマ進化について:
df.write.format("delta") \
  .option("mergeSchema", "true") \
  .mode("append") \
  .save("/path/to/table")

シナリオ G — Delta Lake AnalysisException

エラー 原因 修正
リーダー/ライター バージョン N が必要なテーブルに書き込めません デルタ プロトコルの非互換性 必要なプロトコルをサポートするランタイムを使用する
Delta テーブルへの書き込み時にスキーマの不一致が検出されました 新しいデータに余分な列または不足している列がある スキーマのマージを有効にするか、スキーマを修正する
互換性のない形式が検出されました デルタ以外の形式でデルタ パスに書き込む ターゲット パスが Delta テーブルであることを確認する
操作が許可されていません: パーティション列を変更できません パーティション分割を変更しようとしています 目的のパーティション分割を使用して新しいテーブルを作成する

Delta Lake スキーマの進化、テーブル機能、プロトコルバージョンの詳細については、 Delta Lake のドキュメントを参照してください。

シナリオ H — パス/ファイルが見つかりません

Path does not exist: abfss://container@account.dfs.core.windows.net/my/path

対処方法:

  • パスの誤字:コンテナ名、ストレージアカウント、ファイルパスを再確認してください。

  • ファイルが削除または移動されました。ファイルが lakehouse/Storage エクスプローラーに存在するかどうかを確認します。

  • 間違ったストレージ アカウントまたはワークスペース。

  • 権限の問題: 実際には "アクセスが拒否されました" であるにもかかわらず、エラーに "パスが見つかりません" と表示されることがあります。

Important

Fabric ノートブックでは、Spark を使用した nbresource フォルダーからの読み取りはサポートされていません。 ノートブックのリソース ファイルには、open() ではなく Python のファイル I/O (spark.read) を使用してください。 明示的なパスに書き込む場合は、.save()の代わりに.saveAsTable()を使用します。

シナリオ I — サポートされていない操作

Unsupported operation: ALTER TABLE ADD COLUMNS ... for non-Delta tables

実行する操作: 機能に差分形式が必要かどうかを確認します。 必要に応じて変換します。

from delta.tables import DeltaTable  
DeltaTable.convertToDelta(spark, "parquet.`/path/to/table`")

デバッグ手法

  • スキーマを印刷します。
df.printSchema()  
spark.sql("DESCRIBE EXTENDED my_table").show(truncate=False)
  • 使用可能なテーブルの一覧表示:
spark.sql("SHOW TABLES").show()
  • 使用可能な列の一覧表示:
spark.sql("DESCRIBE my_table").show()
  • クエリを段階的にテストする - ステップ バイ ステップでビルドします。
spark.sql("SELECT * FROM my_table LIMIT 5").show()  
spark.sql("SELECT col_a, col_b FROM my_table LIMIT 5").show()
  • Spark 構成を確認します。
for k, v in sorted(spark.sparkContext.getConf().getAll()):  
    print(f"{k} = {v}")

トラブルシューティング早見表

エラーメッセージには以下が含まれます 考えられる原因 最初のアクション
テーブルまたはビューが見つかりません テーブルがないか、データベースが間違っている スペルチェック;完全に修飾された名前を使え
解決できない + 列名 列が存在しないか、列名のスペルが間違っています df.printSchema()または DESCRIBE テーブルを実行する
参照 ... は曖昧である 結合後に列名が重複する テーブルエイリアスを付けて指定: a.id
データ型が一致していません 互換性のない型の比較 列を共通型にキャストする
未定義関数 見つからない、または未登録の UDF スペル チェック;カスタムの場合は UDF を登録する
互換性のないデータを書き込めません 書き込み時のスキーマの不一致 ソースとターゲットのスキーマを比較する。cast/select
パスが存在しない 間違ったファイル パスまたは削除されたファイル ストレージ エクスプローラーでパスを確認する
安全にキャストできない INSERT での厳密な型チェック 書き込む前に列を明示的にキャストする
DeltaAnalysisException デルタ固有のスキーマ/プロトコルの問題 上の「Delta Lake」セクションを参照してください
サポートされていない操作です テーブル形式では使用できない機能 デルタ形式が必要かどうかを確認する

テーブルまたはビューが見つかりません

エラー コード:Spark_User_MetaStore_TableOrViewNotFound

このエラーは何を意味しますか? 「承認済みの標準 DCasV5/ECasv5 Family Cores クォータを超過することになるため、操作を完了できませんでした」

Sparkはクエリ解析中にテーブルやビュー名をメタストアに対して解決できませんでした。Sparkがデータを処理する前にです。 そのテーブルはあなたが使った名前で存在しないか、別のデータベースやワークスペースのコンテキストに存在しているか、削除または名前変更されたかのどちらかです。

確認すべきエラー メッセージ

Table or view not found: my_table
[TABLE_OR_VIEW_NOT_FOUND]
AnalysisException: Table or view not found

一般的な原因と修正

これらの典型的な原因を確認し、あなたの状況に合ったものを見つけ、それを適用してください。

タイプミスまたは無条件のテーブル名

この原因が最も一般的です。 スペルを確認し、名前の解決が現在のデータベースの文脈に依存しないように、完全に限定的な名前を使いましょう。

-- Prefer fully qualified names
SELECT * FROM my_lakehouse.dbo.sales_orders;

-- List what actually exists
SHOW TABLES IN my_lakehouse;

間違ったデータベースやレイクハウスコンテキスト

テーブルは存在しますが、現在ノートブックに接続されているものとは異なるデータベース、スキーマ、またはレイクハウスに入っています。 Fabricでは、無条件のテーブル名はノートブックのデフォルトのレイクハウスに対して解決されます。

  • ノートブックエクスプローラーでデフォルトで割り当てられている湖の家を確認してください。
  • spark.catalog.currentDatabase()を実行して、アクティブなデータベースコンテキストを確認してください。

テーブルがドロップされた、名前変更、またはまだ作成されていない

上流のパイプラインや他のノートブック、あるいは他のユーザーがテーブルを落としたり名前を変えたりしました。 マルチステップパイプラインでは、上流のテーブル作成ステップが完了する前に下流のアクティビティが実行されることがあります。

  • パイプライン依存関係やアクティビティの順序を確認してください。
  • 読む前に存在チェックを追加してください: spark.catalog.tableExists("my_lakehouse.dbo.sales_orders")。

セッションの再起動で一時的な表示が消去されました

createOrReplaceTempView()で作成された一時的なビューは現在のSparkセッションのみで有効です。 セッションが再起動した場合(タイムアウト、カーネル再起動、または %%configure 再実行)、以前の一時的なビューは消え、それらを再作成しなければなりません。

アクセスなしのワークスペース間参照

他のワークスペースのレイクハウスのテーブルを必要な権限なしで参照したり、テーブルを裏付けるショートカットがもう存在しない場所を指し示したりします。

注

ノートブックのSQLセル内で発生するこのコードのエラーは AnalysisExceptionとして現れます。 詳細については、 SparkのAnalysisExceptionをご覧ください。 Sparkジョブ定義やパイプライン活動からのエラーは、このコードに直接表れます。 解決のステップは同じです。

トラブルシューティング早見表

症状 考えられる原因 最初のアクション
無条件の名前でしか失敗しない 間違ったデフォルトのレイクハウスやデータベース catalog.schema.table を使用する
昨日は動いたのに、今日は失敗しました テーブルが上流で削除または名前変更された パイプラインの系譜を確認
カーネル再起動後に失敗 セッションで一時的な表示が失われました 一時的なビューを再現する
一部のユーザーだけが失敗します クロスワークスペース権限 ワークスペースアクセスの確認

Parquet スキーマを推論できない

エラー コード:Spark_User_Parquet_NeedsManualSchema

このエラーは何を意味しますか? 「承認済みの標準 DCasV5/ECasv5 Family Cores クォータを超過することになるため、操作を完了できませんでした」

SparkはParquetファイルを読み取る際に自動的にスキーマを推測できません。 Parquetファイルには独自のスキーマメタデータが含まれているため、このエラーは通常、Sparkがパス上で利用可能なParquetファイルを検出しなかったことを意味します。 ディレクトリは空であったり、Parquetでないファイルのみを含んだり、スキーマが互いに矛盾しているファイルが含まれている場合があります。

確認すべきエラー メッセージ

Spark_User_Parquet_NeedsManualSchema
Unable to infer schema for Parquet
Schema must be specified manually

なぜこのエラーが起こるのか

  • 空のディレクトリから読み取ろうとしますが、スキーマを推測できるParquetファイルは存在しません。
  • ディレクトリには、異なるパイプラインバージョンによって書かれた異なるスキーマのParquetファイルが含まれています。
  • パスは存在しますが、Parquetのメタデータがありません(パスが間違っているか、ファイルが実際にはCSVやJSONです)。

解決手順

  1. 読む前にディレクトリが空かどうかを確認してください:

    files = notebookutils.fs.ls("abfss://path")
    if len(files) == 0:
        print("Directory is empty - no schema to infer")
    
  2. 空のディレクトリが正当な状態(例えば、パーティションにまだデータがない場合)であれば、スキーマを明示的に提供してください:

    from pyspark.sql.types import StructType, StructField, StringType, IntegerType
    
    schema = StructType([
        StructField("name", StringType(), True),
        StructField("age", IntegerType(), True),
    ])
    
    df = spark.read.schema(schema).parquet("abfss://path")
    
  3. ファイル間でスキーマが一貫しない場合は、互換性のある違いを調整するためにスキーマのマージを有効にしてください:

    df = spark.read.option("mergeSchema", "true").parquet("abfss://path")
    
  4. ファイルが本当にParquetであることを確認し、ファイル拡張子を確認し、書き込みプロセスが成功したか確認してください。

注

mergeSchema 互換性のあるスキーマの違い(列の追加)を調整しますが、同じ列の競合型は修正できません。 型の衝突については、ファイルグループを別々に読み、共通スキーマにキャストし、ユニオンします。

トラブルシューティング早見表

症状 考えられる原因 最初のアクション
空ディレクトリでのエラー スキーマを推測できるParquetファイルはありません スキーマを明示的に提供してください
ファイルバージョンのミックス後に失敗 ファイル間での一貫性のないスキーマ mergeSchema を有効にする
パスにはParquetのメタデータがありません パスが間違っているか、ファイルがCSVかJSONです ファイル拡張子とパスの確認