Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.
# Utilisation de documents
En tant que base de données de documents, Amazon DocumentDB facilite le stockage, l'interrogation et l'indexation des données JSON. Dans Amazon DocumentDB, une collection est analogue à une table dans une base de données relationnelle, sauf qu'aucun schéma unique n'est appliqué à tous les documents. Les collections vous permettent de regrouper des documents similaires, tout en les conservant tous dans la même base de données, sans que leur structure doive être identique.
En utilisant les documents d'exemple des rubriques précédentes, il est probable que vous ayez des collections pour `reading_material` et `office_supplies`. Votre logiciel est responsable d'associer un document avec la collection à laquelle il appartient.
Les exemples suivants utilisent l'API MongoDB pour montrer comment ajouter, interroger, mettre à jour et supprimer des documents.
**Topics**
+ [Ajouter des documents](#document-database-adding-documents)
+ [Interrogation de documents](#document-database-queries)
+ [Mettre à jour des documents](#document-database-updating)
+ [Supprimer des documents](#document-database-deleting)
## Ajouter des documents
Dans Amazon DocumentDB, une base de données est créée lorsque vous ajoutez un document pour la première fois à une collection. Dans cet exemple, vous créez une collection nommée `example` dans la base de données `test`, qui est la base de données par défaut lorsque vous vous connectez à un cluster. Comme la collection est créée implicitement lors de l'insertion du premier document, aucune erreur ne vérifie le nom de la collection. Par conséquent, une faute de frappe dans le nom de la collection, telle que `eexample` au lieu de `example`, créera et ajoutera le document à la collection `eexample` au lieu de l’ajouter à la collection souhaitée. Votre application est chargée de la vérification des erreurs.
Les exemples suivants utilisent l'API MongoDB pour ajouter des documents.
**Topics**
+ [Ajouter un seul document](#document-database-adding-documents-single)
+ [Ajouter plusieurs documents](#document-database-adding-documents-multiple)
### Ajouter un seul document
Pour ajouter un seul document à une collection, utilisez l'opération `insertOne( {} )` avec le document que vous souhaitez ajouter à la collection.
```
db.example.insertOne(
{
"Item": "Ruler",
"Colors": ["Red","Green","Blue","Clear","Yellow"],
"Inventory": {
"OnHand": 47,
"MinOnHand": 40
},
"UnitPrice": 0.89
}
)
```
La sortie de cette opération ressemble à ceci (format JSON).
```
{
"acknowledged" : true,
"insertedId" : ObjectId("5bedafbcf65ff161707de24f")
}
```
### Ajouter plusieurs documents
Pour ajouter plusieurs documents à une collection, utilisez l'opération `insertMany( [{},...,{}] )` avec une liste des document que vous souhaitez ajouter à la collection. Bien que dans cette liste particulière, les documents ont des schémas différents, ils peuvent tous être ajoutés à la même collection.
```
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 sortie de cette opération ressemble à ceci (format JSON).
```
{
"acknowledged" : true,
"insertedIds" : [
ObjectId("5bedb07941ca8d9198f5934c"),
ObjectId("5bedb07941ca8d9198f5934d"),
ObjectId("5bedb07941ca8d9198f5934e")
]
}
```
## Interrogation de documents
Il arrive que vous ayez besoin de consulter le stock de votre boutique en ligne, pour que les clients puissent voir et acheter ce que vous vendez. Interroger une collection est relativement simple, qu'il s'agisse de tous les documents dans la collection ou uniquement ceux qui répondent à un critère particulier.
Pour interroger des documents, utilisez l'opération `find()`. La commande `find()` possède un seul paramètre de document qui définit les critères à utiliser pour choisir le documents à renvoyer Le résultat obtenu à partir de `find()` est d'un document formaté en une seule ligne de texte sans sauts de ligne. Pour formater le document de sortie afin d'en faciliter la lecture, utilisez `find().pretty()`. Tous les exemples de cette rubrique utilisent `.pretty()` pour mettre en forme les données de sortie.
Utilisez les quatre documents que vous avez insérés dans la `example` collection lors des deux exercices précédents — `insertOne()` et`insertMany()`.
**Topics**
+ [Récupération de tous les documents d'une collection](#document-database-queries-all-documents)
+ [Récupération de documents correspondant à une valeur de champ](#document-database-queries-match-criteria)
+ [Récupération de documents correspondant à un document intégré](#document-database-queries-entire-embedded-document)
+ [Extraction de documents qui correspondent à une valeur de champ dans un document intégré](#document-database-queries-embeded-document-field)
+ [Récupération de documents correspondant à un tableau](#document-database-queries-array-match)
+ [Récupération de documents correspondant à une valeur d'un tableau](#document-database-queries-array-value-match)
+ [Récupération de documents à l'aide d'opérateurs](#document-database-query-operators)
### Récupération de tous les documents d'une collection
Pour récupérer tous les documents de votre collection, utilisez l'opération `find()` avec un document de requête vide.
La requête suivante renvoie tous les documents de la collection `example`.
```
db.example.find( {} ).pretty()
```
### Récupération de documents correspondant à une valeur de champ
Pour récupérer tous les documents qui correspondent à un champ et à une valeur, utilisez l'opération `find()` avec un document de requête qui identifie les champs et les valeurs à faire correspondre.
En utilisant les documents précédents, cette requête renvoie tous les documents où le champ « Item (Élément) » est défini sur « Pen ».
```
db.example.find( { "Item": "Pen" } ).pretty()
```
### Récupération de documents correspondant à un document intégré
Pour rechercher tous les documents qui correspondent à un document intégré, utilisez l'opération `find()` avec un document de requête qui spécifie le nom du document intégré et tous les champs et les valeurs de ce document intégré.
Lorsqu'une correspondance est établie avec un document intégré , le nom de ce document doit être identique à celui spécifié dans la requête. De plus, les champs et les valeurs dans le document intégré doivent correspondre à la requête.
La requête suivante renvoie uniquement le document « Poster Paint ». Cela est dû au fait que « Pen » a des valeurs différentes pour « `OnHand` » et « `MinOnHand` », et que et « Spray Paint » a un champ de plus (`OrderQnty`) que le document de requête.
```
db.example.find({"Inventory": {
"OnHand": 47,
"MinOnHand": 50 } } ).pretty()
```
### Extraction de documents qui correspondent à une valeur de champ dans un document intégré
Pour rechercher tous les documents qui correspondent à un document intégré, utilisez l'opération `find()` avec un document de requête qui spécifie le nom du document intégré et tous les champs et les valeurs de ce document intégré.
Au vu des documents précédents, la requête suivante utilise la « notation de points » pour spécifier le document intégré et les champs d'intérêt. Tout document correspondant est renvoyé, quels que soient les autres champs présents dans le document intégré. La requête renvoie « Poster Paint » et « Spray Paint », car ils correspondent tous deux aux champs et aux valeurs spécifiés.
```
db.example.find({"Inventory.OnHand": 47, "Inventory.MinOnHand": 50 }).pretty()
```
### Récupération de documents correspondant à un tableau
Pour rechercher tous les documents qui correspondent à un tableau, utilisez l'opération `find()` avec le nom du tableau qui vous intéresse et toutes les valeurs de ce tableau. La requête renvoie tous les documents ayant un tableau avec ce nom et dans lequel les valeurs sont identiques et figurent dans le même ordre que dans la requête.
La requête suivante renvoie uniquement « Pen », car « Poster Paint » a une couleur supplémentaire (blanc) et les couleurs de « Spray Paint » figurent dans un ordre différent.
```
db.example.find( { "Colors": ["Red","Green","Blue","Black"] } ).pretty()
```
### Récupération de documents correspondant à une valeur d'un tableau
Pour rechercher tous les documents contenant une valeur de tableau particulière, utilisez l'opération `find()` avec le nom du tableau et la valeur qui vous intéressent.
```
db.example.find( { "Colors": "Red" } ).pretty()
```
L'opération précédente renvoie les trois documents, car chacun d'entre eux possède un tableau nommé `Colors` et la valeur « `Red` » dans le tableau. Si vous spécifiez la valeur « `White` », la requête renvoie uniquement « Poster Paint ».
### Récupération de documents à l'aide d'opérateurs
La requête suivante renvoie tous les documents où la valeur « `Inventory.OnHand` » est inférieure à 50.
```
db.example.find(
{ "Inventory.OnHand": { $lt: 50 } } )
```
Pour obtenir une liste des opérateurs de requête pris en charge, consultez [Opérateurs de requête et de projection](mongo-apis.md#mongo-apis-query).
## Mettre à jour des documents
Généralement, vos documents ne sont pas statiques et sont mis à jour dans le cadre de vos flux de travaux applicatifs. Les exemples suivants illustrent les différentes façons de mettre à jour des documents.
Pour mettre à jour un document existant, utilisez l'opération `update()`. L'opération `update()` possède deux paramètres de document. Le premier document identifie le ou les documents à mettre à jour. Le deuxième document spécifie les mises à jour à effectuer.
Lorsque vous mettez à jour un champ existant, qu'il s'agisse d'un champ simple, d'un tableau ou d'un document intégré, vous spécifiez le nom du champ et ses valeurs. À la fin de l'opération, c'est comme si le champ de l'ancien document avait été remplacé par le nouveau champ et ses valeurs.
**Topics**
+ [Mettre à jour les valeurs d'un champ existant](#document-database-updating-existing-fields)
+ [Ajouter un nouveau champ](#document-database-updating-adding-field)
+ [Remplacement d'un document intégré](#document-database-replacing-embedded-document)
+ [Insertion de nouveaux champs dans un document intégré](#document-database-updating-adding-field-embedded)
+ [Supprimer un champ d'un document](#document-database-remove-field)
+ [Supprimer un champ de plusieurs documents](#document-database-remove-field-all)
### Mettre à jour les valeurs d'un champ existant
Utilisez les quatre documents suivants que vous avez ajoutés précédemment pour les opérations de mise à jour suivantes.
```
{
"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
}
}
```
**Pour mettre à jour un champ simple**
Pour mettre à jour un champ simple, utilisez `update()` avec `$set` pour spécifier le nom du champ et la nouvelle valeur. L'exemple suivant modifie l'élément `Item` de « Pen » en « Gel Pen ».
```
db.example.update(
{ "Item" : "Pen" },
{ $set: { "Item": "Gel Pen" } }
)
```
Les résultats de cette opération ressemblent à ce qui suit.
```
{
"Item": "Gel Pen",
"Colors": ["Red","Green","Blue","Black"],
"Inventory": {
"OnHand": 244,
"MinOnHand": 72
}
}
```
**Pour mettre à jour un tableau :**
L'exemple suivant remplace le tableau de couleurs existant par un nouveau tableau qui inclut `Orange` et supprime `White` de la liste des couleurs. La nouvelle liste de couleurs est dans l'ordre spécifié dans l'opération `update()`.
```
db.example.update(
{ "Item" : "Poster Paint" },
{ $set: { "Colors": ["Red","Green","Blue","Orange","Black"] } }
)
```
Les résultats de cette opération ressemblent à ce qui suit.
```
{
"Item": "Poster Paint",
"Colors": ["Red","Green","Blue","Orange","Black"],
"Inventory": {
"OnHand": 47,
"MinOnHand": 50
}
}
```
### Ajouter un nouveau champ
Pour modifier un document en ajoutant un ou plusieurs nouveaux champs, utilisez l'opération `update()`, avec un document de requête qui identifie le document à insérer et les nouveaux champs et valeurs à insérer à l'aide de l'opérateur `$set`.
L'exemple suivant ajoute le champ `UnitPrice` avec la valeur `3.99` pour le document Spray Paints. Notez que la valeur `3.99` est numérique et non une chaîne.
```
db.example.update(
{ "Item": "Spray Paint" },
{ $set: { "UnitPrice": 3.99 } }
)
```
Les résultats de cette opération ressemblent à ce qui suit (format JSON).
```
{
"Item": "Spray Paint",
"Colors": ["Black","Red","Green","Blue"],
"Inventory": {
"OnHand": 47,
"MinOnHand": 50,
"OrderQnty": 36
},
"UnitPrice": 3.99
}
```
### Remplacement d'un document intégré
Pour modifier un document en remplaçant un document intégré, utilisez l'opération `update()` avec des documents qui identifient le document intégré et ses nouveaux champs et valeurs à insérer à l'aide de l'opérateur `$set`.
Prenons l'exemple du document suivant :
```
db.example.insert({
"DocName": "Document 1",
"Date": {
"Year": 1987,
"Month": 4,
"Day": 18
}
})
```
**Pour remplacer un document intégré**
L'exemple suivant remplace le document actuel Date par un nouveau, qui dispose uniquement des champs `Month` et `Day`, `Year` ayant été supprimé.
```
db.example.update(
{ "DocName" : "Document 1" },
{ $set: { "Date": { "Month": 4, "Day": 18 } } }
)
```
Les résultats de cette opération ressemblent à ce qui suit.
```
{
"DocName": "Document 1",
"Date": {
"Month": 4,
"Day": 18
}
}
```
### Insertion de nouveaux champs dans un document intégré
**Pour ajouter des champs à un document intégré**
Pour modifier un document en ajoutant un ou plusieurs nouveaux champs à un document intégré, utilisez l'opération `update()`, avec des documents qui identifient le document intégré et la « notation de points » pour spécifier le document intégré et les nouveaux champs et valeurs à insérer à l'aide de l'opérateur `$set`.
Au vu du document suivant, le code ci-après utilise la « notation de points » pour insérer les champs `Year` et `DoW` dans le document intégré `Date` et `Words` dans le document parent.
```
{
"DocName": "Document 1",
"Date": {
"Month": 4,
"Day": 18
}
}
```
```
db.example.update(
{ "DocName" : "Document 1" },
{ $set: { "Date.Year": 1987,
"Date.DoW": "Saturday",
"Words": 2482 } }
)
```
Les résultats de cette opération ressemblent à ce qui suit.
```
{
"DocName": "Document 1",
"Date": {
"Month": 4,
"Day": 18,
"Year": 1987,
"DoW": "Saturday"
},
"Words": 2482
}
```
### Supprimer un champ d'un document
Pour modifier un document en supprimant un champ dans le document, utilisez l'opération `update()`, avec un document de requête qui identifie le document dans lequel il faut supprimer le champ, ainsi que le champ à supprimer à l'aide de l'opérateur `$unset`.
L'exemple suivant supprime le champ `Words` dans le document précédent.
```
db.example.update(
{ "DocName" : "Document 1" },
{ $unset: { Words:1 } }
)
```
Les résultats de cette opération ressemblent à ce qui suit.
```
{
"DocName": "Document 1",
"Date": {
"Month": 4,
"Day": 18,
"Year": 1987,
"DoW": "Saturday"
}
}
```
### Supprimer un champ de plusieurs documents
Pour modifier un document en supprimant un champ de plusieurs documents, utilisez l'opération `update()` avec l'opérateur `$unset` et l'option `multi` définie sur `true`.
L'exemple suivant supprime le champ `Inventory` de tous les documents de l’exemple de collection. Si un document n'a pas de champ `Inventory`, aucune action n'est effectuée sur celui-ci. Si `multi: true` n'est pas spécifié, l'action est uniquement effectuée sur le premier document qui répond aux critères.
```
db.example.update(
{},
{ $unset: { Inventory:1 } },
{ multi: true }
)
```
## Supprimer des documents
Pour supprimer un document de votre base de données, utilisez l'opération `remove()`, en indiquant quel document il faut supprimer. Le code suivant supprime « Gel Pen » de votre collection `example`.
```
db.example.remove( { "Item": "Gel Pen" } )
```
Pour supprimer tous les documents de votre base de données, utilisez l'`remove()`opération avec une requête vide.
```
db.example.remove( { } )
```