BSON

Visão geral

Neste guia, você pode aprender a criar documentos BSON, ler BSON de um arquivo e escrever BSON em um arquivo usando o PyMongo.

BSON, ou Binary JSON, é o formato de dados que o MongoDB usa para organizar e armazenar dados. Este formato de dados inclui todos os tipos de estrutura de dados JSON e adiciona suporte para tipos incluindo datas, inteiros de tamanhos diferentes, ObjectIds e dados binários. Você pode usar documentos BSON em seu aplicação Python incluindo o pacote BSON. Para obter uma lista completa dos tipos compatíveis, consulte a página de manual do servidor de tipos de BSON.

Os documentos BSON são armazenados em coleções MongoDB em formato binário, enquanto o PyMongo representa documentos BSON como dicionários Python. O PyMongo converte automaticamente os dicionários do Python em documentos BSON ao inseri-los em uma collection. Da mesma forma, quando você recupera um documento de uma coleção, o PyMongo converte o documento BSON de volta em um dicionário Python.

O exemplo a seguir mostra um documento nos formatos dicionário e BSON. Use a aba Dictionary ou BSON para ver o formato correspondente:

{"hello": "world"}

\x16\x00\x00\x00           # total document size
\x02                       # 0x02 = type String
hello\x00                  # field name
\x06\x00\x00\x00world\x00  # field value
\x00                       # 0x00 = type EOO ("end of object")

Dados de amostra

As amostras de código neste guia usam o seguinte documento BSON como exemplo:

{
    "address" : {
        "street" : "Pizza St",
        "zipcode" : "10003"
    },
    "coord" : [-73.982419, 41.579505]
    "cuisine" : "Pizza",
    "name" : "Mongo's Pizza"
}

Crie um documento BSON

Você pode criar um documento BSON usando a mesma notação usada para criar um dicionário no Python. O exemplo a seguir cria um documento BSON que representa o documento BSON de amostra anterior:

document = {
    "address": {
        "street": "Pizza St",
        "zipcode": "10003"
    },
    "coord": [-73.982419, 41.579505],
    "cuisine": "Pizza",
    "name": "Mongo's Pizza"
}

Altere um documento BSON

Você pode modificar o conteúdo de um documento BSON usando a mesma notação usada para modificar um dicionário no Python. O exemplo a seguir faz três alterações no documento BSON de amostra :

Adiciona um novo campo, restaurant_id, com o valor 12345
Remove o campo cuisine
Define o valor do campo name como "Mongo's Pizza Place"

document["restaurant_id"] = 12345
del document["cuisine"]
document["name"] = "Mongo's Pizza Place"

Grave BSON em um arquivo

Para escrever dados BSON em um arquivo, abra um fluxo de arquivo no modo binário de escrita no arquivo de saída. Em seguida, escreva cada documento no arquivo de saída. Certifique-se de que os documentos estejam codificados no formato BSON usando o método bson.encode().

O exemplo seguinte grava o documento BSON de amostra no file.bson:

with open("file.bson", "w") as file:
    file.write(bson.encode(document))

Leia BSON de um arquivo

Para ler documentos BSON de um arquivo, abra um fluxo de arquivo no modo binário de leitura no arquivo de entrada. Em seguida, decodifique os documentos do formato BSON conforme você os lê usando o método bson.decode() .

O exemplo a seguir lê o documento BSON de amostra de file.bson:

   with open("file.bson", "rb") as file:
       data = file.read()
       document = bson.decode(data)
       print(document)

{"address": {"street": "Pizza St", "zipcode": "10003"}, "coord": [-73.982419, 41.579505], "cuisine": "Pizza", "name": "Mongo's Pizza"}

Use dados BSON brutos

O PyMongo suporta o uso de documentos BSON brutos. A lista a seguir contém algumas situações que podem exigir o uso de documentos BSON brutos:

Movendo um documento entre bancos de dados ou coleções
Escrevendo dados binários em um disco
Ignorando a sobrecarga de desempenho da conversão de e para dicionários Python

A classe RawBSONDocument é uma representação de um documento BSON que fornece acesso aos bytes BSON brutos subjacentes. Para utilizar objetos RawBSONDocument para representar documentos em sua coleção, configure o parâmetro document_class do construtor MongoClient para RawBSONDocument.

Observação

RawBSONDocument os objetos são somente leitura. Para modificar um RawBSONDocument, você deve primeiro convertê-lo em um dicionário Python.

O exemplo a seguir configura um objeto MongoClient para usar objetos RawBSONDocument para modelar a coleção e, em seguida, recupera o documento de amostra dos exemplos anteriores:

from bson.raw_bson import RawBSONDocument
client = pymongo.MongoClient("<connection URI>", document_class=RawBSONDocument)
collection = client.sample_restaurants.restaurants
raw_doc = collection.find_one({"name": "Mongo's Pizza"})
print(type(raw_doc))

<class 'bson.raw_bson.RawBSONDocument'>

Documentação da API

Para saber mais sobre qualquer um dos métodos ou tipos discutidos neste guia, consulte a documentação da API BSON.

Voltar

Data Formats

Extended JSON