实体、属性和键

在 Datastore 模式 Firestore 中的数据对象称为实体。实体具有一个或多个命名的属性，且每个属性可具有一个或多个值。相同种类的实体无需具有相同的属性，且实体的给定属性的值无需都是同一数据类型。（必要时，应用可在其自身的数据模型中设定和实施此类限制）。

Datastore 模式支持多种属性值数据类型，其中包括：

  • 整数
  • 浮点数
  • 字符串
  • 日期
  • 二进制数据

Datastore 模式的数据库中的每个实体都有一个明确标识它的键。键由以下部分组成：

  • 实体的命名空间，可用于实现多租户
  • 实体所属的种类，用于对实体进行分类以执行查询
  • 具体实体的标识符，可以是下面任意一种
    • 键名字符串
    • 整数数字 ID
  • （可选）祖先路径，用于在数据库层次结构中确定实体的位置

应用可以使用具体实体的键从数据库中提取该实体，也可以根据实体的键或属性值发出查询以检索一个或多个实体。

Datastore 模式 Firestore 本身并不对实体结构施加任何限制，例如限制给定属性采用特定类型的值；该任务由应用执行。

本页中的代码段基于 Datastore 模式 Firestore 入门中的示例构建。

处理实体

应用可以使用 Datastore 模式 Firestore API 来创建、检索、更新和删除实体。如果应用知道完整的实体键（或可从其父键、种类和标识符中提取），则可使用此键直接操作实体。应用还可以通过查询获取实体键；如需了解详情，请参阅查询主题。

创建实体

可通过初始化实体并设置其属性来创建新的实体：

C#

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

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

Entity task = new Entity()
{
    Key = _db.CreateKeyFactory("Task").CreateKey("sampleTask"),
    ["category"] = "Personal",
    ["done"] = false,
    ["priority"] = 4,
    ["description"] = "Learn Cloud Datastore"
};

Go

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

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

type Task struct {
	Category        string
	Done            bool
	Priority        float64
	Description     string `datastore:",noindex"`
	PercentComplete float64
	Created         time.Time
}
task := &Task{
	Category:        "Personal",
	Done:            false,
	Priority:        4,
	Description:     "Learn Cloud Datastore",
	PercentComplete: 10.0,
	Created:         time.Now(),
}

Java

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

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

Key taskKey = datastore.newKeyFactory().setKind("Task").newKey("sampleTask");
Entity task =
    Entity.newBuilder(taskKey)
        .set("category", "Personal")
        .set("done", false)
        .set("priority", 4)
        .set("description", "Learn Cloud Datastore")
        .build();

Node.js

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

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

const task = {
  category: 'Personal',
  done: false,
  priority: 4,
  description: 'Learn Cloud Datastore',
};

PHP

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

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

$task = $datastore->entity('Task', [
    'category' => 'Personal',
    'done' => false,
    'priority' => 4,
    'description' => 'Learn Cloud Datastore'
]);

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()

task = datastore.Entity(client.key("Task"))
task.update(
    {
        "category": "Personal",
        "done": False,
        "priority": 4,
        "description": "Learn Cloud Datastore",
    }
)

Ruby

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

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

task = datastore.entity "Task" do |t|
  t["category"] = "Personal"
  t["done"] = false
  t["priority"] = 4
  t["description"] = "Learn Cloud Datastore"
end

您可使用 upsert 或 insert 将实体保存到数据库；前者将覆盖 Datastore 模式中已经存在的实体，后者要求实体键尚不存在。

使用 upsert 插入实体的方式如下：

C#

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

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

_db.Upsert(_sampleTask);

Go

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

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

key := datastore.IncompleteKey("Task", nil)
key, err := client.Put(ctx, key, task)

Java

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

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

Entity task = Entity.newBuilder(keyFactory.newKey("sampleTask")).build();
datastore.put(task);

Node.js

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

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

const taskKey = datastore.key('Task');
const task = {
  category: 'Personal',
  done: false,
  priority: 4,
  description: 'Learn Cloud Datastore',
};

const entity = {
  key: taskKey,
  data: task,
};

await datastore.upsert(entity);
// Task inserted successfully.

PHP

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

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

$key = $datastore->key('Task', 'sampleTask');
$task = $datastore->entity($key, [
    'category' => 'Personal',
    'done' => false,
    'priority' => 4,
    'description' => 'Learn Cloud Datastore'
]);
$datastore->upsert($task);

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()

complete_key = client.key("Task", "sampleTask")

task = datastore.Entity(key=complete_key)

task.update(
    {
        "category": "Personal",
        "done": False,
        "priority": 4,
        "description": "Learn Cloud Datastore",
    }
)

client.put(task)

Ruby

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

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

# task_name = "sampleTask"
task = datastore.entity "Task", task_name do |t|
  t["category"] = "Personal"
  t["done"] = false
  t["priority"] = 4
  t["description"] = "Learn Cloud Datastore"
end
datastore.save task

使用 insert 插入实体的方式如下：

C#

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

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

Entity task = new Entity()
{
    Key = _keyFactory.CreateIncompleteKey()
};
task.Key = _db.Insert(task);

Go

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

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

taskKey := datastore.NameKey("Task", "sampleTask", nil)
_, err := client.RunInTransaction(ctx, func(tx *datastore.Transaction) error {
	// We first check that there is no entity stored with the given key.
	var empty Task
	if err := tx.Get(taskKey, &empty); err != datastore.ErrNoSuchEntity {
		return err
	}
	// If there was no matching entity, store it now.
	_, err := tx.Put(taskKey, &task)
	return err
})

Java

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

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

Key taskKey = datastore.add(FullEntity.newBuilder(keyFactory.newKey()).build()).getKey();

Node.js

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

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

const taskKey = datastore.key('Task');
const task = {
  category: 'Personal',
  done: false,
  priority: 4,
  description: 'Learn Cloud Datastore',
};

const entity = {
  key: taskKey,
  data: task,
};

datastore.insert(entity).then(() => {
  // Task inserted successfully.
});

PHP

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

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

$task = $datastore->entity('Task', [
    'category' => 'Personal',
    'done' => false,
    'priority' => 4,
    'description' => 'Learn Cloud Datastore'
]);
$datastore->insert($task);

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()

with client.transaction():
    incomplete_key = client.key("Task")

    task = datastore.Entity(key=incomplete_key)

    task.update(
        {
            "category": "Personal",
            "done": False,
            "priority": 4,
            "description": "Learn Cloud Datastore",
        }
    )

    client.put(task)

Ruby

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

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

datastore.transaction do |_tx|
  task = datastore.entity "Task" do |t|
    t["category"] = "Personal"
    t["done"] = false
    t["priority"] = 4
    t["description"] = "Learn Cloud Datastore"
  end
  datastore.save task
end

检索实体

要从数据库中检索实体，请在查询中使用实体键：

C#

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

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

Entity task = _db.Lookup(_sampleTask.Key);

Go

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

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

var task Task
taskKey := datastore.NameKey("Task", "sampleTask", nil)
err := client.Get(ctx, taskKey, &task)

Java

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

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

Entity task = datastore.get(taskKey);

Node.js

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

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

const taskKey = datastore.key('Task');
const [entity] = await datastore.get(taskKey);
// entity = {
//   category: 'Personal',
//   done: false,
//   priority: 4,
//   description: 'Learn Cloud Datastore',
//   [Symbol(KEY)]:
//    Key {
//      namespace: undefined,
//      id: '...',
//      kind: 'Task',
//      path: [Getter]
//    }
//   }
// };
console.log(entity);

PHP

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

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

$task = $datastore->lookup($key);

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", "sampleTask")
task = client.get(key)

Ruby

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

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

# task_name = "sampleTask"
task_key = datastore.key "Task", task_name
task = datastore.find task_key

更新实体

如需使用 update 更新现有实体，请修改之前检索到的实体属性并使用键存储该实体：

C#

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

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

_sampleTask["priority"] = 5;
_db.Update(_sampleTask);

Go

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

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

taskKey := datastore.NameKey("Task", "sampleTask", nil)
tx, err := client.NewTransaction(ctx)
if err != nil {
	log.Fatalf("client.NewTransaction: %v", err)
}
var task Task
if err := tx.Get(taskKey, &task); err != nil {
	log.Fatalf("tx.Get: %v", err)
}
task.Priority = 5
if _, err := tx.Put(taskKey, &task); err != nil {
	log.Fatalf("tx.Put: %v", err)
}
if _, err := tx.Commit(); err != nil {
	log.Fatalf("tx.Commit: %v", err)
}

Java

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

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

Entity task;
Transaction txn = datastore.newTransaction();
try {
  task = Entity.newBuilder(txn.get(taskKey)).set("priority", 5).build();
  txn.put(task);
  txn.commit();
} finally {
  if (txn.isActive()) {
    txn.rollback();
  }
}

Node.js

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

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

const taskKey = datastore.key('Task');
const task = {
  category: 'Personal',
  done: false,
  priority: 4,
  description: 'Learn Cloud Datastore',
};

const entity = {
  key: taskKey,
  data: task,
};

await datastore.update(entity);
// Task updated successfully.

PHP

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

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

$transaction = $datastore->transaction();
$key = $datastore->key('Task', 'sampleTask');
$task = $transaction->lookup($key);
$task['priority'] = 5;
$transaction->update($task);
$transaction->commit();

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()

with client.transaction():
    key = client.key("Task", "sampleTask")
    task = client.get(key)

    task["done"] = True

    client.put(task)

Ruby

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

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

# task_name = "sampleTask"
datastore.transaction do |_tx|
  task = datastore.find "Task", task_name
  task["priority"] = 5
  datastore.save task
end

提供的数据将覆盖现有实体。整个对象必须发送到数据库。如果实体不存在，则更新失败。如果您想更新或创建实体，请如前所述使用 upsert。通过使用事务，您可以在一项原子事务中执行 get 和 update 操作。

删除实体

如果您知道实体的键，就可以使用 delete 删除实体：

C#

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

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

_db.Delete(_sampleTask.Key);

Go

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

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

key := datastore.NameKey("Task", "sampletask", nil)
err := client.Delete(ctx, key)

Java

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

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

datastore.delete(taskKey);

Node.js

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

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

const taskKey = datastore.key('Task');
await datastore.delete(taskKey);
// Task deleted successfully.

PHP

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

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

$datastore->delete($taskKey);

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", "sampleTask")
client.delete(key)

Ruby

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

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

# task_name = "sampleTask"
task_key = datastore.key "Task", task_name
datastore.delete task_key

批量操作

Datastore 模式 Firestore 支持批量操作，因此可在单个 Datastore 模式调用中操作多个对象。

相对于分别调用每个单独的实体，这种批量调用速度更快，因为它们仅产生一次服务调用的开销。如果涉及多个实体组，则在服务器端对所有组并行执行该操作。

例如，您可以使用 upsert 插入/更新多个实体：

C#

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

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

var taskList = new[]
{
    new Entity()
    {
        Key = _keyFactory.CreateIncompleteKey(),
        ["category"] = "Personal",
        ["done"] = false,
        ["priority"] = 4,
        ["description"] = "Learn Cloud Datastore"
    },
    new Entity()
    {
        Key = _keyFactory.CreateIncompleteKey(),
        ["category"] = "Personal",
        ["done"] = "false",
        ["priority"] = 5,
        ["description"] = "Integrate Cloud Datastore"
    }
};
var keyList = _db.Upsert(taskList[0], taskList[1]);

Go

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

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

tasks := []*Task{
	{
		Category:    "Personal",
		Done:        false,
		Priority:    4,
		Description: "Learn Cloud Datastore",
	},
	{
		Category:    "Personal",
		Done:        false,
		Priority:    5,
		Description: "Integrate Cloud Datastore",
	},
}
keys := []*datastore.Key{
	datastore.IncompleteKey("Task", nil),
	datastore.IncompleteKey("Task", nil),
}

keys, err := client.PutMulti(ctx, keys, tasks)

Java

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

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

FullEntity<IncompleteKey> task1 =
    FullEntity.newBuilder(keyFactory.newKey())
        .set("category", "Personal")
        .set("done", false)
        .set("priority", 4)
        .set("description", "Learn Cloud Datastore")
        .build();
FullEntity<IncompleteKey> task2 =
    Entity.newBuilder(keyFactory.newKey())
        .set("category", "Personal")
        .set("done", false)
        .set("priority", 5)
        .set("description", "Integrate Cloud Datastore")
        .build();
List<Entity> tasks = datastore.add(task1, task2);
Key taskKey1 = tasks.get(0).getKey();
Key taskKey2 = tasks.get(1).getKey();

Node.js

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

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

const taskKey1 = this.datastore.key(['Task', 1]);
const taskKey2 = this.datastore.key(['Task', 2]);

const task1 = {
  category: 'Personal',
  done: false,
  priority: 4,
  description: 'Learn Cloud Datastore',
};

const task2 = {
  category: 'Work',
  done: false,
  priority: 8,
  description: 'Integrate Cloud Datastore',
};

const entities = [
  {
    key: taskKey1,
    data: task1,
  },
  {
    key: taskKey2,
    data: task2,
  },
];

await datastore.upsert(entities);
// Tasks inserted successfully.

PHP

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

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

$result = $datastore->upsertBatch($tasks);

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()

task1 = datastore.Entity(client.key("Task", 1))

task1.update(
    {
        "category": "Personal",
        "done": False,
        "priority": 4,
        "description": "Learn Cloud Datastore",
    }
)

task2 = datastore.Entity(client.key("Task", 2))

task2.update(
    {
        "category": "Work",
        "done": False,
        "priority": 8,
        "description": "Integrate Cloud Datastore",
    }
)

client.put_multi([task1, task2])

Ruby

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

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

task_1 = datastore.entity "Task" do |t|
  t["category"] = "Personal"
  t["done"] = false
  t["priority"] = 4
  t["description"] = "Learn Cloud Datastore"
end

task_2 = datastore.entity "Task" do |t|
  t["category"] = "Personal"
  t["done"] = false
  t["priority"] = 5
  t["description"] = "Integrate Cloud Datastore"
end

tasks = datastore.save task_1, task_2
task_key_1 = tasks[0].key
task_key_2 = tasks[1].key

您可查询多个实体：

C#

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

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

var keys = new Key[] { _keyFactory.CreateKey(1), _keyFactory.CreateKey(2) };
var tasks = _db.Lookup(keys[0], keys[1]);

Go

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

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

var taskKeys []*datastore.Key // Populated with incomplete keys.
tasks := make([]*Task, len(taskKeys))
err := client.GetMulti(ctx, taskKeys, &tasks)

Java

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

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

Iterator<Entity> tasks = datastore.get(taskKey1, taskKey2);

Node.js

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

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

const taskKey1 = this.datastore.key(['Task', 1]);
const taskKey2 = this.datastore.key(['Task', 2]);

const keys = [taskKey1, taskKey2];

const [tasks] = await datastore.get(keys);
// Tasks retrieved successfully.
console.log(tasks);

PHP

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

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

$result = $datastore->lookupBatch($keys);
if (isset($result['found'])) {
    // $result['found'] is an array of entities.
} else {
    // No entities found.
}

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()

keys = [client.key("Task", 1), client.key("Task", 2)]
tasks = client.get_multi(keys)

Ruby

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

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

# task_name_1 = "sampleTask1"
# task_name_2 = "sampleTask2"
task_key_1 = datastore.key "Task", task_name_1
task_key_2 = datastore.key "Task", task_name_2
tasks = datastore.find_all task_key_1, task_key_2

您可删除多个实体：

C#

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

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

var keys = new Key[] { _keyFactory.CreateKey(1), _keyFactory.CreateKey(2) };
_db.Delete(keys);

Go

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

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

err := client.DeleteMulti(ctx, taskKeys)

Java

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

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

datastore.delete(taskKey1, taskKey2);

Node.js

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

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

const taskKey1 = this.datastore.key(['Task', 1]);
const taskKey2 = this.datastore.key(['Task', 2]);

const keys = [taskKey1, taskKey2];

await datastore.delete(keys);
// Tasks deleted successfully.

PHP

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

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

$result = $datastore->deleteBatch($keys);

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()

keys = [client.key("Task", 1), client.key("Task", 2)]
client.delete_multi(keys)

Ruby

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

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

# task_name_1 = "sampleTask1"
# task_name_2 = "sampleTask2"
task_key_1 = datastore.key "Task", task_name_1
task_key_2 = datastore.key "Task", task_name_2
datastore.delete task_key_1, task_key_2

批量操作时，读取、写入和删除操作的费用不变，详见价格和配额。无论每个键是否存在，您都要为批量操作中的每个键付费。

操作所涉及的实体大小不影响读取、写入和删除操作的费用。但是，实体大小确实会影响存储空间大小费用。

增量和其他属性转换

使用 increment 等属性转换对属性进行服务器端更新。属性转换可避免执行额外的客户端读取操作来获取当前值，并避免执行客户端计算来确定新值。

Datastore 模式支持以下属性转换：

  • increment
  • maximum
  • minimum
  • appendMissingElements
  • removeAllFromArray
  • setToServerValue(REQUEST_TIME)

以下示例演示了属性转换。此操作会按指定值递增属性：

REST

POST https://datastore.googleapis.com/v1/projects/{projectId}:commit
{
  "mode": "NON_TRANSACTIONAL",
  "mutations": [
    {
      "propertyMask": {},  // Empty write mask indicates only transforms can change the entity.
      "propertyTransforms": [
        {
          "property": "quantity",
          "increment": {
            "integerValue": 2
          }
        },
        {
          "property": "inStock",
          "maximum": {
            "integerValue": 100
          }
        },
      ]
      "upsert": {
        "key": {
          "path": [
            {
              "kind": "Items",
              "name": "entity_1"
            }
          ]
        }
      }
    }
  ]
}

以下示例将属性值设置为服务器处理请求的时间（精确到毫秒）。

REST

POST https://datastore.googleapis.com/v1/projects/{projectId}:commit
{
  "mode": "NON_TRANSACTIONAL",
  "mutations": [
    {
      "propertyMask": {},  // // Empty write mask indicates only transforms can change the entity.
      "propertyTransforms": [
        {
          "property": "timeField",
          "setToServerValue": "REQUEST_TIME"
        },
      ]
      "upsert": {
        "key": {
          "path": [
            {
              "kind": "Kind_1",
              "name": "entity_1"
            }
          ]
        }
      }
    }
  ]
}

以下示例会在数组元素缺失时附加数组元素。

REST

POST https://datastore.googleapis.com/v1/projects/{projectId}:commit
{
  "mode": "NON_TRANSACTIONAL",
  "mutations": [
    {
      "propertyMask": {},  // Empty write mask indicates only transforms can change the entity.
      "propertyTransforms": [
        {
          "property": "arrayField",
          "appendMissingElements": {
            "values": [
              { "stringValue": "str" }, { "integerValue": 10 }
            ]
          }
        },
      ]
      "upsert": {
        "key": {
          "path": [
            {
              "kind": "Kind_1",
              "name": "entity_1"
            }
          ]
        }
      }
    }
  ]
}

混合类型（maximum 和 minimum）

maximum 和 minimum 属性转换接受整数或双精度（浮点数）值作为输入。目标属性中的值也可以是整数或双精度值。

如果属性不是整数或双精度值，或者属性不存在，则转换会将属性设置为给定的输入值和类型。如果应用 maximum 运算，并且属性和输入值的类型不同（即一个是整数，一个是双精度），则属性会采用较大运算数的类型。对于 minimum，该属性采用较小运算数的类型。

如果操作数等同（例如 3 和 3.0），则属性不会发生变化。0、0.0 和 -0.0 均为零。存储值为零且输入值为零的 maximum 或 minimum 始终为存储值。任何数值和 NaN 的 maximum 或 minimum 均为 NaN。

多个更改和 PropertyMask

在请求中的任何其他更改之后，系统会按顺序应用属性转换。PropertyMask 会将 insert、update 和 upsert 的更改限制为仅作用于指定的属性，但不会限制属性转换。

例如，从以下实体开始：

REST

entity: {
  "key" : {
    "path": [
      {
        "kind": "Kind_1",
        "name": "entity_1"
      }
    ]
  }
  "properties" : {
    "a": 1,
    "b": 2,
    "c": 3
  }
}

以下请求会同时更新 a 和 b，然后将属性转换应用于属性 b：

POST https://datastore.googleapis.com/v1/projects/{projectId}:commit
{
  "mode": "NON_TRANSACTIONAL",
  "mutations": [
    {
      "propertyMask": {"a", "b"},  // update property a, b
      "update": {
        "key": {
          "path": [
            {
              "kind": "Kind_1",
              "name": "entity_1"
            }
          ]
        }
        "properties": {
          "a" : "new_value",
          "b" : -2
        }
      },
      "propertyTransforms": [
        {
          "property": "b",
          "increment": { 
            "integerValue": 2
          }
        }
      ]
    }
  ]
}

结果如下：

REST

entity: {
  "key" : {
    "path": [
      {
        "kind": "Kind_1",
        "name": "entity_1"
      }
    ]
  }
  "properties" : {
    "a": "new_value",
    "b": 0,
    "c": 3
  }
}

种类和标识符

每个实体都属于某个种类，种类用于对实体进行分类以执行查询。例如，任务列表应用可以用 Task 种类的实体来表示待完成的各项任务。

以两个下划线 (__) 开头的所有种类名称均预留给系统，不得使用。

分配标识符

除了种类，在创建实体时还会为每个实体分配标识符。标识符是实体键的一部分，因此与实体永久关联且不可更改。标识符可通过下述两种方式分配：

  • 应用可为实体指定自己的键名字符串。

    如需了解实体键字符串的大小上限，请参阅限制。

  • 您可让 Datastore 模式 Firestore 自动为实体分配整数数字 ID。

  • 如需了解分配标识符的最佳实践，请参阅最佳实践中的“键”部分。

以下示例使用键名“sampleTask”作为标识符创建种类为 Task 的键：

C#

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

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

Key key = _db.CreateKeyFactory("Task").CreateKey("sampleTask");

Go

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

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

taskKey := datastore.NameKey("Task", "sampletask", nil)

Java

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

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

Key taskKey = datastore.newKeyFactory().setKind("Task").newKey("sampleTask");

Node.js

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

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

const taskKey = datastore.key(['Task', 'sampleTask']);

PHP

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

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

$taskKey = $datastore->key('Task', 'sampleTask');

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", "sampleTask")

Ruby

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

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

# task_name = "sampleTask"
task_key = datastore.key "Task", task_name

Datastore 模式还可自动分配 ID。Datastore 模式生成大致均匀分布的未使用 ID 的随机序列。每个 ID 最多可包含 16 位十进制数字。

以下示例使用 Task 种类而不使用键名创建键。当具有不完整键的实体保存为 Datastore 模式时，将返回实体的完整键（包括自动分配的 ID）：

C#

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

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

Key incompleteKey = _db.CreateKeyFactory("Task").CreateIncompleteKey();
Key key = _db.AllocateId(incompleteKey);

Go

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

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

// A complete key is assigned to the entity when it is Put.
taskKey := datastore.IncompleteKey("Task", nil)

Java

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

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

KeyFactory keyFactory = datastore.newKeyFactory().setKind("Task");
Key taskKey = datastore.allocateId(keyFactory.newKey());

Node.js

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

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

const taskKey = datastore.key('Task');

PHP

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

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

$taskKey = $datastore->key('Task');

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")

Ruby

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

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

task_key = datastore.key "Task"

如果希望向用户显示实体 ID 和/或按照顺序显示实体 ID，最好是使用手动分配。

分配您自己的数字 ID

有时，高级应用可能希望为其创建的实体手动分配自己的数字 ID，而不是使用键名字符串或自动生成数字 ID。但要注意，没有什么方法可以阻止 Datastore 模式的数据库将您手动分配的数字 ID 分配给其他实体。避免这种冲突的唯一方法是让应用通过 allocateIds() 方法获取一批 ID。

Datastore 模式的自动 ID 生成器将跟踪已按这些方法分配的 ID，并避免将其重复用于其他实体，因此您可以安全地使用这些 ID 而不引发冲突。您无法手动选择 allocateIds() 方法返回的值，allocateIds() 返回的值由 Datastore 模式分配。

祖先路径

Datastore 模式下的实体形成一个与文件系统目录结构类似的层级结构空间。创建实体时，您可选择指定另一实体作为其父实体；新实体是父实体的子实体（请注意，与文件系统不同，无需实际存在父实体）。没有父实体的实体是根实体。实体与其父实体之间的关联是永久的，实体创建后就无法更改。Datastore 模式绝不向父实体相同的两个实体分配同一数字 ID，也不分配给两个根实体（即没有父实体的实体）。

实体可以有多个层级的祖先和后代。实体的父实体、父实体的父实体和以此类推得出的实体都是该实体的祖先实体；而实体的子实体和子实体的子实体等都是它的后代实体。实体序列从根实体开始，接着从父实体到子实体，再指向给定的实体，这就构成了实体的祖先路径。标识实体的完整键由一系列种类-标识符对构成，它们指定实体的祖先路径并以实体自身的种类-标识符对终止：

[User:alice, TaskList:default, Task:sampleTask]

对于根实体，祖先路径为空，且键仅由实体自身的种类和标识符组成：

[User:alice]

父实体级别

父实体级别可用于整理数据。例如，如果应用按 TaskList 实体整理 Task 实体，请使用一个父实体级别：

C#

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

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

Key rootKey = _db.CreateKeyFactory("TaskList").CreateKey("default");
Key key = new KeyFactory(rootKey, "Task").CreateKey("sampleTask");

Go

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

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

parentKey := datastore.NameKey("TaskList", "default", nil)
taskKey := datastore.NameKey("Task", "sampleTask", parentKey)

Java

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

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

Key taskKey =
    datastore
        .newKeyFactory()
        .addAncestors(PathElement.of("TaskList", "default"))
        .setKind("Task")
        .newKey("sampleTask");

Node.js

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

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

const taskKey = datastore.key([
  'TaskList',
  'default',
  'Task',
  'sampleTask',
]);

PHP

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

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

$taskKey = $datastore->key('TaskList', 'default')
    ->pathElement('Task', 'sampleTask');

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("TaskList", "default", "Task", "sampleTask")
# Alternatively
parent_key = client.key("TaskList", "default")
key = client.key("Task", "sampleTask", parent=parent_key)

Ruby

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

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

# task_list_name = "default"
# task_name = "sampleTask"
task_key = datastore.key [["TaskList", task_list_name], ["Task", task_name]]

如果应用先按 User 实体组织 Task 实体，再按 TaskList 实体进行整理，请使用多个父实体级别：

C#

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

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

Key rootKey = _db.CreateKeyFactory("User").CreateKey("Alice");
Key taskListKey = new KeyFactory(rootKey, "TaskList").CreateKey("default");
Key key = new KeyFactory(taskListKey, "Task").CreateKey("sampleTask");

Go

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

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

userKey := datastore.NameKey("User", "alice", nil)
parentKey := datastore.NameKey("TaskList", "default", userKey)
taskKey := datastore.NameKey("Task", "sampleTask", parentKey)

Java

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

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

KeyFactory keyFactory =
    datastore
        .newKeyFactory()
        .addAncestors(PathElement.of("User", "Alice"), PathElement.of("TaskList", "default"))
        .setKind("Task");
Key taskKey = keyFactory.newKey("sampleTask");

Node.js

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

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

const taskKey = datastore.key([
  'User',
  'alice',
  'TaskList',
  'default',
  'Task',
  'sampleTask',
]);

PHP

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

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

$taskKey = $datastore->key('User', 'alice')
    ->pathElement('TaskList', 'default')
    ->pathElement('Task', 'sampleTask');

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("User", "alice", "TaskList", "default", "Task", "sampleTask")

Ruby

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

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

# user_name = "alice"
# task_list_name = "default"
# task_name = "sampleTask"
task_key = datastore.key([
                           ["User", user_name],
                           ["TaskList", task_list_name],
                           ["Task", task_name]
                         ])

如前面的示例所示，创建具有父实体的实体时，需指定父实体的完整祖先路径。

维护用户个人资料的应用可能只需要用户个人资料数据的一个父实体级别。例如，对 Profile 实体使用单级别 User 祖先路径：

[User:alice, Profile:public]

实现会议室安排的应用可能需要多个级别的父实体，比如对 Room 实体使用多级别 Building/Floor 祖先路径：

[Building:C, Floor:1, Room:123]

实体组

实体组由一个根实体及其所有后代实体组成。应用通常通过实体组整理高度相关的数据。例如，应用可使用实体组来存储一个产品或一个用户个人资料的相关数据。

属性和值类型

与实体关联的数据值由一个或多个属性构成。每个属性都有一个名称和一个或多个值。

属性可具有多个类型的值，且两个实体的同一属性可具有不同类型的值。属性并非一定要编入索引（对属性 p 进行排序或筛选的查询会忽略未将 p 编入索引的实体）。

以下为一些示例属性：

C#

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

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

Entity task = new Entity()
{
    Key = _db.CreateKeyFactory("Task").CreateKey("sampleTask"),
    ["category"] = "Personal",
    ["created"] = new DateTime(1999, 01, 01, 0, 0, 0, DateTimeKind.Utc),
    ["done"] = false,
    ["priority"] = 4,
    ["percent_complete"] = 10.0,
    ["description"] = new Value()
    {
        StringValue = "Learn Cloud Datastore",
        ExcludeFromIndexes = true
    },
};

Go

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

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

type Task struct {
	Category        string
	Done            bool
	Priority        int
	Description     string `datastore:",noindex"`
	PercentComplete float64
	Created         time.Time
}
task := &Task{
	Category:        "Personal",
	Done:            false,
	Priority:        4,
	Description:     "Learn Cloud Datastore",
	PercentComplete: 10.0,
	Created:         time.Now(),
}

Java

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

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

Entity task =
    Entity.newBuilder(taskKey)
        .set("category", "Personal")
        .set("created", Timestamp.now())
        .set("done", false)
        .set("priority", 4)
        .set("percent_complete", 10.0)
        .set(
            "description",
            StringValue.newBuilder("Learn Cloud Datastore").setExcludeFromIndexes(true).build())
        .build();

Node.js

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

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

const task = [
  {
    name: 'category',
    value: 'Personal',
  },
  {
    name: 'created',
    value: new Date(),
  },
  {
    name: 'done',
    value: false,
  },
  {
    name: 'priority',
    value: 4,
  },
  {
    name: 'percent_complete',
    value: 10.0,
  },
  {
    name: 'description',
    value: 'Learn Cloud Datastore',
    excludeFromIndexes: true,
  },
];

PHP

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

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

$task = $datastore->entity(
    $key,
    [
        'category' => 'Personal',
        'created' => new DateTime(),
        'done' => false,
        'priority' => 4,
        'percent_complete' => 10.0,
        'description' => 'Learn Cloud Datastore'
    ],
    ['excludeFromIndexes' => ['description']]
);

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()

import datetime

key = client.key("Task")
task = datastore.Entity(key, exclude_from_indexes=("description",))
task.update(
    {
        "category": "Personal",
        "description": "Learn Cloud Datastore",
        "created": datetime.datetime.now(tz=datetime.timezone.utc),
        "done": False,
        "priority": 4,
        "percent_complete": 10.5,
    }
)
client.put(task)

Ruby

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

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

task = datastore.entity "Task" do |t|
  t["category"] = "Personal"
  t["created"] = Time.now
  t["done"] = false
  t["priority"] = 4
  t["percent_complete"] = 10.0
  t["description"] = "Learn Cloud Datastore"
  t.exclude_from_indexes! "description", true
end

数组属性

具有多个值的属性称为数组属性。本示例包含两个数组属性。第一个名为 tags，具有值 fun 和 programming。第二个名为 collaborators，具有值 alice 和 bob。

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

数组属性在某些情况下可能很有用处，例如，在使用相等性过滤条件执行查询时；如果实体属性的任一值与过滤条件中指定的值匹配，该实体就符合查询条件。如需详细了解数组属性（包括注意事项），请参阅查询主题。

支持的值类型

属性以包含实体属性名称和值的 string/value 映射形式进行存储。值支持以下类型：

数组

  • REST API

    • 字段名称：arrayValue
    • 类型：包含 JSON 值对象数组的 ArrayValue 对象
    • 可按以下方式分配数组属性：使用类型为 ArrayValue 的 arrayValue 字段，再将其 values 字段设置为一个值数组。对于未编入索引的属性，请将该属性的值对象的 excludeFromIndexes 字段设置为 true。

  • RPC API

    • 字段名称：array_value
    • 类型：包含一个或多个 Value 消息的 ArrayValue 消息
    • 可按以下方式分配数组属性：使用类型为 ArrayValue 的 array_value 字段，再使用多个 Value 对象来填充其 values 字段。对于未编入索引的属性，请将 Value 的 exclude_from_indexes 字段设置为 true。

  • 排序顺序：无

  • 注意：不能包含其他数组值。值实例不得设置 meaning 或 exclude_from_indexes。

布尔值

  • REST API
    • 字段名称：booleanValue
    • 类型：true 或 false
  • RPC API
    • 字段名称：boolean_value
    • 类型：bool
  • 排序顺序：false<true

Blob

  • REST API
    • 字段名称：blobValue
    • 类型：字符串。必须为 base64 编码。
  • RPC API
    • 字段名称：blob_value
    • 类型：bytes
  • 排序顺序：字节顺序
  • 注意：如果属性编入索引，则不超过 1500 个字节；否则不超过 1048487 个字节（1 MiB - 89 个字节）。

日期和时间

  • REST API
    • 字段名称：timestampValue
    • 类型：字符串（RFC 3339 格式，以毫秒计，例如 2013-05-14T00:01:00.234Z）
  • RPC API
    • 字段名称：timestamp_value
    • 类型：Timestamp
  • 排序顺序：时间顺序
  • 注意：
    • 在 Datastore 模式下存储时，仅精确到微秒；舍掉任何额外的精度。
    • 作为投影查询的一部分返回时，Datastore 模式会将时间戳值转换为微秒（整数值）。

嵌入式实体

  • REST API
    • 字段名称：entityValue
    • 类型：JSON 实体
  • RPC API
    • 字段名称：entity_value
    • 类型：一条 Entity 消息
  • 排序顺序：无
  • 注意：编入索引后，您可对子属性进行查询。如果您将此值从索引中排除，则所有子属性也会从索引中排除。

浮点数

  • REST API
    • 字段名称：doubleValue
    • 类型：数字
  • RPC API
    • 字段名称：double_value
    • 类型：double
  • 排序顺序：数字顺序
  • 注意：64 位双精度，IEEE 754

地理位置点

  • REST API
    • 字段名称：geoPointValue
    • 类型：JSON 纬度/经度对
  • RPC API
    • 字段名称：geo_point_value
    • 类型：一条 LatLng 消息
  • 排序顺序：先按纬度，再按经度

整数

  • REST API
    • 字段名称：integerValue
    • 类型：数字或字符串。对于无法完全表示为数字的整数使用字符串。
  • RPC API
    • 字段名称：integer_value
    • 类型：int64
  • 排序顺序：数字顺序

键

  • REST API
    • 字段名称：keyValue
    • 类型：JSON Datastore 模式键
  • RPC API
    • 字段名称：key_value
    • 类型：一条 Key 消息
  • 排序顺序：按路径元素（种类、标识符、种类、标识符...）

Null

  • REST API
    • 字段名称：nullValue
    • 类型：null
  • RPC API
    • 字段名称：null_value
    • 类型：NullValue
  • 排序顺序：无

文本字符串

  • REST API
    • 字段名称：stringValue
    • 类型：string
  • RPC API
    • 字段名称：string_value
    • 类型：string
  • 排序顺序：UTF-8 编码的字节顺序
  • 注意：如果属性编入索引，则不超过 1500 个字节；否则不超过 1048487 个字节（1 MiB - 89 个字节）。

值类型排序

如果查询涉及的属性具有几种类型的值，Datastore 模式的数据库会使用基于内部表示法的确定性排序方式。以下列表显示了该顺序：

  1. Null 值
  2. 定点数
    • 整数
    • 日期和时间
  3. 布尔值
  4. 字节字符串
  5. Unicode 字符串
  6. 浮点数
  7. NaN 值
  8. 地理位置点
  9. Datastore 模式键