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.
Rubriques
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.
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() etinsertMany().
Rubriques
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 qui correspondent à une valeur dans 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.
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.
Rubriques
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( { } )
