Trabalhe com BSON

Visão geral

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

Leia este guia se quiser saber mais sobre como o Go Driver representa dados BSON ou se precisar 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 a seguir demonstra como construir um filtro de query usando o tipo bson.D para corresponder a documentos com um valor de 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. O Go Driver pode organizar/desordenar estruturas e outros tipos nativos do Go de/para o BSON usando um sistema de codec configurável.

Você pode modificar o comportamento padrão de transferência e remoção de transferência do Go Driver 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 com o Go Driver:

Sem instruções adicionais de marcações de estrutura, o Go Driver organizará as estruturas usando as seguintes regras:

1. O Go Driver apenas ordena e desordena os campos exportados.

2. O Go Driver gera a chave BSON usando a letra minúscula do campo de estrutura correspondente.

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

4. O Go Driver ordena um campo de ponteiro como o tipo subjacente se o ponteiro não for nulo. Se o ponteiro for nulo, o driver o organizará como um valor nulo BSON.

5. Ao desordenar, o Go Driver 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 .

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("school").Collection("students")
filter := bson.D{{"age", 8}}
var result bson.D
err := coll.FindOne(context.TODO(), filter).Decode(&result)
fmt.Println(result)

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)

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