Updating Data (replace)

replace is ObjectQuel's bulk, set-based update statement — QUEL's update verb, run directly against the database through the same EntityManager::executeQuery() entry point as retrieve and the DDL statements on Creating, Altering & Destroying Tables & Indexes. It bypasses the identity map and change tracking entirely. If you need entity lifecycle behavior — cascades, events, per-object optimistic-lock exceptions — use persist()/flush() instead. See also append, delete, and upsert.

explanation

Updating Data with replace

replace is QUEL's update verb — an assignment list plus a mandatory where clause that always scopes which rows are affected, unlike retrieve, which can omit where to mean the whole table: 

$result = $entityManager->executeQuery('
    range of u is App\Entities\UserEntity
    replace u (password = :password) where u.id = :id
', ['password' => 'newpass', 'id' => $id]);

$result->getAffectedRows(); // number of rows updated

Assign several properties in one statement, and reference another column of the same row on the right-hand side of an assignment:

$entityManager->executeQuery('
    range of u is App\Entities\UserEntity
    replace u (password = :password, banned = true) where u.id = :id
', ['password' => 'pw2', 'id' => $id]);

$entityManager->executeQuery('
    range of u is App\Entities\UserEntity
    replace u (username = concat(u.username, "!")) where u.id = :id
', ['id' => $id]);
An entity property backed by @Orm\Version is bumped by replace the same way flush() bumps it for a managed entity — see Optimistic Locking.

Working with the Result

replace returns a QuelResult with no fetchable rows — getAffectedRows() is the accessor that matters here, in place of iterating the result the way a retrieve result is iterated. getGeneratedId() is always null for replace; see append for statements where it's populated.

Scope & Limitations

  • replace targets a single declared range — no join across multiple ranges (no UPDATE ... FROM ...-style form).
  • replace's where is mandatory; there is no "affects every row" shorthand.