Signatur
Beschreibung
Die Klasse BulkWriteException ist eine spezialisierte Exception, die der MongoDB-Treiber wirft, wenn eine oder mehrere Operationen innerhalb einer MongoDB\Driver\BulkWrite-Operation fehlschlagen. Sie erbt von MongoDB\Driver\Exception\WriteException und stellt über die Methode getWriteResult() detaillierte Informationen über das Ergebnis der Bulk-Operation bereit.
Im Gegensatz zu einfachen Write-Fehlern kann eine Bulk-Write-Operation teils erfolgreich und teils fehlerhaft sein. Die Exception ermöglicht es, das MongoDB\Driver\WriteResult-Objekt abzurufen und so zu analysieren, welche Schreibvorgänge erfolgreich waren und welche fehlgeschlagen sind – etwa durch Verletzung von Unique-Index-Constraints oder andere Serverfehler.
Typische Anwendungsfälle sind das massenhafte Einfügen, Aktualisieren oder Löschen von Dokumenten, bei denen einzelne Operationen fehlschlagen können, während andere erfolgreich durchgeführt werden. Mit der Option ordered: false beim Erstellen des BulkWrite-Objekts werden alle Operationen ausgeführt, auch wenn einzelne scheitern – die Exception wird erst am Ende geworfen.
Die Klasse implementiert das Interface MongoDB\Driver\Exception\Exception und kann wie jede andere PHP-Exception mit einem try/catch-Block abgefangen werden. Um alle Write-Fehler allgemein abzufangen, kann stattdessen auch die übergeordnete Klasse MongoDB\Driver\Exception\WriteException verwendet werden.
Beispiele
BulkWriteException bei doppeltem Unique-Index abfangen
<?php
use MongoDB\Driver\BulkWrite;
use MongoDB\Driver\Manager;
use MongoDB\Driver\Exception\BulkWriteException;
$manager = new Manager('mongodb://localhost:27017');
$bulk = new BulkWrite(['ordered' => false]);
$bulk->insert(['_id' => 1, 'name' => 'Alice']);
$bulk->insert(['_id' => 1, 'name' => 'Duplicate']); // Doppelter _id-Wert
$bulk->insert(['_id' => 2, 'name' => 'Bob']);
try {
$result = $manager->executeBulkWrite('testdb.users', $bulk);
echo 'Eingefügt: ' . $result->getInsertedCount() . PHP_EOL;
} catch (BulkWriteException $e) {
$writeResult = $e->getWriteResult();
echo 'Erfolgreich eingefügt: ' . $writeResult->getInsertedCount() . PHP_EOL;
echo 'Fehlermeldung: ' . $e->getMessage() . PHP_EOL;
foreach ($e->getWriteResult()->getWriteErrors() as $writeError) {
echo 'Fehler bei Index ' . $writeError->getIndex()
. ': ' . $writeError->getMessage() . PHP_EOL;
}
}Ordered Bulk Write mit teilweisem Fehler
<?php
use MongoDB\Driver\BulkWrite;
use MongoDB\Driver\Manager;
use MongoDB\Driver\Exception\BulkWriteException;
use MongoDB\Driver\Exception\Exception as MongoException;
$manager = new Manager('mongodb://localhost:27017');
// ordered: true (Standard) – stoppt beim ersten Fehler
$bulk = new BulkWrite(['ordered' => true]);
$bulk->insert(['_id' => 10, 'status' => 'ok']);
$bulk->insert(['_id' => 10, 'status' => 'doppelt']); // Schlägt fehl
$bulk->insert(['_id' => 11, 'status' => 'wird nicht ausgeführt']);
try {
$manager->executeBulkWrite('testdb.orders', $bulk);
} catch (BulkWriteException $e) {
$result = $e->getWriteResult();
echo 'Eingefügt vor Fehler: ' . $result->getInsertedCount() . PHP_EOL;
echo 'Anzahl Write-Errors: ' . count($result->getWriteErrors()) . PHP_EOL;
echo 'Exception-Code: ' . $e->getCode() . PHP_EOL;
} catch (MongoException $e) {
echo 'Anderer MongoDB-Fehler: ' . $e->getMessage() . PHP_EOL;
}// Wichtig · Fallstricke
Ordered vs. Unordered Bulk Writes: Bei ordered: true (Standard) wird die Ausführung beim ersten Fehler gestoppt – nachfolgende Operationen werden nicht mehr ausgeführt. Bei ordered: false werden alle Operationen versucht; die Exception wird erst am Ende der Ausführung geworfen und enthält alle aufgetretenen Fehler.
Partial Success: Das über getWriteResult() abrufbare MongoDB\Driver\WriteResult-Objekt enthält die Zähler für tatsächlich erfolgreich durchgeführte Operationen (getInsertedCount(), getModifiedCount(), getDeletedCount()). Diese sollten nach dem Abfangen der Exception ausgewertet werden, um den tatsächlichen Zustand der Datenbank zu ermitteln.
Write Concern Errors: Fehler, die durch das Write Concern entstehen (z. B. Replikations-Timeout), sind über getWriteResult()->getWriteConcernError() abrufbar und unterscheiden sich von regulären Write-Errors.