Datastore 查詢

附註:強烈建議建構新應用程式的開發人員使用 NDB 用戶端程式庫;相較於這個用戶端程式庫,NDB 用戶端程式庫有幾項優點,例如能透過 Memcache API 自動快取實體。如果您目前使用舊版的「DB 用戶端程式庫」,請參閱將 DB 升級至 NDB 的移轉指南

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

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

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

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

篩選器

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

屬性篩選器

「屬性篩選器」指定

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

q = Person.all()
q.filter("height <=", max_height)

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

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

運算子 意義
= 等於
< 小於
<= 小於或等於
> 大於
>= 大於或等於
!= 不等於
IN 成員 (與指定清單中的任何值相等)

不等於 (!=) 運算子實際上會執行兩項查詢:一項查詢中的其他篩選器皆未變更,「不等於」篩選器會替換為「小於」(<) 篩選器,另一項則是會替換為「大於」(>) 篩選器,然後系統會將結果合併並排序。一項查詢中只能有一個「不等於」篩選器,且不得含有其他不等式篩選器。

IN 運算子也會執行多項查詢:指定清單中的各個項目各有一項查詢,而其他篩選器均未經過變更,且 IN 篩選器已替換為「等於」(=) 篩選器。系統會按照清單中項目的排列順序合併結果。如果一項查詢中包含多個 IN 篩選器,則會以多項查詢的形式執行,每個查詢都會對應於 IN 清單中每個可能的值「組合」

如果一項查詢中包含不等於 (!=) 或 IN 運算子,則其子查詢數量不得超過 30 項。

金鑰篩選器

若要篩選實體金鑰的值,請使用特殊屬性 __key__

q = Person.all()
q.filter('__key__ >', last_seen_key)

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

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

祖系路徑的元素會以類似的方式進行比較:先比較種類 (字串),再比較金鑰名稱或數字 ID。種類和金鑰名稱都是字串,且會按照位元組值排序;數字 ID 為整數,會按照數值順序排序。若父項和種類相同的實體混用金鑰名稱和數字 ID,則會先列出採用數字 ID 的實體,再列出採用金鑰名稱的實體。

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

祖系篩選器

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

q = Person.all()
q.ancestor(ancestor_key)

特殊查詢類型

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

無種類查詢

沒有種類且沒有祖系篩選器的查詢,會從 Datastore 中擷取應用程式的所有實體,包括其他 App Engine 功能建立及代管的實體,例如統計資料實體Blobstore 中繼資料實體 (如有)。這類「無種類的查詢」不能包含屬性值篩選條件或排序順序。但是,其能夠以特定的 __key__ 屬性名稱篩選實體金鑰:

q = db.Query()
q.filter('__key__ >', last_seen_key)

在 Python 中,查詢返回的每個實體必須擁有相對應的模型類別 (實體種類所定義)。若要定義統計實體種類的模型類別,您必須匯入 stats 套件:

from google.appengine.ext.db import stats

若您的應用程式具有 Blobstore 值,您必須新增下列的程式碼以取得查詢 API,用於識別 __BlobInfo__ 實體種類。(匯入 Blobstore API 無法定義此類別。)

from google.appengine.ext import db

class BlobInfo(db.Expando):
  @classmethod
  def kind(cls):
    return '__BlobInfo__'

祖系查詢

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

tom = Person(key_name='Tom')

wedding_photo = Photo(parent=tom)
wedding_photo.image_url='http://domain.com/some/path/to/wedding_photo.jpg'
wedding_photo.put()

baby_photo = Photo(parent=tom)
baby_photo.image_url='http://domain.com/some/path/to/baby_photo.jpg'
baby_photo.put()

dance_photo = Photo(parent=tom)
dance_photo.image_url='http://domain.com/some/path/to/dance_photo.jpg'
dance_photo.put()

camping_photo = Photo()
camping_photo.image_url='http://domain.com/some/path/to/camping_photo.jpg'
camping_photo.put()

photo_query = Photo.all()
photo_query.ancestor(tom)

# This returns wedding_photo, baby_photo, and dance_photo,
# but not camping_photo, because tom is not an ancestor
for photo in photo_query.run(limit=5):
  # Do something with photo

無種類祖系查詢

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

q = db.Query()
q.ancestor(ancestor_key)
q.filter('__key__ >', last_seen_key)

如要使用 GQL (無論是在 App Engine 管理控制台或使用 GqlQuery 類別) 執行無種類祖系查詢,請省略 FROM 子句:

q = db.GqlQuery('SELECT * WHERE ANCESTOR IS :1 AND __key__ > :2',
                ancestor_key,
                last_seen_key)

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

tom = Person(key_name='Tom')

wedding_photo = Photo(parent=tom)
wedding_photo.image_url='http://domain.com/some/path/to/wedding_photo.jpg'
wedding_photo.put()

wedding_video = Video(parent=tom)
wedding_video.video_url='http://domain.com/some/path/to/wedding_video.avi'
wedding_video.put()

# The following query returns both weddingPhoto and weddingVideo,
# even though they are of different entity kinds
media_query = db.query_descendants(tom)
for media in media_query.run(limit=5):
  # Do something with media

僅限金鑰查詢

「僅限金鑰查詢」僅傳回結果實體的金鑰而非實體本身,與擷取整個實體相比,延遲及成本都較低。

q = Person.all(keys_only=True)

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

投影查詢

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

排序順序

查詢的「排序順序」指定

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

在 Python 中,遞減排序的順序會由屬性名稱前面的連字符號 (-) 表示,請省略連字符號在預設情況下指定的遞增順序。例如:

# Order alphabetically by last name:
q = Person.all()
q.order('last_name')

# Order by height, tallest to shortest:
q = Person.all()
q.order('-height')

如果查詢包含多個排序順序,他們將按照指定的順序排序。以下的範例首先將「last name」遞增排列,並將「height」遞減排列。

q = Person.all()
q.order('lastName')
q.order('-height')

若未指定排序順序,則會按照從 Cloud DataStore 擷取的順序傳回結果。

附註:由於 Cloud Datastore 執行查詢的方式所致,如果查詢指定以不等式篩選某個屬性並對其他屬性進行排序,則在不等式篩選中使用的屬性必須排序在其他屬性之前。

索引

每個 Datastore 查詢會使用一或多個「索引來計算其結果,這些索引包含順序由索引屬性及實體祖系 (選用) 指定的實體金鑰。系統會逐步更新索引,以便反映應用程式對其實體所做的任何變更,並在不進行進一步計算的情況下提供所有查詢的正確結果。

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

查詢介面範例

Python Datastore API 提供兩個類別用來準備及執行查詢:

  • Query 會使用方法呼叫來準備查詢。
  • GqlQuery 會使用類似於 SQL 的查詢語言「GQL」,依據查詢字串準備查詢。

    class Person(db.Model):
      first_name = db.StringProperty()
      last_name = db.StringProperty()
      city = db.StringProperty()
      birth_year = db.IntegerProperty()
      height = db.IntegerProperty()
    
    # Query interface constructs a query using instance methods
    q = Person.all()
    q.filter("last_name =", "Smith")
    q.filter("height <=", max_height)
    q.order("-height")
    
    # GqlQuery interface constructs a query using a GQL query string
    q = db.GqlQuery("SELECT * FROM Person " +
                    "WHERE last_name = :1 AND height <= :2 " +
                    "ORDER BY height DESC",
                    "Smith", max_height)
    
    # Query is not executed until results are accessed
    for p in q.run(limit=5):
      print "%s %s, %d inches tall" % (p.first_name, p.last_name, p.height)
    

後續步驟

本頁內容對您是否有任何幫助?請提供意見:

傳送您對下列選項的寶貴意見...

這個網頁
Python 2 適用的 App Engine 標準環境