實體屬性參考資料

使用 Datastore 模式的 Firestore 支援各種屬性值的資料類型。其中包括:

  • 整數
  • 浮點數
  • 字串
  • 日期
  • 二進位資料

如需這些類型的完整清單,請參閱屬性和值類型一節。

屬性和值類型

與實體相關聯的資料值由一或多個「屬性」組成。每個屬性都有一個名稱及一或多個值。一個屬性可能會有多個類型的值,而兩個實體的相同屬性可能會有不同類型的值。屬性可能已建立索引或未建立索引 (排序或篩選屬性「P」的查詢將忽略「P」未建立索引的實體)。一個實體最多可有 20,000 個已建立索引的屬性。

支援的值類型如下:

值類型 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 MB

不會建立索引
位元組字串 (短) com.google.appengine.api.datastore.ShortBlob 位元組順序 最多 1500 個位元組

超過 1500 個位元組的值會擲回 IllegalArgumentException
位元組字串 (長) com.google.appengine.api.datastore.Blob 最多 1 MB

不會建立索引
日期與時間 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
或參考物件 (當做子項)
依路徑元素
(種類、ID、
種類、ID...)
最多 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 值」做為使用者的穩定專屬 ID。

針對文字字串和未編碼的二進位資料 (位元組字串),Datastore 支援兩種值類型:

  • 短字串 (不超過 1,500 個位元組) 會建立索引,可用於查詢篩選器條件和排序順序。
  • 長字串 (不超過 1 MB) 不會建立索引,也不能用於查詢篩選器和排序順序。
注意:長位元組字串類型在 Datastore API 中的名稱為 Blob。這類型與 Blobstore API 中使用的 blob 無關。

當查詢的屬性具有混合類型的值時,Datastore 會根據內部表示法使用確定性排序:

  1. 空值
  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 的解決方式是將空白集合儲存為空值,但也因此無法區分空值和空白清單。為維持回溯相容性,系統仍會將這個方法當做預設行為,運作方式摘要如下:

  • 空值屬性以空值寫入 Datastore
  • 空白集合以空值寫入 Datastore
  • 從 Datastore 讀取的空值會被當做空值
  • 空白集合會被當成空值讀取。

但是,如果您變更預設行為,Appengine Datastore Java SDK 就會支援儲存空白清單。建議您對變更應用程式預設行為一事深思熟慮之後,再開啟空白清單的支援

如果要變更預設行為以能使用空白清單,請在應用程式初始化期間,按照下列方式設定 DATASTORE_EMPTY_LIST_SUPPORT 屬性:

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

將此屬性如上所示設為 true 之後,運作方式如下:

  • 空值屬性以空值寫入 Datastore
  • 空白集合以空白清單寫入 Datastore
  • 從 Datastore 讀取的空值會被當做空值
  • 從 Datastore 讀取時,會以空白集合傳回空白清單。