MongoDB\Collection::watch()

정의

MongoDB\Collection::watch()

컬렉션에서 변경 스트림 작업을 실행합니다. 변경 스트림에서 컬렉션 수준의 변경 사항을 확인할 수 있습니다.

function watch(
    array $pipeline = [],
    array $options = []
): MongoDB\ChangeStream

매개변수

$pipeline : 배열|객체

초기 $changeStream 단계에 추가할 단계의 파이프라인입니다.

$options : 배열

원하는 옵션을 지정하는 배열입니다.

이름	유형	설명
batchSize	integer	초기 aggregate 명령과 후속 getMore 명령 모두에 적용되는 커서의 배치 크기를 지정합니다. 이는 서버의 각 응답에서 반환할 최대 변경 이벤트 수를 결정합니다. batchSize 옵션과 관계없이 change stream에 대한 초기 aggregate 명령 응답에는 일반적으로 점을 구성하는 데 다른 옵션을 사용하지 않는 한(예: 문서 startAfter).
코덱	MongoDB\Codec\DocumentCodec	문서 인코딩 또는 디코딩에 사용할 코덱 입니다. 이 옵션은 typeMap 옵션과 상호 배타적입니다. 컬렉션의 코덱을 기본값으로 설정합니다. 기본 codec 옵션의 상속은 typeMap 옵션의 상속보다 우선합니다. 버전 1.17에 추가 되었습니다.
데이터 정렬	배열|객체	데이터 정렬 을 통해 사용자는 string 비교를 위한 언어별 규칙(예: 대소문자 및 악센트 표시 규칙)을 지정할 수 있습니다. 데이터 정렬을 지정할 때 locale 필드는 필수입니다. 다른 모든 데이터 정렬 필드는 선택 사항입니다. 필드에 대한 설명은 데이터 정렬 문서를 참조하세요. MongoDB 4.2부터 생략하면 기본적으로 단순 이진 비교가 사용됩니다. 이전 버전에서는 단일 collection에서 열린 change stream이 collection의 기본 데이터 정렬을 상속받았습니다.
comment	혼합	사용자가 데이터베이스 프로파일러, currentOp 출력 및 로그를 통해 작업을 추적하는 데 도움이 되는 임의의 주석을 지정할 수 있습니다. MongoDB 4.4 버전부터는 유효한 모든 BSON type을 주석으로 설정할 수 있습니다. 이전 서버 버전에서는 문자열 값만 지원합니다. 버전 1.13에 새로 추가되었습니다.
전체 문서	문자열	업데이트 작업을 위해 fullDocument 응답 필드를 채우는 방법을 결정합니다. 기본적으로 change stream은 업데이트 작업에 대해 필드의 델타만 반환하며( updateDescription 필드를 통해) fullDocument 는 생략됩니다. 삽입 및 바꾸기 작업에는 항상 fullDocument 필드가 포함됩니다. 문서가 더 이상 존재하지 않으므로 삭제 작업에서는 필드가 생략됩니다. 업데이트된 문서의 현재 과반수 커밋 버전을 반환하려면 "updateLookup" 을 지정합니다. MongoDB 6.0+에서는 컬렉션에 changeStreamPreAndPostImages 이 활성화된 경우 수정된 문서의 사후 이미지 반환을 허용합니다. 사후 이미지를 반환하려면 'whenAvailable'을 지정하고, 그렇지 않은 경우 null 값을 반환합니다. 사후 이미지가 있는 경우 사후 이미지를 반환하려면 "필수" 를 지정하고, 그렇지 않은 경우 오류를 발생시킵니다. 지원되는 값은 다음과 같습니다. MongoDB\Operation\Watch::FULL_DOCUMENT_UPDATE_LOOKUP MongoDB\Operation\Watch::FULL_DOCUMENT_WHEN_AVAILABLE MongoDB\Operation\Watch::FULL_DOCUMENT_REQUIRED 이는 $changeStream 파이프라인 단계의 옵션입니다.
fullDocumentBeforeChange	문자열	fullDocumentBeforeChange 응답 필드가 채워지는 방식을 결정합니다. 이 필드는 기본적으로 생략됩니다. MongoDB 6.0+에서는 collection에 changeStreamPreAndPostImages 이 활성화된 경우 수정된 문서의 사전 이미지 반환을 허용합니다. 사용 가능한 경우 사전 이미지를 반환하려면 'whenAvailable'을 지정하고, 그렇지 않은 경우 null 값을 반환합니다. 사용 가능한 경우 사전 이미지를 반환하려면 "필수"를 지정하고, 그렇지 않은 경우 오류를 발생시킵니다. 지원되는 값은 다음과 같습니다. MongoDB\Operation\Watch::FULL_DOCUMENT_BEFORE_CHANGE_WHEN_AVAILABLE MongoDB\Operation\Watch::FULL_DOCUMENT_BEFORE_CHANGE_REQUIRED 이는 $changeStream 파이프라인 단계의 옵션입니다. 버전 1.13에 새로 추가되었습니다.
maxAwaitTimeMS	integer	데이터를 사용할 수 없는 경우 서버가 getMore 작업을 차단하는 시간 제한(밀리초)을 나타내는 양의 정수
readConcern	MongoDB\Driver\ReadConcern	작업에 사용할 읽기 고려 입니다. 기본값은 컬렉션의 읽기 고려입니다.
읽기 설정	MongoDB\Driver\ReadPreference	작업에 사용할 읽기 설정 입니다. 기본값은 컬렉션의 읽기 설정입니다. 이는 초기 change stream 애그리게이션과 자동 재개 중 서버 선택에 모두 사용됩니다.
재개 후	배열|객체	새 change stream의 논리적 점을 지정합니다. change stream에서 반환된 문서의 _id 필드를 여기에서 사용할 수 있습니다. 이 옵션을 startAfter 및/또는 startAtOperationTime 과 함께 사용하면 서버 오류가 발생합니다. 옵션은 상호 배타적입니다. 이는 $changeStream 파이프라인 단계의 옵션입니다.
Session	MongoDB\Driver\Session	작업과 연결할 클라이언트 세션입니다.
showExpandedEvents	부울	true인 경우 변경 스트림에 추가 DDL 이벤트를 포함하도록 서버에 지시합니다. 포함될 수 있는 추가 이벤트는 다음과 같습니다. createIndexes dropIndexes modify create shardCollection reshardCollection (서버 6.1 이상) refineCollectionShardKey (서버 6.1 이상) 이는 6.0 이전의 서버 버전에서는 지원되지 않으며, 사용하는 경우 실행 시 예외가 발생합니다. 이는 $changeStream 파이프라인 단계의 옵션입니다. 버전 1.13에 새로 추가되었습니다.
startAfter	배열|객체	새 변경 스트림의 논리적 시작점을 지정합니다. _id change stream에서 반환된 문서의 필드를 여기에서 사용할 수 있습니다. resumeAfter 와 달리 이 옵션은 "무효화" 이벤트의 재개 토큰과 함께 사용할 수 있습니다. 이 옵션을 resumeAfter 및/또는 startAtOperationTime 과 함께 사용하면 서버 오류가 발생합니다. 옵션은 상호 배타적입니다. 이는 4.2 이전의 서버 버전에서는 지원되지 않으며, 사용하는 경우 실행 시 예외가 발생합니다. 이는 $changeStream 파이프라인 단계의 옵션입니다. 버전 1.5에 새로 추가되었습니다.
startAtOperationTime	MongoDB\BSON\TimestampInterface	지정된 경우 change stream은 지정된 타임스탬프 또는 그 이후에 발생한 변경 사항만 제공합니다. MongoDB 4.0+ 서버의 명령 응답에는 여기에 사용할 수 있는 operationTime 가 포함됩니다. 기본적으로 초기 aggregate 명령에서 반환된 operationTime 가 사용 가능한 경우 사용됩니다. 이 옵션을 resumeAfter 및/또는 startAfter 과 함께 사용하면 서버 오류가 발생합니다. 옵션은 상호 배타적입니다. 이는 4.0 이전의 서버 버전에서는 지원되지 않으며, 사용하는 경우 실행 시 예외가 발생합니다. 이는 $changeStream 파이프라인 단계의 옵션입니다.
typeMap	배열	커서에 적용할 타입 맵으로, BSON 문서가 PHP 값으로 변환되는 방식을 결정합니다. 기본값은 컬렉션의 타입 맵입니다.

Return Values

MongoDB\ChangeStream 반복자 를 통해 변경 스트림의 이벤트를 반복할 수 있는 객체입니다. 인터페이스.

오류/예외

MongoDB\Exception\UnexpectedValueException 서버의 명령 응답이 잘못된 경우입니다.

옵션이 사용되지만 선택한 서버에서 지원되지 않는 경우 MongoDB\Exception\UnsupportedException입니다(예: collation, readConcern, writeConcern).

MongoDB\Exception\InvalidArgumentException 매개변수 또는 옵션의 구문 분석과 관련된 오류의 경우입니다.

MongoDB\ 드라이버\Exception\RuntimeException 확장 수준의 다른 오류(예: 연결 오류).

예시

이 예시에서는 change stream을 반복하는 동안 발생하는 이벤트를 보고합니다.

<?php
$uri = 'mongodb://rs1.example.com,rs2.example.com/?replicaSet=myReplicaSet';
$collection = (new MongoDB\Client($uri))->test->inventory;
$changeStream = $collection->watch();
for ($changeStream->rewind(); true; $changeStream->next()) {
    if ( ! $changeStream->valid()) {
        continue;
    }
    $event = $changeStream->current();
    if ($event['operationType'] === 'invalidate') {
        break;
    }
    $ns = sprintf('%s.%s', $event['ns']['db'], $event['ns']['coll']);
    $id = json_encode($event['documentKey']['_id']);
    switch ($event['operationType']) {
        case 'delete':
            printf("Deleted document in %s with _id: %s\n\n", $ns, $id);
            break;
        case 'insert':
            printf("Inserted new document in %s\n", $ns);
            echo json_encode($event['fullDocument']), "\n\n";
            break;
        case 'replace':
            printf("Replaced new document in %s with _id: %s\n", $ns, $id);
            echo json_encode($event['fullDocument']), "\n\n";
            break;
        case 'update':
            printf("Updated document in %s with _id: %s\n", $ns, $id);
            echo json_encode($event['updateDescription']), "\n\n";
            break;
    }
}

위의 스크립트가 change stream을 반복하는 동안 문서가 삽입, 업데이트 및 삭제되었다고 가정하면 출력은 다음과 유사합니다.

Inserted new document in test.user
{"_id":{"$oid":"5b329c4874083047cc05e60a"},"username":"bob"}
Inserted new document in test.products
{"_id":{"$oid":"5b329c4d74083047cc05e60b"},"name":"Widget","quantity":5}
Updated document in test.user with _id: {"$oid":"5b329a4f74083047cc05e603"}
{"updatedFields":{"username":"robert"},"removedFields":[]}

다음도 참조하세요.

• MongoDB\Client::watch()

• MongoDB\Database::watch()

• MongoDB 매뉴얼의 집계 파이프라인 문서

• MongoDB 매뉴얼의 Change Streams 문서

• MongoDB 매뉴얼의 변경 이벤트 문서