BSON 데이터로 작업하기

개요

이 가이드 에서는 MongoDB Rust 드라이버 와 bson 크레이트가 BSON 데이터를 표현하는 방법, BSON 과 Rust 유형을 변환하는 방법, 애플리케이션 코드에서 직접 BSON 문서로 작업하는 방법을 학습 수 있습니다.

운전자 bson 크레이트를 사용하여 BSON 데이터를 인코딩 및 디코딩하고, Serde 프레임워크 사용하여 Rust 유형을 직렬화 및 역직렬화합니다. 직렬화에 대해 자세히 학습 데이터 모델링 및 직렬화 가이드 참조하세요.

BSON 및 전체 BSON 유형 목록에 대한 자세한 내용은 MongoDB Server 매뉴얼에서BSON 유형을 참조하세요.

let mut restaurant: Document = doc! {
    "address": {
        "street": "Pizza St",
        "zipcode": "10003",
    },
    "coord": [-73.982_419_f64, 41.579_505_f64],
    "cuisine": "Pizza",
    "name": "Mongo's Pizza",
};

BSON 데이터 유형

MongoDB BSON (Binary JSON)이라는 바이너리 표현으로 문서를 저장합니다. BSON 모든 JSON 데이터 구조 유형을 지원하며 날짜, 다른 크기의 정수, ObjectId 값, 바이너리 데이터 등과 같은 추가 유형을 추가합니다.

Rust 에코시스템 에서 bson 크레이트는 bson::Bson 열거형 사용하여 BSON 값을 모델링하고 bson::Document 구조체를 사용하여 BSON 문서를 모델링합니다.

Rust 에서 BSON 표현하기

bson 크레이트는 BSON 데이터 작업을 위한 다음과 같은 핵심 유형과 매크로를 제공합니다.

• bson::Bson: 문자열, 정수, 문서 또는 배열 과 같은 BSON 값을 나타내는 열거형입니다.

• bson::Document: UTF-8 문자열 키에서 BSON 문서 나타내는 Bson 값으로 정렬된 맵입니다.

• bson! 매크로: 리터럴에서 Bson 값을 생성합니다.

• doc! 매크로: 리터럴에서 Document 를 구성합니다.

예시 들어,doc! 매크로를 사용하여 restaurant 이 가이드 의 시작 부분에표시된 샘플 문서 구성할 수 있습니다.

다음 예시 와 같이 헬퍼 메서드를 사용하여 유형이 지정되지 않은 Bson 값 또는 강력한 유형의 Rust 값으로 Document 의 필드에 액세스 할 수 있습니다.

let value = restaurant.get("cuisine"); // Option<&Bson>
let name = restaurant.get_str("name")?; // &str
let address = restaurant.get_document("address")?; // &Document
let zipcode = address.get_str("zipcode")?; // &str

BSON 문서 수정

다음 예시 와 같이 삽입, 교체, 제거와 같은 표준 맵과 유사한 작업을 사용하여 Document 의 내용을 수정할 수 있습니다.

restaurant = Document = doc! {
    "address": {
        "street": "Pizza St",
        "zipcode": "10003",
    },
    "coord": [-73.982_419_f64, 41.579_505_f64],
    "cuisine": "Pizza",
    "name": "Mongo's Pizza",
};
// Adds a new field restaurant_id
restaurant.insert("restaurant_id", Bson::Int32(12345));
// Removes the cuisine field
restaurant.remove("cuisine");
// Updates the name field
if let Some(name) = restaurant.get_mut("name") {
    *name = Bson::String("Mongo's Pizza Place".to_string());
}

Rust 유형을 사용하여 BSON 문서 모델링하기

Document 값으로 직접 작업하는 대신 사용자 지정 Rust 유형을 사용하여 컬렉션 데이터를 모델링할 수 있습니다. 운전자 와 bson 크레이트는 Serde와 통합되어 유형을 BSON 으로 직렬화하고 BSON 다시 해당 유형으로 역직렬화합니다. 사용자 지정 유형을 mongodb::Collection의 일반 매개변수로 사용하려면 구조체에서 serde::Serialize 및 serde::Deserialize 특성을 파생합니다.

다음 예시 name, cuisine 및 last_updated 필드를 포함하는 Restaurant 구조체를 정의하고, 이 구조체를 사용하여 컬렉션 매개변수화한 다음, 현재 타임스탬프를 로 사용하여 Restaurant 문서 구성하고 삽입합니다. last_updated 값:

#[derive(Serialize, Deserialize)]
struct Restaurant {
    name: String,
    cuisine: String,
    last_updated: DateTime,
}
async fn use_collection(client: &Client) -> mongodb::error::Result<()> {
    let coll: Collection<Restaurant> = client
        .database("sample_restaurants")
        .collection("restaurants");
    let doc = Restaurant {
        name: "Mongo's Pizza".to_string(),
        cuisine: "Pizza".to_string(),
        last_updated: DateTime::now(),
    };
    coll.insert_one(doc).await?;
    Ok(())
}

사용자 지정 유형을 사용하여 컬렉션 매개 변수화하면 운전자 쓸 때 자동으로 유형을 BSON 으로 직렬화하고 읽을 때 BSON 다시 유형으로 역직렬화합니다.

직렬화 동작 사용자 지정

bson 크레이트는 Serialize 및 Deserialize를 구현 ObjectId 및 DateTime와 같은 BSON 값 유형을 나타내는 Rust 유형을 제공합니다. 이러한 유형을 도메인 구조체에 직접 포함하여 필드가 BSON 으로 직렬화 및 역직렬화되는 방식을 제어할 수 있습니다.

다음 예시 _id 필드 에 ObjectId 유형을 사용하고 delivery_date 필드 에 DateTime 유형을 사용하는 Order 구조체를 정의하여 이러한 필드가 해당 BSON types로 저장되고 검색되도록 합니다.

#[derive(Serialize, Deserialize)]
struct Order {
    _id: ObjectId,
    item: String,
    delivery_date: DateTime,
}

필드 이름 바꾸기, 필드 건너뛰기, 헬퍼 함수 사용 방법과 같은 추가 사용자 지정 옵션은 데이터 모델링 및 직렬화 가이드 참조하세요.

UUID 값으로 작업

bson 크레이트는 UUID 유형으로 UUID 값을 모델링하며, 이는 하위 유형이 0x(UUID)인 BSON 바이너리 값에04 해당합니다. 적절한 기능 플래그를 사용하면 uuid bson::uuid 모듈을 통해 크레이트와 통합할 수도 있습니다.

다음 예시 와 같이 도메인 유형에 UUID 값을 직접 포함할 수 있습니다.

#[derive(Serialize, Deserialize)]
struct Session {
    id: Uuid,
    user_id: Uuid,
    created_at: DateTime,
}

운전자 와 bson 이 Serde와 통합되므로 UUID 값은 자동으로 BSON 바이너리 UUID로 직렬화되고 적절한 Rust 유형으로 다시 역직렬화됩니다.

원시 BSON 데이터로 작업

성능에 민감한 워크로드의 경우, BSON 문서를 강력한 유형의 Rust 구조체로 완전히 역직렬화하지 않고 검사하거나 유효성을 검사할 수 있습니다. bson 크레이트는 이러한 목적으로 다음과 같은 원시 유형을 노출합니다.

• RawDocument - 와(과) 유사한 BSON 문서 의 빌린 슬라이스 str

• RawDocumentBuf - 와(과) 유사한 BSON 문서 소유합니다.String

• RawBsonRef - 단일 원시 BSON 값에 대한 빌린 참조입니다.

다음 예시 와 같이 바이트 슬라이스 또는 Vec<u8> 에서 RawDocumentBuf 를 만든 다음 키별로 필드를 조회할 수 있습니다.

fn inspect_raw(bytes: Vec<u8>) -> Result<(), mongodb::bson::error::Error> {
    let raw = RawDocumentBuf::from_bytes(bytes)?;
    if let Some(name) = raw.get_str("name").ok() {
        println!("Restaurant name: {name}");
    }
    Ok(())
}

이러한 원시 API를 사용하면 전체 문서를 상위 수준 Rust 유형으로 할당하거나 역직렬화하지 않고도 특정 필드 액세스 하고 문서 구조의 유효성을 검사할 수 있습니다.

파일에 BSON 쓰기

또는 Serde 직렬화 가능 유형을 BSON 와이어 형식 표현으로 직렬화하여 디스크에 쓰기 (write) 수 있습니다.Document bson 크레이트는 문서 BSON 바이트 표현으로 인코딩하는 Document::to_vec() 메서드를 제공합니다.

다음 예시 샘플 레스토랑 문서 파일 에 씁니다.

fn write_bson_to_file(path: &str) -> std::io::Result<()> {
    let restaurant: Document = doc! {
        "address": {
            "street": "Pizza St",
            "zipcode": "10003",
        },
        "coord": [-73.982_419_f64, 41.579_505_f64],
        "cuisine": "Pizza",
        "name": "Mongo's Pizza",
    };
    // Encodes the document as BSON bytes
    let bytes = restaurant.to_vec()
        .expect("failed to encode document to BSON");
    fs::write(path, &bytes)
}

파일에서 BSON 읽기

파일 에서 BSON 데이터를 읽으려면 원시 바이트를 로드한 다음 Document 또는 다른 Serde 직렬화 가능 유형으로 디코딩할 수 있습니다. bson 크레이트는 인메모리 버퍼 또는 판독기에서 직접 문서 읽기를 지원합니다.

다음 예시 디스크에서 BSON 문서 읽고 디버깅을 위해 확장 JSON 으로 출력합니다.

fn read_bson_from_file(path: &str) -> Result<(), Box<dyn std::error::Error>> {
    let bytes = fs::read(path)?;
    let mut cursor = Cursor::new(bytes);
    // Decodes a single document from the reader
    let doc = Document::from_reader(&mut cursor)?;
    // Converts to relaxed Extended JSON for logging
    let bson_value = Bson::Document(doc);
    let json = bson_value.into_relaxed_extjson(); // serde_json::Value
    println!("{}", json);
    Ok(())
}

bson 크레이트의 인코딩 및 디코딩 헬퍼는 MongoDB 드라이버 및 기타 BSON 라이브러리와 상호 운용되도록 설계되었으므로 디스크와 네트워크 모두에서 동일한 BSON 표현을 사용할 수 있습니다.

추가 리소스

이 가이드 에 설명된 유형 및 메서드에 대해 자세히 학습 다음 문서를 참조하세요.

• 데이터 모델링 및 직렬화 가이드

• ,, 원시 유형, UUID 및 확장 JSON 헬퍼에대한 bson crate API 문서 BsonDocument

• MongoDB Server매뉴얼의 BSON types