db.コレクション.findOneAndUpdate()（mongoshメソッド）

filter

ドキュメント

更新の選択基準。find()メソッドと同じクエリ セレクターを使用できます。

コレクションで返される最初のドキュメントを更新するには、空のドキュメント{ }を指定します。

指定しない場合、デフォルトは空のドキュメントになります。

クエリ フィールドがドキュメントでない場合、操作はエラーを返します。

filterに一致するドキュメントがない場合、ドキュメントは更新されません。

update

ドキュメントまたは配列

更新ドキュメントまたは集計パイプライン。

• 更新演算子式を含むドキュメントが渡された場合、findOneAndUpdate() は指定された変更を実行します。

  ドキュメントには更新演算子のみが含まれている必要があります。{ <field1>: <value1>, ...}では、置き換えドキュメントを指定することはできません。置き換えドキュメントを使用する場合は、db.collection.findOneAndReplace()を参照してください。

• 集計パイプライン [ <stage1>, <stage2>, ... ] が渡された場合、findOneAndUpdate() はパイプラインに従ってドキュメントを変更します。パイプラインは次のステージで構成できます。

  • $addFields およびそのエイリアス $set

  • $project およびそのエイリアス $unset

  • $replaceRoot およびそのエイリアス $replaceWith

writeConcern

ドキュメント

任意。書込み保証（write concern）を表現するドキュメント。デフォルトの書込み保証を使用する場合は省略します。

{ w: <value>, j: <boolean>, wtimeout: <number> }

トランザクションで実行される場合、操作の書込み保証 (write concern)を明示的に設定しないでください。トランザクションで書込み保証を使用するには、「トランザクション書込み保証」を参照してください。

projection

ドキュメント

任意。返すフィールドのサブセット。

返されたドキュメント内のすべてのフィールドを返すには、このパラメーターを省略します。

プロジェクションの引数がドキュメントでない場合、操作はエラーになります。

sort

ドキュメント

任意。 filterに一致するドキュメントの並べ替え順序を指定します。

ソート引数がドキュメントでない場合、操作はエラーになります。

cursor.sort() を参照してください。

maxTimeMS

数値

任意。 操作が 以内に完了する必要がある制限時間をミリ秒単位で指定します。 制限を超えた場合はエラーがスローされます。

upsert

ブール値

Optional. When true, findOneAndUpdate() either:

• filter に一致するドキュメントがない場合は、新しいドキュメントを作成します。詳細については、アップサートの動作を参照してください。returnNewDocumentがtrueでない限り、新しいドキュメントを挿入した後にnullを返します。

• filter に一致する 1 つのドキュメントをアップデートします。

複数のアップサートを回避するため、filterフィールドが一意にインデックスされていることを確認します。

デフォルトは false で、一致するものが見つからなくても新しいドキュメントは挿入されません。

returnDocument

string

Optional. Starting in mongosh 0.13.2, returnDocument is an alternative for returnNewDocument. If both options are set, returnDocument takes precedence.

returnDocument: "before" は元のドキュメントを返します。 returnDocument: "after"は更新されたドキュメントを返します。

returnNewDocument

ブール値

任意。trueの場合、元のドキュメントではなく更新されたドキュメントを返します。

デフォルトは false です。

collation

ドキュメント

任意。

任意。操作に使用する照合を指定します。

照合を指定すると、大文字・小文字やアクセント記号など、文字列を比較するための言語独自のルールを指定できます。

照合オプションの構文は次のとおりです。

collation: {
    locale: <string>,
    caseLevel: <boolean>,
    caseFirst: <string>,
    strength: <int>,
    numericOrdering: <boolean>,
    alternate: <string>,
    maxVariable: <string>,
    backwards: <boolean>
 }

照合を指定する場合、locale フィールドは必須ですが、その他の照合フィールドはすべて任意です。フィールドの説明については、照合ドキュメントを参照してください。

照合が指定されていなくても、コレクションにデフォルトの照合が設定されている場合（db.createCollection() を参照）には、コレクションの照合が使用されます。

コレクションにも操作にも照合が指定されていない場合、MongoDB では以前のバージョンで使用されていた単純なバイナリ比較によって文字列が比較されます。

1 つの操作に複数の照合は指定できません。たとえば、フィールドごとに異なる照合を指定できません。また、ソートと検索を一度に実行する場合、検索とソートで別の照合を使用できません。

arrayFilters

配列

任意。配列フィールドの更新操作でどの配列要素を変更するかを決定するフィルター ドキュメントの配列。

アップデート ドキュメントでは、$[<identifier>] フィルター処理された位置演算子を使用して識別子を定義し、配列フィルター ドキュメントで参照します。識別子がアップデートドキュメントに含まれていない場合、識別子の配列フィルタードキュメントを作成することはできません。

<identifier>は小文字で始まり、含めることができるのは英数字のみです。

アップデート ドキュメントには同じ識別子を複数回含めることができます。ただし、アップデート ドキュメント内の個別の識別子 ($[identifier]) それぞれに対し、対応する配列フィルター ドキュメントを 1 つだけ指定する必要があります。つまり、同じ識別子に対して複数の配列フィルター ドキュメントを指定することはできません。たとえば、アップデート ステートメントに識別子 x が（場合によっては複数回）含まれている場合、x に 2 つの個別のフィルタ　ドキュメントを含む arrayFilters に対して、次のように指定することはできません。

// INVALID
[
  { "x.a": { $gt: 85 } },
  { "x.b": { $gt: 80 } }
]

ただし、次の例のように、単一のフィルター ドキュメント内の同じ識別子に複合条件を指定できます。

// Example 1
[
  { $or: [{"x.a": {$gt: 85}}, {"x.b": {$gt: 80}}] }
]
// Example 2
[
  { $and: [{"x.a": {$gt: 85}}, {"x.b": {$gt: 80}}] }
]
// Example 3
[
  { "x.a": { $gt: 85 }, "x.b": { $gt: 80 } }
]

For examples, see Array Update Operations with arrayFilters.

arrayFilters は、集計パイプラインが使用される更新では使用できません。

<field>: <1 or true>

フィールドを包含することを指定します。プロジェクションの値としてゼロ以外の整数を指定した場合、その値を true として処理します。

<field>: <0 or false>

フィールドの除外を指定します。

"<field>.$": <1 or true>

$ 配列プロジェクション 演算子を使用して、配列フィールドのクエリ条件に一致する最初の要素を返します。プロジェクションの値としてゼロ以外の整数を指定した場合、その値を true として処理します。

ビューには使用できません。

<field>: <array projection>

配列プロジェクション 演算子（$elemMatch、$slice）を使用して、含める配列要素を指定します。

ビューには使用できません。

<field>: <aggregation expression>

プロジェクションを行ったフィールドの値を指定します。

集計式と構文の使用（リテラルと集計変数の使用を含む）では、新しいフィールドをプロジェクションしたり、既存のフィールドを新しい値でプロジェクションしたりできます。

• プロジェクションの値として数値でもブール値でもないリテラル（例えば、文字列リテラルや配列、演算子式）を指定すると、フィールドは新しい値でプロジェクションされます。次に例を示します。

  • { field: [ 1, 2, 3, "$someExistingField" ] }

  • { field: "New String Value" }

  • { field: { status: "Active", total: { $sum: "$existingArray" } } }

• フィールドにリテラル値をプロジェクションするには、$literal 集計式を使用します。次に例を示します。

  • { field: { $literal: 5 } }

  • { field: { $literal: true } }

  • { field: { $literal: { fieldWithValue0: 0, fieldWithValue1: 1 } } }