GQL 參考資料

GQL 類似 SQL 語言，可以從應用服務引擎的彈性資料存放區抓取資料實體。雖然 GQL 的功能與傳統關聯式資料庫的查詢語言不同，但是 GQL 語法與 SQL 類似。

GQL 語法的摘要如下：

  SELECT * FROM <kind>
    [WHERE <condition> [AND <condition> ...]]
    [ORDER BY <property> [ASC | DESC] [, <property> [ASC | DESC] ...]]
    [LIMIT [<offset>,]<count>]
    [OFFSET <offset>]

  <condition> := <property> {< | <= | > | >= | = | != } <value>
  <condition> := <property> IN <list>
  <condition> := ANCESTOR IS <entity or key>

與 SQL 相同，GQL 關鍵字會區分大小寫。種類和屬性名稱區分大小寫。

GQL 會傳回零或多個要求種類的資料實體，作為(該種類模型類別的實例。結果都會是完整的實體，因此每個 GQL 查詢都會以 SELECT * FROM 開頭，後面接著該種類的名稱。(類似 SQL 的欄位指定元是 *。 保留 SQL 語法是為了保留其相似性。) GQL 查詢無法執行類似 SQL 的「join」查詢。

選擇性的 WHERE 子句會篩選結果集，只留下符合一或多個條件的實體。每個條件會使用比較運算子來比對實體的屬性和值。若使用 AND 關鍵字指定多個條件，則查詢只會傳回符合所有條件的實體。GQL 沒有 OR 運算子。不過，它有 IN 運算子，這提供了部分型式的 OR 功能。

IN 運算子會比較屬性的值和清單中的每個項目。 IN 運算子等同於多個 = 查詢，每個值使用一個，就像是使用 OR 敘述將它們連結在一起。查詢所傳回的實體，其針對指定屬性的值等於清單中的任何值。

注意：IN 和 != 運算子在背後會使用多個查詢。例如，IN 運算子會為清單中的每個項目執行個別的基礎資料存放區查詢。傳回的實體是所有基礎資料存放區查詢的總合結果，而且會去除重複的項目。每個單一 GQL 查詢最多允許 30 個資料存放區查詢。

使用 ANCESTOR IS 運算子可以測試條件，以測試實體的上階是否為指定實體。值為模型實例或上階實體的 Key。如需關於上階的詳細資訊，請參閱金鑰和實體群組。

比較運算的左手邊是屬性名稱。右手邊可以是下列其中一項 (依屬性的資料類型而定)：

• str 文字，為單引號字串。字串中的單引號字元必須以 '' 逸出。例如：'Joe''s Diner'
• 整數或浮點數文字。例如：42.7
• 布林值文字，為 TRUE 或 FALSE。
• datetime、date 或 time 文字，搭配下列格式的數值或字串：
  • DATETIME(year, month, day, hour, minute, second)
  • DATETIME('YYYY-MM-DD HH:MM:SS')
  • DATE(year, month, day)
  • DATE('YYYY-MM-DD')
  • TIME(hour, minute, second)
  • TIME('HH:MM:SS')
• 實體 key 文字，搭配以字串編碼的金鑰，或完整的種類和金鑰名稱/ID 路徑：
  • KEY('encoded key')
  • KEY(kind, name/ID [, kind, name/ID...])
• User 物件文字，搭配使用者的電子郵件地址：
  USER(email-address)
• GeoPt 文字，搭配浮點數值的緯度和經度：
  GEOPT(lat, long)
• 繫結參數值。在查詢字串中，數字會參考位置參數：title = :1 名稱會參考關鍵字參數：title = :mytitle

繫結的參數可以繫結為位置引數或關鍵字引數，遞送至 GqlQuery 建構函式或 Model 類別的 gql() 方法。 您必須使用參數繫結來指定沒有相應值文字語法的屬性資料類型，包括清單資料類型。在 GqlQuery 實例的留存期間，可以使用 bind() 方法以新值來重新繫結參數繫結 (以有效地重新使用查詢)。

選擇性的 ORDER BY 子句指出結果應該以指定的屬性傳回，可以是遞增 (ASC) 或遞減 (DESC) 順序。若未指定方向，則預設為 ASC。ORDER BY 子句 可以使用逗號分隔的清單來指定多種排序順序，由左而右進行評估。

在最初的 count 個實體之後，可選用 LIMIT 子句使查詢停止傳回結果。LIMIT 也可以包括 offset，跳過這個數量的結果，找到第一個傳回的結果。選擇性的 OFFSET 子句若沒有使用 LIMIT 子句，則可以指定 offset。

注意：LIMIT 子句的最大值為 1000。若指定的限制超過最大值，則會使用最大值。GqlQuery 類別的 fetch() 方法也具有相同的最大值。

注意：就像 fetch() 方法的 offset 參數，GQL 查詢字串中的 OFFSET 不會減少從資料存放區擷取的實體數量。它只會影響 fetch() 方法傳回的結果。含有位移的查詢效能特色與位移的大小成線性關係。

如需關於執行 GQL 查詢、繫結參數以及存取結果的詳細資訊，請參閱 GqlQuery 類別和 Model.gql() 類別方法。