BSON

Visão geral

Neste guia, você pode aprender a criar documentos BSON, gravar documentos BSON em um arquivo e ler dados BSON de um arquivo usando o driver C.

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. Para obter uma lista completa dos tipos compatíveis, consulte a página de manual do servidor BSON Types.

Você pode usar documentos BSON em seu aplicativo C incluindo o libbson pacote.

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

Os documentos BSON são representados pelo tipo bson_t no driver C. Você pode utilizar a função BCON_NEW() para criar uma instância do bson_t. O exemplo a seguir cria uma representação bson_t do documento BSON de amostra :

bson_t *doc = BCON_NEW( "address", "{",
    "street", BCON_UTF8("Pizza St"),
    "zipcode", BCON_UTF8("10003"), "}",
    "coord", "[", BCON_DOUBLE(-73.982419), BCON_DOUBLE(41.579505), "]",
    "cuisine", BCON_UTF8("Pizza"),
    "name", BCON_UTF8("Mongo's Pizza")
);

Observação

Valores do campo BSON

Ao criar ou anexar campos a um documento BSON, certifique-se de utilizar a função BCON_* apropriada para representar os valores de campo corretamente. Para obter uma lista completa das funções BCON_*, consulte o arquivo bson-bcon.h no repositório GitHub do driver C.

Anexar a um documento BSON

Você pode anexar pares campo-valor a uma instância bson_t existente usando a função BCON_APPEND(). O exemplo a seguir anexa um novo campo yearEstablished e valor ao documento BSON de amostra :

BCON_APPEND(doc, "yearEstablished", BCON_INT32(1996));

Você também pode utilizar a função bson_append_* que corresponde ao tipo de dados do valor a ser anexado. O exemplo seguinte adiciona o mesmo par campo-valor do exemplo anterior utilizando a função bson_append_int32():

bson_append_int32(doc, "yearEstablished", -1, 1996);

For a complete list of bson_append_* functions, see bson_t in the libbson API documentation.

Grave BSON em um arquivo

Você pode usar a função bson_get_data() com a biblioteca de E/S de arquivo C padrão para gravar dados BSON em um arquivo. O exemplo a seguir grava o documento BSON de amostra em um arquivo chamado output.bson:

FILE *fp;
if ((fp = fopen("output.bson", "wb"))) {
    fwrite(bson_get_data(doc), 1, doc->len, fp);
    fclose(fp);
} else {
    fprintf(stderr, "Failed to open file for writing.\n");
    return EXIT_FAILURE;
}

Leia BSON de um arquivo

Você pode usar o tipo bson_reader_t para ler uma sequência de documentos BSON de um arquivo, região de memória ou um chamada de resposta personalizado. O exemplo a seguir lê documentos BSON de um arquivo chamado example.bson e imprime a representação JSON de cada documento:

bson_reader_t *reader;
bson_error_t error;
const bson_t *b;
char *str;
if (!((reader = bson_reader_new_from_file("example.json", &error)))) {
    fprintf(stderr, "Failed to open file: %s\n", error.message);
    return EXIT_FAILURE;
}
while ((b = bson_reader_read(reader, NULL))) {
    str = bson_as_canonical_extended_json(b, NULL);
    fprintf(stdout, "%s\n", str);
    bson_free(str);
}
bson_reader_destroy(reader);

Lendo JSON de um arquivo

Você pode usar o tipo bson_json_reader_t para ler uma sequência de documentos JSON e convertê-los em documentos bson_t. O exemplo a seguir lê documentos JSON de um arquivo chamado example.json, converte cada documento para o formato BSON e imprime os documentos:

bson_json_reader_t *reader;
int b;
bson_error_t error;
bson_t doc = BSON_INITIALIZER;
if (!((reader = bson_json_reader_new_from_file("example.json", &error)))) {
    fprintf(stderr, "Failed to open file: %s\n", error.message);
    return EXIT_FAILURE;
}
while ((b = bson_json_reader_read(reader, &doc, &error))) {
    if (b < 0) {
        fprintf(stderr, "Failed to parse JSON: %s\n", error.message);
        abort();
    }
    if (fwrite(bson_get_data(&doc), 1, doc.len, stdout) != doc.len) {
        fprintf(stderr, "Failed to write BSON to stdout, exiting.\n");
        exit(1);
    }
    bson_reinit(&doc);
}
bson_json_reader_destroy(reader);
bson_destroy(&doc);

Aviso

Validar entrada não confiável antes de converter JSON em BSON

Se você converter uma string JSON em BSON e utilizar o BSON resultante em uma query, atualização ou comando, um invasor poderá injetar operadores ou valores de campo inesperados que alteram o significado da operação. Esse risco é maior quando o JSON se origina de um usuário, de uma solicitação de API ou de outra fonte não confiável.

To learn more about validating input before conversion, see Validate Untrusted Input Before Converting JSON to BSON.

Limpeza

Você pode liberar a memória alocada para um documento BSON usando a função bson_destroy(), como mostrado no seguinte exemplo:

bson_t *doc = BCON_NEW("test", BCON_UTF8("example"));
// Operations using doc
bson_destroy(doc);

Importante

Sempre chame bson_destroy() em uma instância bson_t quando terminar de usá-la para evitar vazamentos de memória em seu aplicativo.

Documentação da API

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

Voltar

Agregação

Extended JSON