Documentos

Overview

En esta guía, puede aprender a utilizar documentos en el controlador Java de MongoDB.

Un documento de MongoDB es una estructura de datos que contiene campos clave-valor en formato JSON binario (BSON). Puede usar documentos y los datos que contienen en sus campos para almacenar datos, así como para ejecutar comandos o consultas en MongoDB.

Para obtener más información sobre la terminología, la estructura y las limitaciones de los documentos, lea nuestra página sobre Documentos en el manual de MongoDB.

El controlador Java de MongoDB y la biblioteca BSON incluyen las siguientes clases que le ayudan a acceder y manipular los datos BSON en los documentos:

Si bien puede usar cualquiera de estas clases en su aplicación, le recomendamos usar la clase Document, ya que puede representar de forma concisa documentos con estructura dinámica de cualquier complejidad. Implementa la interfaz Map<String, Object>, lo que le permite usar valores de tipo flexible.

Documento

La clase Document ofrece una representación flexible de un documento BSON. Con esta clase, puede acceder y manipular campos utilizando tipos Java de la biblioteca estándar. Consulte la siguiente tabla para ver las asignaciones entre los tipos BSON y Java más utilizados:

La tabla de mapeo anterior muestra la asignación predeterminada al trabajar con la clase Document. Puede personalizar la asignación de tipos especificando un códec personalizado. Para obtener más información sobre cómo personalizar los tipos mapeados, consulte nuestra guía sobre el uso de Códecs.

En el siguiente fragmento de código, mostramos cómo crear y crear una instancia de muestra Document que representa un documento que contiene varios tipos de campos diferentes:

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 insertar este documento en una colección, cree una colección usando el getCollection() método y llame a la operación insertOne de la siguiente manera:

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

Una vez que realice una inserción exitosa, puede recuperar los datos del documento de muestra de la colección utilizando el siguiente código:

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"));
        });
}

La salida del código anterior se parece a la siguiente:

_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 obtener más información sobre cómo recuperar y manipular datos de MongoDB, consulte nuestra guía CRUD.

Para obtener más información sobre los métodos y clases mencionados en esta sección, consulte la siguiente documentación de API:

• Documento

• getCollection()

• conseguir()

Documento Bson

La clase BsonDocument proporciona una API con seguridad de tipos para acceder y manipular un documento BSON. Debe especificar el tipo BSON de la biblioteca BSON de Java para cada campo. Consulte la siguiente tabla para ver las asignaciones entre los tipos BSON de uso frecuente y los tipos de la biblioteca BSON de Java:

En el siguiente fragmento de código, mostramos cómo crear y crear una instancia de muestra BsonDocument que representa un documento que contiene varios tipos de campos diferentes:

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 insertar este documento en una colección, instancia una colección utilizando el método getCollection() especificando la clase BsonDocument como el parámetro documentClass. Luego, llama a la operación insertOne de la siguiente manera:

// 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);

Una vez que realice una inserción exitosa, puede recuperar los datos del documento de muestra de la colección utilizando el siguiente código:

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());
    });
}

La salida del código anterior se parece a la siguiente:

_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 obtener más información sobre los métodos y clases mencionados en esta sección, consulte la siguiente documentación de API:

• Documento Bson

• getCollection()

• BsonInvalidOperationException

• conseguir()

• Valor de Bson

JsonObject

La clase JsonObject actúa como contenedor de cadenas JSON. Si solo desea trabajar con datos JSON, puede usar JsonObject para evitar la conversión innecesaria de datos a un objeto Map.

De forma predeterminada, JsonObject almacena JSON extendido. Puede personalizar el formato de JSON en JsonObject especificando un JsonObjectCodec y pasándole un JsonWriterSettings objeto. Para obtener más información sobre los formatos JSON, consulte nuestra guía de JSON extendido. Para obtener más información sobre la especificación de códecs, consulte nuestra guía de códecs.

En el siguiente fragmento de código, mostramos cómo crear una instancia de muestra JsonObject que envuelva una cadena JSON extendida que contenga diferentes tipos de pares clave-valor:

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 insertar este documento en una colección, instancia una colección utilizando el método getCollection() especificando la clase JsonObject como el parámetro documentClass. Luego, llama a la operación insertOne de la siguiente manera:

// 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);

Una vez realizada la inserción correctamente, podrá recuperar los datos JSON de muestra de la colección. Si bien puede usar cualquier clase que extienda Bson para especificar su consulta, aquí le mostramos cómo consultar sus datos usando 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());
}

La salida del código anterior se parece a la siguiente:

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 obtener más información sobre los métodos y clases mencionados en esta sección, consulte la siguiente documentación de API:

• JsonObject

• JsonObjectCodec

• Configuración de JsonWriter

• getCollection()

ObjetoDBBásico

La clase BasicDBObject permite acceder y manipular datos de documentos mediante tipos Java. Recomendamos evitar esta clase a menos que esté migrando una aplicación desde una versión anterior del controlador debido a las siguientes limitaciones:

• BasicDBObject no implementa Map<K, V> y por lo tanto carece de los métodos convenientes de acceso y manipulación de datos de un Map.

• Implementa la DBObject interfaz en lugar de una clase, por lo que no se puede extender la API sin afectar la compatibilidad binaria. Esto significa que si la interfaz se modifica de forma que afecte la compatibilidad binaria, todas las aplicaciones y clases que la usan deben recompilarse para ejecutar la nueva versión sin errores.

En el siguiente fragmento de código, mostramos cómo crear y crear una instancia de muestra BasicDBObject que representa un documento que contiene varios tipos de campos diferentes:

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 insertar este documento en una colección, instancia una colección utilizando el método getCollection() especificando la clase BasicDBObject como el parámetro documentClass. Luego, llama a la operación insertOne de la siguiente manera:

// 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);

Una vez que realice una inserción exitosa, puede recuperar los datos del documento de muestra de la colección utilizando el siguiente código:

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"));
        }
    }
}

La salida del código anterior se parece a la siguiente:

_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 obtener más información sobre los métodos y clases mencionados en esta sección, consulte la siguiente documentación de API:

• ObjetoDBBásico

• getCollection()

• conseguir()

Resumen

En esta guía, cubrimos los siguientes temas sobre las clases que puede utilizar para trabajar con datos BSON:

• Se describen cuatro clases Java que puedes usar para trabajar con documentos MongoDB y por qué podrías preferir una sobre la otra.

• Se proporcionan ejemplos de uso para cada clase sobre cómo construir documentos que contienen varios tipos, insertarlos en una colección y recuperar/acceder a sus campos tipados.