FireDAC: Array DMLを用いたバルク挿入と行単位の堅牢なエラーハンドリング

Ein BDE-Ablosung mit nativer Anbindung Bulk-Insert mit Array DML ist oft der schnellste Weg, um viele Datensätze in eine Datenbank zu bekommen: statt tausend einzelner Inserts wird ein Parameter-Array gebunden und in einem Rutsch an den Server geschickt. In der Praxis kommt der Knackpunkt aber schnell: Ein Datensatz verletzt einen Unique-Index, ein NOT NULL-Feld ist leer, ein Foreign Key passt nicht – und plötzlich ist unklar, welche Zeile das Batch gekillt hat, ob ein Teil schon geschrieben wurde und wie du sauber weitermachst, ohne Dateninkonsistenzen zu erzeugen.

Genau darum geht es hier: Wie du Array DML so einsetzt, dass du pro Zeile belastbare Fehlerinfos bekommst, die Transaktion im Griff behältst und im Betrieb nachvollziehen kannst, was passiert ist. Der Fokus liegt nicht auf akademischer API-Lektüre, sondern auf dem Randfall, der in echten Importen regelmäßig aufschlägt: Ein großer Batch, wenige kaputte Zeilen, aber du willst trotzdem Tempo.

FireDAC Bulk-Insert mit Array DML: Warum Array DML beim Bulk-Insert überhaupt lohnt

Array DML (Data Manipulation Language) bedeutet in FireDAC: Du bindest Parameter nicht als Einzelwert, sondern als Array. FireDAC sendet dann (je nach Treiber/DB) weniger Roundtrips, kann serverseitig effizienter arbeiten und reduziert den Overhead im Client drastisch. Das ist in drei Situationen besonders relevant:

• ETL- und Importstrecken: CSV/XML/JSON rein, Normalisierung/Mapping, dann in Staging- oder Zieltabelle.
• Schnittstellen-Puffer: REST- oder MQ-Payloads werden gesammelt und periodisch persistiert.
• Protokoll-/Event-Tabellen: viele kleine Inserts, bei denen Latenz dominiert.

Der Gewinn kommt aber nicht gratis. Mit Array DML verschiebst du Komplexität von „viele einzelne Statements“ zu „ein Statement mit vielen Zeilen“. Das ist gut für Performance, aber anspruchsvoller für Fehlerdiagnose, Transaktionslogik und Wiederanlauf.

Der typische Randfall: Ein Batch, eine kaputte Zeile

Der Klassiker im Betrieb: Du importierst 50.000 Zeilen. Du wählst eine ArraySize von 1.000, weil du nicht für jede Zeile einen Roundtrip willst. Batch 17 scheitert. Die DB meldet nur „duplicate key“ oder „violates foreign key constraint“. In der UI oder im Service-Log steht dann oft nur: „ExecSQL failed“.

Ohne sauberes Error-Handling passieren dann meist zwei schlechte Dinge:

• Du wirfst den ganzen Batch weg, obwohl 999 von 1.000 Zeilen ok wären.
• Du fällst auf Einzel-Inserts zurück und verlierst den Performancevorteil dauerhaft.

目指すのは第三の道です: バッチのパフォーマンスを維持しつつ、不具合を正確に（行インデックス、キー値、DBエラーテキスト）記録し、必要に応じて「正常な行」をコミットする — これはプロセスにおける整合性と冪等性（同一処理を複数回実行しても重複した効果が発生しないこと）がどれほど重要かに依存します。

FireDAC Array DML: 関連する調整項目（神話抜き）

Bulk-Insert を Array DML で行う際に実務で常に決定的になる調整項目は概ね同じです:

1) ArraySize とバッチサイズ

ArraySize（TFDQuery/TFDCommand 使用時）は、1 回の呼び出しで処理する「行」FireDAC の数を決定します。大きければ必ずしも良いというわけではありません。大きすぎるとクライアント側のメモリ増、ネットワーク上のペイロード増、サーバ側のロックやログ負荷増、障害時の影響範囲（影響範囲の拡大）を招きます。堅牢なインポートでは、列数、BLOB の有無、レイテンシに依存しますが、200〜2,000 のバッチサイズが実務上の出発点として有効なことが多いです。

2) トランザクションの境界

明確に決める必要があります: バッチごとにコミットするか、あるいは インポート全体を通してコミットを遅らせるか。これは好みの問題ではなく運用上の判断です:

• バッチごとにコミット: ロックとトランザクションログの範囲を限定でき、再実行が容易ですが、途中の状態が見える（Isolation Level に依存）ため、バッチ17でエラーが起きてもバッチ1〜16はシステムに残ります。
• 最後にコミット: 「全てか無か」の振る舞いで、業務的に一貫した状態を保証しますが、大量データでは長時間のロックや大きなロールバックリスクがあり、エラー時にはすべてが失われる可能性があります。

多くのインターフェースやインポート処理では、運用上より現実的なのは「バッチごとにコミット」です — ただし、これは冪等性や重複対策（自然キー、アップサート、インポートID 等）を確実に設計している場合に限ります。

3) UpdateOptions と Prepared Statements

繰り返しバッチを実行する場合、ステートメントを準備したままにしておく価値があります。「Prepare」とは: FireDAC が DB に対してステートメントをパース／コンパイルさせ、それを再利用させることを意味します。DB によってはこれが顕著な効果をもたらします。重要なのは「手抜きの小技」ではなく、同一の Query オブジェクト（または同一の TFDCommand）を一貫して再利用し、パラメータ型を安定させることです。

行単位の適切なエラーハンドリング: 本当に必要なもの

「行ごと」にエラーを扱いたいなら、次の三つが必要です:

1. 割り当て: どの Array インデックス (0..N-1) が失敗したか？
2. コンテキスト: その行の業務的なキー値は何か（例: 外部 ID、顧客番号、タイムスタンプ）？
3. 制御: その後どうするか？中断するか、問題のある行だけスキップするか、バッチを分割するか？

FireDAC はドライバによっては各配列要素ごとのエラー情報を返すことがありますが、実務では「常にそうだ」とは限りません。あるデータベースやプロバイダは最初のエラーしか報告しない、あるいはバッチ内のエラーで残りの処理を実行しないこともあります。だからこそ、堅牢なパターンは多くの場合 二段階です:

• 段階 A: まずバッチを Array DML で試行する。
• 段階 B: バッチが失敗したら、それを分割（半分にする等）するか、あるいはそのバッチに限り単一行処理へ落とし込む — その上できちんとログを残す。

手間が増えるように聞こえますが、インポートの現場では「深夜2時にすべてが停止する」か「インポートは継続し、7 行だけがエラー一覧に載る」かの差を生みます。

実務に使えるパターン: まずバッチ、次に狙いを定めて切り分ける

以下のパターンは、データ品質が混在するプロセス密接型ソフトウェアソリューションで有効であることが実証されています：

ステップ1: データをバッチ構造に格納する（エラーコンテキストを含む）

インポートするデータを単に生の値として保存するのではなく、最小限のコンテキストとともに保存してください: 外部ID、ソースの行番号、場合によってはハッシュ/チェックサム。これは「あると便利」ではありません。エラー発生時に、何が壊れているかを確認するためだけに再度CSVをパースしたくないはずです。

ステップ2: Array DML を実行する

ArraySize をバッチ長に設定し、パラメータを配列としてバインドして ExecSQL を実行します。重要なのはパラメータ型を安定させることです（例：数値フィールドを時々文字列、時々整数としてバインドしない）。そうしないと、DB が暗黙のキャストを行うか、または FireDAC が要素ごとに変換しなければならなくなります。

ステップ3: エラー時 — 無差別に繰り返すのではなくバッチを絞る

ExecSQL が失敗した場合、堅牢な選択肢が二つあります:

• Binary Split（半分に分割）: バッチを二つに分割し、それぞれを再度 Array DML として試行します。これを繰り返して、個別に確認できる程度の小さな量になるまで続けます。利点: 壊れている行が少数の場合、高い性能を保てます。欠点: ロジックが増えること、そしてデータ型の不一致などの体系的なエラーにはほとんど効果がありません。
• Fallback auf Einzelzeilen（当該バッチで単一行にフォールバック）: ArraySize=1 に設定する（または単一値をバインドする）ことで行ごとに実行し、エラーをログに記録して処理を継続します。利点: シンプルで各行ごとの確実な処理。欠点: そのバッチ内ではスループットが低下します。

実務では両方を組み合わせます: まず1〜2回分割して「良いブロック」を迅速に通し、その後小さな残りに対しては個別行モードに切り替えて明確なエラー情報をログします。

エラーオブジェクトとメッセージ: FireDAC から抽出すべき項目

FireDAC は DB エラーを詳細情報付きの例外（典型的には EFDDBEngineException）としてカプセル化します。運用上は三つのレベルが重要です:

• DBエラーコード（DB固有）: 例: PostgreSQL の SQLSTATE、SQL Server の Error Number。
• 制約／オブジェクト名: エラーテキストに含まれていることが多い（Unique インデックス、FK 制約など）。
• ステートメントのコンテキスト: テーブル、操作、必要に応じてパラメータ値（個人データには注意）。

行単位でログを取りたい場合、エラー発生時にどの行かを特定する必要があります。FireDAC は場合によって配列インデックスを返すことがありますが、それだけに頼らないでください。必ず独自のインデックス（バッチ内の位置）を用意し、その位置に対して少なくとも1つの業務上のキーをログしてください。

実際のインポートで時間を浪費する落とし穴

1) 「たった一行だけだった」—しかしトランザクションは既に „dirty“

DB やドライバによっては、エラーが発生するとステートメント実行全体が失敗扱いとなり、トランザクションが明示的にロールバックしないといけない状態になる、または以降のステートメントが失敗する状態になることがあります。特に一部のドライバでは「エラー後にそのまま続行する」は安全な前提ではありません。

結果として: トランザクション内で作業していてバッチが失敗した場合、標準的な対応は現在のバッチコンテキスト（またはトランザクション全体）のロールバックを行い、再試行することです。これは「バッチごとにコミットする」という方針に適しています。

2) Autocommit と 明示的トランザクション

明示的なトランザクションを開始しない場合、どのようにステートメントがコミットされるかは多くの場合ドライバ/プロバイダに委ねられます。バルクインポートではそれは望ましくないことが多いです。明示的トランザクションは以下を制御できます:

• ロックの保持期間
• ロールバックの挙動
• 再試行ポイント

そして: 明示的というのは「巨大なトランザクション」という意味ではない。意味するのは「意図的に」である。

3) トリガー、制約、そして副作用

Array DMLはデータ渡しを高速化するが、サーバー側の処理自体を自動的に高速化するわけではない。ターゲットテーブルにトリガーがある場合（例: 監査ログ、ステータス自動計算など）、ボトルネックはInsertではなくトリガーコードであることがある。その場合、バッチはラウンドトリップを減らせても、DBサーバー上のCPUが制約要因のままである。

管理者および技術責任者向け: パフォーマンス問題では Wait Events/Locks とトランザクションログの確認が有効である。Bulk-Insertはそのきっかけにすぎず、根本原因とは限らない。

4) データ型と暗黙の変換

「なぜ遅いのか？」で最も多い原因の一つは、パラメータが文字列としてバインドされ、DBが行ごとにInteger/Date/Decimalへキャストしていることだ。これは見えにくいが高コストである。安定した性能のために:

• パラメータのデータ型を適切に設定する（日時は日時、数値は数値として）。
• Decimal系はロケールの落とし穴に注意（カンマとピリオド）。FireDAC は通常ここで正しいが、混在ソースは問題になる。
• タイムゾーン/UTC戦略を事前に決める（インポート時のタイムスタンプは典型例）。

5) エラーメッセージは人間向けであり、自動化には適さない

エラーメッセージをパースして処理する（「duplicate key value violates unique constraint …」のように）ことは誘惑的だが、それは最後の手段としてのみ行うべきである。より良いのは構造化されたコード（SQLSTATE、Error Number）である。ただしドライバによっては情報の出し方が異なるため、コードとテキストの両方を考慮し、オプションで「制約名をテキストから抽出する」程度に留め、厳密な依存は避ける設計にすること。

デバッグのヒント: 壊れた行を素早く特定する方法

バッチを再現可能にする

インポートが断続的に失敗する場合は再現性が必要である。バッチごとに小さな診断ファイルやログエントリを保存し、以下を含めるとよい:

• バッチ番号と時刻
• ArraySize とトランザクションモード
• バッチ内の業務キー一覧（例: 外部ID）

これで多くの場合、後でこれらのIDだけを対象にしたミニインポートを実行して原因を絞れる。

最終的な SQL を可視化する（ただしデータ漏洩なく）

デバッグ時に知りたいのは、SQLが正しいか、パラメータが正しいか、という点である。FireDAC は FDMoniコンポーネントやドライバーロギングを通じたモニタリング/トレース機能を提供する。ほぼ本番に近い環境では、次を守ることが重要である:

• Tracingは性能とデータ保護のため、明確に限定して一時的にのみ有効化すること。
• パラメータ値は安全な環境でのみ、あるいはマスクしてログに残すこと。
• 個人データを扱う場合は、ログには技術的キー（ID）のみを残し、平文の内容は記録しないこと。

スプリットテストを行う場合: 中止基準を定義する

バイナリ分割（Binary Split）では無限に分割したくない。下限を設定し、例えば「20行未満なら単一行モードに切り替える」とする。また、インポートを中止するまでに許容するエラー総数（例: マッピングに系統的な問題がある場合）に上限を設けること。これをしないと終わりのないエラー一覧に陥り、後続処理が停止する。

いつこの労力をかける価値があるか（いつはないか）

1行ごとのエラーハンドリングを伴う Array DML は、特に次の場合に有効である:

• 多数の行が処理される（数千〜数百万）。
• 少数の行がエラーであっても処理を継続したい場合。
• 稼働中のインポートが安定して動作する必要がある（例: 夜間処理、UIのないサービス）。
• 業務部門やデータ提供元へ行単位のエラー一覧を返却する必要がある場合（行参照付き）。

次の場合はあまり有益ではありません：

• 数十行程度しか挿入しない場合（単一インサートは問題ありません）、
• データ品質が非常に低く、行の30〜50%が失敗する場合（その場合はステージング戦略の方が適切です）、
• 既にDBネイティブのバルクロード手法を使っている場合（例: COPY in PostgreSQL、BCP/BULK INSERT in SQL Server）—その場合はArray DMLは適切な手段ではありません。

代替アーキテクチャ: ステージングテーブル（「直接ターゲットへ」ではなく）

定期的に混在したデータ品質に悩まされる場合、単純に「対象テーブルへ直接INSERT」するのは多くの場合誤った判断です。ステージングテーブル（前段）は、データをまず技術的に正しく保存するためのテーブル（必要に応じて緩い型で保持）であり、その後に検証して対象テーブルへ移行します。

運用上の利点：

• 不正なデータ行は追跡可能な形で保存される（生データを含む）。
• 検証を分離して繰り返し実行できる。
• インターフェース受け入れと業務処理を切り離せる。

多くの場合、Array DMLはステージングテーブルへの高速な投入手段となり、対象テーブルへの移行はセットベースのSQL（またはストアドプロシージャ）で行います。これによりエラー処理がDB側に大きく移るため、組織（DBAの役割、デプロイ方式）によっては望ましい場合と望ましくない場合があります。

運用と管理: ITリードや管理者が知っておくべきこと

モニタリング: エラー率とスループットが主要指標

バルクインポートの安定稼働には、単に「実行時間」だけでなく以下の2つの指標が有益です：

• スループット: 分あたり（またはバッチあたり）の行数、ピーク/中央値を含む。
• エラー率: 実行あたりのエラー行数。理想的にはエラー種別（Unique、FK、NOT NULL、型の不整合）で分類する。

これら2つの値を定期的に確認していれば、ソース側での変更（例: 新フォーマット）やターゲット側の制約強化（例: 新しいConstraints）を早期に検知できます。

ロックと負荷ウィンドウ

バルクインサートはロックやIO負荷を発生させます。並行してユーザーが同じテーブルを操作する場合は、Isolation Level、インデックス、必要に応じてパーティショニングを検討する必要があります。実務的には、インポートを負荷の低い時間帯に行うか、稼働中のシステムと共存できるようにデータフローを設計する（例: ステージング＋非同期取り込み）ことになります。

Array DMLを用いた堅牢なバルクインサートのための具体的チェックリスト

• バッチサイズを設定する（初期値500〜1,000）および測定に基づきチューニングする。
• 明示的トランザクション: デフォルトはバッチ毎にコミット。「最後にまとめてコミット」は意図的な場合のみ選択する。
• パラメータ型を安定させる: 暗黙のキャストを強制しない。
• 各レコードごとのエラーコンテキストを保持する（外部ID、ソース行など）。
• エラー戦略: まずバッチ単位で処理し、必要に応じて分割/フォールバック、行単位でログを残す。
• ログ: コードとテキストを記録する。ただしデータ保護に準拠すること。バッチIDと実行IDを記録する。
• リトライ（再実行）: 冪等性を確保する（キー/Upsert/インポートID）。

結論: Array DMLは高速だが、堅牢にするにはプロセスとエラー戦略が必要

Array DMLを用いたFireDACバルクインサートは、エラーが存在しないかのように振る舞わない限り強力な手段です。実運用のデータストリームには常に例外が含まれます：重複、参照の欠落、不正な日付値など。したがって適切なアプローチは、パフォーマンスのためのArray DMLと、制御された分離戦略（SplitまたはFallback）および行単位で追跡可能なエラーリストの組み合わせです。これによりパフォーマンスと運用の確実性を両立でき、インポートがラボだけでなく毎晩確実に実行される必要がある状況で真価を発揮します。

既存のインポートやインターフェースプロセスを Delphi/FireDAC で安定化させたい（パフォーマンス、トランザクション、再実行、ロギング）場合は、技術的な面談で構造的に整理して確認します：

このテーマでは、Delphi Bulk Insert と Bulk Insert Delphi FireDAC も重要です。この記事はこれらの観点を分かりやすく整理し、日常運用で何に注意すべきかを示します。

Net-Base とプロジェクトやモダナイゼーション案件について相談する.