/ /

문서 교체

개요

이 가이드 에서는 코틀린 (Kotlin) 운전자 사용하여 MongoDB 컬렉션 의 문서를 교체하는 방법을 학습 수 있습니다. 바꾸기 작업은 쿼리 필터하다 사용하여 컬렉션 의 문서 일치시킨 다음 문서 새 문서로 바꿉니다.

하나의 문서 바꾸기

replaceOne() 메서드는 일치하는 문서 에서 모든 기존 필드와 값(_id 필드 제외)을 제거하고 대체 문서 에서 필드와 값을 삽입합니다.

다음과 같이 MongoCollection 인스턴스에서 replaceOne() 메서드를 호출할 수 있습니다.

collection.replaceOne(<query>, <replacementDocument>)

여러 문서가 replaceOne() 메서드에 지정된 쿼리 필터와 일치하는 경우 작업은 첫 번째 결과를 대체합니다. 다음 코드와 같이 ReplaceOptions 인스턴스 에서 정렬을 지정하여 드라이버 바꾸기 작업을 수행하기 전에 일치하는 문서에 순서를 적용 할 수 있습니다.

val opts = ReplaceOptions().sort(Sorts.ascending(PaintOrder::color.name))

바꾸기 작업의 쿼리 필터하다 와 일치하는 문서가 0개인 경우 replaceOne() 은 컬렉션 의 문서를 변경하지 않습니다. 일치하는 문서가 없는 경우 새 문서를 삽입하는 대신 새 문서 삽입하는 방법을 학습 업서트 가이드 참조하세요.

중요

replaceOne() 메서드는 컬렉션 의 고유 인덱스 제약 조건을 위반하는 문서 를 변경할 수 없습니다. 고유 인덱스에 대한 자세한 내용은 MongoDB Server 매뉴얼을 참조하세요.

작업 매개변수 바꾸기

replaceOne() 메서드는 다음 매개 변수를 허용합니다:

Parameter	설명
`filter`	바꿀 문서 지정하는 쿼리 필터하다 . 쿼리 필터에 대한 자세한 내용은 MongoDB Server 매뉴얼을 참조하세요. 데이터 유형: BSON
`replacement`	새 문서 에 삽입할 필드와 값을 지정하는 대체 문서 입니다. 컬렉션 의 문서가 코틀린 (Kotlin) 클래스에 매핑된 경우 대체 문서 이 클래스의 인스턴스 될 수 있습니다. 데이터 유형: `document: T`
`options`	선택 사항. 바꾸기 작업에 대한 구성을 지정하는 `ReplaceOptions` 클래스의 인스턴스 . 기본값 은 `null`입니다. 데이터 유형: ReplaceOptions

대체 작업 사용자 지정

replaceOne() 메서드는 선택적으로 ReplaceOptions 객체 매개 변수로 허용하며, 이는 대체 작업을 구성하는 데 사용할 수 있는 옵션을 나타냅니다.

ReplaceOptions 클래스에는 다음과 같은 속성이 포함되어 있습니다.

속성	설명
`bypassDocumentValidation`	바꾸기 작업에서 문서 유효성 검사 우회할지 여부를 지정합니다. 이를 통해 스키마 유효성 검사 요구 사항을 충족하지 않는 문서(있는 경우)를 대체할 수 있습니다. 스키마 유효성 검사 에 대한 자세한 내용은 MongoDB Server 매뉴얼을 참조하세요. 데이터 유형: 부울
`collation`	결과를 정렬할 때 사용할 언어 데이터 정렬의 종류를 지정합니다. 데이터 유형: 데이터 정렬
`comment`	작업에 대해 사용자가 제공한 설명을 가져오거나 설정합니다. 자세한 내용은 MongoDB Server 매뉴얼을 참조하세요. 데이터 유형: 문자열 또는 BsonValue
`hint`	문서를 스캔하는 데 사용할 인덱스 를 가져오거나 설정합니다. 자세한 내용은 MongoDB Server 매뉴얼을 참조하세요. 데이터 유형: Bson
`hintString`	문서를 스캔하는 데 사용할 인덱스 를 가져오거나 설정합니다. 자세한 내용은 MongoDB Server 매뉴얼을 참조하세요. 데이터 유형: 문자열
`upsert`	쿼리 필터하다 와 일치하는 문서가 없는 경우 대체 작업에서 업서트 작업을 수행할지 여부를 지정합니다. 자세한 내용은 MongoDB Server 매뉴얼을 참조하세요. 데이터 유형: 부울
`sort`	대체 작업은 지정된 정렬 순서의 첫 번째 문서 대체하기 때문에 쿼리 여러 문서를 선택하는 경우 작업에서 대체할 문서 를 결정합니다. 데이터 유형: Bson
`let`	작업에 대한 최상위 변수를 추가할 let 문서 가져오거나 설정합니다. 자세한 내용은 MongoDB Server 매뉴얼 을 참조하세요. 데이터 유형: Bson

반환 값

성공적인 실행되면 replaceOne() 메서드는 UpdateResult 인스턴스 반환합니다. UpdateResult 클래스에는 다음과 같은 속성이 포함되어 있습니다.

속성	설명
`wasAcknowledged`	MongoDB에서 대체 작업을 승인했는지 여부를 나타냅니다. 데이터 유형: `boolean`
`getMatchedCount`	쿼리 필터가 대체되었는지 여부에 관계없이 쿼리 필터와 일치하는 문서 수입니다. 데이터 유형: `long`
`getModifiedCount`	대체 작업으로 바뀐 문서 수입니다. 데이터 유형: `long`
`getUpsertedId`	드라이버가 업서트를 수행한 경우 데이터베이스에 업서트된 문서의 ID입니다. 데이터 유형: BsonValue

예외

교체 작업이 실패하면 드라이버 예외가 발생합니다.

예시 를 들어 대체 문서 의 _id 필드 값이 원본 문서 의 값과 다른 경우 메서드는 다음과 같은 MongoWriteException을 발생시킵니다.

After applying the update, the (immutable) field '_id' was found to have been altered to _id: ObjectId('...)

교체 문서 에 고유 인덱스 규칙을 위반하는 변경 사항이 포함된 경우 메서드는 다음과 유사한 오류 메시지와 함께 MongoWriteException 을 발생시킵니다.

E11000 duplicate key error collection: ...

특정 조건에서 발생하는 예외 유형에 대한 자세한 내용은 이 페이지 하단에 링크된 replaceOne() 에 대한 API 문서를 참조하세요.

하나의 예제 바꾸기

페인트 저장 5가지 색상의 페인트를 판매합니다. 다음 컬렉션 의 문서는 스토어 인벤토리의 페인트 색상을 나타냅니다.

{ "_id": 1, "color": "red", "qty": 5 }
{ "_id": 2, "color": "purple", "qty": 8 }
{ "_id": 3, "color": "yellow", "qty": 0 }
{ "_id": 4, "color": "green", "qty": 6 }
{ "_id": 5, "color": "pink", "qty": 20 }

다음 코틀린 (Kotlin) 데이터 클래스는 이 데이터를 모델링합니다.

data class PaintOrder(
    @BsonId val id: Int,
    val color: String,
    val qty: Int
)

페인트 저장 재고를 업데이트하여 분홍 페인트 20 캔을 주황색 페인트 25 캔으로 교체해야 합니다.

인벤토리를 업데이트 하려면 replaceOne() 메서드를 호출합니다.

val filter = Filters.eq(PaintOrder::color.name, "pink")
val update = PaintOrder(5, "orange", 25)
val result = collection.replaceOne(filter, update)
println("Matched document count: $result.matchedCount")
println("Modified document count: $result.modifiedCount")

  Matched document count: 1
  Modified document count: 1

앞의 바꾸기 작업은 다음 문서 생성합니다.

 { "_id": 5, "color": "orange", "qty": 25 }

고급 1개 바꾸기 예시

다음 예시 에서 replaceOne() 메서드는 Atlas sample_mflix.movies 데이터 세트 의 movies 컬렉션 에 있는 쿼리 필터의 첫 번째 일치 항목을 대체 문서 로 바꿉니다. 이 작업은 원본 문서 에서 _id 를 제외한 모든 필드를 삭제하고 대체 문서 에서 필드를 삽입합니다. 다음 Movie 데이터 클래스는 Kotlin 드라이버 와 함께 사용할 수 있도록 이 컬렉션 의 문서를 모델링합니다.

data class Movie(
    val title: String,
    val year: Int,
    val genres: List<String>,
    val rated: String,
    val plot: String,
    val runtime: Int,
    val imdb: IMDB,
    val fullplot: String? = "No full plot",
){
    data class IMDB(
        val rating: Double
    )
}

팁

빌더 메서드 및 데이터 클래스 속성

애플리케이션 에 선택적 코틀린 (Kotlin) 운전자 확장 종속성을 추가하여 빌더 클래스의 메서드를 데이터 클래스 속성과 함께 직접 사용할 수 있습니다. 자세한 내용을 학습 예제를 보려면 데이터 클래스와 함께 빌더 사용 가이드 참조하세요.

replaceOne() 작업이 실행되기 전에는 원본 문서에 영화를 설명하는 여러 필드가 포함되어 있습니다. 작업이 실행된 후 결과 문서에는 대체 문서(title 및 fullplot)와 _id 필드로 지정된 필드만 포함됩니다.

다음 예시 다음 객체와 메서드를 사용합니다.

replaceOne() 메서드에 전달되는 쿼리 필터입니다 . eq 필터는 제목이 "Music of the Heart" 텍스트와 정확히 일치하는 영화만 일치합니다.
일치하는 문서 를 대체하는 문서 포함된 대체 문서 입니다(있는 경우).
upsert 옵션이 true(으)로 설정된 ReplaceOptions 개체. 이 옵션은 쿼리 필터하다 어떤 문서와도 일치하지 않는 경우 메서드가 대체 문서 에 포함된 데이터를 삽입하도록 지정합니다.

참고

이 예시 연결 URI를 사용하여 MongoDB 인스턴스 에 연결합니다. MongoDB 인스턴스에 연결하는 방법에 대해 자세히 학습하려면 연결 가이드를 참조하세요.

import com.mongodb.MongoException
import com.mongodb.client.model.Filters
import com.mongodb.client.model.ReplaceOptions
import com.mongodb.kotlin.client.coroutine.MongoClient
import kotlinx.coroutines.runBlocking
data class Movie(val title: String, val fullplot: String)
fun main() = runBlocking {
    // Replace the uri string with your MongoDB deployment's connection string
    val uri = "<connection string uri>"
    val mongoClient = MongoClient.create(uri)
    val database = mongoClient.getDatabase("sample_mflix")
    val collection = database.getCollection<Movie>("movies")
    try {
        val query = Filters.eq("title", "Music of the Heart")
        val replaceDocument = Movie( "50 Violins", " A dramatization of the true story of Roberta Guaspari who co-founded the Opus 118 Harlem School of Music")
        val options = ReplaceOptions().upsert(true)
        val result = collection.replaceOne(query, replaceDocument, options)
        println("Modified document count: " + result.modifiedCount)
        println("Upserted id: " + result.upsertedId) // only contains a non-null value when an upsert is performed
    } catch (e: MongoException) {
        System.err.println("Unable to replace due to an error: $e")
    }
    mongoClient.close()
}

앞의 예시 다음과 같은 출력이 반환됩니다.

Modified document count: 1
Upserted id: null

앞의 예시 로 인해 업서트 발생한 경우 코드는 다음 출력을 반환합니다.

Modified document count: 0
Upserted id: BsonObjectId{value=...}

대체된 문서 쿼리 하면 다음과 같은 출력 쿼리 반환됩니다.

Movie(title=50 Violins, fullplot= A dramatization of the true story of Roberta Guaspari
who co-founded the Opus 118 Harlem School of Music)

추가 정보

이 페이지에서 사용되는 메서드 및 클래스에 대해 자세히 학습 다음 API 설명서를 참조하세요.

돌아가기

문서 업서트

문서 삭제