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.
**Topics**
+ [Adición de documentos](#document-database-adding-documents)
+ [Consulta de documentos](#document-database-queries)
+ [Actualización de documentos](#document-database-updating)
+ [Eliminación de documentos](#document-database-deleting)
## 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.
**Topics**
+ [Adición de un solo documento](#document-database-adding-documents-single)
+ [Adición de varios documentos](#document-database-adding-documents-multiple)
### 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()`.
**Topics**
+ [Recuperar todos los documentos de una colección](#document-database-queries-all-documents)
+ [Recuperación de documentos que coincidan con un valor de campo](#document-database-queries-match-criteria)
+ [Recuperación de documentos que coincidan con un documento incrustado](#document-database-queries-entire-embedded-document)
+ [Recuperación de documentos que coincidan con un valor de campo de un documento incrustado](#document-database-queries-embeded-document-field)
+ [Recuperación de documentos que coincidan con una matriz](#document-database-queries-array-match)
+ [Recuperación de documentos que coincidan con un valor de una matriz](#document-database-queries-array-value-match)
+ [Recuperación de documentos mediante operadores](#document-database-query-operators)
### 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](mongo-apis.md#mongo-apis-query).
## 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.
**Topics**
+ [Actualizar los valores de un campo existente](#document-database-updating-existing-fields)
+ [Agregado de un campo nuevo](#document-database-updating-adding-field)
+ [Sustitución de un documento incrustado](#document-database-replacing-embedded-document)
+ [Inserción de campos nuevos en un documento incrustado](#document-database-updating-adding-field-embedded)
+ [Eliminación de un campo de un documento](#document-database-remove-field)
+ [Eliminación de un campo de varios documentos](#document-database-remove-field-all)
### 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
}
}
```
### Agregado de un campo nuevo
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, use la operación `remove()` con una consulta vacía.
```
db.example.remove( { } )
```