Datastore 查询

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

查询作用于给定种类的实体,可基于实体的属性值、键和祖先实体指定过滤条件,并可作为结果返回零个或零个以上的实体。查询还可以指定排序顺序,以使结果按实体的属性值排序。结果会包含符合以下条件的所有实体:在过滤条件和排序顺序中指定的每个属性至少有一个值,且这些属性值满足所有指定的过滤条件。查询可以返回整个实体、投影的实体,也可仅仅返回实体键。

典型的查询包括以下元素:

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

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

每个查询都会使用一个或多个索引来计算其结果,索引按索引属性指定的序列包含实体键和实体的祖先实体(可选)。索引会执行增量更新,以反映应用对其实体所做的任何更改。因此您无需执行其他计算即可获得所有查询的正确结果。

基于索引的查询机制支持多种查询,适用于大多数应用。但它不支持其他数据库技术中常见的某些种类的查询:特别是 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

不适用

查询结构

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

过滤条件

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

属性过滤条件

属性过滤条件会指定:

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

本示例返回标记为未完成的 Task 实体:

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 的 Task 实体:

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

    

Datastore 模式 Firestore 仅以原生方式支持将过滤条件与 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 的实体排在使用键名称的实体前面。

针对键的查询就像针对属性的查询一样使用索引,并且在相同情况下需要自定义索引,但有一些例外:不等性过滤条件或键的升序排序不需要自定义索引,但键的降序排序则需要自定义索引。与所有查询一样,如果在开发环境中使用了需要自定义索引的查询,则开发服务器会在索引配置文件中创建适当的条目。

排序顺序

查询的排序顺序会指定:

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

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

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

    

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

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 实体作为祖先实体的所有 Task 实体:

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 查询会返回删节的结果,其中只有指定的属性(prioritypercent_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 种类的实体的属性 tag 具有 funprogramming 这两个值,则该实体将与以下查询不匹配:

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 值都不满足这两个过滤条件也是如此。

类似地,具有多个值的属性的排序顺序也不同寻常。这些属性的每个不同值都会在索引中出现一次,因此索引中的第一个值将决定实体的排序顺序。

如果一个多值属性未用在任何过滤条件中:

  • 并且查询结果按该属性升序排序,则属性的最小值将用于排序。
  • 查询结果按该属性降序排列,则最大值将用于排序。
  • 其他值不会影响排序顺序,值的数目也不会影响排序顺序。

这会产生不寻常的结果:无论在升序还是降序排列中,具有属性值 19 的实体都排在具有值 4567 的实体之前

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

如果一个多值属性用在了不等性过滤条件中:

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

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

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

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

WHERE tags = 'math'
    

投影和数组值属性

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

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'
tags = 'fun', collaborators = 'bob'
tags = 'programming', collaborators = 'alice'
tags = 'programming', collaborators = 'bob'

游标、限制和偏移

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

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 GETPOST 参数的形式嵌入网页中),然后可以使用游标作为后续检索操作的起点,从上一次检索结束的位置获取下一批结果。检索还可以指定结束游标,以限制所返回的结果集的范围。

以下示例展示了分页游标的用法:

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

游标的限制

游标受限于以下限制:

  • 游标只能由执行原始查询的相同项目使用,并且只能用于继续相同的查询。若未设置与最初生成的查询相同的查询,则无法使用游标检索结果。
  • 如果以下任何项发生更改,则游标仍可用于后续检索。
    • 开始游标
    • 结束游标
    • 偏移
    • 限制
  • 如果以下任何项发生更改,则游标不能用于后续检索。
    • 投影
    • 种类
    • 祖先实体
    • 过滤器
    • distinct on
    • 排序顺序

      一种例外情况是,原始查询的最终排序顺序基于 __key__。在这种情况下,您可以在反向查询中使用游标,反向查询即在原始查询的基础上将各排序顺序逆转。反向查询可以修改开始游标、结束游标、偏移量和限制。

  • 在针对具有多个值的属性上使用不等性过滤条件或排序顺序的查询上,游标并非总能如期工作。这种多值属性的去重逻辑不会在多次检索之间持续存在,可能导致多次返回相同结果。
  • 新的 Datastore 模式版本可能会更改内部实现细节,导致依赖于这些细节的游标失效。如果应用尝试使用失效的游标,则 Datastore 模式 Firestore 会引发异常。

游标和数据更新

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

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

查询限制

索引查询机制的性质对查询的能力施加了一定的限制。Datastore 模式查询不支持子字符串匹配、不区分大小写的匹配或所谓的全文搜索。NOTOR!= 运算符并不具备原生支持,但某些客户端库可能会在 Datastore 模式的基础之上添加支持。此外:

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

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

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

查询无法找到未编入索引的属性值,也无法根据这些属性进行排序。有关未编入索引的属性的详细讨论,请参阅未编入索引的属性部分。

不等性过滤条件最多仅限一个属性

为了不必扫描整个索引,查询机制要求查询的所有潜在结果在索引中彼此相邻。为了满足这项约束,单个查询的所有过滤条件中不能对一个以上的属性使用不等性比较(LESS_THANLESS_THAN_OR_EQUALGREATER_THANGREATER_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 模式会将时间戳值转换为微秒整数值。

后续步骤