Documentos

Visão geral

Neste guia, você pode aprender como usar documentos no Driver Java MongoDB.

Um documento do MongoDB é uma estrutura de dados que contém campos de chave/valor no formato JSON binário (BSON). Você pode usar documentos e os dados que eles contêm em seus campos para armazenar dados, bem como para emitir comandos ou queries no MongoDB.

Para obter mais informações sobre a terminologia, estrutura e limitações de documentos, leia nossa página sobre Documentos no manual do MongoDB.

O driver Java do MongoDB e a biblioteca BSON incluem as seguintes classes que ajudam a acessar e manipular os dados BSON em documentos:

Embora possa usar qualquer uma dessas classes em seu aplicativo, recomendamos utilizar a classe Document, pois ela representa de forma concisa documentos estruturados dinamicamente de qualquer complexidade. Ela implementa a interface Map<String, Object>, o que lhe permite usar valores de tipos livres.

Documento

A classe Document oferece uma representação flexível de um documento BSON. Você pode acessar e manipular campos utilizando tipos Java da biblioteca padrão com esta classe. Consulte a tabela a seguir para mapeamentos entre os tipos BSON e Java usados com frequência:

A tabela de mapeamento anterior mostra o mapeamento padrão ao trabalhar com a classe Document . Você pode personalizar o mapeamento de tipo especificando um codec personalizado. Para obter mais informações sobre como personalizar os tipos mapeados, consulte o nosso guia sobre o uso de codecs.

No trecho de código abaixo, mostramos como instanciar e construir uma instância Document de amostra que representa um documento com vários tipos de campos:

Document author = new Document("_id", new ObjectId())
    .append("name", "Gabriel García Márquez")
    .append("dateOfDeath", Date.from(LocalDate.of(2014, 4, 17).atStartOfDay(ZoneId.systemDefault()).toInstant()))
    .append("novels", Arrays.asList(
        new Document("title", "One Hundred Years of Solitude").append("yearPublished", 1967),
        new Document("title", "Chronicle of a Death Foretold").append("yearPublished", 1981),
        new Document("title", "Love in the Time of Cholera").append("yearPublished", 1985)));

Para inserir esse documento em uma coleção, instancie uma coleção usando o método getCollection() e chame a operação insertOne da seguinte forma:

// MongoClient mongoClient = <code to instantiate your client>;
MongoDatabase database = mongoClient.getDatabase("fundamentals_data");
MongoCollection<Document> collection = database.getCollection("authors");
InsertOneResult result = collection.insertOne(author);

Depois de realizar uma inserção bem-sucedida, você pode recuperar os dados do documento de amostra da coleção usando o código a seguir:

import com.mongodb.client.model.Filters;
// <MongoCollection setup code here>
Document doc = collection.find(Filters.eq("name", "Gabriel García Márquez")).first();
if (doc != null) {
    System.out.println("_id: " + doc.getObjectId("_id")
        + ", name: " + doc.getString("name")
        + ", dateOfDeath: " + doc.getDate("dateOfDeath"));
    doc.getList("novels", Document.class).forEach((novel) -> {
        System.out.println("title: " + novel.getString("title")
            + ", yearPublished: " + novel.getInteger("yearPublished"));
        });
}

A saída do código anterior se assemelha ao seguinte:

_id: 5fb5fad05f734e3794741a35, name: Gabriel García Márquez, dateOfDeath: Thu Apr 17 00:00:00 EDT 2014
title: One Hundred Years of Solitude, yearPublished: 1967
title: Chronicle of a Death Foretold, yearPublished: 1981
title: Love in the Time of Cholera, yearPublished: 1985

Para obter mais informações sobre como recuperar e manipular dados do MongoDB, consulte nosso guia CRUD.

Para obter mais informações sobre os métodos e as classes mencionadas nesta seção, consulte a seguinte documentação da API:

• Documento

• getCollection()

• pegar()

Documento BSON

A classe BsonDocument fornece uma API segura por tipo para acessar e manipular um documento BSON. Você deve especificar o tipo BSON da biblioteca Java BSON para cada campo. Consulte a tabela a seguir para mapeamentos entre os tipos de biblioteca BSON e Java BSON usados com frequência:

No trecho de código abaixo, mostramos como instanciar e construir uma instância BsonDocument de amostra que representa um documento com vários tipos de campos:

BsonDocument author = new BsonDocument()
    .append("_id", new BsonObjectId())
    .append("name", new BsonString("Gabriel García Márquez"))
    .append("dateOfDeath", new BsonDateTime(LocalDate.of(2014, 4, 17).atStartOfDay(ZoneId.systemDefault()).toInstant().toEpochMilli()))
    .append("novels", new BsonArray(Arrays.asList(
        new BsonDocument().append("title", new BsonString("One Hundred Years of Solitude")).append("yearPublished", new BsonInt32(1967)),
        new BsonDocument().append("title", new BsonString("Chronicle of a Death Foretold")).append("yearPublished", new BsonInt32(1981)),
        new BsonDocument().append("title", new BsonString("Love in the Time of Cholera")).append("yearPublished", new BsonInt32(1985))
   )));

Para inserir este documento em uma coleção, instancie uma coleção utilizando o método getCollection() especificando a classe BsonDocument como o parâmetro documentClass. Em seguida, ligue para a operação insertOne da seguinte maneira:

// MongoClient mongoClient = <code to instantiate your client>;
MongoDatabase database = mongoClient.getDatabase("fundamentals_data");
MongoCollection<BsonDocument> collection = database.getCollection("authors", BsonDocument.class);
InsertOneResult result = collection.insertOne(author);

Depois de realizar uma inserção bem-sucedida, você pode recuperar os dados do documento de amostra da coleção usando o código a seguir:

import com.mongodb.client.model.Filters;
// <MongoCollection setup code here>
BsonDocument doc = collection.find(Filters.eq("name", "Gabriel García Márquez")).first();
if (doc != null) {
    System.out.println("_id: " + doc.getObjectId("_id").getValue()
            + ", name: " + doc.getString("name").getValue()
            + ", dateOfDeath: " + new Date(doc.getDateTime("dateOfDeath").getValue()));
    doc.getArray("novels").forEach((novel) -> {
        System.out.println("title: " + novel.asDocument().getString("title").getValue()
                + ", yearPublished: " + novel.asDocument().getInt32("yearPublished").getValue());
    });
}

A saída do código anterior se assemelha ao seguinte:

_id: 5fb5fad05f734e3794741a35, name: Gabriel García Márquez, dateOfDeath: Thu Apr 17 00:00:00 EDT 2014
title: One Hundred Years of Solitude, yearPublished: 1967
title: Chronicle of a Death Foretold, yearPublished: 1981
title: Love in the Time of Cholera, yearPublished: 1985

Para obter mais informações sobre os métodos e as classes mencionadas nesta seção, consulte a seguinte documentação da API:

• Documento BSON

• getCollection()

• Exceção de operação inválida do BSON

• pegar()

• BsonValor

JsonObject

A classe JsonObject age como um wrapper para strings JSON. Se você deseja trabalhar somente com dados JSON, use o JsonObject para evitar uma conversão de dados desnecessária para um objeto Map.

Por padrão, JsonObject armazena JSON estendido. Você pode personalizar o formato de JSON no JsonObject especificando um JsonObjectCodec e passando um objeto JsonWriterSettings . Para mais informações sobre formatos JSON, consulte nosso guia JSON estendido. Para obter mais informações sobre como especificar codecs, consulte nosso guia de codecs.

No trecho de código a seguir, mostramos como instanciar uma instância de JsonObject de exemplo encapsulando uma string JSON estendida contendo diferentes tipos de pares de valores de chave:

String ejsonStr = "{\"_id\": {\"$oid\": \"6035210f35bd203721c3eab8\"},"
        + "\"name\": \"Gabriel Garc\\u00eda M\\u00e1rquez\","
        + "\"dateOfDeath\": {\"$date\": \"2014-04-17T04:00:00Z\"},"
        + "\"novels\": ["
        + "{\"title\": \"One Hundred Years of Solitude\",\"yearPublished\": 1967},"
        + "{\"title\": \"Chronicle of a Death Foretold\",\"yearPublished\": 1981},"
        + "{\"title\": \"Love in the Time of Cholera\",\"yearPublished\": 1985}]}";
JsonObject author = new JsonObject(ejsonStr);

Para inserir este documento em uma coleção, instancie uma coleção utilizando o método getCollection() especificando a classe JsonObject como o parâmetro documentClass. Em seguida, ligue para a operação insertOne da seguinte maneira:

// MongoClient mongoClient = <code to instantiate your client>;
MongoDatabase database = mongoClient.getDatabase("fundamentals_data");
MongoCollection<JsonObject> collection = database.getCollection("authors", JsonObject.class);
InsertOneResult result = collection.insertOne(author);

Após executar uma inserção bem-sucedida, você pode recuperar a amostra de dados JSON da coleção. Enquanto você pode utilizar qualquer classe que estenda o Bson para especificar sua query, aqui está como executar query de seus dados utilizando um JsonObject:

// MongoClient mongoClient = <code to instantiate your client>;
JsonObject query = new JsonObject("{\"name\": \"Gabriel Garc\\u00eda M\\u00e1rquez\"}");
JsonObject jsonResult = collection.find(query).first();
if (jsonResult != null) {
    System.out.println("query result in extended json format: " + jsonResult.getJson());
}

A saída do código anterior se assemelha ao seguinte:

query result in extended json format: {"_id": {"$oid": "6035210f35bd203721c3eab8"}, "name": "Gabriel García Márquez", "dateOfDeath": {"$date": "2014-04-17T04:00:00Z"}, "novels": [{"title": "One Hundred Years of Solitude", "yearPublished": 1967}, {"title": "Chronicle of a Death Foretold", "yearPublished": 1981}, {"title": "Love in the Time of Cholera", "yearPublished": 1985}]}

import static org.bson.codecs.configuration.CodecRegistries.fromCodecs;
// MongoClient mongoClient = <code to instantiate your client>;
MongoDatabase database = mongoClient.getDatabase("fundamentals_data");
MongoCollection<JsonObject> collection = database.getCollection("authors", JsonObject.class)
        .withCodecRegistry(
                fromCodecs(
                        // define a JsonObjectCodec with a JsonWriterSettings in Relaxed mode
                        new JsonObjectCodec(JsonWriterSettings
                                .builder()
                                .outputMode(JsonMode.RELAXED)
                                .objectIdConverter((objectId, strictJsonWriter) -> {
                                    strictJsonWriter.writeString(objectId.toHexString());
                                })
                                .build())));
JsonObject author = new JsonObject("{\"_id\": \"6035210f35bd203721c3eab8\", "
        + "\"name\": \"Gabriel García Márquez\", "
        + "\"dateOfDeath\": {\"$date\": \"2014-04-17T04:00:00Z\"}, "
        + "\"novels\": [{\"title\": \"One Hundred Years of Solitude\", \"yearPublished\": 1967}, {\"title\": \"Chronicle of a Death Foretold\", \"yearPublished\": 1981}, "
        + "{\"title\": \"Love in the Time of Cholera\", \"yearPublished\": 1985}]}\n");
collection.insertOne(author);
JsonObject query = new JsonObject("{\"name\": \"Gabriel Garc\\u00eda M\\u00e1rquez\"}");
JsonObject jsonResult = collection.find(query).first();
if (jsonResult != null) {
    System.out.println("query result in relaxed json format: " + jsonResult.getJson());
}

query result in relaxed json format: {"_id": "6035210f35bd203721c3eab8", "name": "Gabriel García Márquez", "dateOfDeath": {"$date": "2014-04-17T04:00:00Z"}, "novels": [{"title": "One Hundred Years of Solitude", "yearPublished": 1967}, {"title": "Chronicle of a Death Foretold", "yearPublished": 1981}, {"title": "Love in the Time of Cholera", "yearPublished": 1985}]}

Para obter mais informações sobre os métodos e as classes mencionadas nesta seção, consulte a seguinte documentação da API:

• JsonObject

• JsonObjectCodec

• JsonWriterSettings

• getCollection()

Objeto de banco de dados básico

A classe BasicDBObject permite acessar e manipular dados do documento utilizando tipos Java. Recomendamos não usar essa classe, a menos que você esteja migrando um aplicativo de uma versão de driver mais antiga devido às seguintes limitações:

• BasicDBObject não implementa o Map<K, V> e, portanto, não tem acesso aos dados e métodos de conveniência de manipulação de um Map.

• Ele implementa a DBObject interface em vez de uma classe, portanto, você não pode estender a API sem quebrar a compatibilidade binária. Isso significa que, se a interface tiver sido alterada de uma forma que interrompa a compatibilidade binária, todos os aplicativos e classes que usam a interface deverão ser recompilados para executar a nova versão sem erros.

No trecho de código abaixo, mostramos como instanciar e construir uma instância BasicDBObject de amostra que representa um documento com vários tipos de campos:

BasicDBObject author = new BasicDBObject("_id", new ObjectId())
    .append("name", "Gabriel García Márquez")
    .append("dateOfDeath", Date.from(LocalDate.of(2014, 4, 17).atStartOfDay(ZoneId.systemDefault()).toInstant()))
    .append("novels", Arrays.asList(
        new BasicDBObject("title", "One Hundred Years of Solitude").append("yearPublished", 1967),
        new BasicDBObject("title", "Chronicle of a Death Foretold").append("yearPublished", 1981),
        new BasicDBObject("title", "Love in the Time of Cholera").append("yearPublished", 1985)));

Para inserir este documento em uma coleção, instancie uma coleção utilizando o método getCollection() especificando a classe BasicDBObject como o parâmetro documentClass. Em seguida, ligue para a operação insertOne da seguinte maneira:

// MongoClient mongoClient = <code to instantiate your client>;
MongoDatabase database = mongoClient.getDatabase("fundamentals_data");
MongoCollection<BasicDBObject> collection = database.getCollection("authors", BasicDBObject.class);
InsertOneResult result = collection.insertOne(author);

Depois de realizar uma inserção bem-sucedida, você pode recuperar os dados do documento de amostra da coleção usando o código a seguir:

import com.mongodb.client.model.Filters;
// <MongoCollection setup code here>
BasicDBObject doc = collection.find(Filters.eq("name", "Gabriel García Márquez")).first();
if (doc != null) {
    System.out.println("_id: " + doc.getObjectId("_id")
        + ", name: " + doc.getString("name")
        + ", dateOfDeath: " + doc.getDate("dateOfDeath"));
    BasicDBList novels = (BasicDBList) doc.get("novels");
    if (novels != null) {
        BasicDBObject[] novelArr = novels.toArray(new BasicDBObject[0]);
        for (BasicDBObject novel : novelArr) {
            System.out.println("title: " + novel.getString("title")
            + ", yearPublished: " + novel.getInt("yearPublished"));
        }
    }
}

A saída do código anterior se assemelha ao seguinte:

_id: 5fb5fad05f734e3794741a35, name: Gabriel García Márquez, dateOfDeath: Thu Apr 17 00:00:00 EDT 2014
title: One Hundred Years of Solitude, yearPublished: 1967
title: Chronicle of a Death Foretold, yearPublished: 1981
title: Love in the Time of Cholera, yearPublished: 1985

Para obter mais informações sobre os métodos e as classes mencionadas nesta seção, consulte a seguinte documentação da API:

• Objeto de banco de dados básico

• getCollection()

• pegar()

Resumo

Neste guia, descrevemos os seguintes tópicos de classes que você pode usar para trabalhar com dados BSON:

• Descreveu quatro classes Java que você pode usar para trabalhar com documentos do MongoDB, e por que uma classe pode ser melhor que a outra.

• Fornecer exemplos de uso para cada classe em documentos de construção contendo vários tipos, inserindo-os em uma coleção e recuperando/acessando seus campos digitados.