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.

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

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

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

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

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

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

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

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

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

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

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

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

PECL mongo 1.0.5 Добавлена опция "safe".
PECL mongo 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)
);

?>

© 2008—2024 «phpm.ru | Документация и сервисы»       PHP | MySQL | Smarty | PEAR | PHP-GTK | Типограф | Сокращатель ссылок