MongoDB\Driver\BulkWriteCommand — Klasse · PHP-Referenz

Signatur

class MongoDB\Driver\BulkWriteCommand

Beschreibung

MongoDB\Driver\BulkWriteCommand ermöglicht es, mehrere Schreiboperationen (Einfügen, Aktualisieren, Löschen) gesammelt als einen einzigen Befehl an den MongoDB-Server zu senden. Dies reduziert die Anzahl der Netzwerk-Roundtrips erheblich und verbessert die Performance bei Massenoperationen deutlich gegenüber einzeln ausgeführten Schreibbefehlen.

Im Unterschied zu MongoDB\Driver\BulkWrite (das mit Manager::executeBulkWrite() verwendet wird) ist BulkWriteCommand für die Verwendung mit dem neueren bulkWrite-Datenbankbefehl ausgelegt, der ab MongoDB 8.0 verfügbar ist. Er unterstützt Operationen über mehrere Collections innerhalb derselben Datenbank.

Schreiboperationen werden der Instanz sequenziell hinzugefügt und dann über MongoDB\Driver\Manager::executeBulkWriteCommand() ausgeführt. Das Ergebnis wird als MongoDB\Driver\BulkWriteCommandResult zurückgegeben, das detaillierte Informationen über die durchgeführten Operationen enthält.

Geordnete (ordered) Bulk-Writes stoppen die Ausführung beim ersten Fehler, während ungeordnete Bulk-Writes alle Operationen versuchen und Fehler am Ende melden. Dies kann über die Konstruktoroptionen gesteuert werden.

Parameter

Name	Typ	Default	Beschreibung
$options	array	[]	Optionales Array zur Konfiguration des Bulk-Write-Befehls. Unterstützte Schlüssel: `bypassDocumentValidation` (bool): Wenn `true`, wird die Dokumentvalidierung umgangen. `comment` (mixed): Ein beliebiger Kommentar für den Befehl (sichtbar in Logs und Profiler). `let` (array\|object): Definiert Variablen, die in Update- und Delete-Ausdrücken verwendet werden können. `ordered` (bool): Wenn `true` (Standard), werden Operationen geordnet ausgeführt und bei erstem Fehler abgebrochen. Bei `false` werden alle Operationen ausgeführt. `verboseResults` (bool): Wenn `true`, werden detaillierte Ergebnisse pro Operation zurückgegeben. `writeConcern` (`MongoDB\Driver\WriteConcern`): Das Write-Concern für die gesamte Operation.

Beispiele

Grundlegendes Bulk-Write mit Insert, Update und Delete

<?php
use MongoDB\Driver\BulkWriteCommand;
use MongoDB\Driver\Manager;

$manager = new Manager('mongodb://localhost:27017');

$bulk = new BulkWriteCommand(['ordered' => true]);

// Dokument einfügen
$bulk->insertOne('mydb.users', [
    'name' => 'Alice',
    'email' => 'alice@example.com',
    'active' => true
]);

// Dokument aktualisieren
$bulk->updateOne(
    'mydb.users',
    ['name' => 'Bob'],
    ['$set' => ['active' => false]]
);

// Dokument löschen
$bulk->deleteOne('mydb.users', ['active' => false]);

try {
    $result = $manager->executeBulkWriteCommand($bulk);
    echo 'Eingefügt: ' . $result->getInsertedCount() . PHP_EOL;
    echo 'Aktualisiert: ' . $result->getModifiedCount() . PHP_EOL;
    echo 'Gelöscht: ' . $result->getDeletedCount() . PHP_EOL;
} catch (MongoDB\Driver\Exception\BulkWriteCommandException $e) {
    echo 'Bulk-Write-Fehler: ' . $e->getMessage() . PHP_EOL;
}

Eingefügt: 1 Aktualisiert: 1 Gelöscht: 1

Ungeordneter Bulk-Write über mehrere Collections

<?php
use MongoDB\Driver\BulkWriteCommand;
use MongoDB\Driver\Manager;
use MongoDB\Driver\WriteConcern;

$manager = new Manager('mongodb://localhost:27017');

// Ungeordnet: Alle Operationen werden versucht, auch nach Fehlern
$bulk = new BulkWriteCommand([
    'ordered' => false,
    'writeConcern' => new WriteConcern(WriteConcern::MAJORITY, 1000),
]);

// Operationen in verschiedene Collections
$bulk->insertOne('mydb.orders', [
    'orderId' => 1001,
    'status' => 'pending',
    'total' => 49.99
]);

$bulk->insertOne('mydb.inventory', [
    'sku' => 'ABC-123',
    'quantity' => 50
]);

$bulk->updateMany(
    'mydb.orders',
    ['status' => 'pending'],
    ['$set' => ['status' => 'processed']]
);

$bulk->deleteMany('mydb.orders', ['status' => 'cancelled']);

try {
    $result = $manager->executeBulkWriteCommand($bulk);
    printf(
        "Eingefügt: %d, Aktualisiert: %d, Gelöscht: %d\n",
        $result->getInsertedCount(),
        $result->getModifiedCount(),
        $result->getDeletedCount()
    );
} catch (MongoDB\Driver\Exception\BulkWriteCommandException $e) {
    $writeResult = $e->getPartialResult();
    echo 'Teilweise ausgeführt. Eingefügt: ' . $writeResult->getInsertedCount() . PHP_EOL;
    echo 'Fehler: ' . $e->getMessage() . PHP_EOL;
}

Eingefügt: 2, Aktualisiert: 1, Gelöscht: 0

// Wichtig · Fallstricke

Versionsanforderung: BulkWriteCommand setzt MongoDB Server 8.0 oder neuer voraus, da es den bulkWrite-Datenbankbefehl verwendet. Bei älteren Server-Versionen sollte stattdessen MongoDB\Driver\BulkWrite verwendet werden.

Fehlerbehandlung: Bei geordneten Bulk-Writes (ordered: true) wird die Ausführung beim ersten Fehler abgebrochen. Bei ungeordneten Writes werden alle Operationen versucht. In beiden Fällen wird eine MongoDB\Driver\Exception\BulkWriteCommandException geworfen; über getPartialResult() lässt sich das teilweise Ergebnis abrufen.

Performance: Das Bündeln vieler Operationen in einem einzigen BulkWriteCommand ist deutlich effizienter als viele einzelne Befehle. Für sehr große Mengen sollte die maximale BSON-Dokumentgröße (16 MB) und das Limit von 100.000 Operationen pro Befehl beachtet werden.

Siehe auch

MongoDB\Driver\BulkWrite MongoDB\Driver\Manager::executeBulkWriteCommand MongoDB\Driver\BulkWriteCommandResult MongoDB\Driver\WriteConcern MongoDB\Driver\Exception\BulkWriteCommandException