Indici

Ogni query Firestore in modalità Datastore calcola i suoi risultati utilizzando uno o più indici che contengono chiavi di entità in una sequenza specificata dalle proprietà dell'indice e, facoltativamente, i predecessori dell'entità. Gli indici vengono aggiornati per riflettere eventuali modifiche apportate dall'applicazione alle entità, in modo che i risultati corretti di tutte le query siano disponibili senza ulteriori calcoli.

Esistono due tipi di indici:

Indici integrati: Per impostazione predefinita, un database in modalità Datastore predefinisce automaticamente un indice per ogni proprietà di ogni tipo di entità. Questi indici di proprietà singola sono adatti per tipi semplici di query.
Indici compositi: Gli indici composti indicizzano più valori delle proprietà per entità indicizzata. Gli indici composti supportano query complesse e sono definiti in un file di configurazione dell'indice (index.yaml).

I tipi di indici vengono discussi più in dettaglio più avanti in questo argomento.

Definizione e struttura dell'indice

Un indice è definito su un elenco di proprietà di un determinato tipo di entità, con un ordine corrispondente (crescente o decrescente) per ogni proprietà. Per l'utilizzo con le query dei predecessori, l'indice può anche includere antenati di un'entità.

Una tabella di indice contiene una colonna per ogni proprietà denominata nella definizione dell'indice. Ogni riga della tabella rappresenta un'entità che potrebbe essere un potenziale risultato per le query in base all'indice. Un'entità viene inclusa nell'indice solo se dispone di un valore indicizzato per ogni proprietà utilizzata nell'indice; se la definizione dell'indice si riferisce a una proprietà per la quale non esiste un valore, l'entità non verrà visualizzata nell'indice e di conseguenza non verrà mai restituita come risultato per nessuna query basata sull'indice.

Le righe di una tabella indice vengono ordinate prima per predecessore e poi per valori della proprietà, nell'ordine specificato nella definizione dell'indice. L'indice perfetto per una query, che consente di eseguire la query in modo più efficiente, viene definito nelle seguenti proprietà, in ordine:

Proprietà utilizzate nei filtri per l'uguaglianza
Proprietà utilizzata in un filtro di disuguaglianza (di cui non ne può più di una)
Proprietà utilizzate per ordinare
Proprietà utilizzate nelle proiezioni (non già incluse negli ordini di ordinamento)

In questo modo, tutti i risultati per ogni possibile esecuzione della query vengono visualizzati in righe consecutive della tabella. I database in modalità Datastore eseguono una query utilizzando un indice perfetto seguendo questi passaggi:

Identifica l'indice corrispondente al tipo, alla proprietà filtro, agli operatori di filtro e all'ordinamento della query.
Esegue la scansione dall'inizio dell'indice alla prima entità che soddisfa tutte le condizioni di filtro della query
Continua la scansione dell'indice, restituendo a turno ciascuna entità, finché non
- incontra un'entità che non soddisfa le condizioni di filtro; o
- raggiunge la fine dell'indice, oppure
- ha raccolto il numero massimo di risultati richiesti dalla query

Ad esempio, considera la seguente query:

SELECT * FROM Task
WHERE category = 'Personal'
  AND priority < 3
ORDER BY priority DESC

L'indice perfetto per questa query è una tabella di chiavi per le entità di tipo Task, con colonne per i valori delle proprietà category e priority. L'indice viene ordinato prima in ordine crescente per category, quindi in ordine decrescente per priority:

indexes:
- kind: Task
  properties:
  - name: category
    direction: asc
  - name: priority
    direction: desc

Due query della stessa forma ma con valori di filtro diversi utilizzano lo stesso indice. Ad esempio, la seguente query utilizza lo stesso indice di quello precedente:

SELECT * FROM Task
WHERE category = 'Work'
  AND priority < 5
ORDER BY priority DESC

Per questo indice

indexes:
- kind: Task
  properties:
  - name: category
    direction: asc
  - name: priority
    direction: asc
  - name: created
    direction: asc

anche le seguenti due query utilizzano lo stesso indice, nonostante abbiano forme diverse:

SELECT * FROM Task
WHERE category = 'Personal'
  AND priority = 5
ORDER BY created ASC

SELECT * FROM Task
WHERE category = 'Work'
ORDER BY priority ASC, created ASC

L'indice creato sopra può soddisfare entrambe queste query.

Configurazione degli indici

Firestore in modalità Datastore fornisce indici integrati o automatici per le query dei seguenti formati:

Query senza tipo di dati utilizzando solo predecessori e filtri chiave
Query che utilizzano solo filtri di predecessore e di uguaglianza
Query che utilizzano solo filtri di disuguaglianza (limitati a una singola proprietà)
Query che utilizzano solo filtri predecessore, filtri di uguaglianza nelle proprietà e filtri di disuguaglianza nelle chiavi
Query senza filtri e con un solo ordinamento in una proprietà, in ordine crescente o decrescente.

Ad esempio, per impostazione predefinita, i database in modalità Datastore predefiniscono automaticamente due indici di proprietà singola per ogni proprietà di ogni tipo di entità, uno in ordine crescente e uno in ordine decrescente. Se non vuoi che il tuo database mantenga un indice per una proprietà, escludila dai tuoi indici. Tieni presente che l'esclusione di una proprietà ne comporta la rimozione da tutti gli indici composti.

Gli indici integrati sono sufficienti per eseguire molte semplici query, come le query di sola uguaglianza e le disuguaglianze semplici.

Gli indici integrati non vengono visualizzati nella pagina Indici della console Google Cloud.

Per query più complesse, un'applicazione deve definire indici compositi o manuali. Gli indici compositi sono obbligatori per le query nel seguente formato:

Query con filtri predecessore e disuguaglianza
Query con uno o più filtri di disuguaglianza in una proprietà e uno o più filtri di parità nelle altre proprietà
Query con un ordinamento delle chiavi in ordine decrescente
Query con più ordinamenti
Query con uno o più filtri e uno o più ordini

Gli indici composti sono definiti nel file di configurazione dell'indice (index.yaml) dell'applicazione. Gli indici integrati non sono contenuti nel file di configurazione dell'indice.

Gli indici composti sono composti da più proprietà e richiedono che ogni singola proprietà non sia esclusa dagli indici.

Gli indici composti sono visualizzabili nella pagina Indici della console Google Cloud. Non puoi utilizzare la console Google Cloud per creare o aggiornare gli indici composti.

Se l'applicazione tenta di eseguire una query che non può essere eseguita con gli indici disponibili (integrati o specificati nel file di configurazione dell'indice), la query non riuscirà.

L'API della modalità Datastore suggerisce automaticamente gli indici appropriati per la maggior parte delle applicazioni. A seconda dell'utilizzo del database in modalità Datastore da parte dell'applicazione e delle dimensioni e della forma dei dati, potrebbero essere necessarie modifiche manuali agli indici. Ad esempio, la scrittura di entità con più valori di proprietà può comportare un indice esplosivo con elevati costi di archiviazione e un'elevata latenza di scrittura.

L'emulatore di Datastore può semplificare la gestione del file di configurazione dell'indice. Anziché non eseguire una query che richiede un indice e non ne ha una, l'emulatore Datastore può generare una configurazione di indice che consentirebbe alla query di avere esito positivo. Se il test locale di un'applicazione esercita ogni possibile query eseguita dall'applicazione, utilizzando ogni combinazione di filtro e ordinamento, le voci generate rappresenteranno un insieme completo di indici. Se il tuo test non esercita ogni possibile modulo di query, puoi esaminare e modificare il file di configurazione dell'indice prima di aggiornare gli indici.

Per saperne di più su index.yaml, consulta la pagina Configurazione dell'indice.

Deployment o eliminazione degli indici

Quando hai finito di modificare il file di configurazione dell'indice, esegui il comando gcloud datastore indexes create per attivare gli indici. Scopri di più su come aggiornare gli indici.

Se in precedenza hai eseguito il deployment degli indici che non sono più necessari, puoi eliminare gli indici inutilizzati.

Costi di archiviazione e latenza di scrittura

Gli indici contribuiscono ai costi di archiviazione. Dimensioni della voce di indice: indica in che modo gli indici integrati e composti contribuiscono alle dimensioni di archiviazione del database. Puoi utilizzare le statistiche di Firestore in modalità Datastore per visualizzare ulteriori informazioni sulle voci e sulle dimensioni di archiviazione degli indici.

Gli indici contribuiscono anche alla latenza di scrittura. Quando aggiorni il valore di una proprietà, il database aggiorna anche ogni indice correlato. Maggiore è il numero di indici da aggiornare, maggiore è il tempo necessario per l'operazione.

Puoi ridurre i costi di archiviazione e migliorare le prestazioni della scrittura eliminando gli indici inutilizzati ed escludendo le proprietà dall'indicizzazione. Impedisce inoltre che le operazioni non vadano a buon fine a causa dei limiti dell'indice.

Indici e proprietà

Di seguito sono riportate alcune considerazioni speciali da tenere a mente per gli indici e il loro rapporto con le proprietà delle tue entità:

Proprietà con tipi di valori misti

Quando due entità hanno proprietà con lo stesso nome ma tipi di valore diversi, un indice della proprietà ordina le entità per tipo di valore e poi per ordinamento secondario appropriato per ciascun tipo. Ad esempio, se due entità hanno ciascuna una proprietà denominata age, una con valore intero e una con valore stringa, l'entità con valore intero precede sempre quella con il valore stringa quando ordinata dalla proprietà age, indipendentemente dai valori della proprietà stessa.

Questo vale soprattutto per i numeri interi e in virgola mobile, che vengono considerati come tipi separati dalla modalità Datastore. Poiché tutti i numeri interi vengono ordinati prima di tutti i numeri mobili, una proprietà con il valore intero 38 viene ordinata prima di quelli con valore a virgola mobile 37.5.

Proprietà escluse

Se sai che non dovrai mai filtrare o ordinare i dati in base a una determinata proprietà, puoi indicare al database della modalità Datastore di non gestire le voci di indice per quella proprietà escludendola dagli indici. Questo riduce il costo dell'esecuzione dell'applicazione riducendo le dimensioni di archiviazione necessarie per le voci di indice. Questo può anche migliorare la latenza di scrittura. Un'entità con una proprietà esclusa si comporta come se la proprietà non fosse impostata: le query con un filtro o un ordinamento nella proprietà esclusa non corrisponderanno mai a questa entità.

La proprietà description nell'esempio seguente è esclusa dagli indici:

C#

Per scoprire come installare e utilizzare la libreria client per Cloud Datastore, consulta la pagina relativa alle librerie client di Cloud Datastore. Per ulteriori informazioni, consulta la documentazione di riferimento per l'API Cloud DatastoreC#.

Per eseguire l'autenticazione in Cloud Datastore, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.

Indici

Definizione e struttura dell'indice

Configurazione degli indici

Deployment o eliminazione degli indici

Costi di archiviazione e latenza di scrittura

Indici e proprietà

Proprietà con tipi di valori misti

Proprietà escluse

C#

Go

Java

Node.js

PHP

Python

Ruby

GQL

C#

Go

Java

Node.js

PHP

Python

Ruby

GQL

Limiti di indicizzazione

C#

Go

Java

Node.js

PHP

Python

Ruby

GQL

Indici per le proiezioni