Indici Datastore

Questa API è supportata per runtime di prima generazione e può essere utilizzata quando eseguire l'upgrade ai runtime di seconda generazione corrispondenti. Se esegui l'aggiornamento al runtime App Engine Java 11/17, consulta la guida alla migrazione per scoprire di più sulle opzioni di migrazione per i servizi in bundle legacy.

Avviso: di seguito viene descritto l'utilizzo del file di configurazione dell'indice, datastore-indexes.xml, associato all'SDK di App Engine, che ora è ritirato. Dovresti passare a strumenti basati su Cloud SDK, come il comando riga di comando "gcloud", che utilizza il file di configurazione index.yaml.

App Engine predefinisce un indice semplice per ogni proprietà di un'entità. Un'applicazione App Engine può definire ulteriori indici personalizzati in un file di configurazione dell'indice denominato datastore-indexes.xml, che viene generato nella directory /war/WEB-INF/appengine-generated dell'applicazione. Il server di sviluppo aggiunge automaticamente suggerimenti a questo file quando rileva query che non possono essere eseguite con gli indici esistenti. Puoi ottimizzare gli indici manualmente modificando il file prima di caricare l'applicazione.

Nota: il meccanismo di query basato su indici supporta una vasta gamma di query ed è adatto per la maggior parte delle applicazioni. Tuttavia, non supporta alcuni tipi di query comuni in altre tecnologie di database: in particolare, le unioni e le query aggregate non sono supportate nel motore di query di Datastore. Consulta la pagina Query Datastore per informazioni sui limiti delle query Datastore.

Definizione e struttura dell'indice

Un indice è definito in 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 sugli antenati, l'indice può facoltativamente includere anche gli antenati di un'entità.

Una tabella di indici contiene una colonna per ogni proprietà denominata nella definizione dell'indice. Ogni riga della tabella rappresenta un'entità in Datastore che è un potenziale risultato per le query basate sull'indice. Un'entità viene inclusa nell'indice solo se ha un valore indicizzato per ogni proprietà utilizzata nell'indice. Se la definizione dell'indice fa riferimento a una proprietà per la quale l'entità non ha un valore, l'entità non verrà visualizzata nell'indice e, di conseguenza, non verrà mai restituita come risultato di alcuna query basata sull'indice.

Nota: Datastore distingue tra un'entità che non possiede una proprietà e un'entità che possiede la proprietà con un valore nullo (null). Se assegni esplicitamente un valore nullo alla proprietà di un'entità, questa può essere inclusa nei risultati di una query che fa riferimento alla proprietà.

Nota: gli indici composti da più proprietà richiedono che ogni singola proprietà non sia impostata su Non indicizzato.

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

1. Proprietà utilizzate nei filtri di uguaglianza
2. Proprietà utilizzata in un filtro di disuguaglianza (di cui non può essercene più di uno).
3. Proprietà utilizzate negli ordini di ordinamento

In questo modo, tutti i risultati per ogni possibile esecuzione della query vengono visualizzati in righe consecutive della tabella. Datastore esegue una query utilizzando un indice perfetto seguendo i seguenti passaggi:

1. Identifica l'indice corrispondente al tipo di query, alle proprietà di filtro, agli operatori di filtro e agli ordini di ordinamento.
2. Esegue la scansione dall'inizio dell'indice fino alla prima entità che soddisfa tutte le condizioni di filtro della query.
3. Continua a eseguire la scansione dell'indice, restituendo ogni entità in ordine fino a quando
   • rileva un'entità che non soddisfa le condizioni del filtro oppure
   • raggiunge la fine dell'indice
   • ha raccolto il numero massimo di risultati richiesti dalla query.

Ad esempio, considera la seguente query:

Query q1 =
    new Query("Person")
        .setFilter(
            CompositeFilterOperator.and(
                new FilterPredicate("lastName", FilterOperator.EQUAL, "Smith"),
                new FilterPredicate("height", FilterOperator.EQUAL, 72)))
        .addSort("height", Query.SortDirection.DESCENDING);

L'indice perfetto per questa query è una tabella di chiavi per le entità di tipo Person, con colonne per i valori delle proprietà lastName e height. L'indice viene ordinato prima in ordine crescente per lastName e poi in ordine decrescente per height.

Per generare questi indici, configurali come segue:

<?xml version="1.0" encoding="utf-8"?>
<datastore-indexes autoGenerate="false">
  <datastore-index kind="Person" ancestor="false" source="manual">
    <property name="lastName" direction="asc"/>
    <property name="height" direction="desc"/>
  </datastore-index>
</datastore-indexes>

Due query dello stesso tipo, ma con valori di filtro diversi, utilizzano lo stesso indice. Ad esempio, la seguente query utilizza lo stesso indice di quella precedente:

Query q2 =
    new Query("Person")
        .setFilter(
            CompositeFilterOperator.and(
                new FilterPredicate("lastName", FilterOperator.EQUAL, "Jones"),
                new FilterPredicate("height", FilterOperator.EQUAL, 63)))
        .addSort("height", Query.SortDirection.DESCENDING);

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

Query q3 =
    new Query("Person")
        .setFilter(
            CompositeFilterOperator.and(
                new FilterPredicate("lastName", FilterOperator.EQUAL, "Friedkin"),
                new FilterPredicate("firstName", FilterOperator.EQUAL, "Damian")))
        .addSort("height", Query.SortDirection.ASCENDING);

e

Query q4 =
    new Query("Person")
        .setFilter(new FilterPredicate("lastName", FilterOperator.EQUAL, "Blair"))
        .addSort("firstName", Query.SortDirection.ASCENDING)
        .addSort("height", Query.SortDirection.ASCENDING);

Nota: puoi ottenere un elenco degli indici della tua applicazione in fase di esecuzione chiamando i metodi DatastoreService.getIndexes() o AsyncDatastoreService.getIndexes().

Attenzione: l'utilizzo di un indice perfetto può aumentare notevolmente il costo della scrittura delle entità, in particolare nel caso di indici esplosivi.

Configurazione degli indici

Per impostazione predefinita, Datastore predefinisce automaticamente un indice per ogni proprietà di ogni tipo di entità. Questi indici predefiniti sono sufficienti per eseguire molte query semplici, ad esempio query solo di uguaglianza e query di semplice disuguaglianza. Per tutte le altre query, l'applicazione deve definire gli indici di cui ha bisogno in un file di configurazione dell'indice chiamato datastore-indexes.xml. Se l'applicazione tenta di eseguire una query che non può essere eseguita con gli indici disponibili (predefiniti o specificati nel file di configurazione dell'indice), la query non andrà a buon fine con un DatastoreNeedIndexException.

Datastore crea indici automatici per le query dei seguenti tipi:

• Query senza tipo che utilizzano solo filtri di tipo ancestor e key
• Query che utilizzano solo filtri di eguaglianza e antenato
• Query che utilizzano solo filtri di disuguaglianza (limitati a una singola proprietà)
• Query che utilizzano solo filtri di antenati, filtri di uguaglianza sulle proprietà e filtri di disuguaglianza sulle chiavi
• Query senza filtri e con un solo ordinamento per proprietà, crescente o decrescente

Altre forme di query richiedono che gli indici vengano specificati nel file di configurazione dell'indice, tra cui:

• Query con filtri di antenato e di diseguaglianza
• Query con uno o più filtri di disuguaglianza su una proprietà e uno o più filtri di uguaglianza su altre proprietà
• Query con un ordinamento delle chiavi in ordine decrescente
• Query con più ordini di ordinamento

Nota: Datastore suggerisce automaticamente gli indici che sono appropriati per la maggior parte delle applicazioni. A seconda dell'utilizzo da parte dell'applicazione Datastore, dimensioni e forma dei dati, regolazioni manuali ai tuoi indici possono essere garantiti. Ad esempio, scrivere entità con più dei valori delle proprietà può causare un indice esplosivo con valori e scrivere i costi.

Nota: il server web di sviluppo può semplificare la gestione dell'indice di configurazione del deployment. Invece di non riuscire a eseguire una query che richiede un indice e non ne ha uno, il server web di sviluppo può generare un indice che consentirebbe il completamento della query. Se il test locale di un l'applicazione esegue ogni possibile query inviata dall'applicazione, utilizzando ogni combinazione di filtro e ordinamento, le voci generate rappresenteranno un insieme completo di indici. Se il test non si esercita ogni possibile modulo di query, puoi rivedere e modificare il file di configurazione dell'indice prima caricare l'applicazione.

Indici e proprietà

Ecco alcune considerazioni speciali da tenere presenti sugli indici e sul loro rapporto con le proprietà delle entità in Datastore:

Proprietà con tipi di valori misti

Quando due entità hanno proprietà dello stesso nome, ma tipi di valore diversi, un indice della proprietà ordina le entità innanzitutto in base al tipo di valore e poi in base a un ordinamento secondario appropriato per ogni tipo. Ad esempio, se due entità hanno ciascuna una proprietà age, una con un valore intero e una con un valore di stringa, l'entità con il valore intero precede sempre quella con il valore di stringa quando vengono ordinate in base alla proprietà age, indipendentemente dai valori delle proprietà stesse.

Questo è particolarmente importante nel caso di numeri interi e con virgola mobile, che vengono trattati come tipi distinti da Datastore. Poiché tutti i numeri interi vengono ordinati prima di tutti i numeri in virgola mobile, una proprietà con il valore intero 38 viene ordinata prima di una con il valore in virgola mobile 37.5.

Proprietà non indicizzate

Se sai che non dovrai mai filtrare o ordinare in base a una determinata proprietà, puoi indicare a Datastore di non gestire le voci dell'indice per quella proprietà dichiarandola non indicizzata. In questo modo, si riduce il costo di esecuzione della tua applicazione diminuendo il numero di scritture di Datastore che deve eseguire. Un'entità con una proprietà non indicizzata si comporta come se la proprietà non fosse impostata: le query con un filtro o un ordine di ordinamento per la proprietà non indicizzata non corrisponderanno mai a quell'entità.

Nota: se una proprietà viene visualizzata in un indice composto da più proprietà e impostandola su Non indicizzato, non verrà indicizzata nell'indice composto.

Ad esempio, supponiamo che un'entità abbia le proprietà a e b e che tu voglia creare un indice in grado di soddisfare query come WHERE a ="bike" and b="red". Supponiamo inoltre che le query WHERE a="bike" e WHERE b="red" non ti interessino. Se imposti a su Non indicizzato e crei un indice per a e b, il datastore non creerà voci di indice per gli indici a e b e, di conseguenza, la query WHERE a="bike" and b="red" non funzionerà. Affinché Datastore crei voci per gli indici a e b, sia a che b devono essere indicizzati.

Nota: oltre alle proprietà non indicizzate dichiarate esplicitamente, quelle scritte come stringhe di testo lunghe (Text), stringhe di byte lunghe (Blob) ed entità incorporate (EmbeddedEntity) vengono trattate automaticamente come non indicizzate.

Nell'API Datastore Java di basso livello, le proprietà vengono definite come indicizzate o non indicizzate in base all'entità, a seconda del metodo utilizzato per impostarle (setProperty() o setUnindexedProperty()):

DatastoreService datastore = DatastoreServiceFactory.getDatastoreService();

Key acmeKey = KeyFactory.createKey("Company", "Acme");

Entity tom = new Entity("Person", "Tom", acmeKey);
tom.setProperty("name", "Tom");
tom.setProperty("age", 32);
datastore.put(tom);

Entity lucy = new Entity("Person", "Lucy", acmeKey);
lucy.setProperty("name", "Lucy");
lucy.setUnindexedProperty("age", 29);
datastore.put(lucy);

Filter ageFilter = new FilterPredicate("age", FilterOperator.GREATER_THAN, 25);

Query q = new Query("Person").setAncestor(acmeKey).setFilter(ageFilter);

// Returns tom but not lucy, because her age is unindexed
List<Entity> results = datastore.prepare(q).asList(FetchOptions.Builder.withDefaults());

Puoi modificare una proprietà indicizzata in non indicizzata reimpostandone il valore con setUnindexedProperty() oppure da non indicizzata a indicizzata reimpostandola con setProperty().

Tieni presente, tuttavia, che la modifica di una proprietà da non indicizzata a indicizzata non influisce sulle entità esistenti che potrebbero essere state create prima della modifica. Le query che filtrano in base alla proprietà non restituiranno queste entità esistenti, perché non sono state scritte nell'indice della query al momento della loro creazione. Per rendere le entità accessibili dalle query future, devi riscriverle in Datastore in modo che vengano inserite negli indici appropriati. In altre parole, devi eseguire le seguenti operazioni per ogni entità esistente:

1. Recupera (ottieni) l'entità da Datastore.
2. Scrivi (put) di nuovo l'entità in Datastore.

Analogamente, la modifica di una proprietà da indicizzata a non indicizzata interessa solo le entità successivamente scritte in Datastore. Le voci di indice per eventuali entità esistenti con quella proprietà continueranno a esistere finché le entità non vengono aggiornate o eliminate. Per evitare risultati indesiderati, devi eliminare dal codice tutte le query che filtrano o ordinano in base alla proprietà (ora non indicizzata).

Limiti per gli indici

Datastore impone limiti al numero e alle dimensioni complessive delle voci dell'indice che possono essere associate a una singola entità. Questi limiti sono elevati e la maggior parte delle applicazioni non è interessata. Tuttavia, esistono situazioni in cui potresti riscontrare dei limiti.

Come descritto sopra, Datastore crea una voce in un indice predefinito per ogni proprietà di ogni entità, tranne per le stringhe di testo lunghe (Text), le stringhe di byte lunghe (Blob) e le entità incorporate (EmbeddedEntity) e quelle che hai dichiarato esplicitamente come non indicizzate. La proprietà può anche essere inclusa in altri indici personalizzati dichiarati nel file di configurazione di datastore-indexes.xml. Se un'entità non ha proprietà elenco, avrà al massimo una voce in ciascun indice personalizzato (per gli indici non predecessori) o una per ciascuno dei predecessori dell'entità (per gli indici dei predecessori). Ognuna di queste voci di indice va aggiornata ogni volta che cambia il valore della proprietà.

Per una proprietà con un singolo valore per ogni entità, ogni possibile valore deve essere archiviato una sola volta per entità nell'indice predefinito della proprietà. Tuttavia, è possibile che un'entità con un numero elevato di proprietà con un solo valore superi il limite di dimensioni o di voci dell'indice. Analogamente, un'entità che può avere più valori per la stessa proprietà richiede una voce dell'indice distinta per ogni valore. Anche in questo caso, se il numero di valori possibili è elevato, un'entità di questo tipo può superare il limite di voci.

La situazione peggiora nel caso di entità con più proprietà, ciascuna delle quali può assumere più valori. Per supportare un'entità di questo tipo, l'indice deve includere una voce per ogni possibile combinazione di valori delle proprietà. Gli indici personalizzati che fanno riferimento a più proprietà, ciascuna con più valori, possono "esplodere" in modo combinatorio, richiedendo un numero elevato di voci per un'entità con solo un numero relativamente ridotto di possibili valori delle proprietà. Questi indici esplosivi possono aumentare notevolmente il costo della scrittura di un'entità in Datastore, a causa del numero elevato di voci dell'indice che devono essere aggiornate, e possono anche causare facilmente il superamento della voce dell'indice o del limite di dimensioni dell'entità.

Considera la query

Query q =
    new Query("Widget")
        .setFilter(
            CompositeFilterOperator.and(
                new FilterPredicate("x", FilterOperator.EQUAL, 1),
                new FilterPredicate("y", FilterOperator.EQUAL, 2)))
        .addSort("date", Query.SortDirection.ASCENDING);

L'SDK suggerisce quindi il seguente indice:

<?xml version="1.0" encoding="utf-8"?>
<datastore-indexes autoGenerate="false">
  <datastore-index kind="Widget" ancestor="false" source="manual">
    <property name="x" direction="asc"/>
    <property name="y" direction="asc"/>
    <property name="date" direction="asc"/>
  </datastore-index>
</datastore-indexes>

Questo indice richiede un totale di |x| * |y| * |date| voci per ogni entità (dove |x| indica il numero di valori associati all'entità per la proprietà x). Ad esempio, il seguente codice

Entity widget = new Entity("Widget");
widget.setProperty("x", Arrays.asList(1, 2, 3, 4));
widget.setProperty("y", Arrays.asList("red", "green", "blue"));
widget.setProperty("date", new Date());
datastore.put(widget);

crea un'entità con quattro valori per la proprietà x, tre valori per la proprietà y e date impostato sulla data corrente. Ciò richiederà 12 voci di indice, una per ogni possibile combinazione di valori delle proprietà:

(1, "red", <now>) (1, "green", <now>) (1, "blue", <now>)

(2, "red", <now>) (2, "green", <now>) (2, "blue", <now>)

(3, "red", <now>) (3, "green", <now>) (3, "blue", <now>)

(4, "red", <now>) (4, "green", <now>) (4, "blue", <now>)

Quando la stessa proprietà viene ripetuta più volte, Datastore può rilevare gli indici in crescita e suggerire un indice alternativo. Tuttavia, in tutte le altre circostanze (ad esempio la query definita in questo esempio), Datastore genererà un indice enorme. In questo caso, puoiaggirare l'indice enorme configurando manualmente un indice nel file di configurazione dell'indice:

<?xml version="1.0" encoding="utf-8"?>
<datastore-indexes autoGenerate="false">
  <datastore-index kind="Widget">
    <property name="x" direction="asc" />
    <property name="date" direction="asc" />
  </datastore-index>
  <datastore-index kind="Widget">
    <property name="y" direction="asc" />
    <property name="date" direction="asc" />
  </datastore-index>
</datastore-indexes>

In questo modo, il numero di voci necessarie si riduce a (|x| * |date| + |y| * |date|), ovvero 7 voci anziché 12:

(1, <now>) (2, <now>) (3, <now>) (4, <now>)

("red", <now>) ("green", <now>) ("blue", <now>)

Qualsiasi operazione put che causerebbe il superamento del limite di dimensioni o di voci dell'indice non andrà a buon fine con un messaggio IllegalArgumentException. Il testo dell'eccezione descrive quale limite è stato superato ("Too many indexed properties" o "Index entries too large") e quale indice personalizzato ne è la causa. Se crei un nuovo indice che supererebbe i limiti per qualsiasi entità al momento della creazione, le query sull'indice non andranno a buon fine e l'indice verrà visualizzato nello stato Error nella console Google Cloud. Per risolvere gli indici nello stato Error:

1. Rimuovi l'indice nello stato Error dal file datastore-indexes.xml.

2. Esegui il seguente comando dalla directory in cui si trova datastore-indexes.xml per rimuovere l'indice da Datastore:

   gcloud datastore indexes cleanup datastore-indexes.xml
   

3. Risolvi la causa dell'errore. Ad esempio:

   • Riformula la definizione dell'indice e le query corrispondenti.
   • Rimuovi le entità che causano l'esplosione dell'indice.

4. Aggiungi di nuovo l'indice al file datastore-indexes.xml.

5. Esegui il seguente comando dalla directory in cui si trova datastore-indexes.xml per creare l'indice in Datastore:

   gcloud datastore indexes create datastore-indexes.xml
   

Puoi evitare di creare indici esplosi evitando le query che richiederebbero un indice personalizzato utilizzando una proprietà elenco. Come descritto sopra, sono incluse le query con più ordini di ordinamento o con una combinazione di filtri di uguaglianza e disuguaglianza.