注: Java 8 は、2024 年 1 月 31 日にサポートが終了しました。既存の Java 8 アプリケーションは引き続き実行され、トラフィックを受信します。ただし、サポート終了日を過ぎると、ランタイムを使用するアプリケーションの再デプロイが App Engine によってブロックされることがあります。サポートされている最新バージョンの Java に移行することをおすすめします。

エンティティプロパティリファレンス

Datastore モードの Firestore（Datastore）では、プロパティ値にさまざまなデータ型がサポートされています。サポートしているデータ型の例を次に示します。

整数
浮動小数点数
文字列
日付
バイナリデータ

サポートしているすべてのデータ型については、プロパティと値の型をご覧ください。

プロパティと値の型

エンティティに関連付けられたデータ値は 1 つ以上のプロパティで構成されます。各プロパティには名前と 1 つ以上の値があります。プロパティは異なる型の複数の値を持つことができるため、2 つのエンティティの同じプロパティに異なる型の値が存在する場合もあります。プロパティはインデックス付けされている場合とされていない場合があります（プロパティ P で並べ替えまたはフィルタリングを行うクエリでは、P がインデックス付けされていないエンティティは無視されます）。1 つのエンティティに、インデックスが付けられたプロパティを最大 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	最大 1,500 バイト 1,500 バイトを超える値は `IllegalArgumentException` をスローします。
テキスト文字列（長い）	`com.google.appengine.api.datastore.Text`	なし	最大 1 メガバイトインデックス付けなし
バイト文字列（短）	`com.google.appengine.api.datastore.ShortBlob`	バイト順	最大 1,500 バイト 1,500 バイトを超える値は `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`	数値
データストアのキー	`com.google.appengine.api.datastore.Key` または参照先オブジェクト（子として）	パス要素順（種類、識別子、種類、識別子...）	最大 1,500 バイト 1,500 バイトを超える値は `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 は次の 2 つの値の型をサポートします。

短い文字列（最大 1,500 バイト）は、インデックスに登録され、クエリのフィルタ条件や並べ替えの順序付けに使用できます。
長い文字列（最大 1 メガバイト）は、インデックスに登録されず、クエリのフィルタや並べ替えの順序付けには使用できません。

注: 長いバイト文字列型は、Datastore API では Blob と呼ばれています。この型は、Blobstore API で使用される blob とは関係ありません。

型が混合した値を持つプロパティをクエリで扱う場合、Datastore では内部表現に基づく決定論的な順序付けが使用されます。

Null 値
固定小数点数
- 整数
- 日時型
- 評価
ブール値
バイト列
- バイト文字列
- Unicode 文字列
- Blobstore のキー
浮動小数点数
地理的座標
Google アカウントのユーザー
Datastore のキー

長いテキスト文字列、長いバイト文字列、埋め込みエンティティはインデックスに登録されないため、順序付けは定義されていません。

反復プロパティ

1 つのプロパティに複数の値を保存できます。

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

エンティティの埋め込み

あるエンティティを別のエンティティのプロパティとして埋め込むと便利な場合があります。たとえば、1 つのエンティティ内でプロパティ値の階層構造を作成する場合などです。これは 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 に書き込まれます。
null は、null として Datastore から読み取られます。
空のコレクションは、null として読み取られます。

ただし、デフォルトの動作を変更することで、Appengine Datastore Java SDK は、空のリストの保存をサポートするようになります。アプリケーションのデフォルトの動作を変更した場合の影響について考慮したうえで、空のリストのサポートを有効にしてください。

空のリストを使用できるようにデフォルトの動作を変更するには、アプリの初期化時に、次に示すように DATASTORE_EMPTY_LIST_SUPPORT プロパティを設定します。

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

上記のように、このプロパティを true に設定すると、次のようになります。

null のプロパティは、null として Datastore に書き込まれます。
空のコレクションは、空のリストとして Datastore に書き込まれます。
null は、null として Datastore から読み取られます。
空のリストを Datastore から読み取ると、空の Collection として返されます。