문서

이 페이지의 내용

개요

문서
BsonDocument
JsonObject
요약

개요

이 가이드에서는 MongoDB 코틀린(Kotlin) 드라이버에서 문서 를 사용하는 방법을 배울 수 있습니다.

MongoDB 문서는 바이너리 JSON (BSON) 형식의 키/값 필드를 포함하는 데이터 구조입니다. 문서와 문서 필드에 포함된 데이터를 사용하여 데이터를 저장할 수 있을 뿐만 아니라 MongoDB에서 명령이나 쿼리를 실행할 수도 있습니다.

문서의 용어, 구조, 제한 사항에 대한 자세한 내용은 MongoDB 매뉴얼의 문서 페이지를 참조하세요.

MongoDB 코틀린(Kotlin) 드라이버와 BSON 라이브러리에는 문서의 BSON 데이터에 액세스하고 조작하는 데 도움이 되는 다음 클래스가 포함되어 있습니다.

이름	패키지	맵 구현 여부	권장 사용법
`Document`	`org.bson`	구현함 `Map<String, Object>`	유연하고 간결한 데이터 표현이 필요한 경우.
`BsonDocument`	`org.bson`	구현함 `Map<String, BsonValue>`	안전한 유형의 API가 필요한 경우.
`JsonObject`	`org.bson.json`	No	JSON 문자열로만 작업하려는 경우.

애플리케이션에서 이러한 클래스를 모두 사용할 수 있지만 복잡성에 관계없이 동적으로 구조화된 문서를 간결하게 표현할 수 있는 Document 클래스를 사용하는 것이 좋습니다. 느슨한 유형의 값을 사용할 수 있게 해주는 Map<String, Object> 인터페이스를 구현합니다.

문서

Document 클래스를 사용하면 BSON 문서를 유연하게 표현할 수 있습니다. 이 클래스와 함께 표준 라이브러리의 Kotlin 유형을 사용하여 필드에 액세스하고 조작할 수 있습니다. 자주 사용되는 BSON과 Kotlin 유형 간의 매핑은 다음 표를 참조하세요.

BSON type	Kotlin 유형
배열	`kotlin.collections.List`
바이너리	`org.bson.types.Binary`
부울	`kotlin.Boolean`
날짜	`java.time.LocalDateTime`
문서	`org.bson.Document`
Double	`kotlin.Double`
Int32	`kotlin.Int`
Int64	`kotlin.Long`
Null	`null`
ObjectId	`org.bson.types.ObjectId`
문자열	`kotlin.String`

다음 코드 스니펫은 여러 가지 필드 유형이 포함된 문서를 나타내는 샘플 Document 인스턴스를 인스턴스화하고 빌드하는 방법을 보여 줍니다.

val author = Document("_id", ObjectId())
    .append("name", "Gabriel García Márquez")
    .append(
        "dateOfDeath",
        LocalDateTime.of(2014, 4, 17, 4, 0)
    )
    .append(
        "novels", listOf(
            Document("title", "One Hundred Years of Solitude").append("yearPublished", 1967),
            Document("title", "Chronicle of a Death Foretold").append("yearPublished", 1981),
            Document("title", "Love in the Time of Cholera").append("yearPublished", 1985)
        )
    )

이 문서 를 컬렉션 에 삽입하려면 getCollection() 메서드를 사용하여 컬렉션 을 인스턴스화하고 다음과 같이 insertOne 작업을 호출합니다.

// val mongoClient = <code to instantiate your client>
val database = mongoClient.getDatabase("fundamentals_data")
val collection = database.getCollection<Document>("authors")
val result = collection.insertOne(author)

삽입이 성공적으로 수행되면 다음 코드를 사용하여 컬렉션에서 샘플 문서 데이터를 조회할 수 있습니다.

val doc = collection.find(Filters.eq("name", "Gabriel García Márquez")).firstOrNull()
doc?.let {
    println("_id: ${it.getObjectId("_id")}, name: ${it.getString("name")}, dateOfDeath: ${it.getDate("dateOfDeath")}")
    it.getList("novels", Document::class.java).forEach { novel ->
        println("title: ${novel.getString("title")}, yearPublished: ${novel.getInteger("yearPublished")}")
    }
}

_id: 5fb5fad05f734e3794741a35, name: Gabriel García Márquez, dateOfDeath: Thu Apr 17 00:00:00 EDT 2014
title: One Hundred Years of Solitude, yearPublished: 1967
title: Chronicle of a Death Foretold, yearPublished: 1981
title: Love in the Time of Cholera, yearPublished: 1985

팁

앞에 설명한 코드 샘플에서는 반환된 유형을 확인하고 필드 값을 캐스팅할 수 없는 경우 예외를 발생시키는 헬퍼 메서드를 사용합니다. get() 메서드를 호출하여 값을 Object 유형으로 조회하고 유형 검사를 건너뛸 수 있습니다.

MongoDB 데이터 검색 및 조작에 대한 자세한 내용은 CRUD 가이드를 참조하세요.

이 섹션에 언급된 메서드 및 클래스에 대한 자세한 내용은 다음 API 문서를 참조하세요.

BsonDocument

BsonDocument 클래스는 BSON 문서에 액세스하고 조작할 수 있는 안전한 형식의 API를 제공합니다. 각 필드에 대해 BSON 라이브러리에서 BSON type을 지정해야 합니다. 자주 사용되는 BSON 및 BSON 라이브러리 유형 간의 매핑은 다음 표를 참조하세요.

BSON type	BSON 라이브러리 유형
배열	`org.bson.BsonArray`
바이너리	`org.bson.BsonBinary`
부울	`org.bson.Boolean`
날짜(긴 값)	`org.bson.BsonDateTime`
문서	`org.bson.BsonDocument`
Double	`org.bson.BsonDouble`
Int32	`org.bson.BsonInt32`
Int64	`org.bson.BsonInt64`
Null	`org.bson.BsonNull`
ObjectId	`org.bson.BsonObjectId`
문자열	`org.bson.BsonString`

다음 코드 스니펫은 여러 가지 필드 유형이 포함된 문서를 나타내는 샘플 BsonDocument 인스턴스를 인스턴스화하고 빌드하는 방법을 보여 줍니다.

val author = BsonDocument()
    .append("_id", BsonObjectId())
    .append("name", BsonString("Gabriel García Márquez"))
    .append(
        "dateOfDeath",
        BsonDateTime(
            LocalDateTime.of(2014, 4, 17, 0, 0).atZone(ZoneId.of("America/New_York")).toInstant().toEpochMilli()
        )
    )
    .append(
        "novels", BsonArray(
            listOf(
                BsonDocument().append("title", BsonString("One Hundred Years of Solitude"))
                    .append("yearPublished", BsonInt32(1967)),
                BsonDocument().append("title", BsonString("Chronicle of a Death Foretold"))
                    .append("yearPublished", BsonInt32(1981)),
                BsonDocument().append("title", BsonString("Love in the Time of Cholera"))
                    .append("yearPublished", BsonInt32(1985))
            )
        )
    )

이 문서를 컬렉션에 삽입하려면 BsonDocument 클래스를 documentClass 매개 변수로 지정하는 getCollection() 메서드를 사용하여 컬렉션을 인스턴스화합니다. 그런 다음, insertOne 작업을 호출합니다.

// val mongoClient = <code to instantiate your client>
val database = mongoClient.getDatabase("fundamentals_data")
val collection = database.getCollection<BsonDocument>("authors")
val result: InsertOneResult = collection.insertOne(author)

삽입이 성공적으로 수행되면 다음 코드를 사용하여 컬렉션에서 샘플 문서 데이터를 조회할 수 있습니다.

// <MongoCollection setup code here>
val doc = collection.find(Filters.eq("name", "Gabriel García Márquez")).firstOrNull()
doc?.let {
    println("_id: ${it.getObjectId("_id").value}, name: ${it.getString("name").value}, dateOfDeath: ${Instant.ofEpochMilli(it.getDateTime("dateOfDeath").value).atZone(ZoneId.of("America/New_York")).toLocalDateTime()}")
    it.getArray("novels").forEach { novel ->
        val novelDocument = novel.asDocument()
        println("title: ${novelDocument.getString("title").value}, yearPublished: ${novelDocument.getInt32("yearPublished").value}")
    }
}

_id: 5fb5fad05f734e3794741a35, name: Gabriel García Márquez, dateOfDeath: 2014-04-17T00:00
title: One Hundred Years of Solitude, yearPublished: 1967
title: Chronicle of a Death Foretold, yearPublished: 1981
title: Love in the Time of Cholera, yearPublished: 1985

팁

앞의 코드 샘플에서는 반환된 유형을 확인하고 필드 값을 캐스팅할 수 없는 경우 BsonInvalidOperationException 을 발생시키는 헬퍼 메서드를 사용합니다. get() 메서드를 호출하여 값을 BsonValue 유형으로 조회하고 유형 검사를 건너뛸 수 있습니다.

이 섹션에 언급된 메서드 및 클래스에 대한 자세한 내용은 다음 API 문서를 참조하세요.

JsonObject

JsonObject 클래스는 JSON 문자열의 래퍼(wrapper) 역할을 합니다. JSON 데이터로만 작업하려는 경우 JsonObject를 사용하여 불필요한 데이터가 Map 객체로 변환되는 것을 방지할 수 있습니다.

기본값 으로 JsonObject 은 확장 JSON 을 저장합니다. JsonObjectCodec 를 지정하고 JsonWriterSettings 객체 를 전달하여 JsonObject 에서 JSON 형식을 사용자 지정할 수 있습니다. JSON 형식에 대한 자세한 내용은 확장 JSON 가이드 를 참조하세요.

다음 코드 스니펫은 다양한 유형의 키 값 쌍을 포함하는 확장 JSON 문자열을 래핑하는 샘플 JsonObject 인스턴스를 인스턴스화하는 방법을 보여 줍니다.

val ejsonStr = """
    {"_id": {"${"$"}oid": "6035210f35bd203721c3eab8"},
    "name": "Gabriel García Márquez",
    "dateOfDeath": {"${"$"}date": "2014-04-17T04:00:00Z"},
    "novels": [
        {"title": "One Hundred Years of Solitude","yearPublished": 1967},
        {"title": "Chronicle of a Death Foretold","yearPublished": 1981},
        {"title": "Love in the Time of Cholera","yearPublished": 1985}]}
    """.trimIndent()
val author = JsonObject(ejsonStr)

이 문서를 컬렉션에 삽입하려면 JsonObject 클래스를 documentClass 매개 변수로 지정하는 getCollection() 메서드를 사용하여 컬렉션을 인스턴스화합니다. 그런 다음, insertOne 작업을 호출합니다.

// val mongoClient = <code to instantiate your client>;
val database = mongoClient.getDatabase("fundamentals_data")
val collection= database.getCollection<JsonObject>("authors")
val result = collection.insertOne(author)

삽입이 성공적으로 수행되면 컬렉션에서 샘플 JSON 데이터를 검색할 수 있습니다. Bson을 확장하는 모든 클래스를 사용하여 쿼리를 지정할 수 있지만, 다음과 같이 JsonObject를 사용하여 데이터를 쿼리할 수 있습니다.

// val mongoClient = <code to instantiate your client>;
val query = JsonObject("{\"name\": \"Gabriel Garc\\u00eda M\\u00e1rquez\"}")
val jsonResult = collection.find(query).firstOrNull()
jsonResult?.let {
    println("query result in extended json format: " + jsonResult.json)
}

query result in extended json format: {"_id": {"$oid": "6035210f35bd203721c3eab8"}, "name": "Gabriel García Márquez", "dateOfDeath": {"$date": "2014-04-17T04:00:00Z"}, "novels": [{"title": "One Hundred Years of Solitude", "yearPublished": 1967}, {"title": "Chronicle of a Death Foretold", "yearPublished": 1981}, {"title": "Love in the Time of Cholera", "yearPublished": 1985}]}

이 섹션에 언급된 메서드 및 클래스에 대한 자세한 내용은 다음 API 문서를 참조하세요.

요약

이 가이드에서는 BSON 데이터로 작업하는 데 사용할 수 있는 클래스에 대한 다음 주제를 다루고 있습니다.

MongoDB 문서 작업에 사용할 수 있는 Kotlin 클래스와 어떤 클래스를 선호하는 것이 좋은지 설명합니다.
여러 유형을 포함하는 문서 작성, 이러한 문서를 컬렉션에 삽입, 유형이 지정된 필드 검색/액세스에 대한 각 클래스 사용법의 예시 제공.

돌아가기

문서 데이터 형식: 확장 JSON

코틀린(Kotlin) 직렬화