Datastore 查询

本文中的查询是指从 Datastore 模式 Firestore 中检索满足一组指定条件的实体的过程。

您可以对给定种类的实体执行查询，并针对实体的属性值、键和祖先实体指定过滤条件；查询可以返回零个或零个以上实体作为结果。您还可以在查询中指定排序顺序，以使结果按实体的属性值排序。结果包括针对过滤条件和排序顺序中指定的每个属性均至少有一个值，并且其属性值符合所有指定过滤条件的全部实体。查询可以返回整个实体、投影的实体，也可仅仅返回实体键。

一个典型查询包括以下元素：

执行时，查询将检索给定种类的实体中满足过滤条件的所有实体，并按指定顺序排序。查询以只读方式执行。

注意：为了节约内存并提高性能，查询应尽可能指定对返回结果数量的限制。

每个查询都使用一个或多个索引来计算其结果，索引包含其属性指定的序列中的实体键，还可以选择包含实体的祖先实体。索引会逐渐更新以体现应用对其实体所做的更改，从而保证无需进一步计算即可提供所有查询的正确结果。

基于索引的查询机制支持多种查询，适用于大多数应用，但不适用于非伸缩查询（例如联接查询）。对于 关于 Datastore 模式限制的更多详情 请参阅查询限制。

查询接口

您可以发出针对 Datastore 模式的查询 数据库。以下示例展示了如何检索所有优先级大于或等于 4 并且尚未完成的任务，并按优先级的降序顺序排列查询结果：

C#

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 有关详情，请参阅 Cloud Datastore C# API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

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 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

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

Java

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 如需了解详情，请参阅 Cloud Datastore Java API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

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 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

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

PHP

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 有关详情，请参阅 Cloud Datastore PHP API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

$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 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

from google.cloud import datastore

# For help authenticating your client, visit
# https://cloud.google.com/docs/authentication/getting-started
client = datastore.Client()

query = client.query(kind="Task")
query.add_filter(filter=datastore.query.PropertyFilter("done", "=", False))
query.add_filter(filter=datastore.query.PropertyFilter("priority", ">=", 4))
query.order = ["-priority"]

Ruby

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 有关详情，请参阅 Cloud Datastore Ruby API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

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 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

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

Go

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 有关详情，请参阅 Cloud Datastore Go API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

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 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

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

Node.js

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 如需了解详情，请参阅 Cloud Datastore Node.js API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

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

PHP

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 如需了解详情，请参阅 Cloud Datastore PHP API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

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

Python

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 如需了解详情，请参阅 Cloud Datastore Python API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

from google.cloud import datastore

# For help authenticating your client, visit
# https://cloud.google.com/docs/authentication/getting-started
client = datastore.Client()

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

Ruby

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 如需了解详情，请参阅 Cloud Datastore Ruby API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

tasks = datastore.run query

GQL

不适用

查询结构

在一个查询中，您可以指定一个实体种类、零个或零个以上过滤条件，以及零个或零个以上排序顺序。

过滤条件

查询的过滤条件用于为待检索实体的属性、键和祖先实体设定限制条件。

属性过滤条件

属性过滤条件会指定以下内容：

  • 属性名称
  • 比较运算符
  • 属性值

以下示例返回标记为未完成的任务实体：

C#

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 有关详情，请参阅 Cloud Datastore C# API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

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

Go

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 如需了解详情，请参阅 Cloud Datastore Go API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

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

Java

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 有关详情，请参阅 Cloud Datastore Java API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

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

Node.js

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 如需了解详情，请参阅 Cloud Datastore Node.js API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

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

PHP

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 有关详情，请参阅 Cloud Datastore PHP API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

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

Python

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 如需了解详情，请参阅 Cloud Datastore Python API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

from google.cloud import datastore

# For help authenticating your client, visit
# https://cloud.google.com/docs/authentication/getting-started
client = datastore.Client()

query = client.query(kind="Task")
query.add_filter(filter=datastore.query.PropertyFilter("done", "=", False))

Ruby

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 如需了解详情，请参阅 Cloud Datastore Ruby API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

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 大于或等于
NOT_EQUAL 不等于
IN 指定列表的成员。等于指定列表中的任意值。
NOT_IN 不属于指定列表。不等于指定列表中的任何值。

复合过滤条件

复合过滤条件由多个属性过滤条件组成。您可以 将过滤条件与 AND 和 OR 结合使用。以下示例 返回标记为未完成且优先级为 4 的 Task 实体：

C#

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 如需了解详情，请参阅 Cloud Datastore C# API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

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 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

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

Java

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 如需了解详情，请参阅 Cloud Datastore Java API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

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 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

const query = datastore
  .createQuery('Task')
  .filter(
    and([
      new PropertyFilter('done', '=', false),
      new PropertyFilter('priority', '=', 4),
    ])
  );

PHP

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 如需了解详情，请参阅 Cloud Datastore PHP API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

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

Python

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 有关详情，请参阅 Cloud Datastore Python API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

from google.cloud import datastore

# For help authenticating your client, visit
# https://cloud.google.com/docs/authentication/getting-started
client = datastore.Client()

query = client.query(kind="Task")
query.add_filter(filter=datastore.query.PropertyFilter("done", "=", False))
query.add_filter(filter=datastore.query.PropertyFilter("priority", "=", 4))

Ruby

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 有关详情，请参阅 Cloud Datastore Ruby API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

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

GQL

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

以下示例将过滤条件与逻辑 OR 组合在一起：

C#

无可用代码段。

Go

无可用代码段。

Java

如需了解如何安装和使用 Datastore 模式的客户端库，请参阅 Datastore 模式客户端库。 如需了解详情，请参阅 Datastore 模式 Java API 参考文档。

如需向 Datastore 模式进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

import com.google.cloud.datastore.Datastore;
import com.google.cloud.datastore.DatastoreOptions;
import com.google.cloud.datastore.Entity;
import com.google.cloud.datastore.Query;
import com.google.cloud.datastore.QueryResults;
import com.google.cloud.datastore.StructuredQuery.CompositeFilter;
import com.google.cloud.datastore.StructuredQuery.Filter;
import com.google.cloud.datastore.StructuredQuery.PropertyFilter;

public class OrFilterQuery {
  public static void invoke() throws Exception {

    // Instantiates a client
    Datastore datastore = DatastoreOptions.getDefaultInstance().getService();
    String propertyName = "description";

    // Create the two filters
    Filter orFilter =
        CompositeFilter.or(
            PropertyFilter.eq(propertyName, "Feed cats"),
            PropertyFilter.eq(propertyName, "Buy milk"));

    // Build the query
    Query<Entity> query = Query.newEntityQueryBuilder().setKind("Task").setFilter(orFilter).build();

    // Get the results back from Datastore
    QueryResults<Entity> results = datastore.run(query);

    if (!results.hasNext()) {
      throw new Exception("query yielded no results");
    }

    while (results.hasNext()) {
      Entity entity = results.next();
      System.out.printf("Entity: %s%n", entity);
    }
  }
}

Node.js

如需了解如何安装和使用 Datastore 模式的客户端库，请参阅 Datastore 模式客户端库。 如需了解详情，请参阅 Datastore 模式 Node.js API 参考文档。

如需向 Datastore 模式进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

/**
 * TODO(developer): Uncomment these variables before running the sample.
 */
// const projectId = "your Google Cloud project id";

// Imports the Cloud Datastore
const {Datastore, PropertyFilter, or} = require('@google-cloud/datastore');

async function queryFilterOr() {
  // Instantiate the Datastore
  const datastore = new Datastore();
  const query = datastore
    .createQuery('Task')
    .filter(
      or([
        new PropertyFilter('description', '=', 'Buy milk'),
        new PropertyFilter('description', '=', 'Feed cats'),
      ])
    );

  const [entities] = await datastore.runQuery(query);
  for (const entity of entities) {
    console.log(`Entity found: ${entity['description']}`);
  }
}

queryFilterOr();
PHP

无可用代码段。

Python

如需了解如何安装和使用适用于 Datastore 模式的客户端库，请参阅 Datastore 模式客户端库。 如需了解详情，请参阅 Datastore 模式 Python API 参考文档。

如需向 Datastore 模式进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

from google.cloud import datastore
from google.cloud.datastore import query


def query_filter_or(project_id: str) -> None:
    """Builds a union of two queries (OR) filter.

    Arguments:
        project_id: your Google Cloud Project ID
    """
    client = datastore.Client(project=project_id)

    or_query = client.query(kind="Task")
    or_filter = query.Or(
        [
            query.PropertyFilter("description", "=", "Buy milk"),
            query.PropertyFilter("description", "=", "Feed cats"),
        ]
    )

    or_query.add_filter(filter=or_filter)

    results = list(or_query.fetch())
    for result in results:
        print(result["description"])
Ruby

无可用代码段。

GQL

无可用代码段。

Datastore 模式 Firestore 支持将过滤条件与 AND 和 OR 运算符结合使用。以下示例返回已加星标或标记为“未完成”且优先级为 4 的 Task 实体：
C#

无可用代码段。

Go

无可用代码段。

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

无可用代码段。

PHP

无可用代码段。

Python
and_or_query = client.query(kind="Task")

query_filter = query.Or(
    [
        query.PropertyFilter("starred", "=", True),
        query.And([query.PropertyFilter("done", "=", False),
                    query.PropertyFilter("priority", "=", 4,),
        ]
        )
    ]
)

and_or_query.add_filter(filter=query_filter)

results = and_or_query.fetch()
for result in results:
    print(result["description"])
Ruby

无可用代码段。

GQL

无可用代码段。

键过滤条件

如需将实体键的值作为过滤条件，请使用特殊属性 __key__：

C#

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 如需了解详情，请参阅 Cloud Datastore C# API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

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

Go

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 有关详情，请参阅 Cloud Datastore Go API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

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

Java

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 如需了解详情，请参阅 Cloud Datastore Java API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

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 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

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

PHP

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 有关详情，请参阅 Cloud Datastore PHP API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

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

Python

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 有关详情，请参阅 Cloud Datastore Python API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

from google.cloud import datastore

# For help authenticating your client, visit
# https://cloud.google.com/docs/authentication/getting-started
client = datastore.Client()

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 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

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 的实体排在使用键名称的实体前面。

针对键的查询就像针对属性的查询一样使用索引，并且在相同情况下需要自定义索引。以下例外情况无需自定义索引：

  • 不等式过滤条件
  • 键的升序排序顺序

键的降序排序顺序需要使用自定义索引。与所有查询一样，如果在开发环境中使用了需要自定义索引的查询，则开发服务器会在索引配置文件中创建适当的条目。

排序顺序

查询的排序顺序会指定：

  • 属性名称。
  • 排序方向（升序或降序）。默认的排序顺序是升序。

此示例按创建时间对 Task 实体进行升序排序：

C#

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 如需了解详情，请参阅 Cloud Datastore C# API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

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

Go

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 有关详情，请参阅 Cloud Datastore Go API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

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

Java

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 如需了解详情，请参阅 Cloud Datastore Java API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

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

Node.js

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 有关详情，请参阅 Cloud Datastore Node.js API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

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

PHP

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 如需了解详情，请参阅 Cloud Datastore PHP API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

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

Python

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 有关详情，请参阅 Cloud Datastore Python API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

from google.cloud import datastore

# For help authenticating your client, visit
# https://cloud.google.com/docs/authentication/getting-started
client = datastore.Client()

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

Ruby

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 有关详情，请参阅 Cloud Datastore Ruby API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

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

GQL

SELECT * FROM Task ORDER BY created ASC

此示例按创建时间对 Task 实体进行降序排序：

C#

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 如需了解详情，请参阅 Cloud Datastore C# API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

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

Go

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 如需了解详情，请参阅 Cloud Datastore Go API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

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

Java

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 有关详情，请参阅 Cloud Datastore Java API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

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

Node.js

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 如需了解详情，请参阅 Cloud Datastore Node.js API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

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

PHP

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 有关详情，请参阅 Cloud Datastore PHP API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

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

Python

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 有关详情，请参阅 Cloud Datastore Python API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

from google.cloud import datastore

# For help authenticating your client, visit
# https://cloud.google.com/docs/authentication/getting-started
client = datastore.Client()

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

Ruby

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 如需了解详情，请参阅 Cloud Datastore Ruby API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

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

GQL

SELECT * FROM Task ORDER BY created DESC

如果查询包含多个排序顺序，则按其在查询中指定的序列加以应用。以下示例先按优先级降序排序，然后按创建时间升序排序：

C#

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 有关详情，请参阅 Cloud Datastore C# API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

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 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

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

Java

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 有关详情，请参阅 Cloud Datastore Java API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

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 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

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

PHP

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 有关详情，请参阅 Cloud Datastore PHP API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

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

Python

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 有关详情，请参阅 Cloud Datastore Python API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

from google.cloud import datastore

# For help authenticating your client, visit
# https://cloud.google.com/docs/authentication/getting-started
client = datastore.Client()

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

Ruby

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 有关详情，请参阅 Cloud Datastore Ruby API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

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

GQL

SELECT * FROM Task ORDER BY priority DESC, created ASC

如果未指定排序顺序，将按照从 Datastore 模式检索的顺序返回结果。

限制

排序顺序存在以下限制：

特殊查询类型

应特别注意一些特定类型的查询：

!= Not equal

使用不等于 (!=) 运算符返回具有给定属性的实体 存在，并且与比较值不匹配。

C#

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 如需了解详情，请参阅 Cloud Datastore C# API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。

不适用

Go

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 有关详情，请参阅 Cloud Datastore Go API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

package datastore_snippets

import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/datastore"
	"google.golang.org/api/iterator"
)

func queryNotEquals(w io.Writer, projectId string) error {
	ctx := context.Background()
	client, err := datastore.NewClient(ctx, projectId)
	if err != nil {
		return fmt.Errorf("NewClient: %w", err)
	}
	defer client.Close()

	q := datastore.NewQuery("TaskList")
	q.FilterField("Task", "!=", []string{"notASimpleTask"})

	it := client.Run(ctx, q)
	for {
		var dst struct {
			Task string
		}
		key, err := it.Next(&dst)
		if err == iterator.Done {
			break
		}

		if err != nil {
			return err
		}
		fmt.Fprintf(w, "Key retrieved: %v\n", key)
	}

	return nil
}

Java

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 如需了解详情，请参阅 Cloud Datastore Java API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

Query<Entity> query =
    Query.newEntityQueryBuilder()
        .setKind("Task")
        .setFilter(PropertyFilter.neq("category", "Work"))
        .build();

Node.js

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 如需了解详情，请参阅 Cloud Datastore Node.js API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。

不适用

PHP

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 有关详情，请参阅 Cloud Datastore PHP API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。

不适用

Python

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 如需了解详情，请参阅 Cloud Datastore Python API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

query = client.query(kind="Task")
query.add_filter("category", "!=", "work")

Ruby

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 有关详情，请参阅 Cloud Datastore Ruby API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。

不适用

GQL

SELECT * FROM Task WHERE category != 'work'

此查询会返回 category 属性所在的每个 Task 实体 并设置为 Work 以外的任何值。

此查询不返回实体 其中 category 属性不存在。不等于 (!=) 和 NOT_IN 查询会排除指定属性不存在或 从索引中排除。只要属性设置了值（包括空字符串或 null），该属性就会存在。

限制

请注意 != 查询的以下限制：

  • 只有给定属性存在的实体才能与查询匹配。
  • 每个查询只允许有一个 NOT_IN 或 !=。

IN

使用 IN 运算符合并最多 30 个等式 (==) 具有逻辑 OR 的同一属性的多个子句。IN 查询会返回给定属性与任意比较值匹配的实体。

C#

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 有关详情，请参阅 Cloud Datastore C# API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。

不适用

Go

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 如需了解详情，请参阅 Cloud Datastore Go API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

package datastore_snippets

import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/datastore"
	"google.golang.org/api/iterator"
)

func queryIn(w io.Writer, projectId string) error {
	ctx := context.Background()
	client, err := datastore.NewClient(ctx, projectId)
	if err != nil {
		return fmt.Errorf("NewClient: %w", err)
	}
	defer client.Close()

	q := datastore.NewQuery("TaskList")
	q.FilterField("Task", "in", []string{"simpleTask", "easyTask"})

	it := client.Run(ctx, q)
	for {
		var dst struct {
			Task string
		}
		key, err := it.Next(&dst)
		if err == iterator.Done {
			break
		}

		if err != nil {
			return err
		}
		fmt.Fprintf(w, "Key retrieved: %v\n", key)
	}

	return nil
}

Java

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 如需了解详情，请参阅 Cloud Datastore Java API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

Query<Entity> query =
    Query.newEntityQueryBuilder()
        .setKind("Task")
        .setFilter(PropertyFilter.in("tag", ListValue.of("learn", "study")))
        .build();

Node.js

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 如需了解详情，请参阅 Cloud Datastore Node.js API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。

不适用

PHP

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 有关详情，请参阅 Cloud Datastore PHP API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。

不适用

Python

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 如需了解详情，请参阅 Cloud Datastore Python API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

query = client.query(kind="Task")
query.add_filter("tag", "IN", ["learn", "study"])

Ruby

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 有关详情，请参阅 Cloud Datastore Ruby API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。

不适用

GQL

SELECT * FROM Task WHERE tag IN ARRAY('learn', 'study')

此查询会返回 tag 属性设置为 learn 的每个 Task 实体 或 study。这包括 Task 实体，其中 tag 属性包含其中一个值，但不包含另一个值。

NOT_IN

使用 NOT_IN 运算符可通过逻辑 AND 在同一属性上结合使用最多 10 个不等于 (!=) 子句。NOT_IN 查询会返回 指定的属性存在，并且与任何比较值都不匹配。

C#

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 如需了解详情，请参阅 Cloud Datastore C# API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。

不适用

Go

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 有关详情，请参阅 Cloud Datastore Go API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

package datastore_snippets

import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/datastore"
	"google.golang.org/api/iterator"
)

func queryNotIn(w io.Writer, projectId string) error {
	ctx := context.Background()
	client, err := datastore.NewClient(ctx, projectId)
	if err != nil {
		return fmt.Errorf("NewClient: %w", err)
	}
	defer client.Close()

	q := datastore.NewQuery("TaskList")
	q.FilterField("Task", "not-in", []string{"notASimpleTask", "notAnEasyTask"})

	it := client.Run(ctx, q)
	for {
		var dst struct {
			Task string
		}
		key, err := it.Next(&dst)
		if err == iterator.Done {
			break
		}

		if err != nil {
			return err
		}
		fmt.Fprintf(w, "Key retrieved: %v\n", key)
	}

	return nil
}

Java

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 如需了解详情，请参阅 Cloud Datastore Java API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

Query<Entity> query =
    Query.newEntityQueryBuilder()
        .setKind("Task")
        .setFilter(PropertyFilter.not_in("category", ListValue.of("Work", "Chores", "School")))
        .build();

Node.js

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 有关详情，请参阅 Cloud Datastore Node.js API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。

不适用

PHP

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 有关详情，请参阅 Cloud Datastore PHP API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。

不适用

Python

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 如需了解详情，请参阅 Cloud Datastore Python API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

query = client.query(kind="Task")
query.add_filter("category", "NOT_IN", ["work", "chores", "school"])

Ruby

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 有关详情，请参阅 Cloud Datastore Ruby API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。

不适用

GQL

SELECT * FROM Task WHERE category NOT IN ARRAY('work', 'chores', 'school')

此查询不返回实体 其中 category 实体不存在。不等于 (!=) 和 NOT_IN 查询会排除指定属性不存在的实体。只要属性设置了值（包括空字符串或 null），该属性就会存在。

限制

请注意 NOT_IN 查询的以下限制：

  • 只有具有给定属性的实体才能与该查询匹配。
  • 每个查询只允许有一个 NOT_IN 或 !=。

祖先查询

祖先查询会将其结果限制为指定的实体及其后代。此示例返回以指定的 TaskList 实体作为祖先实体的所有 Task 实体：

C#

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 有关详情，请参阅 Cloud Datastore C# API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

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

Go

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 有关详情，请参阅 Cloud Datastore Go API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

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

Java

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 如需了解详情，请参阅 Cloud Datastore Java API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

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 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

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

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

PHP

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 如需了解详情，请参阅 Cloud Datastore PHP API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

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

Python

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 如需了解详情，请参阅 Cloud Datastore Python API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

from google.cloud import datastore

# For help authenticating your client, visit
# https://cloud.google.com/docs/authentication/getting-started
client = datastore.Client()

# 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 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

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

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

GQL

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

祖先查询的限制

请注意 Ancestor 查询的以下限制：

  • 所有评估的析取运算必须具有相同的祖先过滤器。

不分类查询

没有种类、没有祖先实体的查询会从 Datastore 模式中检索某个应用的所有实体。这种“不分类查询”不能包含针对属性值的过滤条件或排序顺序。但是，它们可以对实体键进行过滤，并使用祖先实体过滤条件。通过指定 __key__ 作为属性名称，即可使用键过滤条件：

C#

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 有关详情，请参阅 Cloud Datastore C# API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

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

Go

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 如需了解详情，请参阅 Cloud Datastore Go API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

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

Java

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 有关详情，请参阅 Cloud Datastore Java API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

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

Node.js

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 如需了解详情，请参阅 Cloud Datastore Node.js API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

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

PHP

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 有关详情，请参阅 Cloud Datastore PHP API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

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

Python

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 有关详情，请参阅 Cloud Datastore Python API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

from google.cloud import datastore

# For help authenticating your client, visit
# https://cloud.google.com/docs/authentication/getting-started
client = datastore.Client()

last_seen_key = client.key("Task", "a")
query = client.query()
query.key_filter(last_seen_key, ">")

Ruby

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 有关详情，请参阅 Cloud Datastore Ruby API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

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 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

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

Go

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 如需了解详情，请参阅 Cloud Datastore Go API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

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

Java

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 有关详情，请参阅 Cloud Datastore Java API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

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

Node.js

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 如需了解详情，请参阅 Cloud Datastore Node.js API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

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

PHP

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 如需了解详情，请参阅 Cloud Datastore PHP API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

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

Python

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 如需了解详情，请参阅 Cloud Datastore Python API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

from google.cloud import datastore

# For help authenticating your client, visit
# https://cloud.google.com/docs/authentication/getting-started
client = datastore.Client()

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

Ruby

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 如需了解详情，请参阅 Cloud Datastore Ruby API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

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 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

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

Go

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 如需了解详情，请参阅 Cloud Datastore Go API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

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

Java

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 如需了解详情，请参阅 Cloud Datastore Java API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

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

Node.js

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 有关详情，请参阅 Cloud Datastore Node.js API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

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

PHP

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 如需了解详情，请参阅 Cloud Datastore PHP API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

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

Python

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 如需了解详情，请参阅 Cloud Datastore Python API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

from google.cloud import datastore

# For help authenticating your client, visit
# https://cloud.google.com/docs/authentication/getting-started
client = datastore.Client()

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

Ruby

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 如需了解详情，请参阅 Cloud Datastore Ruby API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

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

GQL

SELECT priority, percent_complete FROM Task

下面展示了如何运行投影查询：

C#

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 如需了解详情，请参阅 Cloud Datastore C# API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

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 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

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 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

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 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

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 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

$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 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

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 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

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 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

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 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

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

Java

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 有关详情，请参阅 Cloud Datastore Java API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

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 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

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

PHP

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 有关详情，请参阅 Cloud Datastore PHP API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

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

Python

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 有关详情，请参阅 Cloud Datastore Python API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

from google.cloud import datastore

# For help authenticating your client, visit
# https://cloud.google.com/docs/authentication/getting-started
client = datastore.Client()

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

Ruby

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 有关详情，请参阅 Cloud Datastore Ruby API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

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

如果指定了 order by，则 distinct on 子句中指定的属性集必须出现在 order by 子句中的任何非 distinct on 属性之前。

聚合查询

Datastore 模式 Firestore 支持 count() 聚合查询。请参阅聚合查询。

对多个属性使用的范围和不等式过滤条件

Datastore 模式 Firestore 支持在复合查询中使用多个不等式过滤条件。请参阅对多个属性使用范围和不等式过滤条件的查询。

数组值

Datastore 模式会针对每个索引将每个唯一数组属性值编入索引一次。因此，如需查询数组是否包含值，请使用等式过滤条件。

在查询具有数组值的属性时，应考虑以下事项。

不等式过滤条件

由于它们被编入索引的方式，同一个属性具有多个值的实体有时可能会以意想不到的方式与查询过滤条件和排序顺序进行交互。

如果查询在给定属性上具有多个不等性过滤条件，则只有当属性的至少一个单独值满足所有过滤条件时，实体才与查询匹配。例如，如果 Task 种类的实体的属性 tag 具有 fun 和 programming 这两个值，则该实体将与以下查询不匹配：

C#

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 如需了解详情，请参阅 Cloud Datastore C# API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

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 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

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

Java

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 如需了解详情，请参阅 Cloud Datastore Java API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

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 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

const query = datastore
  .createQuery('Task')
  .filter(
    and([
      new PropertyFilter('tag', '>', 'learn'),
      new PropertyFilter('tag', '<', 'math'),
    ])
  );

PHP

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 如需了解详情，请参阅 Cloud Datastore PHP API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

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

Python

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 如需了解详情，请参阅 Cloud Datastore Python API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

from google.cloud import datastore

# For help authenticating your client, visit
# https://cloud.google.com/docs/authentication/getting-started
client = datastore.Client()

query = client.query(kind="Task")
query.add_filter(filter=datastore.query.PropertyFilter("tag", ">", "learn"))
query.add_filter(filter=datastore.query.PropertyFilter("tag", "<", "math"))

Ruby

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 如需了解详情，请参阅 Cloud Datastore Ruby API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

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

GQL

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

该实体的每个 tag 值都满足一个过滤条件，但没有一个值同时满足这两个过滤条件。

多个等式过滤条件

可以使用多个等式过滤条件来查询 。例如， Task，值为 fun 和 programming 属性 tag 会满足该查询

C#

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 有关详情，请参阅 Cloud Datastore C# API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

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 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

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

Java

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 如需了解详情，请参阅 Cloud Datastore Java API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

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 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

const query = datastore
  .createQuery('Task')
  .filter(
    and([
      new PropertyFilter('tag', '=', 'fun'),
      new PropertyFilter('tag', '=', 'programming'),
    ])
  );

PHP

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 有关详情，请参阅 Cloud Datastore PHP API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

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

Python

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 有关详情，请参阅 Cloud Datastore Python API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

from google.cloud import datastore

# For help authenticating your client, visit
# https://cloud.google.com/docs/authentication/getting-started
client = datastore.Client()

query = client.query(kind="Task")
query.add_filter(filter=datastore.query.PropertyFilter("tag", "=", "fun"))
query.add_filter(filter=datastore.query.PropertyFilter("tag", "=", "programming"))

Ruby

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 如需了解详情，请参阅 Cloud Datastore Ruby API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

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 的实体之前。

如果一个多值属性用在了相等性过滤条件中，则针对该属性的任何排序顺序都将被忽略。

如果一个多值属性用在不等式或 NOT_IN 过滤条件中：

  • 并且查询结果按该属性升序排序，则满足查询的所有不等性过滤条件的最小值将用于排序。
  • 并且查询结果按该属性降序排列，则满足查询的所有不等性过滤条件的最大值将用于排序。

请注意，如果针对属性的一组不等性过滤条件可转换为相等性过滤条件，例如：

WHERE tag >= 'math' AND tag <= 'math'

则针对该属性的任何排序顺序都会被忽略，因为该过滤条件的评估方式与以下相等性过滤条件相同：

WHERE tag = 'math'

投影和数组值属性

投影具有数组值的属性不会填充该属性的所有值。相反，对于匹配查询的投影值的每个唯一组合，都会返回一个单独的实体。例如，假设您有一个种类为 Task 的实体，具有两个多值属性 tag 和 collaborators：

C#

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 有关详情，请参阅 Cloud Datastore C# API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

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 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

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 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

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 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

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

PHP

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 如需了解详情，请参阅 Cloud Datastore PHP API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

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

Python

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 有关详情，请参阅 Cloud Datastore Python API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

from google.cloud import datastore

# For help authenticating your client, visit
# https://cloud.google.com/docs/authentication/getting-started
client = datastore.Client()

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

Ruby

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 有关详情，请参阅 Cloud Datastore Ruby API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

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

GQL

不适用

则以下投影查询

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

将返回具有以下值的组合的四个实体：

tag = 'fun'，collaborators = 'alice'
tag = 'fun'，collaborators = 'bob'
tag = 'programming'，collaborators = 'alice'
tag = 'programming'，collaborators = 'bob'

游标、限制和偏移

您可以为查询指定限制，以控制一个批次中返回的最大结果数。以下示例检索最多五个 Task 实体：

C#

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 如需了解详情，请参阅 Cloud Datastore C# API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

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

Go

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 有关详情，请参阅 Cloud Datastore Go API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

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

Java

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 如需了解详情，请参阅 Cloud Datastore Java API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

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

Node.js

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 如需了解详情，请参阅 Cloud Datastore Node.js API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

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

PHP

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 有关详情，请参阅 Cloud Datastore PHP API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

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

Python

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 如需了解详情，请参阅 Cloud Datastore Python API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

from google.cloud import datastore

# For help authenticating your client, visit
# https://cloud.google.com/docs/authentication/getting-started
client = datastore.Client()

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

Ruby

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 有关详情，请参阅 Cloud Datastore Ruby API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

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 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

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 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

// cursorStr is a cursor to start querying at.
cursorStr := ""

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.
it := client.Run(ctx, query)
var tasks []Task
for {
	var task Task
	_, err := it.Next(&task)
	if err == iterator.Done {
		break
	}
	if err != nil {
		log.Fatalf("Failed fetching results: %v", err)
	}
	tasks = append(tasks, task)
}

// Get the cursor for the next page of results.
// nextCursor.String can be used as the next page's token.
nextCursor, err := it.Cursor()

Java

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 如需了解详情，请参阅 Cloud Datastore Java API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

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 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

// 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 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

/**
 * Fetch a query cursor.
 *
 * @param int $pageSize
 * @param string $pageCursor
 * @param string $namespaceId
 */
function cursor_paging(int $pageSize, string $pageCursor = '', string $namespaceId = null)
{
    $datastore = new DatastoreClient(['namespaceId' => $namespaceId]);
    $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;
    }

    printf('Found %s entities', count($entities));

    $entities = [];
    if (!empty($nextPageCursor)) {
        $query = $datastore->query()
          ->kind('Task')
          ->limit($pageSize)
          ->start($nextPageCursor);
        $result = $datastore->runQuery($query);

        foreach ($result as $entity) {
            $entities[] = $entity;
        }

        printf('Found %s entities with next page cursor', count($entities));
    }
}

Python

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 如需了解详情，请参阅 Cloud Datastore Python API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

from google.cloud import datastore

# For help authenticating your client, visit
# https://cloud.google.com/docs/authentication/getting-started
client = datastore.Client()


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 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

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 模式数据库支持整数偏移，但应该尽量避免使用此类偏移。而应该使用游标。使用偏移仅会避免将跳过的实体返回到应用，但仍会在内部检索这些实体。跳过的实体仍然会增加查询的延迟，而且应用需要为检索这些实体所需的读取操作付费。使用游标取代偏移可让您省掉所有这些费用。

游标的限制

游标受限于以下限制：

  • 游标只能由执行原始查询的相同项目使用，并且只能用于继续相同的查询。若未设置与最初生成的查询相同的查询，则无法使用游标检索结果。
  • 如果以下任何项发生更改，则游标仍可用于后续检索。
    • 开始游标
    • 结束游标
    • 偏移
    • 限制
  • 如果以下任何项发生更改，则游标不能用于后续检索。
    • 投影
    • 种类
    • 祖先实体
    • 过滤器
    • distinct on
    • 排列顺序 一种例外情况是，原始查询的最终排序顺序基于 __key__。在这种情况下，您可以在反向查询中使用游标，反向查询即在原始查询的基础上将各排序顺序逆转。反向查询可以修改开始游标、结束游标、偏移量和限制。
  • 在针对具有多个值的属性上使用不等性过滤条件或排序顺序的查询上，游标并非总能如期工作。这种多值属性的去重逻辑不会在多次检索之间持续存在，可能导致多次返回相同结果。
  • 新的 Datastore 模式版本可能会更改内部实现细节，导致依赖于这些细节的游标失效。如果应用尝试使用失效的游标，则 Datastore 模式 Firestore 会引发异常。

游标和数据更新

游标表示结果列表中上次返回的结果之后的位置。游标不是列表中的相对位置（并非偏移），而是表示 Datastore 模式数据库在开始对结果进行索引扫描时可以跳转到的标记。如果查询的结果在两次使用游标之间发生了变化，则查询只会注意位于游标之后的结果中发生的变化。如果一个新结果出现在查询的游标位置之前，则在获取游标后的结果时不会返回该结果。同样，如果某个不再是查询结果的实体出现在游标之前，则出现在游标后的结果也不会变化。如果从结果集中移除了上次返回的结果，则游标仍然知道如何定位下一个结果。

在检索查询结果时，可以同时使用开始游标和结束游标来返回一组连续的结果。在使用开始游标和结束游标检索结果时，不能保证结果的大小将与生成游标时的结果大小相同。在生成游标与在查询中使用游标这两个时间点之间，可以在数据库中添加实体或者从数据库中删除实体。

查询限制

索引查询机制的性质对查询的能力施加了一定的限制。Datastore 模式查询不支持子字符串匹配、不区分大小写的匹配或全文搜索。此外，还存在以下限制：

缺少查询中所指定属性的实体将被忽略

同类实体不需要具有相同的属性。对于查询的过滤条件和排序顺序中指定的每个属性，实体必须拥有一个对应的值（可能为 null），才能出现在查询结果中。否则，用于执行查询的索引将忽略该实体，因此不会包含在查询结果中。

对未编入索引的属性进行过滤时不会返回任何结果

查询无法找到未编入索引的属性值，也无法根据这些属性进行排序。如需了解详情，请参阅未编入索引的属性。

不等式过滤条件的限制

为防止查询的运行费用过高，Datastore 模式的 Firestore 将范围或不等式属性的数量上限设为 10。如需详细了解使用不等式过滤条件的查询，请参阅对多个属性使用范围和不等式过滤条件的查询。

您不能同时使用 NOT_EQUAL 和 NOT_IN

如果您使用 NOT_IN，则不能同时添加 NOT_EQUAL 子句。

未指定排序顺序时，查询结果的排序无保证

如果查询未指定排序顺序，结果将按照其检索的顺序返回。随着 Datastore 模式实现的发展演进（或者如果项目的索引更改），此顺序可能会发生变化。因此，如果您的应用要求查询结果以特定顺序排列，请务必在查询中明确指定该排序顺序。

对于具有等式过滤条件的属性，将忽略排序顺序

对于包含给定属性的相等性过滤条件的查询，将忽略为该属性指定的任何排列顺序。这是一项优化，可以免去单值属性的不必要处理。由于所有结果都包含 属性值相同，无需进一步排序。但是，除了相等性过滤条件匹配的值之外，多值属性可能还有其他值。由于此类用例较为罕见，并且排序顺序的应用成本高昂，需要额外的索引，因此即使在多值情况下，Datastore 模式查询规划器也会忽略排序顺序。这可能会导致查询结果以不同于看似默示的排序顺序返回。例如，以下查询会忽略排序顺序：

C#

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 如需了解详情，请参阅 Cloud Datastore C# API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。

不适用

Go

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 有关详情，请参阅 Cloud Datastore Go API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。

不适用

Java

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 如需了解详情，请参阅 Cloud Datastore Java API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

Query<Entity> query =
    Query.newEntityQueryBuilder()
        .setKind("Task")
        .setFilter(PropertyFilter.eq("tag", "learn"))
        .setOrderBy(OrderBy.asc("tag"))
        .build();

Node.js

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 如需了解详情，请参阅 Cloud Datastore Node.js API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。

不适用

PHP

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 如需了解详情，请参阅 Cloud Datastore PHP API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。

不适用

Python

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 有关详情，请参阅 Cloud Datastore Python API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。

不适用

Ruby

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 如需了解详情，请参阅 Cloud Datastore Ruby API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。

不适用

GQL

# Sort order on an equality filter is ignored
SELECT * FROM Task WHERE tag = 'learn' ORDER BY tag ASC

这不适用于包含 IN 过滤条件的查询。使用 IN 运算符可通过逻辑 OR 在同一属性上结合使用最多 10 个等式 (==) 子句。如果您添加排序 并将它应用于结果集。

C#

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 有关详情，请参阅 Cloud Datastore C# API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。

不适用

Go

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 有关详情，请参阅 Cloud Datastore Go API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。

不适用

Java

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 如需了解详情，请参阅 Cloud Datastore Java API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

Query<Entity> query =
    Query.newEntityQueryBuilder()
        .setKind("Task")
        .setFilter(PropertyFilter.in("tag", ListValue.of("learn", "study")))
        .setOrderBy(OrderBy.asc("tag"))
        .build();

Node.js

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 如需了解详情，请参阅 Cloud Datastore Node.js API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。

不适用

PHP

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 有关详情，请参阅 Cloud Datastore PHP API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。

不适用

Python

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 如需了解详情，请参阅 Cloud Datastore Python API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。

不适用

Ruby

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 有关详情，请参阅 Cloud Datastore Ruby API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。

不适用

GQL

SELECT * FROM Task WHERE tag IN ARRAY('learn', 'study') ORDER BY tag ASC
  • 对于升序，将满足过滤条件的最小值用于排序。
  • 对于降序排序，系统会使用满足过滤条件的最大值进行排序。
  • 其他值不会影响排序顺序，属性中的值数量也不会影响排序顺序。

不等式过滤条件中所用的属性必须先排序

如需检索与不等性过滤条件匹配的所有结果，查询将扫描与过滤条件匹配的第一行的索引，然后向前扫描，直到遇到不匹配的行。对于包含完整结果集的连续行，必须首先按照不等性过滤条件中所用属性排序，之后再按其他属性排序。因此，如果查询指定一个或多个不等性过滤条件以及一个或多个排序顺序，则第一个排序顺序必须引用不等性过滤条件中指定的相同属性。以下是有效查询：

C#

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 如需了解详情，请参阅 Cloud Datastore C# API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

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 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

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

Java

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 如需了解详情，请参阅 Cloud Datastore Java API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

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 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

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

PHP

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 如需了解详情，请参阅 Cloud Datastore PHP API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

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

Python

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 有关详情，请参阅 Cloud Datastore Python API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

from google.cloud import datastore

# For help authenticating your client, visit
# https://cloud.google.com/docs/authentication/getting-started
client = datastore.Client()

query = client.query(kind="Task")
query.add_filter(filter=datastore.query.PropertyFilter("priority", ">", 3))
query.order = ["priority", "created"]

Ruby

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 如需了解详情，请参阅 Cloud Datastore Ruby API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

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 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

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 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

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

Java

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 如需了解详情，请参阅 Cloud Datastore Java API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

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 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

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

PHP

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 如需了解详情，请参阅 Cloud Datastore PHP API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

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

Python

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 有关详情，请参阅 Cloud Datastore Python API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

from google.cloud import datastore

# For help authenticating your client, visit
# https://cloud.google.com/docs/authentication/getting-started
client = datastore.Client()

    query = client.query(kind="Task")
    query.add_filter(filter=datastore.query.PropertyFilter("priority", ">", 3))
    query.order = ["created"]

Ruby

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 如需了解详情，请参阅 Cloud Datastore Ruby API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

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 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

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 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

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

Java

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 有关详情，请参阅 Cloud Datastore Java API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

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 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

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

PHP

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 有关详情，请参阅 Cloud Datastore PHP API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

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

Python

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 有关详情，请参阅 Cloud Datastore Python API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

from google.cloud import datastore

# For help authenticating your client, visit
# https://cloud.google.com/docs/authentication/getting-started
client = datastore.Client()

    query = client.query(kind="Task")
    query.add_filter(filter=datastore.query.PropertyFilter("priority", ">", 3))
    query.order = ["created", "priority"]

Ruby

如需了解如何安装和使用 Cloud Datastore 客户端库，请参阅 Cloud Datastore 客户端库。 有关详情，请参阅 Cloud Datastore Ruby API 参考文档。

如需向 Cloud Datastore 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

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

GQL

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

OrderBy 及其存在性

当您按给定属性对查询进行排序时，查询只能返回 存在排序依据属性的实体。

例如，以下查询不会返回任何 priority 属性，即使它们符合查询过滤条件也是如此。

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

类似的规则也适用于不等式。使用不等式过滤条件的查询 还意味着按该属性排序。以下 查询不会返回没有 priority 属性的实体 如果 starred = true 在该实体中。解决方法之一是 也可以分别为每个排序创建单独的查询 排序依据

Java
Query<Entity> query =
    Query.newEntityQueryBuilder()
        .setKind("Task")
        .setFilter(CompositeFilter.or(
            PropertyFilter.eq("starred", true)),
            PropertyFilter.ge("priority", 4))
        .build();

前面的查询中的不等式隐含了排序依据 (order-by)，例如：隐式排序依据的方向取决于可用的索引：

Java
Query<Entity> query =
    Query.newEntityQueryBuilder()
        .setKind("Task")
        .setFilter(CompositeFilter.or(
            PropertyFilter.eq("starred", true)),
            PropertyFilter.ge("priority", 4)
        )
        .setOrderBy(OrderBy.asc("priority"))
        .build();

投影限制

投影查询受限于以下限制：

  • 仅可投影编入索引的属性。

    这意味着，查询中使用的所有属性（投影属性或过滤条件）都必须存在于同一索引中。因此，select tag from Task where priority = 1 需要按优先级和标记构建复合索引。

    长度超过 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 模式会将时间戳值转换为微秒整数值。

后续步骤

了解事务。