Php/docs/mongocollection.update
MongoCollection::update
(PECL mongo >=0.9.0)
MongoCollection::update — Update records based on a given criteria
说明
public MongoCollection::update
( array $criteria
, array $new_object
[, array $options
= array()
] ) : bool|array
参数
criteria
Query criteria for the documents to update.
new_object
The object used to update the matched documents. This may either contain update operators (for modifying specific fields) or be a replacement document.
options
An array of options for the update operation. Currently available options include:
"upsert"
If no document matches
$criteria
, a new document will be inserted.If a new document would be inserted and
$new_object
contains atomic modifiers (i.e.$
operators), those operations will be applied to the$criteria
parameter to create the new document. If$new_object
does not contain atomic modifiers, it will be used as-is for the inserted document. See the upsert examples below for more information."multiple"
All documents matching $criteria will be updated. MongoCollection::update() has exactly the opposite behavior of MongoCollection::remove(): it updates one document by default, not all matching documents. It is recommended that you always specify whether you want to update multiple documents or a single document, as the database may change its default behavior at some point in the future.
"fsync"
Boolean, defaults to
false
. If journaling is enabled, it works exactly like"j"
. If journaling is not enabled, the write operation blocks until it is synced to database files on disk. Iftrue
, an acknowledged insert is implied and this option will override setting"w"
to0
.Note: If journaling is enabled, users are strongly encouraged to use the
"j"
option instead of"fsync"
. Do not use"fsync"
and"j"
simultaneously, as that will result in an error."j"
Boolean, defaults to
false
. Forces the write operation to block until it is synced to the journal on disk. Iftrue
, an acknowledged write is implied and this option will override setting"w"
to0
.Note: If this option is used and journaling is disabled, MongoDB 2.6+ will raise an error and the write will fail; older server versions will simply ignore the option.
"socketTimeoutMS"
This option specifies the time limit, in milliseconds, for socket communication. If the server does not respond within the timeout period, a MongoCursorTimeoutException will be thrown and there will be no way to determine if the server actually handled the write or not. A value of
-1
may be specified to block indefinitely. The default value for MongoClient is30000
(30 seconds)."w"
See Write Concerns. The default value for MongoClient is
1
."wTimeoutMS"
This option specifies the time limit, in milliseconds, for write concern acknowledgement. It is only applicable when
"w"
is greater than1
, as the timeout pertains to replication. If the write concern is not satisfied within the time limit, a MongoCursorException will be thrown. A value of0
may be specified to block indefinitely. The default value for MongoClient is10000
(ten seconds).
The following options are deprecated and should no longer be used:
"safe"
Deprecated. Please use the write concern
"w"
option."timeout"
Deprecated alias for
"socketTimeoutMS"
."wtimeout"
Deprecated alias for
"wTimeoutMS"
.
返回值
Returns an array containing the status of the update if the
"w"
option is set. Otherwise, returns true
.
Fields in the status array are described in the documentation for MongoCollection::insert().
错误/异常
Throws MongoCursorException if the "w"
option is set and the write fails.
Throws MongoCursorTimeoutException if the "w"
option is set to a value greater than one and the operation takes longer than MongoCursor::$timeout
milliseconds to complete. This does not kill the operation on the server, it is a client-side timeout. The operation in MongoCollection::$wtimeout
is milliseconds.
更新日志
版本 | 说明 |
---|---|
PECL mongo 1.5.0 |
Added the Added the Emits |
PECL mongo 1.3.4 | Added "wtimeout" option.
|
PECL mongo 1.3.0 |
Added The |
PECL mongo 1.2.11 | Emits E_DEPRECATED when
|
PECL mongo 1.2.0 | Added "timeout" option.
|
PECL mongo 1.0.11 | Disconnects on "not master" errors if "safe" is set.
|
PECL mongo 1.0.9 |
Added ability to pass integers to the Added The return type was changed to be an array containing error information
if the |
PECL mongo 1.0.5 | Added "safe" option.
|
PECL mongo 1.0.1 | Changed options parameter from boolean to array.
Pre-1.0.1, the second parameter was an optional boolean value specifying an upsert. |
范例
Example #1 MongoCollection::update()
Adding an address field to a document.
<?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" }
Example #2 MongoCollection::update() upsert examples
Upserts can simplify code, as a single line can create the document if it
does not exist (based on $criteria
), or update an
existing document if it matches.
In the following example, $new_object
contains an
atomic modifier. Since the collection is empty and upsert must insert a new
document, it will apply those operations to the
$criteria
parameter in order to create the document.
<?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) }
If $new_object
does not contain atomic modifiers
(i.e. $
operators), upsert will use
$new_object
as-is for the new document. This matches
the behavior of a normal update, where not using atomic modifiers causes the
document to be overwritten.
<?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) { } }
Example #3 MongoCollection::update() multiple example
By default, MongoCollection::update() will only update
the first document matching $criteria
that it
finds. Using the "multiple" option can override this behavior, if needed.
This example adds a "gift" field to every person whose birthday is in the next day.
<?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));?>