ビルダを用いた操作

Overview

このガイドでは、操作で使用する型を作成するためにPHPライブラリが提供するビルダ クラスについて学習できます。集計ビルダ機能のビルダ クラスとファクトリー メソッドを使用して、検索、アップデート、削除操作などの他の操作のフィルターを作成できます。集計ビルダの詳細については、 集計ガイドの「 集計ビルダ 」セクションを参照してください。

ビルダを使用してクエリを作成すると、コンパイル時にエラーを識別し、実行時にエラーを回避することができます。このガイドでは、次のタスクを実行するために使用できるビルダ クラスに関する情報を提供します。

• フィルターの作成

• 更新ドキュメントの定義

• 変更ストリーム出力の修正

$options = [    'limit' => 5,    '<option name>' => '<specification>',];

このガイドでは、非集計操作でビルダを使用する方法の例を示します。集計の例については、集計操作ガイドを参照してください。

$collection = $client->sample_geospatial->shipwrecks;

ビルダ クラスのインポート

このガイドの例を実行するには、次のクラスをアプリケーションにインポートする必要があります。

use MongoDB\Builder\Pipeline;use MongoDB\Builder\Query;use MongoDB\Builder\Stage;

フィルターの作成

Query ビルダークラスのファクトリー メソッドを使用して、検索、アップデート、削除操作で使用するフィルター定義を作成できます。Query::query() ファクトリー メソッドを使用してクエリを作成する場合、名前付き引数の構文を使用し、型の安全性を実装できます。フィルターの作成の詳細については、「クエリの指定」ガイドを参照してください。

次の手順では、ビルダを使用してフィルター定義を作成する方法について説明します。

1. クエリを作成するには、Query::query() メソッドを呼び出します。

2. フィルタリングするフィールド名と Queryクラスのファクトリー メソッドを渡します。フィルターでフィールド名と条件の 1 つ以上のペアを渡して、複数の 句を適用できます。

次のコードは、ビルダを使用してフィルター定義を作成するためのテンプレートを示しています。

$filter = Query::query(    <field name>: Query::<factory method>(<parameters>),    <field name>: Query::<factory method>(<parameters>),    ...);

論理クエリ演算子（$and、$or、$not、$nor）を使用してクエリ条件を結合するには、次のクエリ テンプレートを使用できます。

$filter = Query::<logical operator>(    Query::query(<field name>: Query::<factory method>(<parameters>)),    Query::query(<field name>: Query::<factory method>(<parameters>)),    ...);

詳細については、 MongoDB Serverマニュアルの「 論理クエリ演算子 」を参照してください。

以下のセクションでは、ビルダを使用してさまざまな操作のフィルター定義を作成する例を示します。

// Creates a query filter by using builders and// retrieves matching documents$docs = $collection->find(    Query::query(        feature_type: Query::eq('Wrecks - Visible'),        coordinates: Query::near(            Query::geometry(                type: 'Point',                coordinates: [-79.9, 9.3],            ),            maxDistance: 10000,        ),    ),);
// Prints matching documentsforeach ($docs as $doc) {    echo json_encode($doc), PHP_EOL;}

{"_id":...,"feature_type":"Wrecks - Visible","coordinates":[-79.9137115,9.3390503],...}{"_id":...,"feature_type":"Wrecks - Visible","coordinates":[-79.9357223,9.3340302],...}{"_id":...,"feature_type":"Wrecks - Visible","coordinates":[-79.9081268,9.3547792],...}// Results truncated

// Creates a query filter by using builders// and deletes the first matching document$result = $collection->deleteOne(    Query::or(        Query::query(feature_type: Query::regex('nondangerous$', '')),        Query::query(depth: Query::gt(10.0)),    ),);
// Prints number of deleted documentsecho 'Deleted documents: ', $result->getDeletedCount(), PHP_EOL;

Deleted documents: 1

更新ドキュメントの定義

Stage ビルダークラスのファクトリー メソッドを使用してアップデート ドキュメントを作成できます。更新ドキュメントは、ターゲット ドキュメントに対して行う更新について説明します。ドキュメントの更新について詳しくは、「 ドキュメントの更新ガイド 」を参照してください。

次の手順では、ビルダを使用してアップデートドキュメントを作成する方法について説明します。

1. Pipelineインスタンスを作成します。

2. 1 つ以上の ステージを渡すには、Stage::set() などの Stageクラスからメソッドを呼び出し、フィールド名と値を渡します。

次のコードは、ビルダを使用してアップデートを定義するためのテンプレートを示しています。

$update = new Pipeline(    Stage::set(<field name>: <value>),    Stage::set(<field name>: <value>),    ...);

この例では、次のアクションを実行します。

• Query::eq()ファクトリー メソッドを使用して、watlevフィールド値が 'partly submerged at high water' であるドキュメントを一致させます

• Stage::set() メソッドを使用して yearフィールドを 1870 に設定します

• MongoDB\Collection::updateOne()更新を実行するために メソッドを呼び出します

• 更新されたドキュメントの数を出力します

// Creates a query filter and an update document by// using builders and updates the first matching document$result = $collection->updateOne(    Query::query(watlev: Query::eq('partly submerged at high water')),    new Pipeline(        Stage::set(year: 1870),    ),);
// Prints number of updated documentsecho 'Updated documents: ', $result->getModifiedCount(), PHP_EOL;

Updated documents: 1

変更ストリーム出力の修正

Stageクラスのファクトリー メソッドを使用して、パイプラインを作成し、変更ストリームの出力を変更できます。変更ストリームの詳細については、 「変更ストリームによるデータの監視」ガイドを参照してください。

次の手順では、ビルダを使用して変更ストリームフィルターを作成する方法について説明します。

1. 配列を作成します。

2. Stageクラスと必要なパラメータからファクトリー メソッドを呼び出して、1 つ以上の $match ステージを渡します。

次のコードは、ビルダを使用して変更ストリーム出力を変更するためのテンプレートを示しています。

$pipeline = [    Stage::<factory method>(...),    Stage::<factory method>(...),    ...];

このパイプラインは次のメソッドに渡すことができます。

• MongoDB\Client::watch()

• MongoDB\Database::watch()

• MongoDB\Collection::watch()

この例では、次のアクションを実行します。

• Stage::match() メソッドを使用して、更新操作の変更イベントのみをフィルタリングします

• Stage::project() メソッドを使用して、operationType、ns（名前空間）、fullDocument フィールドのみを出力します

• MongoDB\Collection::watch() メソッドを呼び出して変更ストリームを開き、fullDocument オプションを設定して更新後に完全なドキュメントを出力します

• 変更イベントが発生するたびに出力

// Creates a pipeline to filter for update operations and return// only specific fields$pipeline = [    Stage::match(operationType: Query::eq('update')),    Stage::project(operationType: 1, ns: 1, fullDocument: 1),];
// Opens the change stream$changeStream = $collection->watch(    $pipeline,    ['fullDocument' => MongoDB\Operation\Watch::FULL_DOCUMENT_UPDATE_LOOKUP],);
// Prints change events based on the pipeline specificationsfor ($changeStream->rewind(); true; $changeStream->next()) {    if (! $changeStream->valid()) {        continue;    }    $event = $changeStream->current();    echo json_encode($event), PHP_EOL;
    if ($event['operationType'] === 'invalidate') {        break;    }}

{  "_id":...,  "operationType":"update",  "fullDocument":{"_id":...,"feature_type":"Wrecks - Visible",...},  "ns":{"db":"sample_geospatial","coll":"shipwrecks"}}

変更イベントによって提供される情報の詳細については、 MongoDB Serverマニュアルの「 変更イベント 」を参照してください。