Datastore 查詢

「查詢」會從 Cloud Firestore (Datastore 模式) 擷取符合一組特定條件的實體。

查詢會針對指定「種類」的實體執行作業，其可指定實體屬性值、索引鍵和祖系的「篩選條件，而且傳回的「結果」可能會是零個或更多個實體。另外，查詢也能指定「排序順序」，按照結果的屬性值進行排序。結果包含的所有實體都具有每個屬性的至少一個值，這些屬性都在篩選器中具名，並按排序順序列出，其屬性值符合所有指定的篩選條件。查詢可傳回整個實體、投影實體，也可以只傳回實體金鑰。

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

執行時，查詢會擷取符合所有指定篩選條件的特定種類實體，並按照指定的順序進行排序。此外，查詢是以唯讀作業的方式來執行。

附註：為了節省記憶體並提升效能，查詢應盡可能指定傳回結果數目限制。

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

索引查詢機制支援多種查詢，適用於大多數應用程式。不過，這種機制並不支援其他資料庫技術常見的某些查詢種類，Datastore 模式查詢引擎尤其不支援彙整與匯總查詢。如需瞭解 Datastore 模式查詢的限制，請參閱下面的查詢限制一節。

查詢介面

以下列舉對 Datastore 模式資料庫發出查詢的基本範例。這項查詢會擷取優先順序大於或等於 4 但尚未完成的所有工作，並以優先順序為準按遞減順序排序：

C#

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore C# API 參考說明文件。

Query query = new Query("Task")
{
    Filter = Filter.And(Filter.Equal("done", false),
        Filter.GreaterThanOrEqual("priority", 4)),
    Order = { { "priority", PropertyOrder.Types.Direction.Descending } }
};

Go

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore Go API 參考說明文件。

query := datastore.NewQuery("Task").
	Filter("Done =", false).
	Filter("Priority >=", 4).
	Order("-Priority")

Java

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore Java API 參考說明文件。

Query<Entity> query = Query.newEntityQueryBuilder()
    .setKind("Task")
    .setFilter(CompositeFilter.and(
        PropertyFilter.eq("done", false), PropertyFilter.ge("priority", 4)))
    .setOrderBy(OrderBy.desc("priority"))
    .build();

Node.js

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore Node.js API 參考說明文件。

const query = datastore
  .createQuery('Task')
  .filter('done', '=', false)
  .filter('priority', '>=', 4)
  .order('priority', {
    descending: true,
  });

PHP

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore PHP API 參考說明文件。

$query = $datastore->query()
    ->kind('Task')
    ->filter('done', '=', false)
    ->filter('priority', '>=', 4)
    ->order('priority', Query::ORDER_DESCENDING);

Python

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore Python API 參考說明文件。

query = client.query(kind='Task')
query.add_filter('done', '=', False)
query.add_filter('priority', '>=', 4)
query.order = ['-priority']

Ruby

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore Ruby API 參考說明文件。

query = datastore.query("Task")
                 .where("done", "=", false)
                 .where("priority", ">=", 4)
                 .order("priority", :desc)

GQL


SELECT * FROM Task
WHERE done = FALSE AND priority >= 4
ORDER BY priority DESC

執行查詢的方式如下：

C#

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore C# API 參考說明文件。

Query query = new Query("Task");
DatastoreQueryResults tasks = _db.RunQuery(query);

Go

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore Go API 參考說明文件。

it := client.Run(ctx, query)
for {
	var task Task
	_, err := it.Next(&task)
	if err == iterator.Done {
		break
	}
	if err != nil {
		log.Fatalf("Error fetching next task: %v", err)
	}
	fmt.Printf("Task %q, Priority %d\n", task.Description, task.Priority)
}

Java

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore Java API 參考說明文件。

QueryResults<Entity> tasks = datastore.run(query);

Node.js

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore Node.js API 參考說明文件。

const [tasks] = await datastore.runQuery(query);
console.log('Tasks:');
tasks.forEach(task => console.log(task));

PHP

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore PHP API 參考說明文件。

$result = $datastore->runQuery($query);

Python

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore Python API 參考說明文件。

query = client.query()
results = list(query.fetch())

Ruby

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore Ruby API 參考說明文件。

tasks = datastore.run query

GQL

不適用

查詢結構

查詢可以指定實體種類、篩選條件 (非必要)，以及排序順序 (非必要)。

篩選器

查詢的「篩選條件」會對所要擷取實體的屬性、索引鍵及祖系設定限制。

屬性篩選條件

「屬性篩選條件」會指定

  • 屬性名稱
  • 比較運算子
  • 屬性值

以下範例會傳回標註未完成的工作實體：

C#

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore C# API 參考說明文件。

Query query = new Query("Task")
{
    Filter = Filter.Equal("done", false)
};

Go

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore Go API 參考說明文件。

query := datastore.NewQuery("Task").Filter("Done =", false)

Java

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore Java API 參考說明文件。

Query<Entity> query =
    Query.newEntityQueryBuilder().setKind("Task").setFilter(PropertyFilter.eq("done", false))
    .build();

Node.js

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore Node.js API 參考說明文件。

const query = datastore.createQuery('Task').filter('done', '=', false);

PHP

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore PHP API 參考說明文件。

$query = $datastore->query()
    ->kind('Task')
    ->filter('done', '=', false);

Python

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore Python API 參考說明文件。

query = client.query(kind='Task')
query.add_filter('done', '=', False)

Ruby

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore Ruby API 參考說明文件。

query = datastore.query("Task")
                 .where("done", "=", false)

GQL


SELECT * FROM Task WHERE done = FALSE

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

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

運算子 意義
EQUAL 等於
LESS_THAN 小於
LESS_THAN_OR_EQUAL 小於或等於
GREATER_THAN 大於
GREATER_THAN_OR_EQUAL 大於或等於

複合篩選條件

「複合篩選條件」包含一個以上的屬性篩選條件。以下範例會傳回標註未完成且優先順序為 4 的工作實體：

C#

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore C# API 參考說明文件。

Query query = new Query("Task")
{
    Filter = Filter.And(Filter.Equal("done", false),
        Filter.Equal("priority", 4)),
};

Go

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore Go API 參考說明文件。

query := datastore.NewQuery("Task").Filter("Done =", false).Filter("Priority =", 4)

Java

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore Java API 參考說明文件。

Query<Entity> query = Query.newEntityQueryBuilder()
    .setKind("Task")
    .setFilter(
        CompositeFilter.and(PropertyFilter.eq("done", false), PropertyFilter.eq("priority", 4)))
    .build();

Node.js

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore Node.js API 參考說明文件。

const query = datastore
  .createQuery('Task')
  .filter('done', '=', false)
  .filter('priority', '=', 4);

PHP

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore PHP API 參考說明文件。

$query = $datastore->query()
    ->kind('Task')
    ->filter('done', '=', false)
    ->filter('priority', '=', 4);

Python

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore Python API 參考說明文件。

query = client.query(kind='Task')
query.add_filter('done', '=', False)
query.add_filter('priority', '=', 4)

Ruby

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore Ruby API 參考說明文件。

query = datastore.query("Task")
                 .where("done", "=", false)
                 .where("priority", "=", 4)

GQL


SELECT * FROM Task WHERE done = FALSE AND priority = 4

Cloud Firestore (Datastore 模式) 只提供合併使用篩選條件和 AND 運算子的原生支援。

索引鍵篩選器

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

C#

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore C# API 參考說明文件。

Query query = new Query("Task")
{
    Filter = Filter.GreaterThan("__key__", _keyFactory.CreateKey("aTask"))
};

Go

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore Go API 參考說明文件。

key := datastore.NameKey("Task", "someTask", nil)
query := datastore.NewQuery("Task").Filter("__key__ >", key)

Java

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore Java API 參考說明文件。

Query<Entity> query = Query.newEntityQueryBuilder()
    .setKind("Task")
    .setFilter(PropertyFilter.gt("__key__", keyFactory.newKey("someTask")))
    .build();

Node.js

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore Node.js API 參考說明文件。

const query = datastore
  .createQuery('Task')
  .filter('__key__', '>', datastore.key(['Task', 'someTask']));

PHP

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore PHP API 參考說明文件。

$query = $datastore->query()
    ->kind('Task')
    ->filter('__key__', '>', $datastore->key('Task', 'someTask'));

Python

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore Python API 參考說明文件。

query = client.query(kind='Task')
first_key = client.key('Task', 'first_task')
# key_filter(key, op) translates to add_filter('__key__', op, key).
query.key_filter(first_key, '>')

Ruby

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore Ruby API 參考說明文件。

query = datastore.query("Task")
                 .where("__key__", ">", datastore.key("Task", "someTask"))

GQL


SELECT * FROM Task WHERE __key__ > KEY(Task, 'someTask')

在比較不等式時，會根據以下標準排序索引鍵：

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

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

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

排序順序

查詢的「排序順序」會指定

  • 屬性名稱。
  • 排序方向 (遞增或遞減)。預設是遞減排序。

以下範例是以建立時間為準，按遞增順序排序工作實體：

C#

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore C# API 參考說明文件。

Query query = new Query("Task")
{
    Order = { { "created", PropertyOrder.Types.Direction.Ascending } }
};

Go

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore Go API 參考說明文件。

query := datastore.NewQuery("Task").Order("created")

Java

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore Java API 參考說明文件。

Query<Entity> query =
    Query.newEntityQueryBuilder().setKind("Task").setOrderBy(OrderBy.asc("created")).build();

Node.js

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore Node.js API 參考說明文件。

const query = datastore.createQuery('Task').order('created');

PHP

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore PHP API 參考說明文件。

$query = $datastore->query()
    ->kind('Task')
    ->order('created');

Python

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore Python API 參考說明文件。

query = client.query(kind='Task')
query.order = ['created']

Ruby

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore Ruby API 參考說明文件。

query = datastore.query("Task")
                 .order("created", :asc)

GQL


SELECT * FROM Task ORDER BY created ASC

以下範例是以建立時間為準，按遞減順序排序工作實體：

C#

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore C# API 參考說明文件。

Query query = new Query("Task")
{
    Order = { { "created", PropertyOrder.Types.Direction.Descending } }
};

Go

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore Go API 參考說明文件。

query := datastore.NewQuery("Task").Order("-created")

Java

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore Java API 參考說明文件。

Query<Entity> query =
    Query.newEntityQueryBuilder().setKind("Task").setOrderBy(OrderBy.desc("created")).build();

Node.js

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore Node.js API 參考說明文件。

const query = datastore.createQuery('Task').order('created', {
  descending: true,
});

PHP

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore PHP API 參考說明文件。

$query = $datastore->query()
    ->kind('Task')
    ->order('created', Query::ORDER_DESCENDING);

Python

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore Python API 參考說明文件。

query = client.query(kind='Task')
query.order = ['-created']

Ruby

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore Ruby API 參考說明文件。

query = datastore.query("Task")
                 .order("created", :desc)

GQL


SELECT * FROM Task ORDER BY created DESC

如果查詢包含多個排序順序，則會按照指定的順序套用排序。以下範例先按優先順序遞減排序，再按建立時間遞增排序：

C#

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore C# API 參考說明文件。

Query query = new Query("Task")
{
    Order = { { "priority", PropertyOrder.Types.Direction.Descending },
        { "created", PropertyOrder.Types.Direction.Ascending } }
};

Go

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore Go API 參考說明文件。

query := datastore.NewQuery("Task").Order("-priority").Order("created")

Java

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore Java API 參考說明文件。

Query<Entity> query = Query.newEntityQueryBuilder()
    .setKind("Task")
    .setOrderBy(OrderBy.desc("priority"), OrderBy.asc("created"))
    .build();

Node.js

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore Node.js API 參考說明文件。

const query = datastore
  .createQuery('Task')
  .order('priority', {
    descending: true,
  })
  .order('created');

PHP

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore PHP API 參考說明文件。

$query = $datastore->query()
    ->kind('Task')
    ->order('priority', Query::ORDER_DESCENDING)
    ->order('created');

Python

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore Python API 參考說明文件。

query = client.query(kind='Task')
query.order = [
    '-priority',
    'created'
]

Ruby

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore Ruby API 參考說明文件。

query = datastore.query("Task")
                 .order("priority", :desc)
                 .order("created", :asc)

GQL


SELECT * FROM Task ORDER BY priority DESC, created ASC

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

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

特殊查詢類型

應特別注意的幾種特定查詢類型：

祖系查詢

祖系查詢會將結果限制在指定的實體及其子系。以下範例會傳回指定以 TaskList 實體為祖系的所有工作實體：

C#

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore C# API 參考說明文件。

Query query = new Query("Task")
{
    Filter = Filter.HasAncestor(_db.CreateKeyFactory("TaskList")
        .CreateKey(keyName))
};

Go

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore Go API 參考說明文件。

ancestor := datastore.NameKey("TaskList", "default", nil)
query := datastore.NewQuery("Task").Ancestor(ancestor)

Java

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore Java API 參考說明文件。

Query<Entity> query = Query.newEntityQueryBuilder()
    .setKind("Task")
    .setFilter(PropertyFilter.hasAncestor(
        datastore.newKeyFactory().setKind("TaskList").newKey("default")))
    .build();

Node.js

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore Node.js API 參考說明文件。

const ancestorKey = datastore.key(['TaskList', 'default']);

const query = datastore.createQuery('Task').hasAncestor(ancestorKey);

PHP

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore PHP API 參考說明文件。

$ancestorKey = $datastore->key('TaskList', 'default');
$query = $datastore->query()
    ->kind('Task')
    ->hasAncestor($ancestorKey);

Python

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore Python API 參考說明文件。

# Query filters are omitted in this example as any ancestor queries with a
# non-key filter require a composite index.
ancestor = client.key('TaskList', 'default')
query = client.query(kind='Task', ancestor=ancestor)

Ruby

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore Ruby API 參考說明文件。

ancestor_key = datastore.key "TaskList", "default"

query = datastore.query("Task")
                 .ancestor(ancestor_key)

GQL


SELECT * FROM Task WHERE __key__ HAS ANCESTOR KEY(TaskList, 'default')

無種類查詢

沒有種類和祖系的查詢會從 Datastore 模式擷取應用程式的所有實體。這類「無種類查詢」不能對屬性值使用篩選條件或進行排序。不過，這類查詢可以按實體索引鍵篩選，也可以使用祖系篩選條件。將 __key__ 指定為屬性名稱，即可使用索引鍵篩選條件：

C#

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore C# API 參考說明文件。

Query query = new Query()
{
    Filter = Filter.GreaterThan("__key__",
        _keyFactory.CreateKey("aTask"))
};

Go

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore Go API 參考說明文件。

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

Java

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore Java API 參考說明文件。

Query<Entity> query =
    Query.newEntityQueryBuilder().setFilter(PropertyFilter.gt("__key__", lastSeenKey)).build();

Node.js

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore Node.js API 參考說明文件。

const query = datastore
  .createQuery()
  .filter('__key__', '>', lastSeenKey)
  .limit(1);

PHP

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore PHP API 參考說明文件。

$query = $datastore->query()
    ->filter('__key__', '>', $lastSeenKey);

Python

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore Python API 參考說明文件。

query = client.query()
query.key_filter(last_seen_key, '>')

Ruby

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore Ruby API 參考說明文件。

query = Google::Cloud::Datastore::Query.new
query.where "__key__", ">", last_seen_key

GQL


SELECT * WHERE __key__ > KEY(Task, 'someTask')

投影查詢

大多數查詢結果會傳回完整實體，但應用程式真正需要的往往只有該實體的其中幾項屬性。您可以按照實際需求，運用「投影查詢」單純查詢某個實體的特定屬性，相較於擷取完整實體，這種方式更有助於減少延遲時間及降低成本。

投影查詢要求必須為指定的屬性建立索引。

純金鑰查詢

「純金鑰查詢」(投影查詢的其中一種類型) 只會傳回結果實體的金鑰，不會傳回實體本身，相較於擷取全部的實體，這類查詢既能減少延遲時間，也能降低費用。

先執行純金鑰查詢，再從結果擷取實體子集，這種方式通常較為經濟實惠。不需執行一般查詢而擷取多餘的實體。

以下說明僅限索引鍵查詢的建立方式：

C#

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore C# API 參考說明文件。

Query query = new Query("Task")
{
    Projection = { "__key__" }
};

Go

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore Go API 參考說明文件。

query := datastore.NewQuery("Task").KeysOnly()

Java

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore Java API 參考說明文件。

Query<Key> query = Query.newKeyQueryBuilder().setKind("Task").build();

Node.js

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore Node.js API 參考說明文件。

const query = datastore
  .createQuery()
  .select('__key__')
  .limit(1);

PHP

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore PHP API 參考說明文件。

$query = $datastore->query()
    ->keysOnly();

Python

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore Python API 參考說明文件。

query = client.query()
query.keys_only()

Ruby

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore Ruby API 參考說明文件。

query = datastore.query("Task")
                 .select("__key__")

GQL


SELECT __key__ FROM Task

僅限索引鍵的查詢，屬於小型作業，只算查詢本身的單次實體讀取作業。

投影

投影查詢近似於下列形式的 SQL 查詢：

SELECT priority, percent_complete FROM Task

您可以使用所有適用於標準實體查詢的篩選和排序功能，但請注意此段落提及的限制。

SQL 查詢範例會傳回簡略版結果，只包含指定屬性 priority 和 percent_complete，且會填入屬性值；所有其他的屬性均未填入值。以下示範如何建構投影查詢：

C#

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore C# API 參考說明文件。

Query query = new Query("Task")
{
    Projection = { "priority", "percent_complete" }
};

Go

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore Go API 參考說明文件。

query := datastore.NewQuery("Task").Project("Priority", "PercentComplete")

Java

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore Java API 參考說明文件。

Query<ProjectionEntity> query = Query.newProjectionEntityQueryBuilder()
    .setKind("Task")
    .setProjection("priority", "percent_complete")
    .build();

Node.js

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore Node.js API 參考說明文件。

const query = datastore
  .createQuery('Task')
  .select(['priority', 'percent_complete']);

PHP

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore PHP API 參考說明文件。

$query = $datastore->query()
    ->kind('Task')
    ->projection(['priority', 'percent_complete']);

Python

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore Python API 參考說明文件。

query = client.query(kind='Task')
query.projection = ['priority', 'percent_complete']

Ruby

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore Ruby API 參考說明文件。

query = datastore.query("Task")
                 .select("priority", "percent_complete")

GQL


SELECT priority, percent_complete FROM Task

以下則示範執行投影查詢的方式：

C#

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore C# API 參考說明文件。

Query query = new Query("Task")
{
    Projection = { "priority", "percent_complete" }
};
List<long> priorities = new List<long>();
List<double> percentCompletes = new List<double>();
foreach (var entity in _db.RunQuery(query).Entities)
{
    priorities.Add((long)entity["priority"]);
    percentCompletes.Add((double)entity["percent_complete"]);
}

Go

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore Go API 參考說明文件。

var priorities []int
var percents []float64
it := client.Run(ctx, query)
for {
	var task Task
	if _, err := it.Next(&task); err == iterator.Done {
		break
	} else if err != nil {
		log.Fatal(err)
	}
	priorities = append(priorities, task.Priority)
	percents = append(percents, task.PercentComplete)
}

Java

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore Java API 參考說明文件。

List<Long> priorities = new LinkedList<>();
List<Double> percentCompletes = new LinkedList<>();
QueryResults<ProjectionEntity> tasks = datastore.run(query);
while (tasks.hasNext()) {
  ProjectionEntity task = tasks.next();
  priorities.add(task.getLong("priority"));
  percentCompletes.add(task.getDouble("percent_complete"));
}

Node.js

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore Node.js API 參考說明文件。

async function runProjectionQuery() {
  const priorities = [];
  const percentCompletes = [];
  const [tasks] = await datastore.runQuery(query);
  tasks.forEach(task => {
    priorities.push(task.priority);
    percentCompletes.push(task.percent_complete);
  });

  return {
    priorities: priorities,
    percentCompletes: percentCompletes,
  };
}

PHP

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore PHP API 參考說明文件。

$priorities = array();
$percentCompletes = array();
$result = $datastore->runQuery($query);
/* @var Entity $task */
foreach ($result as $task) {
    $priorities[] = $task['priority'];
    $percentCompletes[] = $task['percent_complete'];
}

Python

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore Python API 參考說明文件。

priorities = []
percent_completes = []

for task in query.fetch():
    priorities.append(task['priority'])
    percent_completes.append(task['percent_complete'])

Ruby

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore Ruby API 參考說明文件。

priorities = []
percent_completes = []
datastore.run(query).each do |task|
  priorities << task["priority"]
  percent_completes << task["percent_complete"]
end

GQL

不適用

不使用 distinct on 子句的投影查詢屬於小型作業，只算查詢本身的單次實體讀取作業。

分組

投影查詢可以使用 distinct on 子句，確保只會傳回指定屬性不同值組合的第一個結果。若有投影實體具有相同的屬性值，則只會傳回第一個結果。

C#

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore C# API 參考說明文件。

Query query = new Query("Task")
{
    Projection = { "category", "priority" },
    DistinctOn = { "category" },
    Order = {
        { "category", PropertyOrder.Types.Direction.Ascending},
        {"priority", PropertyOrder.Types.Direction.Ascending }
    }
};

Go

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore Go API 參考說明文件。

query := datastore.NewQuery("Task").
	Project("Priority", "Category").
	DistinctOn("Category").
	Order("Category").Order("Priority")

Java

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore Java API 參考說明文件。

Query<ProjectionEntity> query = Query.newProjectionEntityQueryBuilder()
    .setKind("Task")
    .setProjection("category", "priority")
    .setDistinctOn("category")
    .setOrderBy(OrderBy.asc("category"), OrderBy.asc("priority"))
    .build();

Node.js

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore Node.js API 參考說明文件。

const query = datastore
  .createQuery('Task')
  .groupBy('category')
  .order('category')
  .order('priority');

PHP

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore PHP API 參考說明文件。

$query = $datastore->query()
    ->kind('Task')
    ->order('category')
    ->order('priority')
    ->projection(['category', 'priority'])
    ->distinctOn('category');

Python

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore Python API 參考說明文件。

query = client.query(kind='Task')
query.distinct_on = ['category']
query.order = ['category', 'priority']

Ruby

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore Ruby API 參考說明文件。

query = datastore.query("Task")
                 .select("category", "priority")
                 .distinct_on("category")
                 .order("category")
                 .order("priority")

GQL


SELECT DISTINCT ON (category) category, priority FROM Task
ORDER BY category, priority

陣列值

查詢包含有陣列值的屬性時，請思考以下情形。

含陣列值的屬性可能會出現非預期的行為

由於索引編列方式所致，實體若包含同一個屬性的多個值，有時候可能會與查詢篩選條件及排序順序發生非預期的交互作用，因而出現預料之外的結果。

若查詢包含指定屬性的多個不等式篩選條件，除非屬性至少有一個屬性值符合「所有」篩選條件，否則實體不會與查詢一致。舉例來說，如果屬於 Task 種類的實體包含 fun 和 programming 這兩個 tag 屬性值，就「無法」與查詢相符：

C#

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore C# API 參考說明文件。

Query query = new Query("Task")
{
    Filter = Filter.And(Filter.GreaterThan("tag", "learn"),
        Filter.LessThan("tag", "math"))
};

Go

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore Go API 參考說明文件。

query := datastore.NewQuery("Task").
	Filter("Tag >", "learn").
	Filter("Tag <", "math")

Java

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore Java API 參考說明文件。

Query<Entity> query = Query.newEntityQueryBuilder()
    .setKind("Task")
    .setFilter(CompositeFilter.and(
        PropertyFilter.gt("tag", "learn"), PropertyFilter.lt("tag", "math")))
    .build();

Node.js

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore Node.js API 參考說明文件。

const query = datastore
  .createQuery('Task')
  .filter('tag', '>', 'learn')
  .filter('tag', '<', 'math');

PHP

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore PHP API 參考說明文件。

$query = $datastore->query()
    ->kind('Task')
    ->filter('tag', '>', 'learn')
    ->filter('tag', '<', 'math');

Python

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore Python API 參考說明文件。

query = client.query(kind='Task')
query.add_filter('tag', '>', 'learn')
query.add_filter('tag', '<', 'math')

Ruby

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore Ruby API 參考說明文件。

query = datastore.query("Task")
                 .where("tag", ">", "learn")
                 .where("tag", "<", "math")

GQL


SELECT * FROM Task WHERE tag > 'learn' AND tag < 'math'

每個實體的 tag 值各自符合其中一個篩選條件，但沒有一個值同時符合兩個篩選條件。請注意，等式篩選條件不適用這項原則。舉例來說，以上實體就「會」符合以下查詢條件：

C#

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore C# API 參考說明文件。

Query query = new Query("Task")
{
    Filter = Filter.And(Filter.Equal("tag", "fun"),
        Filter.Equal("tag", "programming"))
};

Go

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore Go API 參考說明文件。

query := datastore.NewQuery("Task").
	Filter("Tag =", "fun").
	Filter("Tag =", "programming")

Java

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore Java API 參考說明文件。

Query<Entity> query = Query.newEntityQueryBuilder()
    .setKind("Task")
    .setFilter(CompositeFilter.and(
        PropertyFilter.eq("tag", "fun"), PropertyFilter.eq("tag", "programming")))
    .build();

Node.js

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore Node.js API 參考說明文件。

const query = datastore
  .createQuery('Task')
  .filter('tag', '=', 'fun')
  .filter('tag', '=', 'programming');

PHP

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore PHP API 參考說明文件。

$query = $datastore->query()
    ->kind('Task')
    ->filter('tag', '=', 'fun')
    ->filter('tag', '=', 'programming');

Python

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore Python API 參考說明文件。

query = client.query(kind='Task')
query.add_filter('tag', '=', 'fun')
query.add_filter('tag', '=', 'programming')

Ruby

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore Ruby API 參考說明文件。

query = datastore.query("Task")
                 .where("tag", "=", "fun")
                 .where("tag", "=", "programming")

GQL


SELECT * FROM Task WHERE tag = 'fun' AND tag = 'programming'

即使實體沒有任何一個 tag 值同時符合兩種篩選條件也無妨。

多值屬性的排序順序也一樣不尋常。這類屬性會在每個不重複值的索引中出現一次，因此，索引中出現的第一個值決定該實體的排序順序。

若沒有任何篩選條件使用多值屬性：

  • 且以屬性為準按遞增順序排序查詢結果，會使用屬性的最小值進行排序。
  • 且以屬性為準按遞減順序排序查詢結果，則會使用最大值進行排序。
  • 其他值和值的數量都不會影響排序順序。

這種情況會出現不尋常的結果：按遞增順序「和」遞減順序排列時，包含 1 和 9 這兩個屬性值的實體會排在包含 4、5、6 和 7 值的實體之前。

若等式篩選條件使用多值屬性，會忽略該屬性的任何排序順序。

若不等式篩選條件使用多值屬性：

  • 且以屬性為準按遞增順序排序查詢結果，會使用符合所有查詢之不等式篩選條件的最小值進行排序。
  • 且以屬性為準按遞減順序排序查詢結果，會使用符合所有查詢之不等式篩選條件的最大值進行排序。

請注意，若將一組屬性不等式篩選條件轉換為等式篩選條件，如下所示：

WHERE tags >= 'math' AND tags <= 'math'

將會忽略該屬性的任何排列順序，因為篩選條件進行評估的方式與等式篩選條件相同。

WHERE tags = 'math'

投影屬性與陣列值屬性

投影含陣列值的屬性時，不會填入該屬性的所有值。反之，每個符合查詢條件且不重複的投影值組合將分別傳回一個獨立實體。例如，假設有一個 Task 種類的實體，包含兩個多值屬性 tags 和 collaborators：

C#

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore C# API 參考說明文件。

Entity task = new Entity()
{
    Key = _db.CreateKeyFactory("Task").CreateKey("sampleTask"),
    ["collaborators"] = new ArrayValue() { Values = { "alice", "bob" } },
    ["tags"] = new ArrayValue() { Values = { "fun", "programming" } }
};

Go

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore Go API 參考說明文件。

type Task struct {
	Tags          []string
	Collaborators []string
}
task := &Task{
	Tags:          []string{"fun", "programming"},
	Collaborators: []string{"alice", "bob"},
}

Java

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore Java API 參考說明文件。

Entity task = Entity.newBuilder(taskKey)
    .set("tags", "fun", "programming")
    .set("collaborators", ListValue.of("alice", "bob"))
    .build();

Node.js

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore Node.js API 參考說明文件。

const task = {
  tags: ['fun', 'programming'],
  collaborators: ['alice', 'bob'],
};

PHP

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore PHP API 參考說明文件。

$task = $datastore->entity(
    $key,
    [
        'tags' => ['fun', 'programming'],
        'collaborators' => ['alice', 'bob']
    ]
);

Python

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore Python API 參考說明文件。

task = datastore.Entity(key)
task.update({
    'tags': [
        'fun',
        'programming'
    ],
    'collaborators': [
        'alice',
        'bob'
    ]
})

Ruby

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore Ruby API 參考說明文件。

task = datastore.entity "Task", "sampleTask" do |t|
  t["tags"] = ["fun", "programming"]
  t["collaborators"] = ["alice", "bob"]
end

GQL

不適用

之後，投影查詢

SELECT tags, collaborators FROM Task WHERE collaborators < 'charlie'

會傳回四個包含下列組合值的實體：

tags = 'fun', collaborators = 'alice'
= 'fun', collaborators = 'bob'
= 'programming', collaborators = 'alice'
= 'programming', collaborators = 'bob'

游標、限制和位移

您可以指定查詢的「限制」，用於控管一批傳回結果的數量上限。以下範例最多會擷取五個工作實體：

C#

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore C# API 參考說明文件。

Query query = new Query("Task")
{
    Limit = 5,
};

Go

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore Go API 參考說明文件。

query := datastore.NewQuery("Task").Limit(5)

Java

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore Java API 參考說明文件。

Query<Entity> query = Query.newEntityQueryBuilder().setKind("Task").setLimit(5).build();

Node.js

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore Node.js API 參考說明文件。

const query = datastore.createQuery('Task').limit(5);

PHP

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore PHP API 參考說明文件。

$query = $datastore->query()
    ->kind('Task')
    ->limit(5);

Python

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore Python API 參考說明文件。

query = client.query()
tasks = list(query.fetch(limit=5))

Ruby

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore Ruby API 參考說明文件。

query = datastore.query("Task")
                 .limit(5)

GQL


SELECT * FROM Task LIMIT 5

「查詢游標」讓應用程式能夠方便地分批擷取查詢結果，而不會造成查詢位移負擔。執行擷取作業後，應用程式可以取得不透明位元組字串游標，這個游標會標示出上一次擷取結果的索引位置。應用程式可以儲存這個字串 (例如儲存在 Datastore 模式資料庫、快取，或是以 base-64 編碼 HTTP GET 或 POST 參數形式嵌入於網頁中)，之後就能以游標做為後續擷取作業的起點，自上一次擷取的終點開始取得下一批結果。擷取作業也可以指定結束游標，用於限制傳回結果集的範圍。

以下範例說明如何使用游標進行分頁作業：

C#

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore C# API 參考說明文件。

Query query = new Query("Task")
{
    Limit = pageSize,
};
if (!string.IsNullOrEmpty(pageCursor))
    query.StartCursor = ByteString.FromBase64(pageCursor);

return _db.RunQuery(query).EndCursor?.ToBase64();

Go

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore Go API 參考說明文件。

const pageSize = 5
query := datastore.NewQuery("Tasks").Limit(pageSize)
if cursorStr != "" {
	cursor, err := datastore.DecodeCursor(cursorStr)
	if err != nil {
		log.Fatalf("Bad cursor %q: %v", cursorStr, err)
	}
	query = query.Start(cursor)
}

// Read the tasks.
var tasks []Task
var task Task
it := client.Run(ctx, query)
_, err := it.Next(&task)
for err == nil {
	tasks = append(tasks, task)
	_, err = it.Next(&task)
}
if err != iterator.Done {
	log.Fatalf("Failed fetching results: %v", err)
}

// Get the cursor for the next page of results.
nextCursor, err := it.Cursor()

Java

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore Java API 參考說明文件。

EntityQuery.Builder queryBuilder = Query.newEntityQueryBuilder().setKind("Task")
    .setLimit(pageSize);
if (pageCursor != null) {
  queryBuilder.setStartCursor(pageCursor);
}
QueryResults<Entity> tasks = datastore.run(queryBuilder.build());
while (tasks.hasNext()) {
  Entity task = tasks.next();
  // do something with the task
}
Cursor nextPageCursor = tasks.getCursorAfter();

Node.js

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore Node.js API 參考說明文件。

// By default, google-cloud-node will automatically paginate through all of
// the results that match a query. However, this sample implements manual
// pagination using limits and cursor tokens.
async function runPageQuery(pageCursor) {
  let query = datastore.createQuery('Task').limit(pageSize);

  if (pageCursor) {
    query = query.start(pageCursor);
  }
  const results = await datastore.runQuery(query);
  const entities = results[0];
  const info = results[1];

  if (info.moreResults !== Datastore.NO_MORE_RESULTS) {
    // If there are more results to retrieve, the end cursor is
    // automatically set on `info`. To get this value directly, access
    // the `endCursor` property.
    const results = await runPageQuery(info.endCursor);

    // Concatenate entities
    results[0] = entities.concat(results[0]);
    return results;
  }

  return [entities, info];
}

PHP

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore PHP API 參考說明文件。

/**
 * Fetch a query cursor.
 *
 * @param DatastoreClient $datastore
 * @param string $pageSize
 * @param string $pageCursor
 * @return array
 */
function cursor_paging(DatastoreClient $datastore, $pageSize, $pageCursor = '')
{
    $query = $datastore->query()
        ->kind('Task')
        ->limit($pageSize)
        ->start($pageCursor);
    $result = $datastore->runQuery($query);
    $nextPageCursor = '';
    $entities = [];
    /* @var Entity $entity */
    foreach ($result as $entity) {
        $nextPageCursor = $entity->cursor();
        $entities[] = $entity;
    }
    return array(
        'nextPageCursor' => $nextPageCursor,
        'entities' => $entities
    );
}

Python

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore Python API 參考說明文件。


def get_one_page_of_tasks(cursor=None):
    query = client.query(kind='Task')
    query_iter = query.fetch(start_cursor=cursor, limit=5)
    page = next(query_iter.pages)

    tasks = list(page)
    next_cursor = query_iter.next_page_token

    return tasks, next_cursor

Ruby

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore Ruby API 參考說明文件。

page_size = 2
query = datastore.query("Task")
                 .limit(page_size)
tasks = datastore.run query

page_cursor = tasks.cursor

query = datastore.query("Task")
                 .limit(page_size)
                 .start(page_cursor)

GQL

不適用

雖然 Datastore 模式資料庫支援整數位移，但建議您避免使用。最好改用游標。使用位移只能避免將略過的實體傳送至應用程式，但仍然可以在內部擷取這些實體。略過的實體會影響查詢延遲時間，您的應用程式仍然必須為擷取這類實體而進行的讀取作業付費。使用游標取代位移可以避免這些費用。

游標的限制

游標必須遵循以下限制：

  • 只有執行原始查詢的專案能夠使用游標，而且只能用於繼續執行相同的查詢。若未設定原始產生游標的查詢，就無法使用這個游標擷取結果。
  • 如變更以下任何項目，後續擷取作業仍然可以使用游標。
    • 開始游標
    • 結束游標
    • 位移
    • 限制
  • 如變更以下任何項目，後續擷取作業就不能使用游標。
    • 投影
    • 種類
    • 祖系
    • 篩選條件
    • 不重複特性
    • 排序順序

      如果原始查詢的最終排序順序為 __key__，則為例外狀況。在此情況下，您可以在「反向查詢」(排序順序與原始查詢相反的查詢) 中使用游標。反向查詢可以修改開始游標、結束游標、位移與限制。

  • 若查詢使用不等式篩選條件或以多值屬性為排序順序，游標就不一定能夠發揮正常作用。每次擷取作業之間不會保留此類多值屬性的清除重複邏輯，因此可能會重複傳回同一個結果。
  • 新版 Datastore 模式可能會變更內部實作詳細資料，撤銷依賴這些屬性的游標。如果應用程式嘗試使用已經失效的游標，Cloud Firestore (Datastore 模式) 就會引發例外狀況。

游標與資料更新

游標代表上一次傳回結果後在結果清單中的位置。游標不是清單中的相對位置 (並非位移)；而是開始在結果中進行索引掃描時，Datastore 模式資料庫可以跳至該處的標記。在兩次使用游標的行為之間，如果查詢結果出現變化，查詢只會注意到游標之後的結果變化。如果新的結果出現在游標位置之前，則在擷取游標之後的結果時，並不會傳回這項新結果。同樣的道理，如果某項實體已不再是查詢的結果，但卻出現在游標之前，則出現在游標之後的結果不會變更。如果將最後傳回的結果從結果集移除，游標仍然知道如何找到下一個結果。

擷取查詢結果時，您可以同時使用開始游標和結束游標傳回一組連續的結果。使用開始游標和結束游標擷取結果時，系統不保證結果大小會與產生游標時的大小相同。從產生游標到在查詢中使用游標的這段時間內，可能新增或刪除資料庫中的實體。

查詢限制

索引查詢機制的性質會對查詢能夠執行的功能造成某些限制。Datastore 模式查詢不支援子字串比對、不區分大小寫比對，以及所謂的全文搜尋。NOT、OR 和 != 運算子均非原生支援對象，但有些用戶端程式庫可能會增加 Datastore 模式以外的資源。此外：

系統會忽略查詢中少了屬性名稱的實體

相同種類的實體不一定具備相同的屬性。針對每一個在查詢篩選器和排序順序中指定的屬性，實體都必須擁有一個值 (可能是空值)，才有資格做為查詢結果。否則用於執行查詢的索引就會忽略該實體，查詢結果自然就不會包含該實體。

篩選未建立索引的屬性不會傳回任何結果

查詢找不到未建立索引的屬性值，也無法排序這類屬性。如需進一步瞭解無索引屬性的討論，請參閱無索引屬性一節。

不等式篩選條件最多限用於一個屬性

為避免必須掃描整個索引，查詢機制會要求一個查詢的所有可能結果在索引中彼此相鄰。為符合這項限制，單一查詢不能使用不等式比較運算子 (LESS_THAN、LESS_THAN_OR_EQUAL、GREATER_THAN、GREATER_THAN_OR_EQUAL) 比較符合其所有篩選條件的多個屬性。例如，以下查詢的兩個不等式篩選器會套用至相同屬性，因此查詢有效：

C#

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore C# API 參考說明文件。

Query query = new Query("Task")
{
    Filter = Filter.And(Filter.GreaterThan("created", _startDate),
        Filter.LessThan("created", _endDate))
};

Go

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore Go API 參考說明文件。

query := datastore.NewQuery("Task").
	Filter("Created >", time.Date(1990, 1, 1, 0, 0, 0, 0, time.UTC)).
	Filter("Created <", time.Date(2000, 1, 1, 0, 0, 0, 0, time.UTC))

Java

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore Java API 參考說明文件。

Query<Entity> query = Query.newEntityQueryBuilder()
    .setKind("Task")
    .setFilter(CompositeFilter.and(
        PropertyFilter.gt("created", startDate), PropertyFilter.lt("created", endDate)))
    .build();

Node.js

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore Node.js API 參考說明文件。

const query = datastore
  .createQuery('Task')
  .filter('created', '>', new Date('1990-01-01T00:00:00z'))
  .filter('created', '<', new Date('2000-12-31T23:59:59z'));

PHP

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore PHP API 參考說明文件。

$query = $datastore->query()
    ->kind('Task')
    ->filter('created', '>', new DateTime('1990-01-01T00:00:00z'))
    ->filter('created', '<', new DateTime('2000-12-31T23:59:59z'));

Python

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore Python API 參考說明文件。

start_date = datetime.datetime(1990, 1, 1)
end_date = datetime.datetime(2000, 1, 1)
query = client.query(kind='Task')
query.add_filter(
    'created', '>', start_date)
query.add_filter(
    'created', '<', end_date)

Ruby

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore Ruby API 參考說明文件。

query = datastore.query("Task")
                 .where("created", ">=", Time.utc(1990, 1, 1))
                 .where("created", "<", Time.utc(2000, 1, 1))

GQL


SELECT * FROM Task
WHERE created > DATETIME('1990-01-01T00:00:00z')
  AND created < DATETIME('2000-12-31T23:59:59z')

但是，以下查詢「無效」，原因在於其對兩個不同的屬性使用不等式篩選器：

C#

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore C# API 參考說明文件。

Query query = new Query("Task")
{
    Filter = Filter.And(Filter.GreaterThan("created", _startDate),
        Filter.GreaterThan("priority", 3))
};

Go

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore Go API 參考說明文件。

query := datastore.NewQuery("Task").
	Filter("Created >", time.Date(1990, 1, 1, 0, 0, 0, 0, time.UTC)).
	Filter("Priority >", 3)

Java

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore Java API 參考說明文件。

Query<Entity> query = Query.newEntityQueryBuilder()
    .setKind("Task")
    .setFilter(CompositeFilter.and(
        PropertyFilter.gt("created", startDate), PropertyFilter.gt("priority", 3)))
    .build();

Node.js

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore Node.js API 參考說明文件。

const query = datastore
  .createQuery('Task')
  .filter('priority', '>', 3)
  .filter('created', '>', new Date('1990-01-01T00:00:00z'));

PHP

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore PHP API 參考說明文件。

$query = $datastore->query()
    ->kind('Task')
    ->filter('priority', '>', 3)
    ->filter('created', '>', new DateTime('1990-01-01T00:00:00z'));

Python

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore Python API 參考說明文件。

start_date = datetime.datetime(1990, 1, 1)
query = client.query(kind='Task')
query.add_filter(
    'created', '>', start_date)
query.add_filter(
    'priority', '>', 3)

Ruby

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore Ruby API 參考說明文件。

query = datastore.query("Task")
                 .where("created", ">=", Time.utc(1990, 1, 1))
                 .where("priority", ">", 3)

GQL


# Invalid query!
SELECT * FROM Task
WHERE created > DATETIME('1990-01-01T00:00:00z')
AND priority > 3

請注意，一項查詢「可以」結合用於查詢不同屬性的等式 (EQUAL) 篩選器，以及用於查詢單一屬性的一或多個不等式篩選器。因此，以下「是」有效查詢：

C#

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore C# API 參考說明文件。

Query query = new Query("Task")
{
    Filter = Filter.And(Filter.Equal("priority", 4),
        Filter.GreaterThan("created", _startDate),
        Filter.LessThan("created", _endDate))
};

Go

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore Go API 參考說明文件。

query := datastore.NewQuery("Task").
	Filter("Priority =", 4).
	Filter("Done =", false).
	Filter("Created >", time.Date(1990, 1, 1, 0, 0, 0, 0, time.UTC)).
	Filter("Created <", time.Date(2000, 1, 1, 0, 0, 0, 0, time.UTC))

Java

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore Java API 參考說明文件。

Query<Entity> query = Query.newEntityQueryBuilder()
    .setKind("Task")
    .setFilter(CompositeFilter.and(PropertyFilter.eq("priority", 4),
        PropertyFilter.gt("created", startDate), PropertyFilter.lt("created", endDate)))
    .build();

Node.js

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore Node.js API 參考說明文件。

const query = datastore
  .createQuery('Task')
  .filter('priority', '=', 4)
  .filter('done', '=', false)
  .filter('created', '>', new Date('1990-01-01T00:00:00z'))
  .filter('created', '<', new Date('2000-12-31T23:59:59z'));

PHP

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore PHP API 參考說明文件。

$query = $datastore->query()
    ->kind('Task')
    ->filter('priority', '=', 4)
    ->filter('done', '=', false)
    ->filter('created', '>', new DateTime('1990-01-01T00:00:00z'))
    ->filter('created', '<', new DateTime('2000-12-31T23:59:59z'));

Python

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore Python API 參考說明文件。

start_date = datetime.datetime(1990, 1, 1)
end_date = datetime.datetime(2000, 12, 31, 23, 59, 59)
query = client.query(kind='Task')
query.add_filter('priority', '=', 4)
query.add_filter('done', '=', False)
query.add_filter(
    'created', '>', start_date)
query.add_filter(
    'created', '<', end_date)

Ruby

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore Ruby API 參考說明文件。

query = datastore.query("Task")
                 .where("done", "=", false)
                 .where("priority", "=", 4)
                 .where("created", ">=", Time.utc(1990, 1, 1))
                 .where("created", "<", Time.utc(2000, 1, 1))

GQL


SELECT * FROM Task
WHERE priority = 4
  AND done = FALSE
  AND created > DATETIME('1990-01-01T00:00:00z')
  AND created < DATETIME('2000-12-31T23:59:59z')

若不指定排序順序，就不會定義查詢結果順序

查詢若不指定排序順序，會依擷取順序傳回結果。隨著 Datastore 模式實作的發展 (或者若專案的索引出現變化)，這個順序可能會改變。因此，若您的應用程式要求按照特定順序排列查詢結果，請務必在查詢中清楚指定該排序順序。

如果有等式篩選器，則屬性的排序順序將被忽略

如果查詢有特定屬性的等式篩選器，系統就會忽略針對這個屬性指定的任何排序順序。因為屬性的所有結果值均相同且不需進一步排序，在不需要針對單值屬性進行多餘處理的狀況下，可以輕鬆地達到最佳化。但如果是多值屬性，除了比對等式篩選條件得出的值之外，可能還包含其他值。由於這樣的使用情形並不多見，套用排序順序需耗費較多成本，而且需要建立其他索引，因此即使是多值屬性，Datastore 模式查詢規劃工具也會直接忽略排序順序。這可能會導致系統採用與排序順序不同的順序傳回查詢結果。

必須先排序不等式篩選器中使用的屬性

如要擷取所有與不等式篩選器相符的結果，查詢會掃描索引中符合篩選器的第一列，接著再繼續掃描，直到發現不一致的列為止。連續列必須按照不等式篩選器中使用的屬性排序，排列在任何其他屬性之前，才能包含完整的結果集。因此，如果查詢指定一或多個不等式篩選器及一或多個排序順序，第一個排序順序必須參照不等式篩選器中具名的相同屬性。以下查詢有效：

C#

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore C# API 參考說明文件。

Query query = new Query("Task")
{
    Filter = Filter.GreaterThan("priority", 3),
    Order = { { "priority", PropertyOrder.Types.Direction.Ascending},
        {"created", PropertyOrder.Types.Direction.Ascending } }
};

Go

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore Go API 參考說明文件。

query := datastore.NewQuery("Task").
	Filter("Priority >", 3).
	Order("Priority").
	Order("Created")

Java

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore Java API 參考說明文件。

Query<Entity> query = Query.newEntityQueryBuilder()
    .setKind("Task")
    .setFilter(PropertyFilter.gt("priority", 3))
    .setOrderBy(OrderBy.asc("priority"), OrderBy.asc("created"))
    .build();

Node.js

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore Node.js API 參考說明文件。

const query = datastore
  .createQuery('Task')
  .filter('priority', '>', 3)
  .order('priority')
  .order('created');

PHP

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore PHP API 參考說明文件。

$query = $datastore->query()
    ->kind('Task')
    ->filter('priority', '>', 3)
    ->order('priority')
    ->order('created');

Python

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore Python API 參考說明文件。

query = client.query(kind='Task')
query.add_filter('priority', '>', 3)
query.order = ['priority', 'created']

Ruby

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore Ruby API 參考說明文件。

query = datastore.query("Task")
                 .where("priority", ">", 3)
                 .order("priority")
                 .order("created")

GQL


SELECT * FROM Task WHERE priority > 3 ORDER BY priority, created

以下查詢「無效」，因為沒有按照不等式篩選器中所用的屬性排序：

C#

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore C# API 參考說明文件。

Query query = new Query("Task")
{
    Filter = Filter.GreaterThan("priority", 3),
    Order = { { "created", PropertyOrder.Types.Direction.Ascending } }
};

Go

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore Go API 參考說明文件。

query := datastore.NewQuery("Task").
	Filter("Priority >", 3).
	Order("Created")

Java

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore Java API 參考說明文件。

Query<Entity> query = Query.newEntityQueryBuilder()
    .setKind("Task")
    .setFilter(PropertyFilter.gt("priority", 3))
    .setOrderBy(OrderBy.asc("created"))
    .build();

Node.js

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore Node.js API 參考說明文件。

const query = datastore
  .createQuery('Task')
  .filter('priority', '>', 3)
  .order('created');

PHP

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore PHP API 參考說明文件。

$query = $datastore->query()
    ->kind('Task')
    ->filter('priority', '>', 3)
    ->order('created');

Python

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore Python API 參考說明文件。

query = client.query(kind='Task')
query.add_filter('priority', '>', 3)
query.order = ['created']

Ruby

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore Ruby API 參考說明文件。

query = datastore.query("Task")
                 .where("priority", ">", 3)
                 .order("created")

GQL


# Invalid query!
SELECT * FROM Task WHERE priority > 3 ORDER BY created

同理可證，以下查詢也無效，原因在於不等式篩選器所用的屬性並不是排序後的第一個屬性：

C#

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore C# API 參考說明文件。

Query query = new Query("Task")
{
    Filter = Filter.GreaterThan("priority", 3),
    Order = { {"created", PropertyOrder.Types.Direction.Ascending },
        { "priority", PropertyOrder.Types.Direction.Ascending} }
};

Go

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore Go API 參考說明文件。

query := datastore.NewQuery("Task").
	Filter("Priority >", 3).
	Order("Created").
	Order("Priority")

Java

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore Java API 參考說明文件。

Query<Entity> query = Query.newEntityQueryBuilder()
    .setKind("Task")
    .setFilter(PropertyFilter.gt("priority", 3))
    .setOrderBy(OrderBy.asc("created"), OrderBy.asc("priority"))
    .build();

Node.js

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore Node.js API 參考說明文件。

const query = datastore
  .createQuery('Task')
  .filter('priority', '>', 3)
  .order('created')
  .order('priority');

PHP

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore PHP API 參考說明文件。

$query = $datastore->query()
    ->kind('Task')
    ->filter('priority', '>', 3)
    ->order('created')
    ->order('priority');

Python

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore Python API 參考說明文件。

query = client.query(kind='Task')
query.add_filter('priority', '>', 3)
query.order = ['created', 'priority']

Ruby

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱 Cloud Datastore 用戶端程式庫相關說明。詳情請參閱 Cloud Datastore Ruby API 參考說明文件。

query = datastore.query("Task")
                 .where("priority", ">", 3)
                 .order("created")
                 .order("priority")

GQL


# Invalid query!
SELECT * FROM Task WHERE priority > 3 ORDER BY created, priority

投影限制

投影查詢必須遵循以下限制：

  • 只能投影已建立索引的屬性。

    長度超過 1500 個位元組的字串、元素數目超過 1500 個的位元組陣列，以及明確標註不建立索引的其他屬性，一律不支援投影。

  • 不能重複投影同一個屬性。

  • 不能投影等式篩選條件參照的屬性。

    例如，

    SELECT tag FROM Task WHERE priority = 1

    有效 (等式篩選器未使用投影屬性)，

    SELECT tag FROM Task WHERE tag > 'fun`

    (非等式篩選器) 也有效，但

    SELECT tag FROM Task WHERE tag = 'fun`

    (等式篩選條件使用了投影屬性) 則無效。

  • 不應將投影查詢傳回的結果存回 Datastore 模式資料庫。

    由於這類查詢只傳回部分填入的結果，因此不應再將結果寫回 Datastore 模式資料庫。

  • 投影查詢會將時間戳記轉換為整數。

    在投影查詢的結果中，Datastore 模式會將時間戳記值轉換為微秒整數值。

後續步驟

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

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

這個網頁
文件意見
Cloud Datastore 說明文件
產品意見