实体、属性和键

此 API 支持第一代运行时，并可在升级到相应的第二代运行时后使用。如果要更新到 App Engine Go 1.12+ 运行时，请参阅迁移指南以了解旧版捆绑服务的迁移选项。

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

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

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

如需查看类型的完整列表，请参阅属性和值类型。

Datastore 中的每个实体都有一个唯一标识它的键。键由以下部分组成：

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

不要将属性命名为“key”。此名称是为用于存储 Model 键的特殊属性保留的。尽管名为“key”的属性在本地可能正常工作，但无法部署到 App Engine 中。

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

Go App Engine SDK 包含一个软件包，用于将 Datastore 实体表示为 Go 结构体，此外还用于在 Datastore 中存储和检索这些实体。

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

种类和标识符

每个 Datastore 实体均属于特定“种类”，如此可将实体进行分类以便于查询；例如，人力资源应用可以通过种类为 Employee 的实体来表示公司的每位员工。在 Go Datastore API 中，您可以在创建 datastore.Key 时指定一个实体的种类。以两个下划线 (__) 字符开头的所有种类名称均属于保留名称，不得使用。

以下示例创建种类为 Employee 的实体，填充其属性值，并将其保存到 Datastore：

import (
	"context"
	"time"

	"google.golang.org/appengine/datastore"
)

type Employee struct {
	FirstName          string
	LastName           string
	HireDate           time.Time
	AttendedHRTraining bool
}

func f(ctx context.Context) {
	// ...
	employee := &Employee{
		FirstName: "Antonio",
		LastName:  "Salieri",
		HireDate:  time.Now(),
	}
	employee.AttendedHRTraining = true

	key := datastore.NewIncompleteKey(ctx, "Employee", nil)
	if _, err := datastore.Put(ctx, key, employee); err != nil {
		// Handle err
	}
	// ...
}

Employee 类型声明了该数据模型的四个属性：FirstName、LastName、HireDate、AttendedHRTraining。

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

• 应用可为实体指定自己的键名字符串。
• 您可让 Datastore 自动为实体分配一个整数数字 ID。

要为实体分配键名，请将一个非空 stringID 参数提供给 datastore.NewKey：

// Create a key with a key name "asalieri".
key := datastore.NewKey(
	ctx,        // context.Context
	"Employee", // Kind
	"asalieri", // String ID; empty means no string ID
	0,          // Integer ID; if 0, generate automatically. Ignored if string ID specified.
	nil,        // Parent Key; nil means no parent
)

如需让 Datastore 自动分配数字 ID，请使用空的 stringID 参数：

// Create a key such as Employee:8261.
key := datastore.NewKey(ctx, "Employee", "", 0, nil)
// This is equivalent:
key = datastore.NewIncompleteKey(ctx, "Employee", nil)

分配标识符

Datastore 可配置为使用两种不同的自动 ID 政策生成自动 ID：

• default 政策会生成大致均匀分布的未使用 ID 的随机序列。每个 ID 最多可包含 16 位十进制数字。
• legacy 政策会创建一系列不连续的较小整数 ID。

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

注意：有时，高级应用可能希望手动将自己的数字 ID 分配给其创建的实体，而不是使用键名字符串或自动生成数字 ID。但要注意的是，您无法防止 Datastore 将您的某个手动数字 ID 分配给另一个实体。避免这种冲突的唯一方法是让应用通过 datastore.AllocateIDs 函数获取一批 ID。Datastore 的自动 ID 生成器将跟踪该函数分配的 ID，并避免在其他实体中重复使用，因此您可以安全地使用这些 ID 而不会发生冲突。

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

祖先路径

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

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

[Person:GreatGrandpa, Person:Grandpa, Person:Dad, Person:Me]

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

[Person:GreatGrandpa]

此概念如下图所示：

如需指定实体的父实体，请将 parent 参数用于 datastore.NewKey。该参数的值应是父实体的键。以下示例将创建种类为 Address 的实体，并将 Employee 实体指定为其父实体：

// Create Employee entity
employee := &Employee{ /* ... */ }
employeeKey, err := datastore.Put(ctx, datastore.NewIncompleteKey(ctx, "Employee", nil), employee)

// Use Employee as Address entity's parent
// and save Address entity to datastore
address := &Address{ /* ... */ }
addressKey := datastore.NewIncompleteKey(ctx, "Address", employeeKey)
_, err = datastore.Put(ctx, addressKey, address)

事务和实体组

每次尝试创建、更新或删除实体时，这些操作都将在事务上下文中进行。单个事务可以包括任意数量的此类操作。为保持数据的一致性，事务确保其包含的所有操作作为一个单元应用于 Datastore，只要有任何操作失败，则所有操作都不会应用。此外，在同一个事务中执行的所有强一致读取（祖先查询或 get 方法）都遵从一致的数据快照。

注意：如果应用在尝试提交事务时收到错误，不一定表示事务失败。即使已提交事务并且最终将成功应用，也可能会收到错误。请尽可能对 Datastore 事务进行结构化设计，这样即便多次应用同一事务也不会影响最终结果。

如上所述，实体组是一组通过祖先实体连接到共同根元素的实体。将数据整理成实体组可以限制可执行的事务：

• 一个事务所访问的所有数据都必须包含在最多 25 个实体组中。
• 如果想在事务内使用查询，必须将数据整理成实体组，如此用户才可以指定与正确数据匹配的祖先过滤器。
• 单个实体组的写入吞吐量限制为每秒约一个事务。存在此限制是因为 Datastore 会在大范围的地理区域内，对每个实体组执行无主同步复制，以提供高可靠性和容错性。

在许多应用中，可在广泛查看互不相关数据时使用最终一致性（即跨多个实体组进行非祖先查询，有时可能会返回稍过时的数据），然后在查看或修改一组高度相关的数据时，使用强一致性（祖先查询，或使用 get 方法查询单个实体）。在此类应用中，通常适合为每组高度相关的数据使用独立的实体组。如需了解详情，请参阅设计结构以确保高度一致性。

注意：请避免将敏感信息存储在实体组键中。在删除实体组后，实体组键可能会被保留，以在 Datastore 中提供快速可靠的服务。

属性和值类型

与实体关联的数据值由一个或多个属性构成。每个属性都有一个名称和一个或多个值。一个属性可具有多个类型的值，且两个实体的同一属性可具有不同类型的值。属性可以编入索引，也可以不编入索引（对属性 P 排序或过滤的查询会忽略未将 P 编入索引的实体）。一个实体最多可以有 20000 个编入索引的属性。

注意：具有多个值的属性在某些情况下会很有用。例如，在使用等式过滤条件执行查询时：只要实体属性的任一值与过滤条件中指定的值匹配，该实体就符合查询条件。如需详细了解多值属性（包括注意事项），请参阅 Datastore 查询页面。

支持以下值类型：

值类型	Go 类型	排列顺序	备注
整数	int int8 int16 int32 int64	数字	64 位整数，有符号
浮点数	float32 float64	数字	64 位双精度， IEEE 754
布尔值	bool	false<true
字符串（短）	string	Unicode	最多 1500 字节。长度超过 1500 字节的值会导致运行时出错。
字符串（长）	string（带 noindex）	无	最多 1 兆字节 未编入索引
字节切片（短）	datastore.ByteString	字节顺序	最多 1500 字节。长度超过 1500 字节的值会导致运行时出错。
字节片（长）	[]byte	无	最多 1 兆字节 未编入索引
日期和时间	time.Time	时间顺序
地理位置点	appengine.GeoPoint	先按纬度排序， 再按经度排序
Datastore 键	*datastore.Key	按路径元素 （种类、标识符、 种类、标识符...）排序
Blobstore 键	appengine.BlobKey	字节顺序

您还可以使用 struct 或 slice 来聚合属性。如需了解详情，请参阅 Datastore 参考文档。

如果查询涉及的属性具有混合类型的值，Datastore 会根据内部表示法确定排序方式：

1. Null 值
2. 定点数
   • 整数
   • 日期和时间
3. 布尔值
4. 字节序列
   • 字节切片（短）
   • Unicode 字符串
   • Blobstore 键
5. 浮点数
6. 地理位置点
7. Datastore 键

由于长字节片和长字符串未编入索引，因此它们没有定义排序方式。

注意：Datastore 将整数和浮点数视为不同的类型。如果实体的同一属性既使用整数，又使用浮点数，则先对所有整数排序，再对所有浮点数排序。例如：

7 < 3.2

处理实体

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

创建实体

在 Go 中，您可以通过以下方式创建一个新实体：构造 Go 结构体的实例，填充其字段，并调用 datastore.Put 将其保存到 Datastore。只有所导出的字段（以大写字母开头）会保存到 Datastore。您可以通过将非空 stringID 参数传递给 datastore.NewKey 来指定实体的键名：

employee := &Employee{
	FirstName: "Antonio",
	LastName:  "Salieri",
	HireDate:  time.Now(),
}
employee.AttendedHRTraining = true
key := datastore.NewKey(ctx, "Employee", "asalieri", 0, nil)
_, err = datastore.Put(ctx, key, employee)

未提供键名或使用 datastore.NewIncompleteKey 时，Datastore 将自动为实体的键生成数字 ID：

employee := &Employee{
	FirstName: "Antonio",
	LastName:  "Salieri",
	HireDate:  time.Now(),
}
employee.AttendedHRTraining = true
key := datastore.NewIncompleteKey(ctx, "Employee", nil)
_, err = datastore.Put(ctx, key, employee)

检索实体

如需检索由给定键标识的实体，请将 *datastore.Key 作为参数传递给 datastore.Get 函数。您可以使用 datastore.NewKey 函数生成 *datastore.Key。

employeeKey := datastore.NewKey(ctx, "Employee", "asalieri", 0, nil)
addressKey := datastore.NewKey(ctx, "Address", "", 1, employeeKey)
var addr Address
err = datastore.Get(ctx, addressKey, &addr)

datastore.Get 将填充相应 Go 结构体的实例。

更新实体

如需更新现有实体，请修改结构体的属性，然后调用 datastore.Put。数据将覆盖现有实体。每次调用 datastore.Put 时，整个对象都会发送到 Datastore。

注意：Datastore API 不区分创建新实体和更新现有实体的操作。如果键表示已存在的实体，则 datastore.Put 函数会覆盖现有实体。在创建实体之前，您可以使用事务来测试是否存在具有给定键的实体。

删除实体

如果您知道实体的键，可以使用 datastore.Delete 函数删除实体：

key := datastore.NewKey(ctx, "Employee", "asalieri", 0, nil)
err = datastore.Delete(ctx, key)

批量操作

datastore.Put、datastore.Get、datastore.Delete 具有批量变体，分别称为 datastore.PutMulti、datastore.GetMulti、datastore.DeleteMulti。它们允许在单次 Datastore 调用中对多个实体执行操作：

// A batch put.
_, err = datastore.PutMulti(ctx, []*datastore.Key{k1, k2, k3}, []interface{}{e1, e2, e3})

// A batch get.
var entities = make([]*T, 3)
err = datastore.GetMulti(ctx, []*datastore.Key{k1, k2, k3}, entities)

// A batch delete.
err = datastore.DeleteMulti(ctx, []*datastore.Key{k1, k2, k3})

批量操作不会改变费用。无论批量操作中的每个键是否存在，您都要为各个键付费。操作所涉及的实体大小不会影响费用。

注意：调用 datastore.PutMulti 或 datastore.DeleteMulti 可能对某些实体有效，而对另一些实体无效。如果调用必须完全成功或完全失败，您必须使用事务且所有受影响的实体必须归入同一实体组。