Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

Trabajo con documentos

Como base de datos de documentos, Amazon DocumentDB facilita el almacenamiento, la consulta y la indexación de datos JSON. En Amazon DocumentDB, una colección es similar a una tabla de una base de datos relacional, con la salvedad de que no se aplica ningún esquema a todos los documentos. Las colecciones le permiten agrupar documentos similares manteniéndolos en la misma base de datos, sin necesidad de que tengan la misma estructura.

Sigamos con los documentos de ejemplo de las secciones anteriores y suponga ahora que tiene colecciones para reading_material y office_supplies. Es responsabilidad de su software decidir a qué colección pertenece un documento.

En los siguientes ejemplos se utiliza la API de MongoDB para mostrar cómo añadir, consultar, actualizar y eliminar documentos.

Adición de documentos

En Amazon DocumentDB, se crea una base de datos cuando se agrega por primera vez un documento a una colección. En este ejemplo, está creando una colección denominada example en la base de datos test, que es la base de datos predeterminada cuando se conecta a un clúster. Dado que la conexión se crea implícitamente cuando se inserta el primer documento, no hay comprobación de errores del nombre de la colección. Por lo tanto, un error tipográfico en el nombre de la colección, como eexample en lugar de example, creará y agregará el documento a la colección eexample en lugar de la colección prevista. La comprobación de errores debe realizarla su aplicación.

En los ejemplos siguientes, se utiliza la API de MongoDB para añadir documentos.

Adición de un solo documento

Para añadir un único documento a una colección, utilice la operación insertOne( {} ) con el documento que desea añadir a la colección.

db.example.insertOne(
    {
        "Item": "Ruler",
        "Colors": ["Red","Green","Blue","Clear","Yellow"],
        "Inventory": {
            "OnHand": 47,
            "MinOnHand": 40
        },
        "UnitPrice": 0.89
    }
)

La salida de esta operación será similar a lo que se indica a continuación (formato JSON).

{
    "acknowledged" : true,
    "insertedId" : ObjectId("5bedafbcf65ff161707de24f")
}

Adición de varios documentos

Para añadir varios documentos a una colección, utilice la operación insertMany( [{},...,{}] ) con una lista de los documentos que desea añadir a la colección. Aunque los documentos de esta lista en particular tengan diferentes esquemas, se pueden añadir a la misma colección.

db.example.insertMany(
    [
        {
            "Item": "Pen",
            "Colors": ["Red","Green","Blue","Black"],
            "Inventory": {
                "OnHand": 244,
                "MinOnHand": 72 
            }
        },
        {
            "Item": "Poster Paint",
            "Colors": ["Red","Green","Blue","Black","White"],
            "Inventory": {
                "OnHand": 47,
                "MinOnHand": 50 
            }
        },
        {
            "Item": "Spray Paint",
            "Colors": ["Black","Red","Green","Blue"],
            "Inventory": {
                "OnHand": 47,
                "MinOnHand": 50,
                "OrderQnty": 36
            }
        }    
    ]
)

La salida de esta operación será similar a lo que se indica a continuación (formato JSON).

{
    "acknowledged" : true,
    "insertedIds" : [
            ObjectId("5bedb07941ca8d9198f5934c"),
            ObjectId("5bedb07941ca8d9198f5934d"),
            ObjectId("5bedb07941ca8d9198f5934e")
    ]
}

Consulta de documentos

A veces, es posible que tenga que examinar el inventario de su tienda online para que los clientes puedan ver y comprar lo que usted vende. Consultar una colección es relativamente fácil, tanto si desea consultar todos los documentos de la colección como solo aquellos que cumplan un determinado criterio.

Para consultar documentos, utilice la operación find(). El comando find() tiene un único parámetro de documento que define los criterios que se utilizan al elegir los documentos que se devuelven. El resultado de find() es un documento formateado como una sola línea de texto sin saltos de línea. Para formatear el documento resultante para facilitar su lectura, utilice find().pretty(). En todos los ejemplos que se muestran en este tema, se utiliza .pretty() para formatear la salida.

Utilice los cuatro documentos que insertó en la colección example de los dos ejercicios anteriores insertOne() e insertMany().

Recuperar todos los documentos de una colección

Para recuperar todos los documentos de la colección, utilice la operación find() con un documento de consulta vacío.

La siguiente consulta devuelve todos los documentos de la colección example.

db.example.find( {} ).pretty()

Recuperación de documentos que coincidan con un valor de campo

Para recuperar todos los documentos que coincidan con un campo y valor, utilice la operación find() con un documento de consulta que identifique los campos y valores que desee.

Si se utilizan los documentos anteriores, esta consulta devuelve todos los documentos cuyo campo "Item" contiene "Pen".

db.example.find( { "Item": "Pen" } ).pretty()

Recuperación de documentos que coincidan con un documento incrustado

Para buscar todos los documentos que coinciden con un documento incrustado, utilice la operación find() con un documento de consulta que especifique el nombre del documento incrustado y todos los campos y los valores de ese documento incrustado.

Cuando se buscan coincidencias con un documento incrustado, el documento incrustado del documento debe tener el mismo nombre que en la consulta. Además, los campos y los valores del documento incrustado deben coincidir con la consulta.

La siguiente consulta devuelve únicamente el documento "Poster Paint". Esto se debe a que "Pen" tiene diferentes valores para "MinOnHand" y "OnHand", y "Spray Paint" tiene un campo más (OrderQnty) que el documento de consulta.

db.example.find({"Inventory": {
    "OnHand": 47,
    "MinOnHand": 50 } } ).pretty()

Recuperación de documentos que coincidan con un valor de campo de un documento incrustado

Para buscar todos los documentos que coinciden con un documento incrustado, utilice la operación find() con un documento de consulta que especifique el nombre del documento incrustado y todos los campos y los valores de ese documento incrustado.

Dados los documentos anteriores, la siguiente consulta utiliza la "notación de puntos" para especificar el documento incrustado y los campos de interés. Se devolverá cualquier documento que coincida con ellos, independientemente de los otros campos que puedan existir en el documento incrustado. La consulta devuelve "Poster Paint" y "Spray Paint", ya que ambos coinciden con los campos y los valores especificados.

db.example.find({"Inventory.OnHand": 47, "Inventory.MinOnHand": 50 }).pretty()

Recuperación de documentos que coincidan con una matriz

Para buscar todos los documentos que coincidan con una matriz, utilice la operación find() con el nombre de la matriz que le interese y todos los valores de esa matriz. La consulta devuelve todos los documentos que tengan una matriz con ese nombre y cuyos valores de la matriz sean idénticos y estén en el mismo orden que en la consulta.

La siguiente consulta devuelve únicamente "Pen", ya que "Poster Paint" tiene un color adicional (White) y "Spray Paint" tiene los colores en otro orden.

db.example.find( { "Colors": ["Red","Green","Blue","Black"] } ).pretty() 

Recuperación de documentos que coincidan con un valor de una matriz

Para buscar todos los documentos que tengan un valor determinado en una matriz, utilice la operación find() con el nombre de la matriz y el valor que le interese.

db.example.find( { "Colors": "Red" } ).pretty() 

La operación anterior devuelve los tres documentos, ya que cada uno de ellos tiene una matriz denominada Colors y el valor "Red" en algún lugar de la matriz. Si especifica el valor "White", la consulta solo devolvería "Poster Paint".

Recuperación de documentos mediante operadores

La siguiente consulta devuelve todos los documentos en los que el valor de "Inventory.OnHand" es menor que 50.

db.example.find(
        { "Inventory.OnHand": { $lt: 50 } } )

Para obtener una lista de los operadores de consulta admitidos, consulte Operadores de consulta y proyección.

Actualización de documentos

Normalmente, los documentos no son estáticos y se actualizan como parte de los flujos de trabajo de la aplicación. En los siguientes ejemplos se muestran algunas de las formas en que puede actualizar los documentos.

Para actualizar un documento existente, use la operación update(). La operación update() tiene dos parámetros de documento. El primer documento identifica el documento o los documentos que se van a actualizar. El segundo documento especifica las actualizaciones que se deben realizar.

Al actualizar un campo existente ya sea un campo sencillo, una matriz o un documento incrustado debe especificar el nombre del campo y sus valores. Al final de la operación, es como si el campo del documento antiguo se ha sustituido por el campo y los valores nuevos.

Actualizar los valores de un campo existente

Utilice los cuatro documentos siguientes que ha añadido anteriormente para las siguientes operaciones de actualización.

{
    "Item": "Ruler",
    "Colors": ["Red","Green","Blue","Clear","Yellow"],
    "Inventory": {
        "OnHand": 47,
        "MinOnHand": 40
    },
    "UnitPrice": 0.89
},
{
    "Item": "Pen",
    "Colors": ["Red","Green","Blue","Black"],
    "Inventory": {
        "OnHand": 244,
        "MinOnHand": 72 
    }
},
{
    "Item": "Poster Paint",
    "Colors": ["Red","Green","Blue","Black","White"],
    "Inventory": {
        "OnHand": 47,
        "MinOnHand": 50 
    }
},
{
    "Item": "Spray Paint",
    "Colors": ["Black","Red","Green","Blue"],
    "Inventory": {
        "OnHand": 47,
        "MinOnHand": 50,
        "OrderQnty": 36
    }
}

Para actualizar un campo sencillo

Para actualizar un campo sencillo, utilice update() con $set para especificar el nombre del campo y el valor nuevo. En el siguiente ejemplo, se cambia Item de "Pen" a "Gel Pen".

db.example.update(
    { "Item" : "Pen" },
    { $set: { "Item": "Gel Pen" } }
)

Los resultados de esta operación serán similares a lo que se indica a continuación (formato JSON).

{
    "Item": "Gel Pen",
    "Colors": ["Red","Green","Blue","Black"],
    "Inventory": {
        "OnHand": 244,
        "MinOnHand": 72 
    }
}

Para actualizar una matriz

En el siguiente ejemplo, se sustituye la gama de colores existente por una matriz nueva que incluye Orange y elimina White de la lista de colores. La lista de colores nueva se encuentra en el orden especificado en la operación update().

db.example.update(
    { "Item" : "Poster Paint" },
    { $set: { "Colors": ["Red","Green","Blue","Orange","Black"] } }
)

Los resultados de esta operación serán similares a lo que se indica a continuación (formato JSON).

{
    "Item": "Poster Paint",
    "Colors": ["Red","Green","Blue","Orange","Black"],
    "Inventory": {
        "OnHand": 47,
        "MinOnHand": 50 
    }
}

Añadir un nuevo campo

Para modificar un documento añadiendo uno o varios campos nuevos, utilice la operación update() con un documento de consulta que identifique el documento que se va a insertar y los nuevos campos y valores que se van a insertar mediante el operador $set.

En el siguiente ejemplo, se añade el campo UnitPrice con el valor 3.99 en el documento Spray Paints. Tenga en cuenta que el valor 3.99 es numérico y no una cadena.

db.example.update(
    { "Item": "Spray Paint" },
    { $set: { "UnitPrice": 3.99 } } 
)

Los resultados de esta operación serán similares a lo que se indica a continuación (JSON format).

{
    "Item": "Spray Paint",
    "Colors": ["Black","Red","Green","Blue"],
    "Inventory": {
        "OnHand": 47,
        "MinOnHand": 50,
        "OrderQnty": 36
    },
    "UnitPrice": 3.99
}

Sustitución de un documento incrustado

Para modificar un documento sustituyendo un documento incrustado, utilice la operación update() con documentos que identifiquen el documento incrustado y sus campos y valores nuevos mediante el operador $set.

Dado el documento siguiente.

db.example.insert({
    "DocName": "Document 1",
    "Date": {
        "Year": 1987,
        "Month": 4,
        "Day": 18
    }
})

Para sustituir un documento incrustado

En el ejemplo siguiente, se sustituye el documento Date actual por uno nuevo que solo tiene los campos Month y Day en el que se ha eliminado Year.

db.example.update(
    { "DocName" : "Document 1" },
    { $set: { "Date": { "Month": 4, "Day": 18 } } }
)

Los resultados de esta operación serán similares a lo que se indica a continuación (formato JSON).

{
    "DocName": "Document 1",
    "Date": {
        "Month": 4,
        "Day": 18
    }
}

Inserción de campos nuevos en un documento incrustado

Para añadir campos a un documento incrustado

Para modificar un documento añadiendo uno o varios campos nuevos a un documento incrustado, utilice la operación update() con documentos que identifiquen el documento incrustado y la "notación de puntos" para especificar el documento incrustado y los campos y valores nuevos que se van a insertar mediante el operador $set.

Teniendo en cuenta el siguiente documento, el código siguiente utiliza la "notación de puntos" para insertar los campos Year y DoW en el documento incrustado Date y Words en el documento principal.

{
    "DocName": "Document 1",
    "Date": {
        "Month": 4,
        "Day": 18
    }
}

db.example.update(
    { "DocName" : "Document 1" },
    { $set: { "Date.Year": 1987, 
              "Date.DoW": "Saturday",
              "Words": 2482 } }
)

Los resultados de esta operación serán similares a lo que se indica a continuación (formato JSON).

{
    "DocName": "Document 1",
    "Date": {
        "Month": 4,
        "Day": 18,
        "Year": 1987,
        "DoW": "Saturday"
    },
    "Words": 2482
}

Eliminación de un campo de un documento

Para modificar un documento eliminando uno se sus campos, utilice la operación update() con un documento de consulta que identifique el documento cuyo campo se va a eliminar y el operador $unset para especificar campo que se va a eliminar.

En el siguiente ejemplo, se elimina el campo Words del documento anterior.

db.example.update(
    { "DocName" : "Document 1" },
    { $unset: { Words:1 } }
)

Los resultados de esta operación serán similares a lo que se indica a continuación (formato JSON).

{
    "DocName": "Document 1",
    "Date": {
        "Month": 4,
        "Day": 18,
        "Year": 1987,
        "DoW": "Saturday"
    }
}
                

Eliminación de un campo de varios documentos

Para modificar un documento mediante la eliminación de un campo de varios documentos, utilice la operación update() con el operador $unset y la opción multi establecida en true.

En el ejemplo siguiente se quita el campo Inventory de todos los documentos de la colección de ejemplo. Si un documento no tiene el campo Inventory, no se realiza ninguna acción en ese documento. Si multi: true se omite, la acción solo se realiza en el primer documento que cumple el criterio.

db.example.update(
    {},
    { $unset: { Inventory:1 } },
    { multi: true }
)
                

Eliminación de documentos

Para eliminar un documento de la base de datos, utilice la operación remove(), especificando el documento que se va a eliminar. El código siguiente elimina "Gel Pen" de la colección example.

db.example.remove( { "Item": "Gel Pen" } )

Para eliminar todos los documentos de la base de datos, utilice la operación remove() con una consulta vacía, tal y como se muestra a continuación.

db.example.remove( { } )