エラーメッセージガイドライン

このガイドは、Apache Sparkにおける標準化され、実行可能なエラーメッセージを作成するための参考資料です。

何を、なぜ、どのようにを記述する

Sparkからスローされる例外は、5W1Hに答える必要があります

• 誰が問題に遭遇したか？
• 何が問題だったか？
• いつ問題が発生したか？
• どこで問題が発生したか？
• なぜ問題が発生したか？
• どのように問題を解決できるか？

例外によって提供されるコンテキストは、誰が（通常はユーザー）、いつ（通常はlog4jを介してログに含まれる）、どこで（通常はスタックトレースに含まれる）に答えるのに役立ちます。しかし、これらの回答だけでは、ユーザーが問題を解決するには不十分なことがよくあります。残りの質問—何が、なぜ、どのように—に答えるエラーメッセージは、ユーザーの不満を最小限に抑えます。

何を、なぜ、どのようにを明示的に記述する

多くの場合、エラーメッセージは、何が、なぜ、どのようにを明示的に答える必要があります。

例1

内部クラス{}のエンコーダーを、このクラスが定義されたスコープにアクセスせずに生成できません。このクラスを親クラスの外に移動してみてください。

• 何が：内部クラスのエンコーダーを生成できません。
• なぜ：クラスが定義されたスコープにアクセスできませんでした。
• どのように：このクラスを親クラスの外に移動してみてください。

例2

提案された修正（どのように）が恣意的だと感じる場合は、なぜエラーが発生したかの説明を提供することで、ユーザーの不満を軽減できます。

変更前

サポートされていません 関数名{}。

• 何が：サポートされていない関数名です。
• なぜ：不明です。
• どのように：不明です。

変更後

関数名{} が無効です。一時的な関数はカタログに属することはできません。1つまたは2つの部分からなる関数名を指定してください。

• 何が：無効な関数名です。
• なぜ：一時的な関数はカタログに属することができません。
• どのように：1つまたは2つの部分からなる関数名を指定してください。

どのようにを暗黙的に記述する

すべてのエラーメッセージがこれほど冗長である必要はありません。場合によっては、どのように問題を解決するかを明示的に説明することが冗長になります。この場合は、明示的な説明を省略しても構いません。

例1

無効なピボット列{}。ピボット列は比較可能である必要があります。

• 何が：無効なピボット列です。
• なぜ：ピボット列は比較可能である必要があります。
• どのように（なぜから暗示される）：比較可能なピボット列を使用してください。

例2

変更前

{}関数にウィンドウフレームを指定できません

• 何が：関数にウィンドウフレームを指定できません。
• なぜ：不明です。
• どのように：不明です。

変更後

ウィンドウ式{}にフレームを指定できません。ウィンドウ式で、関数フレーム{}と指定フレーム{}が一致していません。

• 何が：ウィンドウ式にフレームを指定できません。
• なぜ：ウィンドウ式で、関数フレームと指定フレームが一致していません。
• どのように（なぜから暗示される）：関数フレームと指定フレームを一致させてください。

例3

変更前

10進数を解析できません。

• 何が：10進数を解析できません。
• なぜ：不明です。
• どのように：不明です。

変更後

無効な10進数{}；位置{}で解析中にエラーが発生しました。

• 何が：無効な10進数です。
• なぜ：指定された位置で10進数パーサーがエラーを検出しました。
• どのように（なぜから暗示される）：指定された位置のエラーを修正してください。

なぜとどのようにを暗黙的に記述する

場合によっては、なぜ問題が発生したかを明示的に説明することさえ冗長になります。この場合は、明示的な説明を省略しても構いません。

パスが存在しません：{}

• 何が：パスが存在しません。
• なぜ（何がから暗示される）：ユーザーが無効なパスを指定しました。
• どのように（何がから暗示される）：別のパスを使用してください。

明確な言葉を使う

語彙ガイド

フレーズ	使用する場合	例
サポートされていません	ユーザーは、操作がサポートされていると合理的に想定する可能性がありますが、サポートされていません。開発者が操作のサポートを追加すれば、このエラーは将来解消される可能性があります。	データ型{}はサポートされていません。
無効/許可されていません/予期せぬ	ユーザーは操作を指定する際にミスをしました。メッセージは、ユーザーにエラーの解決方法を知らせる必要があります。	配列のサイズは{}で、インデックス{}は無効です。
		句{}に{}個のジェネレーターが見つかりました。1つのジェネレーターのみ許可されています。
		予期せぬ状態形式バージョン{}が見つかりました。バージョン1または2が期待されていました。
失敗しました	システムで予期せぬエラーが発生し、ユーザーエラーに合理的に起因させることができません。	失敗しました {}のコンパイル。
できません	いつでも、できれば上記のいずれかの代替案が適用されない場合のみ。	できません サポートされていない型{}のコードを生成します。

表現ガイド

ベストプラクティス	変更前	変更後
能動態を使用する	データ型{}はサポートされていません {}。	{} はデータ型{}をサポートしていません。
将来のサポートの約束など、時間ベースの記述を避ける	Pandas UDF集約式は、ピボットでは現在サポートされていません。	ピボットはPandas UDF集約式をサポートしていません。
	Parquet型はまだサポートされていません：{}。	{} はParquet型をサポートしていません。
現在形を使用してエラーを説明し、提案を提供する	見つかりませんでした {}の参照列{}。	見つかりません {}の参照列{}。
	結合戦略ヒントパラメーターは識別子または文字列である必要がありますが、{}でした。	結合戦略ヒントパラメーター{}を使用できません。使用してください テーブル名または識別子を指定してパラメーターを指定します。
解決策が不明な場合は、具体的な例を示す	{}ヒントは、パラメーターとしてパーティション数を期待します。	{}ヒントは、パラメーターとしてパーティション数を期待します。たとえば、{}(3)で3つのパーティションを指定します。
非難的、批判的、または侮辱的な表現を避ける	指定する必要があります {}の金額。	{}は空にできません。{}の金額を指定してください。
直接的に記述する	LEGACYストア割り当てポリシーは、SparkデータソースV2では許可されていません。設定してください 構成spark.sql.storeAssignmentPolicyを他の値に。	SparkデータソースV2は、LEGACYストア割り当てポリシーを許可しません。構成spark.sql.storeAssignmentをANSIまたはSTRICTに設定してください。
ユーザー向けのエラーには、プログラミング用語を使用しない	RENAME TABLEのソースとデスティネーションのデータベースが一致しません：'{}'!='{}'。	RENAME TABLEのソースとデスティネーションのデータベースが一致しません。ソースデータベースは{}ですが、デスティネーションデータベースは{}です。