Strumenti per importare ed esportare dati in MongoDB

In questa breve lezione vedremo alcuni degli strumenti per esportare ed importare dei dati di un database. Sono quattro i comandi a cui facciamo riferimento che, in base al loro modo di operare e al formato dei file, possiamo classificare in due categorie:

• mongoimport e mongoexport per lavorare con file JSON.
• mongodump e mongorestore per i file in formato binario (BSON).

Prima di vedere in dettaglio di cosa si tratta, facciamo un rapido riepilogo di quanto abbiamo appreso nelle precedenti lezioni focalizzando la nostra attenzione sui documenti.

Il formato dei documenti in MongoDB

Abbiamo visto che in MongoDB ogni database contiene una o più collezioni in cui vengono salvati dei documenti. Facendo un parallelo con i classici database relazionali, una collezione svolge un ruolo simile a quello di una tabella solo che al posto delle righe mantiene al suo interno dei documenti. Questi non hanno uno schema fisso e in una stessa collezione potremmo trovare, almeno in linea teorica, documenti con campi differenti.

MongoDB utilizza il formato BSON, che sta per Binary jSON (JSON è l’acronimo di JavaScript Object Notation), per le operazioni di salvataggio e trasferimento in rete dei documenti. Tale formato è stato inventato per sopperire ad alcune mancanze dei file JSON con l’obbiettivo di ottenere migliori prestazioni in termini di spazio occupato e di velocità di lettura e scrittura. Rispetto al formato JSON, BSON è stato esteso per supportare un maggior numero di tipi di valori. Per esempio, in un documento BSON possono essere salvati campi di tipo Date, Byte Array ecc…

Il formato BSON è quindi un’estensione di JSON i cui limiti in termini prestazionali rappresentano tuttavia un vantaggio quando si tratta di dover operare sui documenti. JSON è infatti un formato testuale per salvare le informazioni con una formattazione chiara e leggibile.

In sintesi, sebbene MongoDB usi il formato BSON per il salvataggio ed il trasferimento dei dati, quando dovremo manipolare dei documenti o interrogare un database, andremo ad usare la notazione JSON.

Un documento in formato JSON può considerarsi valido se rispetta i seguenti criteri:

1. Campi e valori sono separati dal carattere ‘:’
2. Ciascuna coppia campo/valore è separata dal carattere ‘,’
3. Sia i campi che i valori devono essere compresi fra doppi apici
4. Le coppie campo/valore sono interamente racchiuse fra parentesi graffe.

Sotto riportiamo un esempio di documento in formato JSON che abbiamo già incontrato nella prima lezione.

{
  "_id": {"$oid": "4212a891f29561a1dbcd24a7"},
  "firstname": "John",
  "lastname": "Doe",
  "email": "[email protected]",
  "age": 44,
  "address": {
    "city": "Leeds",
    "street": "114, Wellington St",
    "postcode": "LS14LT"
  },
  "hobbies": [
    "football",
    "cycling",
    "swimming",
    "cooking"
  ]
}

Ricordiamo inoltre che, nonostante JSON sia il formato richiesto, per le query possiamo semplificare la sintassi e trascurare i doppi apici per le chiavi costituite da una singola parola.

Come importare ed esportare i dati in MongoDB

Visto che MongoDB consente di interagire con i documenti attraverso la notazione JSON e che i documenti sono salvati in formato binario BSON, non dovremo meravigliarci di scoprire che sono disponibili dei comandi da eseguire nella shell per esportare i dati di un database o importare dei documenti sia in formato JSON che in BSON.

Ovviamente quando abbiamo necessità di salvare dei documenti in formato testuale useremo il formato JSON, al contrario per effettuare un backup o il ripristino dei dati possono essere più convenienti i file binari.

mongoimport e mongoexport

Per importare ed esportare dei dati in formato JSON useremo rispettivamente il comando mongoimport e mongoexport. Entrambi gli strumenti consentono di lavorare anche con file CSV e TSV, ma in questa lezione li useremo solo con dati in formato JSON.

A partire da MongoDB 4.4, mongoimport e mongoexport non sono compresi nell’installazione di MongoDB Server.

Su macOS, Homebrew dovrebbe effettuare l’installazione anche di mongodb-database-tools. È comunque possibile verificare che siano stati installati correttamente in due modi.

Se apriamo la shell dei comandi e lanciamo i seguenti comandi, dovremmo ottenere una lista delle diverse opzioni che possiamo usare.

mongoimport --help

mongoexport --help

In ogni caso possiamo confermare la loro presenza eseguendo il comando:

brew list mongodb-database-tools

Su Windows dovremo invece procedere all’installazione manuale scaricando il pacchetto .msi dal sito ufficiale.

Una volta completata l’installazione, troveremo tutti gli eseguibili nella cartella C:Program FilesMongoDBTools100bin. Per non dover digitare l’intero percorso, possiamo aggiungerlo alla variabile d’ambiente Path.

Per l’installazione su Linux, è dedicata una pagina sul sito ufficiale con le istruzioni per le diverse distribuzioni ufficialmente supportate.

Dopo aver completato l’installazione, vediamo come usare mongoimport e mongoexport.

Facciamo riferimento ai dati che abbiamo caricato su MongoDB Atlas nella precedente lezione. Se apriamo la pagina principale e clicchiamo sul pulsante ‘•••’, possiamo selezionare ‘Command Line Tools‘ in cui troviamo delle informazioni sintetiche sull’uso degli strumenti forniti da MongoDB per il backup e ripristino dei dati.

Vediamo come esportare i documenti di una collezione presente su Atlas attraverso mongoexport.

La sintassi da usare è la seguente:

mongoexport 
  --uri mongodb+srv://<USER>:<PASSWORD>@cluster-demo.something.mongodb.net/<NOME-DATABASE> 
  --collection <NOME-COLLEZIONE> 
  --out <NOME-FILE>

La prima opzione --uri consente di specificare una stringa di connessione per collegarsi al server remoto. Tale stringa comprende un prefisso mongodb+srv:// per definire la modalità di connessione. La stringa comprende poi il nome di un utente del database che ha i permessi opportuni e la sua password. Indichiamo inoltre l’indizzo univoco del cluster a cui intendiamo collegarci preceduto dal simbolo ‘@’ e infine appendiamo il carattere ‘/’ seguito dal nome del database. Con l’opzione ‘–collection’ diremo da quale collezione devono essere estratti i documenti. Per concludere, usiamo l’opzione --out per il percorso del file in cui salvare i dati.

Per esempio possiamo salvare i documenti della collezione neighborhoods del database sample_restaurants nel file elenco_quartieri.json con il seguente comando (ricordate di sostituire <USER>,<PASSWORD> e <CLUSTER-ADDRESS> con i correti valori):

mongoexport 
--uri mongodb+srv://<USER>:<PASSWORD>@<CLUSTER-ADDRESS>.mongodb.net/sample_restaurants 
--collection neighborhoods 
--out 'percorso/relativo/esistente/elenco_quartieri.json'

connected to: mongodb+srv://[**REDACTED**]@cluster-demo.something.mongodb.net/sample_restaurants
[........................]  sample_restaurants.neighborhoods  0/195  (0.0%)
[########################]  sample_restaurants.neighborhoods  195/195  (100.0%)
exported 195 records

All’interno del percorso indicato con l’opzione --out troveremo un file in formato JSON con tutti i documenti della collezione neighborhoods del database sample_restaurants.

Se abbiamo installato MongoDB sul nostro computer, possiamo importare i documenti del file elenco_quartieri.json con il comando mongoimport.

mongoimport --drop -c quartieri --host 127.0.0.1 --db ristoranti elenco_quartieri.json

In questo caso ci riferiamo al server locale con l’opzione --host, ma avremmo potuto anche usare una stringa di connessione come fatto con mongoexport. Con l’opzione --drop chiediamo di eliminare la collezione ‘quartieri’ nel caso fosse già presente. Verrà quindi creata la collezione ‘quartieri’ in un nuovo database ‘ristoranti’ usando i documenti presenti nel file JSON ‘elenco_quartieri.json’.

Se ci colleghiamo al server locale eseguendo il comando mongosh senza nessuna opzione, possiamo confermare se i dati sono stati importati.

All’interno della shell di mongodb, eseguiamo il comando show dbs per visualizzare l’elenco dei database presenti.

Selezioniamo quindi il database opportuno con il comando use ristoranti (ovvero use <nome-db>).

Mostriamo poi le collezioni al suo interno con show collections.

Dopo aver selezionato il database ristoranti, possiamo ottenere il numero di documenti presenti nella collezione quartieri con il seguente comando.

db.quartieri.countDocuments()
195

mongorestore e mongodump

Anche mongodump e mongorestore fanno parte degli strumenti di MongoDB e per la loro installazione valgono le medesime considerazioni fatte per mongoexport e mongoimport.

Come mongoexport, mongodump serve per creare una copia di backup, la differenza sta nel fatto che in questo caso verrà usato il formato binario.

Vediamo mongodump all’opera con un altro esempio.

Esportiamo l’intero database sample_restaurants in formato binario come mostrato sotto (anche in questo caso vanno inserite le credenziali di accesso dell’utente creato su atlas ed il corretto indirizzo del cluster creato).

mongodump --uri mongodb+srv://<USER>:<PASSWORD>@<CLUSTER-ADDRESS>.mongodb.net/sample_restaurants

writing sample_restaurants.neighborhoods to dump/sample_restaurants/neighborhoods.bson
writing sample_restaurants.restaurants to dump/sample_restaurants/restaurants.bson
done dumping sample_restaurants.neighborhoods (195 documents)
[........................]  sample_restaurants.restaurants  101/25359  (0.4%)
[########################]  sample_restaurants.restaurants  25359/25359  (100.0%)
done dumping sample_restaurants.restaurants (25359 documents)

Verrà creata una nuova cartella dump con tutti i file del backup. In particolare troviamo una cartella con lo stesso nome del database al cui interno sono presenti 2 coppie di file. Per ciascuna collezione vengono infatti generati un file binario con estensione .bson e un file di metadati in formato JSON.

tree -L 2 dump
dump
└── sample_restaurants
    ├── neighborhoods.bson
    ├── neighborhoods.metadata.json
    ├── restaurants.bson
    └── restaurants.metadata.json

1 directory, 4 files

Possiamo personalizzare l’output di mongodump con diverse opzioni. Per esempio possiamo cambiare la cartella in cui salvare i file usando l’opzione --out o richiedere che venga generato un archivio compresso con l’opzione --gzip oppure specificare quali devono essere le collezioni da includere/escludere dal backup. Per maggiori informazioni, basta eseguire mongodump --help.

Come abbiamo visto per mongoimport, esiste un comando equivalente per ripristinare un database a partire da un file binario, ovvero mongorestore.

Il comportamento predefinito di mongorestore prevede la lettura dei file di ripristino dalla cartella dump della directory corrente. È comunque possibile indicare una cartella diversa passando il suo percorso come argomento finale.

Supponiamo di avere la cartella dump relativa al database sample_restaurants nella cartella corrente, possiamo importare i dati sul server locale con il seguente comando:

mongorestore --host 127.0.0.1

Così facendo, verrà creato il database sample_restaurants e tutte le collezioni in esso contenute.

Conversione da formato binario con bsondump

Per concludere questa lezione vogliamo segnalare un ultimo strumento che fa sempre parte dei MongoDB Database Tools.

bsondump consente di convertire un file binario BSON in formato testuale.

Supponendo di avere sempre il backup del database sample_restaurants, spostiamoci nella cartella in cui sono presenti i file con estensione .bson e lanciamo il seguente comando che converte il file restaurants.bson e ne salva il contenuto in restaurants.json:

bsondump --outFile restaurants.json restaurants.bson

Possiamo poi aprire il file restaurants.json con qualsiasi editor di testo per verificare il contenuto.