資料存放區查詢

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

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

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

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

篩選器

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

屬性篩選器

「屬性篩選器」指定

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

q := datastore.NewQuery("Person").Filter("Height <=", maxHeight)

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

比較運算子可以為以下任何一種：

運算子 含義
= 等於
< 小於
<= 小於或等於
> 大於
>= 大於或等於

金鑰篩選器

如要篩選實體索引鍵的值，請使用特殊屬性 __key__：

q := datastore.NewQuery("Person").Filter("__key__ >", lastSeenKey)

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

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

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

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

祖系篩選條件

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

q := datastore.NewQuery("Person").Ancestor(ancestorKey)

特殊查詢類型

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

無種類查詢

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

q := datastore.NewQuery("").Filter("__key__ >", lastSeenKey)

祖系查詢

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

// Create two Photo entities in the datastore with a Person as their ancestor.
tomKey := datastore.NewKey(ctx, "Person", "Tom", 0, nil)

wPhoto := Photo{URL: "http://example.com/some/path/to/wedding_photo.jpg"}
wKey := datastore.NewKey(ctx, "Photo", "", 0, tomKey)
_, err := datastore.Put(ctx, wKey, wPhoto)
// check err

bPhoto := Photo{URL: "http://example.com/some/path/to/baby_photo.jpg"}
bKey := datastore.NewKey(ctx, "Photo", "", 0, tomKey)
_, err = datastore.Put(ctx, bKey, bPhoto)
// check err

// Now fetch all Photos that have tomKey as an ancestor.
// This will populate the photos slice with wPhoto and bPhoto.
q := datastore.NewQuery("Photo").Ancestor(tomKey)
var photos []Photo
_, err = q.GetAll(ctx, &photos)
// check err
// do something with photos

無種類祖系查詢

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

q := datastore.NewQuery("").Ancestor(ancestorKey).Filter("__key__ >", lastSeenKey)

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

tomKey := datastore.NewKey(ctx, "Person", "Tom", 0, nil)

weddingPhoto := &Photo{URL: "http://example.com/some/path/to/wedding_photo.jpg"}
_, err := datastore.Put(ctx, datastore.NewIncompleteKey(ctx, "Photo", tomKey), weddingPhoto)

weddingVideo := &Video{URL: "http://example.com/some/path/to/wedding_video.avi"}
_, err = datastore.Put(ctx, datastore.NewIncompleteKey(ctx, "Video", tomKey), weddingVideo)

// The following query returns both weddingPhoto and weddingVideo,
// even though they are of different entity kinds.
q := datastore.NewQuery("").Ancestor(tomKey)
t := q.Run(ctx)
for {
	var x interface{}
	_, err := t.Next(&x)
	if err == datastore.Done {
		break
	}
	if err != nil {
		log.Errorf(ctx, "fetching next Photo/Video: %v", err)
		break
	}
	// Do something (e.g. switch on types)
	doSomething(x)
}

純金鑰查詢

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

q := datastore.NewQuery("Person").KeysOnly()

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

請注意，純索引鍵查詢可以傳回超過 1000 個結果，但 GetAll 一次只能擷取 1000 個鍵，如果以較大的結果呼叫，就會失敗並傳回錯誤。因此，建議您在查詢中加入 1000 個鍵的上限。

投影查詢

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

排序順序

查詢的「排序順序」指定

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

在 Go 中，遞減排序順序會在屬性名稱前加上連字號 (-) 表示；省略連字號則會預設以遞增順序排序。例如：

// Order alphabetically by last name:
q := datastore.NewQuery("Person").Order("LastName")

// Order by height, tallest to shortest:
q = datastore.NewQuery("Person").Order("-Height")

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

q := datastore.NewQuery("Person").Order("LastName").Order("-Height")

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

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

索引

每個 Datastore 查詢會使用一或多個「索引」計算結果，這些索引包含由索引屬性指定的連續實體金鑰，也可能包含該實體的祖系。索引會逐步更新並反映應用程式針對實體進行的任何更改，以利提供所有查詢的正確結果，不需再進一步運算。

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

查詢介面範例

Go Datastore API 提供用於準備及執行查詢的查詢類型。

type Person struct {
	FirstName string
	LastName  string
	City      string
	BirthYear int
	Height    int
}

func handle(w http.ResponseWriter, r *http.Request) {
	ctx := appengine.NewContext(r)

	// The Query type and its methods are used to construct a query.
	q := datastore.NewQuery("Person").
		Filter("LastName =", "Smith").
		Filter("Height <=", maxHeight).
		Order("-Height")

	// To retrieve the results,
	// you must execute the Query using its GetAll or Run methods.
	var people []Person
	if _, err := q.GetAll(ctx, &people); err != nil {
		// Handle error.
	}
	// ...
}

後續步驟