实体属性参考

Datastore 模式的 Firestore (Datastore) 支持多种属性值数据类型。其中包括：

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

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

属性和值类型

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

支持以下值类型：

值类型 Java 类型 排序顺序 备注
整数 short
int
long
java.lang.Short
java.lang.Integer
java.lang.Long		 数字 以长整数形式存储，然后转换为字段类型

超出范围的值溢出
浮点数 float
double
java.lang.Float
java.lang.Double		 数字 64 位双精度，
IEEE 754
布尔值 boolean
java.lang.Boolean		 false<true
短文本字符串 java.lang.String Unicode 最多 1500 字节

长度超过 1500 字节的值会引发 IllegalArgumentException
长文本字符串 com.google.appengine.api.datastore.Text 无 最多 1 兆字节

未编入索引
短字节字符串 com.google.appengine.api.datastore.ShortBlob 字节顺序 最多 1500 字节

长度超过 1500 字节的值会引发 IllegalArgumentException
长字节字符串 com.google.appengine.api.datastore.Blob 无 最多 1 兆字节

未编入索引
日期和时间 java.util.Date 时间顺序
地理位置点 com.google.appengine.api.datastore.GeoPt 先按纬度排序，
再按经度排序
邮寄地址 com.google.appengine.api.datastore.PostalAddress Unicode
电话号码 com.google.appengine.api.datastore.PhoneNumber Unicode
电子邮件地址 com.google.appengine.api.datastore.Email Unicode
Google 账号用户 com.google.appengine.api.users.User 按 Unicode 顺序排序的
电子邮件地址
即时消息传输句柄 com.google.appengine.api.datastore.IMHandle Unicode
链接 com.google.appengine.api.datastore.Link Unicode
类别 com.google.appengine.api.datastore.Category Unicode
评分 com.google.appengine.api.datastore.Rating 数字
Datastore 键 com.google.appengine.api.datastore.Key
或引用的对象（作为子对象）		 按路径元素
（种类、标识符、
种类、标识符...）排序		 最多 1500 字节

长度超过 1500 字节的值会引发 IllegalArgumentException
Blobstore 键 com.google.appengine.api.blobstore.BlobKey 字节顺序
嵌入式实体 com.google.appengine.api.datastore.EmbeddedEntity 无 未编入索引
Null null 无

重要提示：强烈建议您不要将 users.User 作为属性值进行存储，因为它包含电子邮件地址和唯一 ID。如果用户更改了其电子邮件地址，当您将其存储的旧 user.User 与新 user.User 值进行比较时，它们将无法匹配。请改为将 User 用户 ID 值用作用户固定的唯一标识符。

对于文本字符串和未编码的二进制数据（字节字符串），Datastore 支持两种值类型：

  • 短字符串（最多 1500 字节）会编入索引，可以在查询过滤条件和排序顺序中使用。
  • 长字符串（最多 1 兆字节）不编入索引，不能在查询过滤条件和排序顺序中使用。
注意：在 Datastore API 中，长字节字符串类型名为 Blob。此类型与 Blobstore API 中使用的 Blob 无关。

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

  1. Null 值
  2. 定点数
    • 整数
    • 日期和时间
    • 评分
  3. 布尔值
  4. 字节序列
    • 字节字符串
    • Unicode 字符串
    • Blobstore 键
  5. 浮点数
  6. 地理位置点
  7. Google 账号用户
  8. Datastore 键

由于长文本字符串、长字节字符串和嵌入式实体未编入索引，因此它们没有定义排序顺序。

重复属性

您可以在单个属性中存储多个值。

Entity employee = new Entity("Employee");
ArrayList<String> favoriteFruit = new ArrayList<String>();
favoriteFruit.add("Pear");
favoriteFruit.add("Apple");
employee.setProperty("favoriteFruit", favoriteFruit);
datastore.put(employee);

// Sometime later
employee = datastore.get(employee.getKey());
@SuppressWarnings("unchecked") // Cast can't verify generic type.
    ArrayList<String> retrievedFruits = (ArrayList<String>) employee
    .getProperty("favoriteFruit");

嵌入式实体

有时，您可能会发现，将一个实体作为另一个实体的属性嵌入十分方便。这在某些情况下很有用，例如创建实体中属性值的层级结构。您可以借助 Java 类 EmbeddedEntity 来实现此目的：

// Entity employee = ...;
EmbeddedEntity embeddedContactInfo = new EmbeddedEntity();

embeddedContactInfo.setProperty("homeAddress", "123 Fake St, Made, UP 45678");
embeddedContactInfo.setProperty("phoneNumber", "555-555-5555");
embeddedContactInfo.setProperty("emailAddress", "test@example.com");

employee.setProperty("contactInfo", embeddedContactInfo);

嵌入式实体的属性未编入索引，无法在查询中使用。您可以选择将键与嵌入式实体相关联，但（与完整实体不同）键不是必需的，即使存在，也不能用于检索实体。

您可以使用 setPropertiesFrom() 方法从现有实体中复制嵌入式实体的属性，而无需手动填充：

// Entity employee = ...;
// Entity contactInfo = ...;
EmbeddedEntity embeddedContactInfo = new EmbeddedEntity();

embeddedContactInfo.setKey(contactInfo.getKey()); // Optional, used so we can recover original.
embeddedContactInfo.setPropertiesFrom(contactInfo);

employee.setProperty("contactInfo", embeddedContactInfo);

之后，您可以使用相同方法从嵌入式实体恢复原始实体：

Entity employee = datastore.get(employeeKey);
EmbeddedEntity embeddedContactInfo = (EmbeddedEntity) employee.getProperty("contactInfo");

Key infoKey = embeddedContactInfo.getKey();
Entity contactInfo = new Entity(infoKey);
contactInfo.setPropertiesFrom(embeddedContactInfo);

使用空列表

过去，Datastore 未提供表示空列表的属性表示法。Java SDK 通过将空集合存储为 null 值解决了此问题，因此无法区分 null 值和空列表。为了保持向后兼容性，这仍是默认行为，概括如下：

  • null 属性作为 null 写入 Datastore
  • 空集合作为 null 写入 Datastore
  • 从 Datastore 中读取的 null 为 null
  • 读取的空集合为 null。

但如果您更改默认行为，Appengine Datastore Java SDK 将支持存储空列表。我们建议您考虑更改应用默认行为的影响，然后启用对空列表的支持。

如需更改默认行为以便使用空列表，请在应用初始化期间设置 DATASTORE_EMPTY_LIST_SUPPORT 属性，如下所示：

System.setProperty(DatastoreServiceConfig.DATASTORE_EMPTY_LIST_SUPPORT, Boolean.TRUE.toString());

按上述方法将此属性设为 true 后，会发生以下情况：

  • null 属性作为 null 写入 Datastore
  • 空集合作为空列表写入 Datastore
  • 从 Datastore 中读取的 null 为 null
  • 从 Datastore 中读取空列表时将返回空集合。