Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

Utilizzo dei documenti

Essendo un database di documenti, Amazon DocumentDB semplifica l'archiviazione, l'interrogazione e l'indicizzazione JSON dei dati. In Amazon DocumentDB, una raccolta è analoga a una tabella in un database relazionale, tranne per il fatto che non esiste un unico schema applicato a tutti i documenti. Le raccolte consentono di raggruppare documenti simili mantenendoli comunque nello stesso database, senza richiedere che siano identici a livello di struttura.

Utilizzando i documenti di esempio delle sezioni precedenti, è probabile che tu disponga di raccolte per reading_material e office_supplies. È responsabilità del software stabilire a quale raccolta appartenga un documento.

I seguenti esempi utilizzano API MongoDB per mostrare come aggiungere, interrogare, aggiornare ed eliminare documenti.

Aggiungere documenti

In Amazon DocumentDB, un database viene creato quando si aggiunge per la prima volta un documento a una raccolta. In questo esempio, viene creata una raccolta denominata example nel database test, che è il database predefinito quando ci si connette a un cluster. Poiché la raccolta viene creata implicitamente quando viene inserito il primo documento, non viene effettuato alcun controllo degli errori sul nome della raccolta. Di conseguenza, un errore di battitura nel nome della raccolta, ad esempio eexample anziché example, creerà e aggiungerà il documento alla raccolta eexample anziché la raccolta desiderata. Il controllo degli errori deve essere gestito dall'applicazione.

I seguenti esempi utilizzano API MongoDB per aggiungere documenti.

Aggiungere un singolo documento

Per aggiungere un singolo documento a una raccolta, utilizza l'operazione insertOne( {} ) con il documento da aggiungere alla raccolta.

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

L'output di questa operazione è simile al seguente (JSONformato).

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

Aggiungere più documenti

Per aggiungere più documenti a una raccolta, utilizza l'operazione insertMany( [{},...,{}] ) con un elenco di documenti da aggiungere alla raccolta. Anche se i documenti in questo specifico elenco hanno schemi diversi, ciascuno può essere aggiunto alla stessa raccolta.

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
            }
        }    
    ]
)

L'output di questa operazione è simile al seguente (JSONformato).

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

Interrogazione di documenti

A volte, potrebbe essere necessario cercare nell'inventario dello store online, in modo che i clienti possano vedere e acquistare ciò che vendi. Eseguire query su una raccolta è relativamente semplice, sia per le ricerche su tutti i documenti della raccolta che per quelle solo sui documenti che soddisfano un determinato criterio.

Per eseguire una query per i documenti, utilizza l'operazione find(). Il comando find() ha un parametro per documenti singoli che definisce i criteri da utilizzare nella scelta dei documenti da restituire. L'output di find() è un documento formattato su una sola riga di testo senza interruzioni di riga. Per formattare il documento di output per facilitare la lettura, utilizza find().pretty(). Tutti gli esempi di questo argomento utilizzano .pretty() per formattare l'output.

Usa i quattro documenti che hai inserito nella example raccolta nei due esercizi precedenti: insertOne() e. insertMany()

Recupero di tutti i documenti di una raccolta

Per recuperare tutti i documenti nella raccolta, usa l'operazione find() con un documento di query vuoto.

La query seguente restituisce tutti i documenti della raccolta example.

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

Recupero di documenti che corrispondono a un valore di campo

Per recuperare tutti i documenti che corrispondono a un campo e a un valore, usa l'operazione find() con un documento di query che identifica i campi e i valori per la corrispondenza.

Usando i documenti precedenti, questa query restituisce tutti i documenti in cui il campo "Item" è uguale a "Pen".

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

Recupero di documenti che corrispondono a un documento incorporato

Per trovare tutti i documenti che corrispondono a un documento incorporato, utilizza l'operazione find() con un documento di query che specifica il nome del documento incorporato e tutti i campi e i valori per quel documento incorporato.

Quando si esegue il confronto di un documento incorporato, il documento incorporato del documento deve avere lo stesso nome che ha nella query. Inoltre, i campi e i valori nel documento incorporato devono corrispondere alla query.

La seguente query restituisce solo il documento "Poster Paint". Questo perché "Pen" ha valori diversi per "OnHand" e "MinOnHand" e "Spray Paint" ha un ulteriore campo (OrderQnty) rispetto al documento di query.

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

Recupero di documenti che corrispondono a un valore di campo in un documento incorporato

Per trovare tutti i documenti che corrispondono a un documento incorporato, utilizza l'operazione find() con un documento di query che specifica il nome del documento incorporato e tutti i campi e i valori per quel documento incorporato.

Considerati i documenti precedenti, la seguente query utilizza la "dot notation" (notazione col punto) per specificare il documento incorporato e i campi di interesse. Vengono restituiti tutti i documenti che corrispondono a questi campi, indipendentemente da quali altri campi possono essere presenti nel documento incorporato. La query restituisce "Poster Paint" e "Spray Paint" perché entrambi corrispondono ai campi e ai valori specificati.

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

Recupero di documenti che corrispondono a aArray

Per trovare tutti i documenti che corrispondono a una matrice, utilizzare l'operazione find() con il nome della matrice richiesta e tutti i valori in quella matrice. La query restituisce tutti i documenti che hanno una matrice con quel nome in cui i valori della matrice sono identici e nello stesso ordine rispetto alla query.

La seguente query restituisce solo "Pen" perché" Poster Paint" ha un ulteriore colore (White) mentre "Spray Paint" ha i colori in un ordine diverso.

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

Recupero di documenti che corrispondono a un valore in una matrice

Per trovare tutti i documenti che hanno un valore specifico di matrice, utilizza l'operazione find() con il nome della matrice e il valore richiesto.

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

L'operazione precedente restituisce tutti e tre i documenti, in quanto ciascuno di essi dispone di una matrice denominata Colors e del valore "Red" all'interno della matrice. Se si specifica il valore "White", la query restituisce solo "Poster Paint".

Recupero di documenti tramite operatori

La seguente query restituisce tutti i documenti in cui il valore "Inventory.OnHand" è inferiore a 50.

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

Per un elenco degli operatori di query supportati, consulta Operatori di interrogazione e proiezione.

Aggiornamento dei documenti

In genere, i documenti non sono statici e vengono aggiornati come parte dei flussi di lavoro dell'applicazione. Gli esempi seguenti mostrano alcune opzioni di aggiornamento dei documenti.

Per aggiornare un documento esistente, utilizza l'operazione update(). L'operazione update() presenta due parametri del documento. Il primo documento identifica il documento o i documenti da aggiornare. Il secondo documento specifica gli aggiornamenti da eseguire.

Quando si aggiorna un campo esistente, indipendentemente dal fatto che si tratti di un campo semplice, di un array o di un documento incorporato, si specifica il nome del campo e i relativi valori. Al termine dell'operazione è come se il campo nel documento precedente fosse stato sostituito dal campo e dai valori nuovi.

Aggiornamento dei valori di un campo esistente

Utilizza i seguenti quattro documenti aggiunti in precedenza per le seguenti operazioni di aggiornamento.

{
    "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
    }
}

Per aggiornare un campo semplice

Per aggiornare un campo semplice, utilizza update() con $set per specificare il nome del campo e il nuovo valore. L'esempio seguente modifica l'elemento Item da "Pen" a "Gel Pen".

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

L'aspetto dei risultati di questa operazione è simile al seguente.

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

Per aggiornare una matrice

L'esempio seguente sostituisce la matrice esistente di colori con una nuova matrice che comprende Orange e rimuove White dall'elenco dei colori. Il nuovo elenco di colori è nell'ordine specificato nell'operazione update().

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

L'aspetto dei risultati di questa operazione è simile al seguente.

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

Aggiunta di un nuovo campo

Per modificare un documento aggiungendo uno o più nuovi campi, utilizza l'operazione update() con un documento di query che identifica il documento in cui inserire i dati e i nuovi campi e valori da inserire utilizzando l'operatore $set.

L'esempio seguente aggiunge il campo UnitPrice con il valore 3.99 al documento Spray Paints. Si noti che il valore 3.99 è numerico e non una stringa.

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

I risultati di questa operazione hanno un aspetto simile al seguente (JSONformato).

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

Sostituzione di un documento incorporato

Per modificare un documento sostituendo un documento incorporato, utilizza l'operazione update() con i documenti che identificano il documento incorporato e i nuovi campi e valori utilizzando l'operatore $set.

Considerato il seguente documento.

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

Per sostituire un documento incorporato

L'esempio seguente sostituisce l'attuale documento Date con uno nuovo che ha solo i campi Month e Day, mentre Year è stato eliminato.

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

L'aspetto dei risultati di questa operazione è simile al seguente.

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

Inserimento di nuovi campi in un documento incorporato

Per aggiungere campi a un documento incorporato

Per modificare un documento aggiungendo uno o più campi nuovi a un documento incorporato, utilizza l'operazione update() con i documenti che identificano il documento incorporato e la "dot notation" per specificare il documento incorporato e i nuovi campi e valori da inserire utilizzando l'operatore $set.

Considerato il seguente documento, il codice seguente usa la "dot notation" per inserire i campi Year e DoW nel documento incorporato Date e Words nel documento padre.

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

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

L'aspetto dei risultati di questa operazione è simile al seguente.

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

Rimozione di un campo da un documento

Per modificare un documento rimuovendo un campo, utilizza l'operazione update() con un documento di query che identifica il documento da cui rimuovere il campo e l'operatore $unset per specificare il campo da rimuovere.

L'esempio seguente rimuove il campo Words dal documento precedente.

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

L'aspetto dei risultati di questa operazione è simile al seguente.

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

Rimozione di un campo da più documenti

Per modificare un documento rimuovendo un campo da più documenti, utilizza l'operazione update() con l'operatore $unset e l'opzione multi impostata su true.

L'esempio seguente rimuove il campo Inventory da tutti i documenti della raccolta di esempi. Se un documento non contiene il campo Inventory, non viene eseguita alcuna azione. Se multi: true viene omesso, l'azione viene eseguita solo nel primo documento che soddisfa il criterio.

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

Eliminazione di documenti

Per rimuovere un documento dal database, utilizza l'operazione remove(), specificando il documento da rimuovere. Il codice seguente rimuove "Gel Pen" dalla raccolta example.

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

Per rimuovere tutti i documenti dal database, utilizza l'operazione remove() con una query vuota, come mostrato di seguito.

db.example.remove( { } )