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)
);

?>

add a note

User Contributed Notes 8 notes

down

nerds at limeworks dot com dot au ¶

13 years ago


For anyone referencing records by the Mongo _id object, it's important to recognise that it is in fact an object, and not a string. 

If you have a record with a Mongo ID of say "4e519d5118617e88f27ea8cd" that you are trying to retrieve or update, you cannot search for it using something like:
<?php
$m = new Mongo();
$db = $m->selectDB('db');
$collection = 'collection';
$db->$collection->findOne(array('_id', '4e519d5118617e88f27ea8cd'));
?>

There is some documentation that mentions simple conversion to string will solve this, but I have found the only reliable way to locate records based on their ID is to first pass it to MondoID(), then use that for reference.

Something like this will be far more reliable:
<?php
$m = new Mongo();
$db = $m->selectDB('db');
$collection = 'collection';
$mongoID = new MongoID('4e519d5118617e88f27ea8cd');
$db->$collection->findOne(array('_id', $mongoID));
?>

This may prove useful for anyone using the ID object like an auto-increment database key would be used in MySQL or similar.

down

joshuadburns at hotmail dot com ¶

13 years ago


Please note under optional third parameter "options":

While the official MongoDB documentation references the keyword "multi" to flag the use of multiple updates, the PHP implementation uses the key "multiple" instead.

This may cause a little confusion if you're basing your keys on the OFFICIAL MongoDB documentation.

down

Vasiliy Makogon ¶

11 years ago


if you want emulate on mongoDb "insert on duplicate key update" in SQL notation, you must use flag "upsert" with "$set" in "update" operation.



In this sample uses unique key (user id and product id) and date user visit  product:page. Each execute this code make update 'lasttime' field:



<?php

$client = new \MongoClient(MONGO_DB);

$users = $client->users;

$last_views = $users->createCollection('last_views');

// create unique index

$result = $last_views->ensureIndex(

    array("user_id" => 1, "warecode" => 1),

    array("unique" => 1)

);



$uviews = new \stdClass();

$uviews->user_id = $this->user_id;

$uviews->warecode = $this->warecode;



$res = $users->last_views->update(

    $uviews, 

    array('$set' => array('lasttime' => new \MongoTimestamp())),

    array('upsert' => true)

);

?>

down

jeff at canuckistani dot ca ¶

14 years ago


The return type of update changed in 1.09 if you are using safe => TRUE. It now returns something that looks like the info returned by MongoDB::lastError:

Array
(
    [err] => 
    [updatedExisting] => 1
    [n] => 1
    [ok] => 1
)

down

bronius at bcswebstudio dot com ¶

10 years ago


Re. nerds @ limeworks comment: 
Thanks for your helpful tip - right what I was looking for.  One note, though: Instead of comma, it's a => as in:
<?php
...->findOne(array('_id' => $mongoID);
?>

down

-3

rithish[at]gmail[dot]com ¶

14 years ago


Do note, for incrementing a value using $inc, typecast the value to an integer before passing the new object to update().



<?php

$votes = (int) $votes;

$newData = array('$inc' => array('votes'=>$votes));

$c->update(array("firstname" => "Bob"), $newData);

?>



This is especially noteworthy, if you are taking values from $_GET and pushing them for increment.

down

-3

bradzo0647 at gmail dot com ¶

10 years ago


A need for an app was to add a new entry to the industries collection if it didn't already exist, and pass that "string" _id back to the caller to add it to the businesses collection (as a string also - database design by others.... :))

function GetIndustryID($db, $industry_name_eng, $industry_name_rus) {

// $db is the MongoDB database object
// $industry_name_eng is English of the industry name
// $industry_name_rus is Russian of the industry name

    if ( $industry_name_eng == "" && $industry_name_rus == "" ) {
        return "";
        exit;
    }
    
    // lookup russian version
    // of industry name from industries collection and try to return the _id
   
    // if not found, add this as a new document and return its _id

        // $c_ind = industry collection object
        // "industries" is the collection name

    $c_ind = $db->industries;

// you could use findOne here....
    $cursor = $c_ind->find(array('industry_name.russian' => $industry_name_rus));

    if ( $cursor->hasNext() ) {
        foreach ( $cursor as $document ) {          
            $id = $document['_id'];
        }
    } else {
        // not found here - go add it
        $document = array(
            "industry_id" => "",
            "industry_name" => array("english" => $industry_name_eng, "russian" => $industry_name_rus )
        );
        $db->industries->insert($document);
        $id = $document['_id'];    
        
        // update the industry_id in the industries collection
        // with the id returned - because we just added it, and
        // we need the industry_id the same as the _id
        
        // see: http://php.net/manual/en/mongocollection.update.php
        
        // update ( array $criteria , array $new_object [, array $options = array() ] )

                // note how I cast the MongoID "object" to a string
        $document['industry_id'] = (string)$id;
                // the $id in the next line is the ObjectID, not a string.
        $db->industries->update(array("_id" => $id), $document, array("upsert" => true));
    }
   
    return (string)$id;
               
}

Results: (using RoboMongo)
{
    "_id" : ObjectId("5427acf7a495dbd420b2e2ea"),
    "industry_id" : "5427acf7a495dbd420b2e2ea",
    "industry_name" : {
        "english" : "Oil and Gas",
        "russian" : "Нефть, Газ, Энергетика"
    }
}

It took me ages to work this out. Hope it helps someone else.

down

-5

Nanhe Kumar ¶

8 years ago


$inc and set in one statement
<?php
    $m = new Mongo();
    $db = $m->selectDB('db');
    $collection = 'collection';
    $db->$collection->insert(array("firstname" => "Nanhe", "lastname" => "Kumar","attempt"=>1 ));
    $newdata = array('$inc'=>array("attempt"=>1),'$set' => array("address" => "Delhi India"));
    $db->$collection->update(array("firstname" => "Nanhe"), $newdata);
?>

add a note

MongoCollection::update

Описание

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

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

Ошибки

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

Примеры

Смотрите также

User Contributed Notes 8 notes