Tutorial MongoDB: come configurare e interrogare database MongoDB

Concetti chiave su MongoDB

Ho ripetuto più volte "database a documenti" finora, ma cosa sono esattamente? Ecco i concetti principali:

• Documenti: i dati sono archiviati in oggetti chiamati documenti. In termini semplici, i documenti sono simili a oggetti JSON key-value. Un singolo documento è equivalente a una riga in una tabella. Se programmi in Python, puoi pensare a un documento come a un dizionario, e sei a posto. Ricorda solo che i documenti possono contenere documenti annidati, una delle caratteristiche principali dei database a documenti.
• Collezioni: le collezioni sono come le tabelle nei database relazionali, ma invece di contenere righe, contengono, indovinato, documenti. Le collezioni sono strutture dati enormi che possono contenere migliaia o milioni di dizionari.
• Senza schema: qui viene il bello. Una collezione può contenere documenti di dimensioni variabili. Ad esempio, il documento 1 può avere 10 coppie chiave-valore mentre il documento 2 può averne 15 (purché l’informazione riguardi la stessa categoria/lo stesso argomento, come i prodotti, affinché la collezione abbia senso).

Ecco una bella tabella che riassume le differenze tra database relazionali e database a documenti:

Passiamo davvero a lavorare con i documenti in MongoDB!

Configurazione di MongoDB: connessione alle fonti dati

Per interrogare i database a documenti, dobbiamo installare il server MongoDB. Ecco le istruzioni specifiche per piattaforma:

• Per Windows, segui le istruzioni a questo link.
• Per i sistemi tipo Unix, puoi installare MongoDB dal terminale:

$ sudo apt-get install -y mongodb

Poi, all’interno di un ambiente virtuale, installa le librerie pymongo e requests. pymongo è l’adapter Python ufficiale per il server MongoDB. Ci servirà la libreria requests per prelevare dati da un’API.

$ pip install pymongo
$ pip install requests

Quindi, dal terminale, avvia il server MongoDB con il seguente comando:

$ sudo service mongodb start

Ora siamo pronti a caricare dei dati in un database a documenti. Ci sono due scenari:

1. Hai i dati in locale in formati appropriati come JSON, BSON, YAML o XML.
2. Devi prelevare i dati da fonti esterne, tipicamente API.

Li copriremo entrambi. Per prima cosa, carichiamo in locale una collezione chiamata drone_races.json. Ecco lo snippet per farlo:

import json

from pymongo import MongoClient

# Establish connection to MongoDB
client = MongoClient("localhost", 27017)
# Create a database named "drones"
drones = client["drones"]
# Create a collection named "races"
races = drones["races"]

# Load dataset into MongoDB
with open("data/drone_races.json", "r") as file:
   data = json.load(file)
   races.insert_many(data)

Gli oggetti più importanti per noi sono drones (un database) e races (una collezione). La maggior parte delle funzioni e dei metodi riguarderà le collezioni. Gli oggetti database servono per lo più a gestire le collezioni.

Ora vediamo come caricare gli stessi dati usando un’API. Ho pubblicato le informazioni come API usando un servizio chiamato Mockaroo. Ecco lo snippet:

import requests
from pymongo import MongoClient

# Fetch data from the API
api_url = (
   "https://my.api.mockaroo.com/drone_race_matches.json?key=6f5a6b50"
)
response = requests.get(api_url)

if response.status_code == 200:
   data = response.json()  # Get the JSON data from the API

   # Establish a connection to MongoDB
   client = MongoClient()

   # Access or create a specific database
   drones = client["drones"]

   # Access or create a specific collection within the database
   races = drones["races"]

   # Insert the fetched data into the MongoDB collection
   races.insert_many(data)
else:
   print("Failed to fetch data from the API.")

Abbiamo caricato dei dati nella collezione races del database a documenti drones, o no? Verifichiamo con delle query!

Query MongoDB di base

Conteggio dei documenti in MongoDB

Per capire se esistono dati in una collezione dobbiamo contarne i documenti. Useremo il metodo count_documents per farlo:

>>> races.count_documents({})
9040

Nota il dizionario vuoto passato a count_documents. Quel dizionario si chiama filtro in MongoDB. Proseguendo nel tutorial, impareremo a popolare il dizionario per creare vari tipi di filtri. Al momento, non abbiamo filtri. Il codice sopra equivale a SELECT COUNT(*) FROM table_name in SQL.

Abbiamo 9040 documenti — evviva! Ora diamo un’occhiata ad alcuni dati.

Estrarre un documento in MongoDB

Per visualizzare un documento con pymongo, possiamo usare il metodo find_one:

from pprint import pprint

>>> pprint(races.find_one())
{'_id': ObjectId('659d31e9255ec0cf4bab529d'),
'laps': 3,
'league': 'F1 Drones',
'location': {'city': 'Ford',
             'country': 'United Kingdom',
             'date': 'error: invalid date "2024-10-25"',
             'venue': 'Manhattan Seas'},
'name': 'Honorable',
'pilots': {'drone': 'DJI3-old',
           'finishing_position': 66,
           'name': 'Kariotta Cow',
           'qualification_time': 27.39,
           'team': 'Sky Crusaders',
           'telemetry': {'altitude': 34.3,
                         'battery_voltage': 12.1,
                         'speed': 68.3,
                         'timestamp': 'error: invalid date '
                                      '"2024-10-25T14:09:26Z"'}},
'sponsors': ['Fat Shark', 'DJI', 'Etisalat'],
'weather_conditions': 'snowy'}

Prendi nota dei campi (chiavi) di questo documento. Memorizza informazioni su una singola gara di droni e include dettagli come:

• Il numero di giri
• Le condizioni meteo al momento della gara
• I piloti (non tutti) durante la gara
• Gli sponsor della gara e così via.

Il documento ha anche un campo obbligatorio _id, che è un hash univoco.

Selezionare tutti i documenti in MongoDB

count_documents restituisce sempre un numero, ma a volte vogliamo vedere i dati che la nostra query corrisponde. Per farlo, possiamo usare il fratello maggiore di find_one, ovvero find:

from pprint import pprint

for race in races.find():
   pprint(race)
   break

{'_id': ObjectId('659d31e9255ec0cf4bab529d'),
'laps': 3,
'league': 'F1 Drones',
'location': {'city': 'Ford',
             'country': 'United Kingdom',
             'date': 'error: invalid date "2024-10-25"',
             'venue': 'Manhattan Seas'},
'name': 'Honorable',
'pilots': {'drone': 'DJI3-old',
           'finishing_position': 66,
           'name': 'Kariotta Cow',
           'qualification_time': 27.39,
           'team': 'Sky Crusaders',
           'telemetry': {'altitude': 34.3,
                         'battery_voltage': 12.1,
                         'speed': 68.3,
                         'timestamp': 'error: invalid date '
                                      '"2024-10-25T14:09:26Z"'}},
'sponsors': ['Fat Shark', 'DJI', 'Etisalat'],
'weather_conditions': 'snowy'}

find con una query vuota (nessun argomento) restituisce i documenti uno alla volta, ma non è ciò che vogliamo! Vogliamo eseguire query per rispondere a domande interessanti sui nostri dati. Qui entrano in gioco i documenti filtro.

Selezionare in base a una condizione in MongoDB

Iniziamo con i filtri più semplici — trovare documenti in cui un certo campo è uguale a un certo valore. Sarebbe l’equivalente di:

SELECT *
 FROM table_name
WHERE field = value

Facciamolo in MongoDB:

criteria = {"sponsors": "Fat Shark"}

fat_shark_races = races.count_documents(criteria)
fat_shark_races

6194

Sopra, stiamo selezionando le gare con "Fat Shark" tra gli sponsor. La sintassi è semplicemente un dizionario che mappa il campo sponsors a "Fat Shark".

Il linguaggio di query di MongoDB non sarebbe un linguaggio se non avesse alcuni comuni operatori di disuguaglianza. Ecco come usare l’operatore "minore di":

criteria = {"pilots.qualification_time": {"$lt": 10}}

quick_races = races.count_documents(criteria)
quick_races

3061

La query sopra introduce quattro nuove caratteristiche del linguaggio di query MongoDB (MQL):

• Puoi accedere ai sotto-campi con la dot notation. pilots.qualification_time estrae il tempo di qualifica annidato all’interno del campo pilots.
• Quasi tutti gli operatori in MQL iniziano con il simbolo del dollaro.
• Gli operatori si usano in un documento annidato come sopra.
• $lt è l’operatore "less than" (minore di).

Quindi, il risultato ci dice che ci sono state 3061 gare in cui un pilota ha avuto un tempo di qualifica inferiore a 10 secondi. Questa query è stata possibile con l’operatore $lt. Ecco i suoi fratelli e sorelle:

• $lte: minore o uguale
• $gt: maggiore di
• $gte: maggiore o uguale.

Hanno la stessa sintassi di $lt.

Selezionare con operatori condizionali logici in MongoDB

MQL include anche operatori condizionali logici come $and e $or. Iniziamo dal secondo.

Recupereremo le gare con il Regno Unito come località oppure Etisalat come sponsor:

criteria = {
   "$or": [
       {"location.country": "United Kingdom"},
       {"sponsors": "Etisalat"},
   ]
}

>>> races.count_documents(criteria)

6223

Ancora, usa il pulsante Explain code per una spiegazione dettagliata.

Ci sono 6223 documenti che corrispondono ai nostri criteri. Per usare una logica OR con più valori per lo stesso campo, possiamo usare l’operatore $in.

Ad esempio, possiamo verificare le condizioni meteo avverse in questo modo:

criteria = {
   "weather_conditions": {"$in": ["rainy", "snowy", "cloudy"]}
}

>>> races.count_documents(criteria)

5508

Questa query sarebbe stata scomoda da scrivere con l’operatore $or. Passiamo a $and.

Questa volta, vogliamo trovare le gare con l’Australia come località E Fat Shark come sponsor. Ecco come farlo con $and:

criteria = {
   "$and": [
       {"location.country": "Australia"},
       {"sponsors": "Fat Shark"},
   ]
}
>>> races.count_documents(criteria)
193

Ma in pratica userai raramente $and perché si può ottenere lo stesso risultato in modo molto più semplice:

criteria = {
   "location.country": "Australia",
   "sponsors": "Fat Shark",
}

races.count_documents(criteria)
193

Basta aggiungere più coppie chiave-valore al documento filtro per ottenere l’operatore logico AND.

Infine, c’è l’operatore $nin, che controlla la non appartenenza. Ad esempio, possiamo restituire tutte le gare che non si sono tenute negli Stati Uniti, nel Regno Unito o in Australia:

criteria = {
   "location.country": {
       "$nin": ["United States", "United Kingdom", "Australia"]
   }
}

>>> races.count_documents(criteria)
126

Questo lascia solo gli Emirati Arabi Uniti come paese, quindi la query sopra potrebbe in realtà essere scritta così:

criteria = {"location.country": "United Arab Emirates"}

>>> races.count_documents(criteria)
126

Ma hai capito l’idea.

Interrogare valori null o mancanti in MongoDB

Controllare valori null o mancanti è un’operazione universale in tutte le attività di analisi dei dati. Per questo in MongoDB c’è un operatore apposito — $exists. Ecco due esempi che verificano se un certo campo esiste:

criteria = {"location.district": {"$exists": True}}

>>> races.count_documents(criteria)

0

Hmm, a quanto pare il campo district non esiste in nessun documento. Il campo laps, invece, deve esistere in tutti i documenti perché è un’informazione chiave sulle gare.

criteria = {"laps": {"$exists": True}}

races.count_documents(criteria)
9040

Come previsto, tutti i documenti hanno il campo laps. Ma che dire dei campi che esistono ma hanno valore null? Possiamo verificarlo anche questo:

criteria = {"pilots.finishing_position": None}

races.count_documents(criteria)
0

Usando l’oggetto built-in None di Python, possiamo verificare la mancanza di valore in qualsiasi campo.

Ci sono anche scenari avanzati che richiedono controlli di null o esistenza. Ad esempio, potresti voler verificare se esistono determinati elementi in grandi array annidati.

Per farlo, possiamo usare la sintassi di indicizzazione degli array in MQL. Per esempio, per trovare le gare con un solo sponsor, dobbiamo verificare se esiste il secondo elemento dell’array sponsors:

# Counting starts with 0 as always
criteria = {"sponsors.1": {"$exists": False}}

races.count_documents(criteria)
2929

Ed è facile come aggiungere il numero di indice dell’elemento alla chiave. Quindi, nella nostra collezione, quasi 3000 gare sono state sponsorizzate da un solo soggetto.

Questa sintassi di indicizzazione degli array funziona per molti altri operatori, non solo per $exists.

Proiezioni (limitare i campi)

Un’ultima cosa che tratteremo nel tutorial sono le proiezioni. Finora, i risultati delle nostre query includevano tutti i campi di ciascun documento. Questo non è l’ideale quando i tuoi documenti hanno centinaia di campi. Immagina che pugno nell’occhio sarebbero le stampe!

Quindi, per scegliere i campi da restituire, possiamo usare le proiezioni. Ecco come:

criteria = {"pilots.telemetry.speed": {"$gte": 20}}
projection = {
   "sponsors": 1,
   "location.country": 1,
   "pilots.telemetry.speed": 1,
   "pilots.name": 1,
}

fast_pilots = races.find(criteria, projection)

for pilot in fast_pilots:
   pprint(pilot)
   break

Nel caso sopra, scriviamo i nostri criteri di filtro come al solito ma, questa volta, definiamo un altro documento con quattro campi impostati a 1. Se passiamo questo documento di projection come secondo argomento a find o count_documents, otterremo in output solo i campi impostati a 1.

{'_id': ObjectId('659d31e9255ec0cf4bab529d'),
'location': {'country': 'United Kingdom'},
'pilots': {'name': 'Kariotta Cow', 'telemetry': {'speed': 68.3}},
'sponsors': ['Fat Shark', 'DJI', 'Etisalat']}

Anche se abbiamo scelto solo quattro campi, il fastidioso campo _id si è infilato comunque. Per sopprimere questo comportamento, impostalo a 0 nel dizionario projection:

criteria = {"pilots.telemetry.speed": {"$gte": 20}}
projection = {
   "sponsors": 1,
   "location.country": 1,
   "pilots.telemetry.speed": 1,
   "pilots.name": 1,
   "_id": 0,
}

fast_pilots = races.find(criteria, projection)

for pilot in fast_pilots:
   pprint(pilot)
   break

{'location': {'country': 'United Kingdom'},
'pilots': {'name': 'Kariotta Cow', 'telemetry': {'speed': 68.3}},
'sponsors': ['Fat Shark', 'DJI', 'Etisalat']}

Adesso è più pulito.

Infine, per restituire tutti i campi tranne alcuni, possiamo impostare quei campi a 0:

projection = {"_id": 0, "league": 0, "pilots": 0}

# Empty criteria for this one
races.find_one({}, projection)

{'name': 'Honorable',
'location': {'venue': 'Manhattan Seas',
 'city': 'Ford',
 'country': 'United Kingdom',
 'date': 'error: invalid date "2024-10-25"'},
'sponsors': ['Fat Shark', 'DJI', 'Etisalat'],
'laps': 3,
'weather_conditions': 'snowy'}

Come vedi, questa volta abbiamo tutti i campi tranne _id, league e pilots.

Conclusione

Questo tutorial non rende giustizia all’enorme portata di MongoDB come strumento di gestione dei database. Oggi abbiamo trattato solo le query GET (per recuperare informazioni), ma MongoDB consente anche a chi lavora con i dati di inserire, aggiornare o eliminare informazioni nei database a documenti. Abbiamo anche tralasciato un’intera classe di query — le aggregazioni.

Tutti questi argomenti esulano dallo scopo dell’articolo e richiedono risorse aggiuntive per essere approfonditi. Perché non dai un’occhiata a questi:

• Introduzione all’uso di MongoDB nella data science con Python — un corso completo che copre anche query avanzate come le aggregazioni
• Introduzione a MongoDB in Python — Un altro tutorial su MongoDB che copre le operazioni CRUD (create, read, update e delete) con pymongo.
• Corso sui concetti NoSQL — se ti interessano i database NoSQL, questo corso fa per te. Oltre ai database a documenti, copre altri database non relazionali.