문서 메뉴

문서 홈 → PHP 라이브러리 매뉴얼

MongoDB\데이터베이스::watch()

이 페이지의 내용

  • 정의
  • 매개변수
  • 반환 값
  • 오류/예외
  • 예제
  • 다음도 참조하세요.

버전 1.4에 새로 추가되었습니다.

정의

MongoDB\Database::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 옵션과 상호 배타적입니다.

버전 1.17에 추가 되었습니다.

데이터 정렬
배열|객체

데이터 정렬 을 통해 사용자는 문자열 비교를 위한 언어별 규칙(예: 대소문자 및 악센트 표시 규칙)을 지정할 수 있습니다. 데이터 정렬을 지정할 때 locale 필드는 필수입니다. 다른 모든 데이터 정렬 필드는 선택 사항입니다. 필드에 대한 설명은 데이터 정렬 문서를 참조하세요.

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 파이프라인 단계의 옵션입니다.

세션
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 값으로 변환되는 방식을 결정합니다. 기본값은 데이터베이스의 유형 맵입니다.

반환 값

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

오류/예외

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

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

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

MongoDB\Driver\Exception\RuntimeException 드라이버 수준의 기타 오류(예: 연결 오류).

예제

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

<?php
$uri = 'mongodb://rs1.example.com,rs2.example.com/?replicaSet=myReplicaSet';
$database = (new MongoDB\Client($uri))->test;
$changeStream = $database->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.inventory
{"_id":{"$oid":"5a81fc0d6118fd1af1790d32"},"name":"Widget","quantity":5}
Updated document in test.inventory with _id: {"$oid":"5a81fc0d6118fd1af1790d32"}
{"updatedFields":{"quantity":4},"removedFields":[]}
Deleted document in test.inventory with _id: {"$oid":"5a81fc0d6118fd1af1790d32"}

다음도 참조하세요.

← MongoDB\데이터베이스::SelectGridFSBucket()
MongoDB\데이터베이스::withOptions() →

이 페이지의 내용