ビルダを用いた操作

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 documents
foreach ($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 documents
echo '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 documents
echo '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 specifications
for ($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マニュアルの「 変更イベント 」を参照してください。