Cursori di query

I cursori delle query consentono a un'applicazione di recuperare i risultati di una query in batch convenienti e sono consigliati rispetto all'utilizzo di offset interi per la paginazione. Per ulteriori informazioni sulla strutturazione delle query per la tua app, consulta la sezione Query.

Cursori di query

I cursori di query consentono a un'applicazione di recuperare i risultati di una query in batch convenienti senza incorrere nell'overhead di un offset di query. Dopo aver eseguito un'operazione di recupero, l'applicazione può ottenere un cursore, ovvero una stringa opaca con codifica Base64 che contrassegna la posizione dell'indice dell'ultimo risultato recuperato. L'applicazione può salvare questa stringa, ad esempio in Datastore, in Memcache, nel payload di un'attività Task Queue o incorporata in una pagina web come parametro HTTP GET o POST, e può quindi utilizzare il cursore come punto di partenza per un'operazione di recupero successiva per ottenere il batch successivo di risultati dal punto in cui è terminato il recupero precedente. Un recupero può specificare anche un cursore finale, per limitare l'estensione del set di risultati restituito.

Offset e cursori

Sebbene Datastore supporti gli offset interi, ti consigliamo di evitarne l'utilizzo. Utilizza invece i cursori. L'utilizzo di un offset evita solo di restituire le entità saltate all'applicazione, ma queste entità vengono comunque recuperate internamente. Le entità ignorate influiscono sulla latenza della query e la tua applicazione viene fatturata per le operazioni di lettura necessarie per recuperarle. L'utilizzo dei cursori anziché degli offset consente di evitare tutti questi costi.

Esempio di cursore di query

Nell'API di basso livello, l'applicazione può utilizzare i cursori tramite le interfacce QueryResultList, QueryResultIterable e QueryResultIterator, restituite dai metodi PreparedQuery asQueryResultList(), asQueryResultIterable() e asQueryResultIterator(), rispettivamente. Ognuno di questi oggetti risultato fornisce un metodo getCursor(), che a sua volta restituisce un oggetto Cursor. L'applicazione può ottenere una stringa sicura per il web che rappresenta il cursore chiamando il metodo toWebSafeString() dell'oggetto Cursor e può utilizzare in un secondo momento il metodo statico Cursor.fromWebSafeString() per ricostituire il cursore dalla stringa.

L'esempio seguente mostra l'utilizzo dei cursori per la paginazione:


import com.google.appengine.api.datastore.Cursor;
import com.google.appengine.api.datastore.DatastoreService;
import com.google.appengine.api.datastore.DatastoreServiceFactory;
import com.google.appengine.api.datastore.Entity;
import com.google.appengine.api.datastore.FetchOptions;
import com.google.appengine.api.datastore.PreparedQuery;
import com.google.appengine.api.datastore.Query;
import com.google.appengine.api.datastore.Query.SortDirection;
import com.google.appengine.api.datastore.QueryResultList;
import java.io.IOException;
import java.io.PrintWriter;
import javax.servlet.ServletException;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;

public class ListPeopleServlet extends HttpServlet {

  static final int PAGE_SIZE = 15;
  private final DatastoreService datastore;

  public ListPeopleServlet() {
    datastore = DatastoreServiceFactory.getDatastoreService();
  }

  @Override
  protected void doGet(HttpServletRequest req, HttpServletResponse resp)
      throws ServletException, IOException {
    FetchOptions fetchOptions = FetchOptions.Builder.withLimit(PAGE_SIZE);

    // If this servlet is passed a cursor parameter, let's use it.
    String startCursor = req.getParameter("cursor");
    if (startCursor != null) {
      fetchOptions.startCursor(Cursor.fromWebSafeString(startCursor));
    }

    Query q = new Query("Person").addSort("name", SortDirection.ASCENDING);
    PreparedQuery pq = datastore.prepare(q);

    QueryResultList<Entity> results;
    try {
      results = pq.asQueryResultList(fetchOptions);
    } catch (IllegalArgumentException e) {
      // IllegalArgumentException happens when an invalid cursor is used.
      // A user could have manually entered a bad cursor in the URL or there
      // may have been an internal implementation detail change in App Engine.
      // Redirect to the page without the cursor parameter to show something
      // rather than an error.
      resp.sendRedirect("/people");
      return;
    }

    resp.setContentType("text/html");
    resp.setCharacterEncoding("UTF-8");
    PrintWriter w = resp.getWriter();
    w.println("<!DOCTYPE html>");
    w.println("<meta charset=\"utf-8\">");
    w.println("<title>Cloud Datastore Cursor Sample</title>");
    w.println("<ul>");
    for (Entity entity : results) {
      w.println("<li>" + entity.getProperty("name") + "</li>");
    }
    w.println("</ul>");

    String cursorString = results.getCursor().toWebSafeString();

    // This servlet lives at '/people'.
    w.println("<a href='/people?cursor=" + cursorString + "'>Next page</a>");
  }
}

Limitazioni dei cursori

I cursori sono soggetti alle seguenti limitazioni:

  • Un cursore può essere utilizzato solo dalla stessa applicazione che ha eseguito la query originale e solo per continuare la stessa query. Per utilizzare il cursore in un'operazione di recupero successiva, devi ricostituire esattamente la query originale, inclusi lo stesso tipo di entità, lo stesso filtro di antenati, gli stessi filtri delle proprietà e gli stessi ordini di ordinamento. Non è possibile recuperare i risultati utilizzando un cursore senza configurare la stessa query da cui è stato generato originariamente.
  • Poiché gli operatori NOT_EQUAL e IN vengono implementati con più query, le query che li utilizzano non supportano i cursori, né le query composite create con il metodo CompositeFilterOperator.or.
  • I cursori non sempre funzionano come previsto con una query che utilizza un filtro di disuguaglianza o un ordinamento in base a una proprietà con più valori. La logica di deduplicazione per queste proprietà con più valori non viene mantenuta tra i recuperi, il che potrebbe causare la restituzione dello stesso risultato più di una volta.
  • Le nuove release di App Engine potrebbero modificare i dettagli di implementazione interni, invalidando i cursori che dipendono da questi dettagli. Se un'applicazione tenta di utilizzare un cursore non più valido, Datastore genera un errore IllegalArgumentException (API di basso livello), JDOFatalUserException (JDO) o PersistenceException (JPA).

Cursori e aggiornamenti dei dati

La posizione del cursore è definita come la posizione nell'elenco dei risultati dopo l'ultimo risultato restituito. Un cursore non è una posizione relativa nell'elenco (non è un offset), ma un marcatore a cui Datastore può passare quando inizia una scansione dell'indice per i risultati. Se i risultati di una query cambiano tra gli utilizzi di un cursore, la query rileva solo le modifiche che si verificano nei risultati dopo il cursore. Se un nuovo risultato viene visualizzato prima della posizione del cursore per la query, non verrà restituito quando vengono recuperati i risultati dopo il cursore. Allo stesso modo, se un'entità non è più un risultato per una query, ma era apparsa prima del cursore, i risultati che vengono visualizzati dopo il cursore non cambiano. Se l'ultimo risultato restituito viene rimosso dal set di risultati, il cursore sa comunque come individuare il risultato successivo.

Quando recuperi i risultati della query, puoi utilizzare sia un cursore di avvio sia un cursore di fine per restituire un gruppo continuo di risultati da Datastore. Quando utilizzi un cursore di inizio e di fine per recuperare i risultati, non è garantito che le dimensioni dei risultati siano le stesse di quando hai generato i cursori. Le entità possono essere aggiunte o eliminate da Datastore tra il momento in cui vengono generati i cursori e il momento in cui vengono utilizzati in una query.

Passaggi successivi