实体属性参考

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

重要提示:强烈建议您不要将 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 中读取空列表时将返回空集合。