Signatur
Beschreibung
Die Klasse MongoDB\Driver\Exception\BulkWriteCommandException wird geworfen, wenn ein Bulk-Write-Befehl (z. B. über MongoDB\Driver\Manager::executeBulkWrite()) fehlschlägt. Sie erweitert MongoDB\Driver\Exception\ServerException und enthält neben der Fehlermeldung auch ein MongoDB\Driver\BulkWriteCommandResult-Objekt, über das detaillierte Informationen zu den erfolgreichen und fehlgeschlagenen Operationen abrufbar sind.
Im Gegensatz zur älteren BulkWriteException wird diese Exception bei Verwendung der neuen Bulk-Write-API (ab MongoDB 8.0 / PHPLIB 1.21) geworfen und bietet eine reichhaltigere Fehlerdiagnose. Sie enthält Informationen darüber, wie viele Dokumente erfolgreich eingefügt, aktualisiert oder gelöscht wurden, bevor der Fehler aufgetreten ist.
Typische Anwendungsfälle sind das Abfangen von Duplikat-Schlüssel-Fehlern (duplicate key errors), Validierungsfehlern auf der Serverseite oder Konflikten bei geordneten Bulk-Writes, bei denen die Verarbeitung nach dem ersten Fehler stoppt. Über getWriteResult() können die Teilergebnisse der Bulk-Operation ausgewertet werden.
Es empfiehlt sich, diese Exception gezielt zu fangen und das Write-Result auszuwerten, um eine differenzierte Fehlerbehandlung zu implementieren – zum Beispiel um festzustellen, welche Dokumente bereits erfolgreich geschrieben wurden, bevor der Fehler auftrat.
Beispiele
Duplikat-Schlüssel-Fehler bei Bulk-Write abfangen
<?php
use MongoDB\Driver\Manager;
use MongoDB\Driver\BulkWrite;
use MongoDB\Driver\Exception\BulkWriteCommandException;
$manager = new Manager('mongodb://localhost:27017');
$bulk = new BulkWrite(['ordered' => true]);
$bulk->insert(['_id' => 1, 'name' => 'Alice']);
$bulk->insert(['_id' => 1, 'name' => 'Bob']); // Duplikat-Schlüssel!
$bulk->insert(['_id' => 2, 'name' => 'Charlie']);
try {
$result = $manager->executeBulkWrite('testdb.users', $bulk);
} catch (BulkWriteCommandException $e) {
echo 'Bulk-Write-Fehler: ' . $e->getMessage() . PHP_EOL;
$writeResult = $e->getWriteResult();
echo 'Erfolgreich eingefügt: ' . $writeResult->getInsertedCount() . PHP_EOL;
foreach ($writeResult->getWriteErrors() as $writeError) {
echo 'Fehler bei Index ' . $writeError->getIndex()
. ': [' . $writeError->getCode() . '] '
. $writeError->getMessage() . PHP_EOL;
}
}Ungeordneten Bulk-Write mit Fehlerbehandlung ausführen
<?php
use MongoDB\Driver\Manager;
use MongoDB\Driver\BulkWrite;
use MongoDB\Driver\Exception\BulkWriteCommandException;
$manager = new Manager('mongodb://localhost:27017');
// Ungeordneter Bulk-Write: alle Operationen werden versucht, auch nach Fehlern
$bulk = new BulkWrite(['ordered' => false]);
$bulk->insert(['_id' => 10, 'value' => 'A']);
$bulk->insert(['_id' => 10, 'value' => 'B']); // Duplikat-Schlüssel
$bulk->insert(['_id' => 11, 'value' => 'C']); // Wird trotzdem versucht
try {
$manager->executeBulkWrite('testdb.items', $bulk);
} catch (BulkWriteCommandException $e) {
$writeResult = $e->getWriteResult();
echo 'Eingefügt: ' . $writeResult->getInsertedCount() . PHP_EOL;
echo 'Fehleranzahl: ' . count($writeResult->getWriteErrors()) . PHP_EOL;
foreach ($writeResult->getWriteErrors() as $error) {
echo ' - Fehler bei Index ' . $error->getIndex()
. ': ' . $error->getMessage() . PHP_EOL;
}
}// Wichtig · Fallstricke
Abgrenzung zu BulkWriteException: Die ältere MongoDB\Driver\Exception\BulkWriteException wird bei der Verwendung von MongoDB\Driver\BulkWrite mit der klassischen API geworfen. BulkWriteCommandException ist für die neuere API ab PHPLIB 1.21 / MongoDB-Treiber 1.21 vorgesehen und bietet ein überarbeitetes Result-Objekt.
Geordnete vs. ungeordnete Bulk-Writes: Bei geordneten Bulk-Writes (ordered: true) stoppt die Verarbeitung beim ersten Fehler. Bei ungeordneten Writes (ordered: false) werden alle Operationen versucht, und alle Fehler werden im Write-Result gesammelt. Das beeinflusst, wie viele Fehler getWriteErrors() zurückgibt.
Teilergebnisse: Auch wenn eine Exception geworfen wird, können über getWriteResult() wertvolle Teilergebnisse abgerufen werden. Diese sollten immer ausgewertet werden, um den tatsächlichen Zustand der Datenbank korrekt einzuschätzen.