Trabalhe com BSON

Visão geral

Neste guia, você aprenderá como o driver Go lida com conversões entre os tipos BSON e Go. O processo de conversão de um tipo Go para BSON é chamado de ordenação, enquanto o processo inverso é chamado de desordenação.

As seções a seguir explicam como o driver Go representa os dados BSON e como você pode ajustar os comportamentos padrão de ordenação e desordenação.

Tipos de dados

O MongoDB armazena documentos em uma representação binária denominada BSON que permite o processamento de dados fácil e flexível.

O driver Go oferece quatro tipos principais de trabalho com dados BSON:

• D: Uma representação ordenada de um documento BSON (fatia)

• M: Uma representação não ordenada de um documento BSON (mapa)

• A: Uma representação ordenada de uma array BSON

• E: Um único elemento dentro de um tipo D

O exemplo abaixo mostra como criar um filtro de queries utilizando o tipo bson.D para corresponder documentos em que o valor do campo quantity é maior que 100:

filter := bson.D{{"quantity", bson.D{{"$gt", 100}}}}

Para saber mais sobre como o driver Go lida com os dados BSON, consulte a documentação da API do pacote bson.

Marcações de estrutura

No Go, uma estrutura é uma collection de campos de dados com tipos de dados declarados. Você pode modificar o comportamento padrão de transferência e remoção de transferência de um campo de estrutura usando marcações de estrutura, que são partes opcionais de metadados anexadas aos campos de estrutura. O uso mais comum de marcações de estrutura é especificar o nome do campo no documento BSON que corresponde ao campo estruturado. A tabela a seguir descreve as marcações de estrutura adicionais que você pode usar no driver Go:

Se você não especificar marcações de estrutura, o driver Go organizará as estruturas usando as seguintes regras:

1. O driver apenas ordena e desordena os campos exportados.

2. O driver gera uma chave BSON utilizando a letra minúscula do campo de estrutura correspondente.

3. O driver ordena campos de estrutura integrados como subdocumentos. Cada chave é a letra minúscula do tipo de campo.

4. O driver ordena um campo de ponteiro como o tipo subjacente se o ponteiro for diferente de nulo. Se o ponteiro for nulo, o driver o ordenará como um valor nulo BSON.

5. Ao desordenar, o driver Go segue esses mapeamentos tipo D/M para campos do tipo interface{}. O driver desordena documentos BSON desordenados em um campo interface{} como um tipo D.

type Address struct {
       Street string
       City   string
       State  string
}
type Student struct {
       FirstName string  `bson:"first_name,omitempty"`
       LastName  string  `bson:"last_name,omitempty"`
       Address   Address `bson:"inline"`
       Age       int
}
coll := client.Database("db").Collection("students")
address1 := Address{ "1 Lakewood Way", "Elwood City", "PA" }
student1 := Student{ FirstName : "Arthur", Address : address1, Age : 8}
_, err = coll.InsertOne(context.TODO(), student1)

{
  "_id" : ObjectId("..."),
  "first_name" : "Arthur",
  "street" : "1 Lakewood Way",
  "city" : "Elwood City",
  "state" : "PA",
  "age" : 8
}

type Address struct {
       Street string
       City   string
       State  string
}
type Student struct {
       FirstName string
       LastName  string
       Address   Address
       Age       int
}
coll := client.Database("db").Collection("students")
address1 := Address{ "1 Lakewood Way", "Elwood City", "PA" }
student1 := Student{ FirstName : "Arthur", Address : address1, Age : 8}
_, err = coll.InsertOne(context.TODO(), student1)

{
  "_id" : ObjectId("..."),
  "firstname" : "Arthur",
  "lastname" : "",
  "address": {
               "street" : "1 Lakewood Way",
               "city" : "Elwood City",
               "state" : "PA"
             },
  "age" : 8
}

Opções de JSON

Você pode especificar opções BSON para ajustar o comportamento de ordenação e desordenação de sua instância Client. Para definir opções de BSON no seu Client, crie e configure uma instância do BSONOptions.

Este exemplo executa as seguintes ações:

• Cria uma instância BSONOptions definindo as seguintes configurações:

  • Define o campo UseJSONStructTags como true, que instrui o driver a usar a marcação "json" de estrutura se uma marcação "bson" de estrutura não for especificada

  • Define o campo NilSliceAsEmpty como true, que instrui o driver a ordenar fatias nil Go como arrays BSON vazias

• Passa a instância BSONOptions para o método auxiliar SetBSONOptions() para especificar uma instância ClientOptions

• Cria um Client para aplicar o comportamento de ordenação e desordenação de BSON especificado

bsonOpts := &options.BSONOptions {
    UseJSONStructTags: true,
    NilSliceAsEmpty: true,
}
clientOpts := options.Client().
    ApplyURI("<connection string>").
    SetBSONOptions(bsonOpts)
client, err := mongo.Connect(context.TODO(), clientOpts)

Desordenação

Você pode desordenar documentos BSON utilizando o método Decode() no resultado do método FindOne ou qualquer instância *mongo.Cursor.

O método Decode() retorna um tipo de error que contém um dos seguintes valores:

• nil se um documento corresponder à sua query e não houver erros ao recuperar e desordenar o documento.

• Se o driver recuperou o documento, mas não pôde desordenar o resultado, o método Decode() retorna o erro de desordenação.

• Se houver um erro ao recuperar seu documento durante a execução do método FindOne(), o erro se propagará para o método Decode() e o método Decode() retornará o erro.

Quando utilizado no tipo SingleResult retornado pelo método FindOne(), o Decode() também pode retornar o erro ErrNoDocuments se nenhum documento corresponder ao filtro de query.

O exemplo seguinte demonstra como você pode utilizar o método Decode() para desordenar e ler o resultado de uma operação simples do FindOne():

coll := client.Database("db").Collection("students")
filter := bson.D{{"age", 8}}
var result bson.D
err := coll.FindOne(context.TODO(), filter).Decode(&result)
fmt.Println(result)

[{_id ObjectID("...")} {first_name Arthur} {street 1 Fern Way} {city Elwood City} {state PA} {age 8}]

O tipo Cursor também utiliza o método All(), que une todos os documentos armazenados no cursor em uma array ao mesmo tempo.

O pacote bson inclui uma família de métodos Marshal() e Unmarshal() que funcionam com dados codificados por BSONs do tipo []byte.

O código a seguir demonstra como você pode desordenar o BSON de volta para uma estrutura definida pelo usuário usando métodos do pacote bson:

type Item struct {
   Category string
   Quantity int32
}
doc, err := bson.Marshal(bson.D{{"category", "plate"}, {"quantity", 6}})
var test Item
err = bson.Unmarshal(doc, &test)
fmt.Printf("Unmarshalled Struct:\n%+v\n", test)

Unmarshalled Struct:
{Category:plate Quantity:6}

Para saber mais sobre os métodos de ordenação e desordenação usados com o tipo Cursor, consulte a documentação da API do cursor

Para saber mais sobre os métodos de ordenação e desordenação no pacote bson, consulte a documentação da API do bson