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

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 数値
Datastore のキー 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 では内部表現に基づく決定論的な順序付けが使用されます。

  1. Null 値
  2. 固定小数点数
    • 整数
    • 日時型
    • 評価
  3. ブール値
  4. バイト列
    • バイト文字列
    • Unicode 文字列
    • Blobstore のキー
  5. 浮動小数点数
  6. 地理的座標
  7. Google アカウントのユーザー
  8. 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 として返されます。