資料存放區查詢

Datastore 的「查詢」會從 Cloud Datastore 中擷取符合一組特定條件的實體。

典型的查詢包含以下幾項：

執行查詢時，查詢會擷取屬於指定種類且符合所有指定篩選器的所有實體，並按照指定順序排序。查詢會以唯讀方式執行。

本頁說明在 App Engine 中，用於從 Cloud Datastore 擷取資料的查詢結構和種類。

篩選器

查詢的「篩選器」會對要擷取實體的屬性、金鑰和祖系設定限制。

屬性篩選器

「屬性篩選器」指定

  • 屬性名稱
  • 比較運算子
  • 屬性值
例如：

Filter propertyFilter =
    new FilterPredicate("height", FilterOperator.GREATER_THAN_OR_EQUAL, minHeight);
Query q = new Query("Person").setFilter(propertyFilter);

屬性值必須由應用程式提供，不能參考或以其他屬性計算而來。如果實體具有指定名稱的屬性，且屬性值與篩選器中指定的值比較，符合比較運算子描述的方式，則該實體符合篩選器的條件。

比較運算子可以為以下任何一種 (在巢狀類別 Query.FilterOperator 中定義為枚舉常數)：

運算子 含義
EQUAL 等於
LESS_THAN 小於
LESS_THAN_OR_EQUAL 小於或等於
GREATER_THAN 大於
GREATER_THAN_OR_EQUAL 大於或等於
NOT_EQUAL 不等於
IN 成員 (與指定清單中的任何值相等)

NOT_EQUAL 運算子實際上執行兩個查詢：一個是在其他所有篩選器皆未變更的情況下，NOT_EQUAL 篩選器會替換為 LESS_THAN 篩選器；另一個則是會替換為 GREATER_THAN 篩選器，然後系統會將結果合併並排序。查詢中只能有一個 NOT_EQUAL 篩選器，且不能有其他任何不等式篩選器。

IN 運算子也會執行多個查詢：每個查詢針對指定清單中的各個項目，而其他篩選器均未變更，且 IN 篩選器替換為 EQUAL 篩選器。結果會依照清單中項目的順序進行合併。如果查詢中包含多個 IN 篩選器，則會以多項查詢執行，每項查詢會對應至 IN 清單中每個可能的值「組合」。

包含 NOT_EQUAL 或 IN 運算子的單一查詢上限為 30 個子查詢。

如要進一步瞭解 NOT_EQUAL 和 IN 查詢如何轉譯為 JDO/JPA 架構中的多個查詢，請參閱「 使用 != 和 IN 篩選器進行查詢」一文。

金鑰篩選器

如要篩選實體金鑰的值，請使用特殊屬性 Entity.KEY_RESERVED_PROPERTY：

Filter keyFilter =
    new FilterPredicate(Entity.KEY_RESERVED_PROPERTY, FilterOperator.GREATER_THAN, lastSeenKey);
Query q = new Query("Person").setFilter(keyFilter);

另外也支援依據 Entity.KEY_RESERVED_PROPERTY 進行遞增排序。

在比較不等式時，金鑰會根據以下標準進行排序：

  1. 祖系路徑
  2. 實體種類
  3. ID (索引鍵名稱或數字 ID)

祖系路徑元素的比較方式類似：依序先比較種類 (字串)，再比較索引鍵名稱或數字 ID。種類和索引鍵名稱都是按位元組值排序的字串；數字 ID 是按數字排序的整數。若父項和種類相同的實體混用索引鍵名稱和數字 ID，則會先列出採用數字 ID 的實體，再列出採用索引鍵名稱的實體。

金鑰查詢像屬性查詢一樣會使用索引，而且在相同情況下都需要自訂索引，只有少數例外狀況：不等式篩選器或金鑰遞增排序不需使用自訂索引，但金鑰遞減排序則必須使用。與所有查詢相同，當測試需要自訂索引的查詢時，開發網路伺服器會在索引設定檔中建立適當的項目。

祖系篩選器

您可以將 Datastore 查詢篩選為指定的祖系，傳回的結果就會只包含來自指定祖系的實體：

Query q = new Query("Person").setAncestor(ancestorKey);

特殊查詢類型

請特別注意下列幾種特定查詢類型：

無種類查詢

沒有種類且沒有祖系篩選器的查詢，會從 Datastore 中擷取應用程式的所有實體，包括其他 App Engine 功能建立及代管的實體，例如統計資料實體和 Blobstore 中繼資料實體 (如有)。這類「無種類查詢」不能對屬性值使用篩選器或進行排序。不過，這類查詢可以指定 Entity.KEY_RESERVED_PROPERTY 做為屬性名稱，藉此篩選實體索引鍵：

Filter keyFilter =
    new FilterPredicate(Entity.KEY_RESERVED_PROPERTY, FilterOperator.GREATER_THAN, lastSeenKey);
Query q = new Query().setFilter(keyFilter);

祖系查詢

採用祖系篩選器的查詢會將結果限制在指定的實體和其子系：

DatastoreService datastore = DatastoreServiceFactory.getDatastoreService();

Entity tom = new Entity("Person", "Tom");
Key tomKey = tom.getKey();
datastore.put(tom);

Entity weddingPhoto = new Entity("Photo", tomKey);
weddingPhoto.setProperty("imageURL", "http://domain.com/some/path/to/wedding_photo.jpg");

Entity babyPhoto = new Entity("Photo", tomKey);
babyPhoto.setProperty("imageURL", "http://domain.com/some/path/to/baby_photo.jpg");

Entity dancePhoto = new Entity("Photo", tomKey);
dancePhoto.setProperty("imageURL", "http://domain.com/some/path/to/dance_photo.jpg");

Entity campingPhoto = new Entity("Photo");
campingPhoto.setProperty("imageURL", "http://domain.com/some/path/to/camping_photo.jpg");

List<Entity> photoList = Arrays.asList(weddingPhoto, babyPhoto, dancePhoto, campingPhoto);
datastore.put(photoList);

Query photoQuery = new Query("Photo").setAncestor(tomKey);

// This returns weddingPhoto, babyPhoto, and dancePhoto,
// but not campingPhoto, because tom is not an ancestor
List<Entity> results =
    datastore.prepare(photoQuery).asList(FetchOptions.Builder.withDefaults());

無種類祖系查詢

無論種類為何，包含祖系篩選器的無種類查詢將會擷取指定的祖系及其所有子系。這類查詢不需要自訂索引。如同所有無種類查詢，這類查詢不能對屬性值使用篩選器或進行排序，但是可以篩選實體索引鍵：

Filter keyFilter =
    new FilterPredicate(Entity.KEY_RESERVED_PROPERTY, FilterOperator.GREATER_THAN, lastSeenKey);
Query q = new Query().setAncestor(ancestorKey).setFilter(keyFilter);

以下範例說明如何擷取指定祖系的所有實體：

DatastoreService datastore = DatastoreServiceFactory.getDatastoreService();

Entity tom = new Entity("Person", "Tom");
Key tomKey = tom.getKey();
datastore.put(tom);

Entity weddingPhoto = new Entity("Photo", tomKey);
weddingPhoto.setProperty("imageURL", "http://domain.com/some/path/to/wedding_photo.jpg");

Entity weddingVideo = new Entity("Video", tomKey);
weddingVideo.setProperty("videoURL", "http://domain.com/some/path/to/wedding_video.avi");

List<Entity> mediaList = Arrays.asList(weddingPhoto, weddingVideo);
datastore.put(mediaList);

// By default, ancestor queries include the specified ancestor itself.
// The following filter excludes the ancestor from the query results.
Filter keyFilter =
    new FilterPredicate(Entity.KEY_RESERVED_PROPERTY, FilterOperator.GREATER_THAN, tomKey);

Query mediaQuery = new Query().setAncestor(tomKey).setFilter(keyFilter);

// Returns both weddingPhoto and weddingVideo,
// even though they are of different entity kinds
List<Entity> results =
    datastore.prepare(mediaQuery).asList(FetchOptions.Builder.withDefaults());

純金鑰查詢

「純索引鍵查詢」僅傳回結果實體的索引鍵而非實體本身，與擷取整個實體相比，延遲時間及成本都較低。

Query q = new Query("Person").setKeysOnly();

先執行僅有金鑰的查詢，並從結果中獲取實體的子集，通常較為經濟實惠。您不需執行一般查詢而得到多餘的實體。

投影查詢

有時候，您只需要用到查詢結果中幾項特定屬性的值。在這種情況下，使用「投影查詢」就能只擷取實際所需屬性。相較於擷取整個實體，這個方式的延遲情況較少，費用也較為低廉。詳情請參閱「投影查詢」頁面。

排序順序

查詢的「排序順序」指定

  • 屬性名稱
  • 排序方向 (遞增或遞減)

例如：

// Order alphabetically by last name:
Query q1 = new Query("Person").addSort("lastName", SortDirection.ASCENDING);

// Order by height, tallest to shortest:
Query q2 = new Query("Person").addSort("height", SortDirection.DESCENDING);

如果查詢包含多個排序順序，則會按照指定的順序套用排序。下列範例會先將「last name」遞增排列，再將「height」遞減排列：

Query q =
    new Query("Person")
        .addSort("lastName", SortDirection.ASCENDING)
        .addSort("height", SortDirection.DESCENDING);

如果未指定排序順序，則會按照從 Datastore 擷取的順序傳回結果。

附註：由於 Datastore 執行查詢的方式，如果查詢指定以不等式篩選條件篩選某個屬性，同時指定其他屬性的排序順序，則在不等式篩選條件中使用的屬性，順序必須在其他屬性之前。

索引

每個 Datastore 查詢會使用一或多個索引 (包含由索引屬性指定的實體金鑰序列，以及實體祖系 (選用)) 計算結果。索引會逐步更新並反映應用程式針對實體進行的任何更改，以利提供所有查詢的正確結果，不需再進一步運算。

應用程式引擎會針對實體的每個屬性預先定義簡單的索引。App Engine 應用程式可在名為 datastore-indexes.xml 的索引設定檔中進一步定義自訂索引，該檔案會在應用程式的 /war/WEB-INF/appengine-generated 目錄中產生。開發伺服器遇到無法使用現有索引執行的查詢時，即會自動在這個檔案中新增建議。您可在上載應用程式之前編輯設定檔，以手動調整索引。

查詢介面範例

低階 Java Datastore API 提供 Query 類別，用於建構查詢，以及 PreparedQuery 介面，用於從 Datastore 擷取實體：

DatastoreService datastore = DatastoreServiceFactory.getDatastoreService();

Filter heightMinFilter =
    new FilterPredicate("height", FilterOperator.GREATER_THAN_OR_EQUAL, minHeight);

Filter heightMaxFilter =
    new FilterPredicate("height", FilterOperator.LESS_THAN_OR_EQUAL, maxHeight);

// Use CompositeFilter to combine multiple filters
CompositeFilter heightRangeFilter =
    CompositeFilterOperator.and(heightMinFilter, heightMaxFilter);

// Use class Query to assemble a query
Query q = new Query("Person").setFilter(heightRangeFilter);

// Use PreparedQuery interface to retrieve results
PreparedQuery pq = datastore.prepare(q);

for (Entity result : pq.asIterable()) {
  String firstName = (String) result.getProperty("firstName");
  String lastName = (String) result.getProperty("lastName");
  Long height = (Long) result.getProperty("height");

  out.println(firstName + " " + lastName + ", " + height + " inches tall");
}

請注意，此處使用 FilterPredicate 和 CompositeFilter 建構篩選器。如果您想在查詢中只設定一個篩選器，則可單獨使用 FilterPredicate：

Filter heightMinFilter =
    new FilterPredicate("height", FilterOperator.GREATER_THAN_OR_EQUAL, minHeight);

Query q = new Query("Person").setFilter(heightMinFilter);

但是，如果您要在查詢中設定多個篩選器，則必須使用至少需要兩個篩選器的 CompositeFilter。上述範例採用捷徑輔助函式 CompositeFilterOperator.and；下列範例則顯示建構複合式 OR 篩選器的一種方式：

Filter tooShortFilter = new FilterPredicate("height", FilterOperator.LESS_THAN, minHeight);

Filter tooTallFilter = new FilterPredicate("height", FilterOperator.GREATER_THAN, maxHeight);

Filter heightOutOfRangeFilter = CompositeFilterOperator.or(tooShortFilter, tooTallFilter);

Query q = new Query("Person").setFilter(heightOutOfRangeFilter);

後續步驟