Docs Menu
Docs Home
/
언어
/
PHP
/
PHP 라이브러리 매뉴얼
/
API 문서
/
MongoDB\Collection

MongoDB\Collection::replaceOne()

이 페이지의 내용

  • 정의
  • 매개변수
  • Return Values
  • 오류/예외
  • 행동
  • 예시
  • 다음도 참조하세요.

정의

MongoDB\Collection::replaceOne()

필터 기준과 일치하는 문서를 하나만 교체합니다. 필터 기준과 일치하는 문서가 여러 개 있는 경우가장 먼저 일치하는 문서만 대체됩니다.

function replaceOne(
    array|object $filter,
    array|object $replacement,
    array $options = []
): MongoDB\UpdateResult

매개변수

$filter : 배열|객체
대체할 문서를 지정하는 필터 기준입니다.
$replacement : 배열|객체
대체 문서입니다.
$options : 배열

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

이름
유형
설명
bypassDocumentValidation
부울
true인 경우 쓰기 작업이 문서 수준 유효성 검사를 우회하도록 허용합니다. 기본값은 false입니다.
코덱
MongoDB\Codec\DocumentCodec

문서 인코딩 또는 디코딩에 사용할 코덱 입니다. 이 옵션은 typeMap 옵션과 상호 배타적입니다.

컬렉션의 코덱을 기본값으로 설정합니다. 기본 codec 옵션의 상속은 typeMap 옵션의 상속보다 우선합니다.

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

데이터 정렬
배열|객체

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

데이터 정렬이 지정되지 않았지만 컬렉션에 기본 데이터 정렬이 있는 경우, 작업은 컬렉션에 지정된 데이터 정렬을 사용합니다. 컬렉션 또는 연산에 대한 데이터 정렬이 지정되지 않은 경우, MongoDB는 이전 버전에서 문자열 비교에 사용된 간단한 이진 비교를 사용합니다.

comment
혼합

사용자가 데이터베이스 프로파일러, currentOp 출력 및 로그를 통해 작업을 추적하는 데 도움이 되는 임의의 주석을 지정할 수 있습니다.

이 옵션은 MongoDB 4.4부터 사용할 수 있으며 이전 서버 버전에 대해 지정된 경우 실행 시 예외가 발생합니다.

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

hint
문자열|배열|객체

사용할 인덱스입니다. 인덱스 이름을 문자열로 지정하거나 인덱스 키 패턴을 문서로 지정합니다. 이 옵션을 지정하면 쿼리 시스템은 힌트 인덱스를 사용하는 계획만 고려합니다.

이 옵션은 MongoDB 4.2부터 사용할 수 있으며 이전 서버 버전에 대해 지정된 경우 실행 시 예외가 발생합니다.

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

하자
배열|객체

매개변수 이름과 값의 맵입니다. 값은 문서 필드를 참조하지 않는 상수 또는 닫힌 표현식이어야 합니다. 그런 다음 매개변수는 애그리게이션 표현식 컨텍스트에서 변수로 액세스될 수 있습니다(예: $$var).

이는 5.0 이전의 서버 버전에서는 지원되지 않으며 사용하는 경우 실행 시 예외가 발생합니다.

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

Session

작업과 연결할 클라이언트 세션입니다.

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

업서트
부울
true로 설정하면 쿼리 기준과 일치하는 문서가 없을 때 새 문서가 만들어집니다. 기본값은 false이며, 일치하는 문서가 없을 경우 새 문서를 삽입하지 않습니다.
쓰기 고려

작업에 사용할 고려를 씁니다 . 기본값은 컬렉션의 쓰기 고려입니다.

트랜잭션의 일부로 개별 작업에 대한 쓰기 고려를 지정할 수 없습니다. 대신 트랜잭션을시작할 때 writeConcern 옵션을 설정합니다.

Return Values

MongoDB\Driver\WriteResult MongoDB\UpdateResult 를 캡슐화하는 객체 객체.

오류/예외

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

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

MongoDB\Driver\Exception\BulkWriteException 쓰기 작업과 관련된 오류의 경우. 사용자는 getWriteResult() 가 반환한 값을 검사해야 합니다. 오류의 특성을 확인합니다.

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

행동

쿼리 기준을 평가할 때 MongoDB 는 BSON types에 대한 자체 비교 규칙 에 따라 유형과 값을 비교하며, 이는 PHP의 비교 와는 다릅니다. 및 유형 저글링 규칙. 특수 BSON 유형과 일치하는 경우 쿼리 기준은 해당 BSON 클래스 를 사용해야 합니다. 확장 프로그램(예: MongoDB\ BSON\ObjectId 사용 ObjectId 와 일치시킵니다.

MongoDB\Driver\Exception\BulkWriteException이 이 발생하면 사용자는 getWriteResult() 를 호출해야 합니다. 반환된 MongoDB\Driver\WriteResult 를 검사합니다. 객체를 사용하여 오류의 특성을 확인합니다.

예를 들어 쓰기 작업이 프라이머리 서버에 성공적으로 적용되었지만 쓰기 고려를 충족하지 못했을 수 있습니다(예시: 복제가 너무 오래 걸렸습니다). 또는 쓰기 작업이 완전히 실패했을 수 있습니다(예시: 고유 키 위반).

예시

다음 예에서는 문서를 test 데이터베이스의 restaurants 컬렉션에 있는 "40356068" 의 restaurant_id 로 바꿉니다.

<?php
$collection = (new MongoDB\Client)->test->restaurants;
$updateResult = $collection->replaceOne(
    [ 'restaurant_id' => '40356068' ],
    [
        'name' => 'New Restaurant',
        'restaurant_id' => '99988877',
        'borough' => 'Queens',
        'cuisine' => 'Cafe',
        'grades' => [],
    ]
);
printf("Matched %d document(s)\n", $updateResult->getMatchedCount());
printf("Modified %d document(s)\n", $updateResult->getModifiedCount());

이 경우 출력은 다음과 유사합니다:

Matched 1 document(s)
Modified 1 document(s)

다음도 참조하세요.

돌아가기

Rename()

다음

updateMany()