MongoCollection::update

(PECL mongo >=0.9.0)

MongoCollection::update — Обновляет записи на основе заданных критериев

Описание

public MongoCollection::update ( array $criteria , array $new_object [, array $options = array() ] ) : bool|array

Список параметров

criteria

Критерии запроса документов для обновления.

new_object

Объект, используемый для обновления сопоставленных документов. Может содержать операторы обновления (для изменения определенных полей) или документ замены.

options

Массив опций для операции обновления. В настоящее время доступны следующие варианты:

  • "upsert"

    Если ни один документ не соответствует $criteria, будет добавлен новый документ.

    Если новый документ будет вставлен, а $new_object содержит атомарные модификаторы (то есть операторы $), эти операции будут применены к параметру $criteria для создания нового документа. Если $new_object не содержит атомарных модификаторов, он будет использоваться как есть для вставленного документа. Смотрите приведенные ниже примеры для получения дополнительной информации.

  • "multiple"

    Все документы, соответствующие $criteria, будут обновлены. MongoCollection::update() имеет совершенно противоположное поведение MongoCollection::remove(): он обновляет один документ по умолчанию, а не все соответствующие документы. Рекомендуется всегда указывать, хотите ли вы обновить несколько документов или один документ, поскольку база данных может изменить свое поведение по умолчанию в какой-то момент в будущем.

  • "fsync"

    Булево, по умолчанию FALSE. Если включено журналирование, то работает также как и "j". Если журналирование не включено, то операции записи блокируются пока не будут синхронизированы с файлами на жестком диске. Если TRUE, то применяется подтвержденная вставка и эта опция переопределяет опцию "w" в значение 0.

    Замечание: Если журналирование включено, то пользователю настоятельно рекомендуется использовать опцию "j" вместо "fsync". Не используйте "fsync" и "j" одновременно,так как это может привести к ошибке.

  • "j"

    Булево, по умолчанию FALSE. Блокирует операции записи пока они не будут синхронизированы с журналом на диске. Если TRUE, то применяется подтвержденная вставка и эта опция переопределяет опцию "w" в значение 0.

    Замечание: Если применяется эта опция и журналирование отключено, то MongoDB 2.6+ выбросит ошибку и прервет запись; старые версии сервера просто игнорируют эту опцию.

  • "socketTimeoutMS"

    Эта опция определяет время в миллисекундах для общения в socket. Если сервер не ответил за отведенное время, то будет брошено исключение MongoCursorTimeoutException, и не будет никакой возможности определить произвел ли сервер запись или нет. Значение -1 используется для постоянно отключения этой функции. Значением по умолчанию для MongoClient является 30000 (30 секунд).

  • "w"

    Смотрите Контроль записи. Значение по умолчанию для MongoClient является 1.

  • "wTimeoutMS"

    Эта опция определяет лимит времени в миллисекундах для подтверждения контроля записи. Она применима только, если "w" больше 1, так как ограничение времени относится к репликации. Если контроль записи не подтвержден за отведенное время, то будет выброшено исключение MongoCursorException. Значение 0 для постоянного отключения. Значением по умолчанию для MongoClient является 10000 (десять секунд).

Следующие параметры устарели и больше не должны использоваться:

  • "safe"

    Устаревшая опция. Используйте опцию "w" контроля записи.

  • "timeout"

    Устаревший псевдоним для "socketTimeoutMS".

  • "wtimeout"

    Устаревший псевдоним для "wTimeoutMS".

Возвращаемые значения

Возвращает массив, содержащий состояние обновления, если установлена опция "w". В противном случае возвращает TRUE.

Поля в массиве статуса описаны в документации к MongoCollection::insert().

Ошибки

Исключение MongoCursorException бросается, если установлена опция "w" и не прошла запись.

Исключение MongoCursorTimeoutException бросается, если опция "w" установлена в значение больше одного и операция заняла больше, чем MongoCursor::$timeout миллисекунд. При этом операция на сервере не прерывается, так как это ограничение времени работает на клиентской стороне. Операция в миллисекундах в MongoCollection::$wtimeout.

Список изменений

Версия Описание
1.5.0

Добавлена опция "wTimeoutMS", которая заменяет "wtimeout". Выдает E_DEPRECATED, когда используется "wtimeout".

Добавлена опция "socketTimeoutMS", которая заменяет "timeout". Выдает E_DEPRECATED, когда используется "timeout".

Выдает E_DEPRECATED, когда используется "safe".

1.3.4 Добавлена опция "wtimeout".
1.3.0

Добавлена опция "w".

Параметр options больше не принимает логическое значение для обозначения слияния. Вместо этого теперь необходимо указывать array('upsert' => true).

1.2.11 Выдает E_DEPRECATED, когда options являются scalar.
1.2.0 Добавлена опция "timeout".
1.0.11 Отключается при ошибках "not master", если установлен "safe".
1.0.9

Добавлена возможность передавать целые числа в опцию "safe", которая ранее принимала только логические значения.

Добавлена опция "fsync".

Тип возвращаемого значения был изменен на массив, содержащий информацию об ошибке, если используется параметр "safe". В противном случае логическое значение возвращается, как и раньше.

1.0.5 Добавлена опция "safe".
1.0.1 Изменен параметр options с логического на массив. До версии 1.0.1 вторым параметром было необязательное логическое значение, определяющее слияние.

Примеры

Пример #1 Пример использования MongoCollection::update()

Добавление адресного поля в документ.

<?php

$c->insert(array("firstname" => "Bob", "lastname" => "Jones" ));
$newdata = array('$set' => array("address" => "1 Smith Lane"));
$c->update(array("firstname" => "Bob"), $newdata);

var_dump($c->findOne(array("firstname" => "Bob")));

?>

Результатом выполнения данного примера будет что-то подобное:

array(4) {
  ["_id"]=>
  object(MongoId)#6 (0) {
  }
  ["firstname"]=>
  string(3) "Bob"
  ["lastname"]=>
  string(5) "Jones"
  ["address"]=>
  string(12) "1 Smith Lane"
}

Пример #2 Пример использования слияния MongoCollection::update()

Слияние может упростить код, так как одна строка может создать документ, если он не существует (на основе $criteria), или обновить существующий документ, если он соответствует.

В следующем примере $new_object содержит атомарный модификатор. Поскольку коллекция пуста и слияние должно вставить новый документ, он будет применять эти операции к параметру $criteria для создания документа.

<?php

$c->drop();
$c->update(
    array("uri" => "/summer_pics"),
    array('$inc' => array("page hits" => 1)),
    array("upsert" => true)
);
var_dump($c->findOne());

?>

Результатом выполнения данного примера будет что-то подобное:

array(3) {
  ["_id"]=>
  object(MongoId)#9 (0) {
  }
  ["uri"]=>
  string(12) "/summer_pics"
  ["page hits"]=>
  int(1)
}

Если $new_object не содержит атомарных модификаторов (то есть операторов $), слияние будет использовать $new_object как есть для нового документа. Это соответствует поведению обычного обновления, когда отсутствие атомарных модификаторов приводит к перезаписи документа.

<?php

$c->drop();
$c->update(
    array("name" => "joe"),
    array("username" => "joe312", "createdAt" => new MongoDate()), 
    array("upsert" => true)
);
var_dump($c->findOne());

?>

Результатом выполнения данного примера будет что-то подобное:

array(3) {
  ["_id"]=>
  object(MongoId)#10 (0) {
  }
  ["username"]=>
  string(6) "joe312"
  ["createdAt"]=>
  object(MongoDate)#4 (0) {
  }
}

Пример #3 Пример использования множественного MongoCollection::update()

По умолчанию MongoCollection::update() обновляет только первый документ, соответствующий $criteria, которые он находит. Использование опции "multiple" может переопределить это поведение, если это необходимо.

В этом примере поле "gift" добавляется каждому человеку, у которого день рождения на следующий день.

<?php

$today = array('$gt' => new MongoDate(), '$lt' => new MongoDate(strtotime("+1 day")));
$people->update(
    array("birthday" => $today),
    array('$set' => array('gift' => $surprise)),
    array("multiple" => true)
);

?>