Referenz zu Entitätsattributen

Diese API wird für Laufzeiten der ersten Generation unterstützt und kann beim Upgrade auf entsprechende Laufzeiten der zweiten Generation verwendet werden. Wenn Sie auf die App Engine Java 11/17-Laufzeit aktualisieren möchten, erfahren Sie in der Migrationsanleitung mehr über Ihre Migrationsoptionen für gebündelte Legacy-Dienste.

Firestore im Datastore-Modus (Datastore) unterstützt eine Vielzahl von Datentypen für Attributwerte. Diese umfassen unter anderem:

• Ganzzahlen
• Gleitkommazahlen
• Strings
• Datumsangaben
• Binärdaten

Eine vollständige Liste der Typen finden Sie unter Eigenschaften und Werttypen.

Eigenschaften und Werttypen

Die mit einer Entität verknüpften Datenwerte bestehen aus einem oder mehreren Attributen. Jedes Attribut hat einen Namen und einen oder mehrere Werte. Ein Attribut kann Werte mit mehr als einem Typ haben und zwei Entitäten können Werte unterschiedlichen Typs für dasselbe Attribut haben. Attribute können indexiert oder nicht indexiert sein. Abfragen, die nach einem Attribut A sortieren oder filtern, ignorieren Entitäten, bei denen A nicht indexiert ist. Eine Entität kann höchstens 20.000 indexierte Attribute haben.

Hinweis: Attribute mit mehreren Werten können beispielsweise bei Abfragen mit Gleichheitsfiltern hilfreich sein. Eine Entität entspricht dann einer Abfrage, wenn ein Wert des Attributs mit dem im Filter angegebenen Wert übereinstimmt. Weitere Informationen zu mehrwertigen Attributen einschließlich möglicher Probleme finden Sie auf der Seite Datenspeicherabfragen.

Die folgenden Werttypen werden unterstützt:

Werttyp	Java-Typ(en)	Sortierreihenfolge	Hinweise
Ganzzahl	short int long java.lang.Short java.lang.Integer java.lang.Long	Numerisch	Gespeichert als lange Ganzzahl, dann Umwandlung in den Feldtyp Überlauf der außerhalb des Bereichs liegenden Werte
Gleitkommazahl	float double java.lang.Float java.lang.Double	Numerisch	64 Bit mit doppelter Genauigkeit, IEEE 754
Boolesch	boolean java.lang.Boolean	false<true
Textstring (kurz)	java.lang.String	Unicode	Bis zu 1.500 Byte Werte über 1.500 Byte geben IllegalArgumentException aus
Textstring (lang)	com.google.appengine.api.datastore.Text	Keine	Bis zu 1 Megabyte Nicht indexiert
Bytestring (kurz)	com.google.appengine.api.datastore.ShortBlob	Bytereihenfolge	Bis zu 1.500 Byte Werte, die länger als 1.500 Byte sind, geben IllegalArgumentException aus
Bytestring (lang)	com.google.appengine.api.datastore.Blob	Keine	Bis zu 1 Megabyte Nicht indexiert
Datum und Uhrzeit	java.util.Date	Chronologisch
Geografischer Punkt	com.google.appengine.api.datastore.GeoPt	Nach Breitengrad, dann nach Längengrad
Postanschrift	com.google.appengine.api.datastore.PostalAddress	Unicode
Telefonnummer	com.google.appengine.api.datastore.PhoneNumber	Unicode
E-Mail-Adresse	com.google.appengine.api.datastore.Email	Unicode
Nutzer eines Google-Kontos	com.google.appengine.api.users.User	E-Mail-Adresse in Unicode-Reihenfolge
Instant-Messaging-Handle	com.google.appengine.api.datastore.IMHandle	Unicode
Link	com.google.appengine.api.datastore.Link	Unicode
Kategorie	com.google.appengine.api.datastore.Category	Unicode
Bewertung	com.google.appengine.api.datastore.Rating	Numerisch
Datastore-Schlüssel	com.google.appengine.api.datastore.Key oder das referenzierte Objekt (als untergeordnetes Element)	Nach Pfadelementen (Art, Kennung, Art, Kennung...)	Bis zu 1.500 Byte Werte, die länger als 1.500 Byte sind, geben IllegalArgumentException aus
Blobstore-Schlüssel	com.google.appengine.api.blobstore.BlobKey	Bytereihenfolge
Eingebettete Entität	com.google.appengine.api.datastore.EmbeddedEntity	–	Nicht indexiert
Null	null	–

Wichtig: Das Speichern von users.User als Attributwert sollte unbedingt vermieden werden, da die E-Mail-Adresse und die eindeutige ID enthalten sind. Wenn ein Nutzer seine E-Mail-Adresse ändert und Sie das alte gespeicherte Objekt user.User mit dem neuen user.User-Wert vergleichen, würden sie nicht übereinstimmen. Stattdessen sollten Sie den Nutzer-ID-Wert User als stabile eindeutige Kennung des Nutzers verwenden.

Für Textstrings und nicht codierte Binärdaten (Bytestrings) unterstützt Datastore zwei Werttypen:

• Kurze Strings (bis zu 1.500 Byte) werden indexiert und können in Filterbedingungen der Abfrage und in Sortierfolgen verwendet werden.
• Lange Strings (bis zu 1 Megabyte) werden nicht indexiert und können nicht in Abfragefiltern und Sortierfolgen verwendet werden.

Hinweis: Der lange Bytestringtyp lautet in der Datastore API Blob. Dieser Typ steht nicht im Zusammenhang mit den Blobs in der Blobstore API.

Wenn eine Abfrage ein Attribut mit Werten verschiedener Typen enthält, verwendet Datastore eine deterministische Sortierung anhand der internen Darstellungen:

1. Nullwerte
2. Festkommazahlen
   • Ganzzahlen
   • Datums- und Uhrzeitwerte
   • Bewertungen
3. Boolesche Werte
4. Bytesequenzen
   • Bytestring
   • Unicode-String
   • Blobstore-Schlüssel
5. Gleitkommazahlen
6. Geografische Punkte
7. Nutzer von Google-Konten
8. Datastore-Schlüssel

Da lange Textstrings, lange Bytestrings und eingebettete Entitäten nicht indexiert werden, ist für sie keine Reihenfolge definiert.

Hinweis: Ganz- und Gleitkommazahlen werden in Datastore als separate Typen betrachtet. Wenn eine Entität für dasselbe Attribut eine Mischung aus Ganz- und Gleitkommazahlen verwendet, werden alle Ganzzahlen vor allen Gleitkommazahlen sortiert. Beispiel:

7 < 3.2

Wiederkehrende Attribute

Sie können mehrere Werte in einem einzelnen Attribut speichern.

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

Eingebettete Entitäten

In manchen Fällen ist es sinnvoll, eine Entität als Attribut in eine andere Entität einzubetten. Dies kann beispielsweise nützlich sein, um eine hierarchische Struktur von Attributwerten innerhalb einer Entität zu erstellen. Mit der Java-Klasse EmbeddedEntity ist das kein Problem:

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

embeddedContactInfo.setProperty("homeAddress", "123 Fake St, Made, UP 45678");
embeddedContactInfo.setProperty("phoneNumber", "555-555-5555");
embeddedContactInfo.setProperty("emailAddress", "[e-mail]");

employee.setProperty("contactInfo", embeddedContactInfo);

Attribute in einer eingebetteten Entität werden nicht indexiert und können nicht in Abfragen verwendet werden. Sie können einer eingebetteten Entität optional einen Schlüssel zuordnen. Im Gegensatz zu einer vollwertigen Entität ist der Schlüssel jedoch nicht erforderlich und kann nicht zum Abrufen der Entität verwendet werden, selbst wenn er vorhanden ist.

Statt die Attribute der eingebetteten Entität manuell auszufüllen, können Sie sie mit der Methode setPropertiesFrom() aus einer vorhandenen Entität kopieren:

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

Sie können später dieselbe Methode zum Wiederherstellen der ursprünglichen Entität aus der eingebetteten Entität verwenden:

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

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

Leere Liste verwenden

In der Vergangenheit konnte Datastore keine Attribute für eine leere Liste darstellen. Im Java SDK wurden leere Sammlungen daher als Nullwerte gespeichert, wodurch es nicht möglich ist, zwischen Nullwerten und leeren Listen zu unterscheiden. Zur Aufrechterhaltung der Abwärtskompatibilität bleibt dies das Standardverhalten, das sich wie folgt zusammenfassen lässt:

• Nullattribute werden in Datastore als Null geschrieben.
• Leere Sammlungen werden in den Datenspeicher als Null geschrieben.
• Nullwerte werden von Datastore als Null gelesen.
• Leere Sammlungen werden als Null gelesen.

Wichtig: Ein Lesen-Ändern-Schreiben-Vorgang für eine Entität mit einer leeren Liste bewirkt, dass diese Liste in einen Nullwert umgewandelt wird.

Wenn Sie jedoch das Standardverhalten ändern, unterstützt das App Engine Datastore Java SDK das Speichern leerer Listen. Es wird empfohlen, die Auswirkungen zu erwägen, die durch Ändern des Standardverhaltens Ihrer Anwendung entstehen, und anschließend die Unterstützung für leere Listen zu aktivieren.

Legen Sie das Attribut DATASTORE_EMPTY_LIST_SUPPORT während der Initialisierung der Anwendung fest, um das Standardverhalten so zu ändern, dass Sie leere Listen verwenden können:

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

Wird dieses Attribut wie oben auf true gesetzt, gilt:

• Nullattribute werden in Datastore als Null geschrieben.
• Leere Sammlungen werden als leere Liste in Datastore geschrieben.
• Nullwerte werden von Datastore als Null gelesen.
• Beim Lesen aus Datastore wird eine leere Liste als leere Sammlung zurückgegeben.

Wichtig: Wenn Sie die Unterstützung für leere Listen aktivieren, kann sich dies auf die Abfragen auswirken. Nullwerte werden in Datastore nämlich indexiert, leere Listen jedoch nicht. Wenn Sie leere Listen als Nullwerte speichern und anschließend nach null suchen, um sie zu finden, führt die Änderung in eine leere Liste dazu, dass diese Abfragen keine Ergebnisse zurückgeben.