Entitäten, Attribute und Schlüssel

Datenobjekte in Firestore im Datastore-Modus werden als Entitäten bezeichnet. Eine Entität hat ein oder mehrere benannte Attribute, von denen jedes einen oder mehrere Werte haben kann. Entitäten derselben Art müssen nicht dieselben Attribute haben und die Werte einer Entität für ein bestimmtes Attribut müssen nicht alle denselben Datentyp aufweisen. (Falls erforderlich kann eine Anwendung derartige Einschränkungen in ihrem eigenen Datenmodell festlegen und erzwingen.)

Der Datastore-Modus unterstützt zahlreiche Datentypen für Attributwerte. Diese umfassen unter anderem:

Ganzzahlen
Gleitkommazahlen
Strings
Datumsangaben
Binärdaten

Jede Entität in einer Datenbank im Datastore-Modus hat einen Schlüssel, der sie eindeutig identifiziert. Der Schlüssel besteht aus den folgenden Komponenten:

Namespace der Entität, der die Mehrinstanzenfähigkeit ermöglicht
Art der Entität, mit der die Entität für Abfragen kategorisiert wird
Kennung für die einzelne Entität, entweder
- ein Schlüsselnamen-String oder
- eine ganzzahlige numerische ID
Optionaler Ancestor-Pfad zur Entität innerhalb der Datenbankhierarchie

Eine Anwendung kann eine einzelne Entität mithilfe des Entitätsschlüssels aus der Datenbank abrufen oder eine bzw. mehrere Entitäten mit einer Abfrage ermitteln, die auf den Schlüsseln oder Attributwerten der Entitäten basiert.

Firestore im Datastore-Modus selbst erzwingt keine Einschränkungen für die Struktur der Entitäten, beispielsweise ob ein bestimmtes Attribut einen Wert eines bestimmten Typs hat. Diese Aufgabe bleibt der Anwendung überlassen.

Die Snippets auf dieser Seite beruhen auf dem Beispiel aus Erste Schritte mit der Firestore in Datastore mode API.

Mit Entitäten arbeiten

Anwendungen können die Firestore in Datastore mode API verwenden, um Entitäten zu erstellen, abzurufen, zu aktualisieren und zu löschen. Wenn die Anwendung den vollständigen Schlüssel für eine Entität kennt (oder ihn aus dem übergeordneten Schlüssel, der Art und der Kennung ableiten kann), kann sie mithilfe des Schlüssels direkt mit der Entität arbeiten. Eine Anwendung kann auch den Schlüssel einer Entität als Ergebnis einer Abfrage erhalten. Weitere Informationen finden Sie im Thema Abfragen.

Entität erstellen

Sie erstellen eine neue Entität, indem Sie sie initialisieren und ihre Attribute festlegen:

C#

Informationen zum Installieren und Verwenden der Clientbibliothek für Cloud Datastore finden Sie unter Cloud Datastore-Clientbibliotheken. Weitere Informationen finden Sie in der Referenzdokumentation zur Cloud Datastore C# API.

Richten Sie Standardanmeldedaten für Anwendungen ein, um sich bei Cloud Datastore zu authentifizieren. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten.

Entity task = new Entity()
{
    Key = _db.CreateKeyFactory("Task").CreateKey("sampleTask"),
    ["category"] = "Personal",
    ["done"] = false,
    ["priority"] = 4,
    ["description"] = "Learn Cloud Datastore"
};

Go

type Task struct {
	Category        string
	Done            bool
	Priority        float64
	Description     string `datastore:",noindex"`
	PercentComplete float64
	Created         time.Time
}
task := &Task{
	Category:        "Personal",
	Done:            false,
	Priority:        4,
	Description:     "Learn Cloud Datastore",
	PercentComplete: 10.0,
	Created:         time.Now(),
}

Java

Key taskKey = datastore.newKeyFactory().setKind("Task").newKey("sampleTask");
Entity task =
    Entity.newBuilder(taskKey)
        .set("category", "Personal")
        .set("done", false)
        .set("priority", 4)
        .set("description", "Learn Cloud Datastore")
        .build();

Node.js

const task = {
  category: 'Personal',
  done: false,
  priority: 4,
  description: 'Learn Cloud Datastore',
};

PHP

$task = $datastore->entity('Task', [
    'category' => 'Personal',
    'done' => false,
    'priority' => 4,
    'description' => 'Learn Cloud Datastore'
]);

Python

from google.cloud import datastore

# For help authenticating your client, visit
# https://cloud.google.com/docs/authentication/getting-started
client = datastore.Client()

task = datastore.Entity(client.key("Task"))
task.update(
    {
        "category": "Personal",
        "done": False,
        "priority": 4,
        "description": "Learn Cloud Datastore",
    }
)

Ruby

task = datastore.entity "Task" do |t|
  t["category"] = "Personal"
  t["done"] = false
  t["priority"] = 4
  t["description"] = "Learn Cloud Datastore"
end

Sie können die Entität in der Datenbank mit upsert speichern (dadurch wird eine Entität überschrieben, wenn sie im Datastore-Modus bereits vorhanden ist) oder mit insert (dabei darf der Entitätsschlüssel noch nicht vorhanden sein).

So speichern Sie eine Entität mit upsert:

C#

_db.Upsert(_sampleTask);

Go

key := datastore.IncompleteKey("Task", nil)
key, err := client.Put(ctx, key, task)

Java

Entity task = Entity.newBuilder(keyFactory.newKey("sampleTask")).build();
datastore.put(task);

Node.js

const taskKey = datastore.key('Task');
const task = {
  category: 'Personal',
  done: false,
  priority: 4,
  description: 'Learn Cloud Datastore',
};

const entity = {
  key: taskKey,
  data: task,
};

await datastore.upsert(entity);
// Task inserted successfully.

PHP

$key = $datastore->key('Task', 'sampleTask');
$task = $datastore->entity($key, [
    'category' => 'Personal',
    'done' => false,
    'priority' => 4,
    'description' => 'Learn Cloud Datastore'
]);
$datastore->upsert($task);

Python

from google.cloud import datastore

# For help authenticating your client, visit
# https://cloud.google.com/docs/authentication/getting-started
client = datastore.Client()

complete_key = client.key("Task", "sampleTask")

task = datastore.Entity(key=complete_key)

task.update(
    {
        "category": "Personal",
        "done": False,
        "priority": 4,
        "description": "Learn Cloud Datastore",
    }
)

client.put(task)

Ruby

# task_name = "sampleTask"
task = datastore.entity "Task", task_name do |t|
  t["category"] = "Personal"
  t["done"] = false
  t["priority"] = 4
  t["description"] = "Learn Cloud Datastore"
end
datastore.save task

So speichern Sie eine Entität mit insert:

C#

Entity task = new Entity()
{
    Key = _keyFactory.CreateIncompleteKey()
};
task.Key = _db.Insert(task);

Go

taskKey := datastore.NameKey("Task", "sampleTask", nil)
_, err := client.RunInTransaction(ctx, func(tx *datastore.Transaction) error {
	// We first check that there is no entity stored with the given key.
	var empty Task
	if err := tx.Get(taskKey, &empty); err != datastore.ErrNoSuchEntity {
		return err
	}
	// If there was no matching entity, store it now.
	_, err := tx.Put(taskKey, &task)
	return err
})

Java

Key taskKey = datastore.add(FullEntity.newBuilder(keyFactory.newKey()).build()).getKey();

Node.js

const taskKey = datastore.key('Task');
const task = {
  category: 'Personal',
  done: false,
  priority: 4,
  description: 'Learn Cloud Datastore',
};

const entity = {
  key: taskKey,
  data: task,
};

datastore.insert(entity).then(() => {
  // Task inserted successfully.
});

PHP

$task = $datastore->entity('Task', [
    'category' => 'Personal',
    'done' => false,
    'priority' => 4,
    'description' => 'Learn Cloud Datastore'
]);
$datastore->insert($task);

Python

from google.cloud import datastore

# For help authenticating your client, visit
# https://cloud.google.com/docs/authentication/getting-started
client = datastore.Client()

with client.transaction():
    incomplete_key = client.key("Task")

    task = datastore.Entity(key=incomplete_key)

    task.update(
        {
            "category": "Personal",
            "done": False,
            "priority": 4,
            "description": "Learn Cloud Datastore",
        }
    )

    client.put(task)

Ruby

datastore.transaction do |_tx|
  task = datastore.entity "Task" do |t|
    t["category"] = "Personal"
    t["done"] = false
    t["priority"] = 4
    t["description"] = "Learn Cloud Datastore"
  end
  datastore.save task
end

Entität abrufen

Verwenden Sie für den Abruf einer Entität aus der Datenbank deren Schlüssel für ein lookup:

C#

Entity task = _db.Lookup(_sampleTask.Key);

Go

var task Task
taskKey := datastore.NameKey("Task", "sampleTask", nil)
err := client.Get(ctx, taskKey, &task)

Java

Entity task = datastore.get(taskKey);

Node.js

const taskKey = datastore.key('Task');
const [entity] = await datastore.get(taskKey);
// entity = {
//   category: 'Personal',
//   done: false,
//   priority: 4,
//   description: 'Learn Cloud Datastore',
//   [Symbol(KEY)]:
//    Key {
//      namespace: undefined,
//      id: '...',
//      kind: 'Task',
//      path: [Getter]
//    }
//   }
// };
console.log(entity);

PHP

$task = $datastore->lookup($key);

Python

from google.cloud import datastore

# For help authenticating your client, visit
# https://cloud.google.com/docs/authentication/getting-started
client = datastore.Client()

key = client.key("Task", "sampleTask")
task = client.get(key)

Ruby

# task_name = "sampleTask"
task_key = datastore.key "Task", task_name
task = datastore.find task_key

Entität aktualisieren

Wenn Sie eine vorhandene Entität mit update aktualisieren möchten, ändern Sie die Attribute der zuvor abgerufenen Entität und speichern Sie die Entität mit dem folgenden Schlüssel:

C#

_sampleTask["priority"] = 5;
_db.Update(_sampleTask);

Go

taskKey := datastore.NameKey("Task", "sampleTask", nil)
tx, err := client.NewTransaction(ctx)
if err != nil {
	log.Fatalf("client.NewTransaction: %v", err)
}
var task Task
if err := tx.Get(taskKey, &task); err != nil {
	log.Fatalf("tx.Get: %v", err)
}
task.Priority = 5
if _, err := tx.Put(taskKey, &task); err != nil {
	log.Fatalf("tx.Put: %v", err)
}
if _, err := tx.Commit(); err != nil {
	log.Fatalf("tx.Commit: %v", err)
}

Java

Entity task = Entity.newBuilder(datastore.get(taskKey)).set("priority", 5).build();
datastore.update(task);

Node.js

const taskKey = datastore.key('Task');
const task = {
  category: 'Personal',
  done: false,
  priority: 4,
  description: 'Learn Cloud Datastore',
};

const entity = {
  key: taskKey,
  data: task,
};

await datastore.update(entity);
// Task updated successfully.

PHP

$transaction = $datastore->transaction();
$key = $datastore->key('Task', 'sampleTask');
$task = $transaction->lookup($key);
$task['priority'] = 5;
$transaction->update($task);
$transaction->commit();

Python

from google.cloud import datastore

# For help authenticating your client, visit
# https://cloud.google.com/docs/authentication/getting-started
client = datastore.Client()

with client.transaction():
    key = client.key("Task", "sampleTask")
    task = client.get(key)

    task["done"] = True

    client.put(task)

Ruby

# task_name = "sampleTask"
datastore.transaction do |_tx|
  task = datastore.find "Task", task_name
  task["priority"] = 5
  datastore.save task
end

Die angegebenen Daten überschreiben die vorhandene Entität. Das gesamte Objekt muss an die Datenbank gesendet werden. Wenn die Entität nicht vorhanden ist, schlägt die Aktualisierung fehl. Wenn Sie eine Entität aktualisieren oder erstellen möchten, verwenden Sie upsert wie oben beschrieben. Mit einer Transaktion können Sie die Vorgänge get und update in einer einzigen atomaren Transaktion ausführen.

Entität löschen

Sie können eine Entität unter Angabe ihres Schlüssels mit delete löschen:

C#

_db.Delete(_sampleTask.Key);

Go

key := datastore.NameKey("Task", "sampletask", nil)
err := client.Delete(ctx, key)

Java

datastore.delete(taskKey);

Node.js

const taskKey = datastore.key('Task');
await datastore.delete(taskKey);
// Task deleted successfully.

PHP

$datastore->delete($taskKey);

Python

from google.cloud import datastore

# For help authenticating your client, visit
# https://cloud.google.com/docs/authentication/getting-started
client = datastore.Client()

key = client.key("Task", "sampleTask")
client.delete(key)

Ruby

# task_name = "sampleTask"
task_key = datastore.key "Task", task_name
datastore.delete task_key

Batchvorgänge

Firestore im Datastore-Modus unterstützt Batchversionen der Vorgänge, die die Verarbeitung mehrerer Objekte in einem einzigen Aufruf des Datastore-Modus ermöglichen.

Solche Batchaufrufe können schneller ausgeführt werden als separate Aufrufe für jede einzelne Entität, weil nur der Overhead für einen Dienstaufruf anfällt. Wenn mehrere Entitätengruppen betroffen sind, wird die Arbeit für alle Gruppen im Parallelverfahren auf der Serverseite ausgeführt.

So ist beispielsweise ein upsert von mehreren Entitäten möglich:

C#

var taskList = new[]
{
    new Entity()
    {
        Key = _keyFactory.CreateIncompleteKey(),
        ["category"] = "Personal",
        ["done"] = false,
        ["priority"] = 4,
        ["description"] = "Learn Cloud Datastore"
    },
    new Entity()
    {
        Key = _keyFactory.CreateIncompleteKey(),
        ["category"] = "Personal",
        ["done"] = "false",
        ["priority"] = 5,
        ["description"] = "Integrate Cloud Datastore"
    }
};
var keyList = _db.Upsert(taskList[0], taskList[1]);

Go

tasks := []*Task{
	{
		Category:    "Personal",
		Done:        false,
		Priority:    4,
		Description: "Learn Cloud Datastore",
	},
	{
		Category:    "Personal",
		Done:        false,
		Priority:    5,
		Description: "Integrate Cloud Datastore",
	},
}
keys := []*datastore.Key{
	datastore.IncompleteKey("Task", nil),
	datastore.IncompleteKey("Task", nil),
}

keys, err := client.PutMulti(ctx, keys, tasks)

Java

FullEntity<IncompleteKey> task1 =
    FullEntity.newBuilder(keyFactory.newKey())
        .set("category", "Personal")
        .set("done", false)
        .set("priority", 4)
        .set("description", "Learn Cloud Datastore")
        .build();
FullEntity<IncompleteKey> task2 =
    Entity.newBuilder(keyFactory.newKey())
        .set("category", "Personal")
        .set("done", false)
        .set("priority", 5)
        .set("description", "Integrate Cloud Datastore")
        .build();
List<Entity> tasks = datastore.add(task1, task2);
Key taskKey1 = tasks.get(0).getKey();
Key taskKey2 = tasks.get(1).getKey();

Node.js

const taskKey1 = this.datastore.key(['Task', 1]);
const taskKey2 = this.datastore.key(['Task', 2]);

const task1 = {
  category: 'Personal',
  done: false,
  priority: 4,
  description: 'Learn Cloud Datastore',
};

const task2 = {
  category: 'Work',
  done: false,
  priority: 8,
  description: 'Integrate Cloud Datastore',
};

const entities = [
  {
    key: taskKey1,
    data: task1,
  },
  {
    key: taskKey2,
    data: task2,
  },
];

await datastore.upsert(entities);
// Tasks inserted successfully.

PHP

$result = $datastore->upsertBatch($tasks);

Python

from google.cloud import datastore

# For help authenticating your client, visit
# https://cloud.google.com/docs/authentication/getting-started
client = datastore.Client()

task1 = datastore.Entity(client.key("Task", 1))

task1.update(
    {
        "category": "Personal",
        "done": False,
        "priority": 4,
        "description": "Learn Cloud Datastore",
    }
)

task2 = datastore.Entity(client.key("Task", 2))

task2.update(
    {
        "category": "Work",
        "done": False,
        "priority": 8,
        "description": "Integrate Cloud Datastore",
    }
)

client.put_multi([task1, task2])

Ruby

task_1 = datastore.entity "Task" do |t|
  t["category"] = "Personal"
  t["done"] = false
  t["priority"] = 4
  t["description"] = "Learn Cloud Datastore"
end

task_2 = datastore.entity "Task" do |t|
  t["category"] = "Personal"
  t["done"] = false
  t["priority"] = 5
  t["description"] = "Integrate Cloud Datastore"
end

tasks = datastore.save task_1, task_2
task_key_1 = tasks[0].key
task_key_2 = tasks[1].key

Ein lookup mehrerer Entitäten ist möglich:

C#

var keys = new Key[] { _keyFactory.CreateKey(1), _keyFactory.CreateKey(2) };
var tasks = _db.Lookup(keys[0], keys[1]);

Go

var taskKeys []*datastore.Key // Populated with incomplete keys.
tasks := make([]*Task, len(taskKeys))
err := client.GetMulti(ctx, taskKeys, &tasks)

Java

Iterator<Entity> tasks = datastore.get(taskKey1, taskKey2);

Node.js

const taskKey1 = this.datastore.key(['Task', 1]);
const taskKey2 = this.datastore.key(['Task', 2]);

const keys = [taskKey1, taskKey2];

const [tasks] = await datastore.get(keys);
// Tasks retrieved successfully.
console.log(tasks);

PHP

$result = $datastore->lookupBatch($keys);
if (isset($result['found'])) {
    // $result['found'] is an array of entities.
} else {
    // No entities found.
}

Python

from google.cloud import datastore

# For help authenticating your client, visit
# https://cloud.google.com/docs/authentication/getting-started
client = datastore.Client()

keys = [client.key("Task", 1), client.key("Task", 2)]
tasks = client.get_multi(keys)

Ruby

# task_name_1 = "sampleTask1"
# task_name_2 = "sampleTask2"
task_key_1 = datastore.key "Task", task_name_1
task_key_2 = datastore.key "Task", task_name_2
tasks = datastore.find_all task_key_1, task_key_2

Sie können mehrere Entitäten löschen:

C#

var keys = new Key[] { _keyFactory.CreateKey(1), _keyFactory.CreateKey(2) };
_db.Delete(keys);

Go

err := client.DeleteMulti(ctx, taskKeys)

Java

datastore.delete(taskKey1, taskKey2);

Node.js

const taskKey1 = this.datastore.key(['Task', 1]);
const taskKey2 = this.datastore.key(['Task', 2]);

const keys = [taskKey1, taskKey2];

await datastore.delete(keys);
// Tasks deleted successfully.

PHP

$result = $datastore->deleteBatch($keys);

Python

from google.cloud import datastore

# For help authenticating your client, visit
# https://cloud.google.com/docs/authentication/getting-started
client = datastore.Client()

keys = [client.key("Task", 1), client.key("Task", 2)]
client.delete_multi(keys)

Ruby

# task_name_1 = "sampleTask1"
# task_name_2 = "sampleTask2"
task_key_1 = datastore.key "Task", task_name_1
task_key_2 = datastore.key "Task", task_name_2
datastore.delete task_key_1, task_key_2

Batch-Vorgänge ändern nicht die in Preise und Kontingente dokumentierten Kosten für Lese-, Schreib- oder Löschvorgänge. Jeder Schlüssel in einem Batch-Vorgang wird in Rechnung gestellt, unabhängig davon, ob der Schlüssel vorhanden ist oder nicht.

Die Größe der Entitäten in einem Vorgang wirkt sich nicht auf die Kosten für einen Lese-, Schreib- oder Löschvorgang aus. Allerdings wirkt sich die Größe der Entitäten auf die Speicherplatzkosten aus.

Arten und Kennungen

Jede Entität hat eine bestimmte Art, durch die sie aus der Sicht von Abfragen in eine bestimmte Kategorie eingeordnet wird. Beispielsweise könnte eine Aufgabenlistenanwendung die einzelnen zu erledigenden Aufgaben jeweils mit einer Entität der Art Task darstellen.

Alle Artnamen, die mit zwei Unterstrichen (__) beginnen, sind reserviert und dürfen nicht verwendet werden.

Kennungen zuweisen

Neben der Art verfügt jede Entität auch über eine Kennung, die beim Erstellen der Entität zugewiesen wird. Weil sie zum Schlüssel der Entität gehört, ist die Kennung dauerhaft mit der Entität verknüpft und kann nicht geändert werden. Es gibt zwei Möglichkeiten der Zuweisung:

Die Anwendung kann ihren eigenen Schlüsselnamen-String für die Entität angeben.
Firestore im Datastore-Modus kann der Entität automatisch eine ganzzahlige numerische ID zuweisen.

Im folgenden Beispiel wird ein Schlüssel der Art Task mit einem Schlüsselnamen "sampleTask" als Kennung erstellt:

C#

Key key = _db.CreateKeyFactory("Task").CreateKey("sampleTask");

Go

taskKey := datastore.NameKey("Task", "sampletask", nil)

Java

Key taskKey = datastore.newKeyFactory().setKind("Task").newKey("sampleTask");

Node.js

const taskKey = datastore.key(['Task', 'sampleTask']);

PHP

$taskKey = $datastore->key('Task', 'sampleTask');

Python

from google.cloud import datastore

# For help authenticating your client, visit
# https://cloud.google.com/docs/authentication/getting-started
client = datastore.Client()

key = client.key("Task", "sampleTask")

Ruby

# task_name = "sampleTask"
task_key = datastore.key "Task", task_name

Im Datastore-Modus können IDs auch automatisch zugewiesen werden. Der Datastore-Modus generiert eine zufällige Abfolge von nicht verwendeten IDs, die annähernd gleichmäßig verteilt sind. Jede ID kann maximal 16 Dezimalstellen enthalten.

Im folgenden Beispiel wird ein Schlüssel der Art Task ohne einen Schlüsselnamen erstellt. Der vollständige Schlüssel (einschließlich der automatisch zugewiesenen ID) der Entität wird zurückgegeben, wenn eine Entität mit dem unvollständigen Schlüssel im Datastore-Modus gespeichert wird:

C#

Key incompleteKey = _db.CreateKeyFactory("Task").CreateIncompleteKey();
Key key = _db.AllocateId(incompleteKey);

Go

// A complete key is assigned to the entity when it is Put.
taskKey := datastore.IncompleteKey("Task", nil)

Java

KeyFactory keyFactory = datastore.newKeyFactory().setKind("Task");
Key taskKey = datastore.allocateId(keyFactory.newKey());

Node.js

const taskKey = datastore.key('Task');

PHP

$taskKey = $datastore->key('Task');

Python

from google.cloud import datastore

# For help authenticating your client, visit
# https://cloud.google.com/docs/authentication/getting-started
client = datastore.Client()

key = client.key("Task")

Ruby

task_key = datastore.key "Task"

Wenn Sie die Entitäts-IDs für den Nutzer anzeigen möchten und/oder deren Reihenfolge wichtig ist, ist eine manuelle Zuordnung die beste Lösung.

Eigene numerische ID vergeben

Komplexere Anwendungen versuchen gelegentlich, den von ihnen erstellten Entitäten manuell eigene numerische IDs zuzuweisen, anstatt Schlüsselnamenstrings zu verwenden oder numerische IDs automatisch zu generieren. Beachten Sie jedoch, dass eine Datenbank im Datastore-Modus nicht daran gehindert werden kann, eine Ihrer manuell vergebenen numerischen IDs einer anderen Entität zuzuweisen. Derartige Konflikte können nur vermieden werden, indem die Anwendung einen Block von IDs mit der Methode allocateIds() abruft.

Der automatische ID-Generator im Datastore-Modus verfolgt IDs, die mit diesen Methoden zugewiesen wurden. So wird vermieden, dass diese für eine andere Entität wiederverwendet werden, damit Sie solche IDs ohne Konflikt sicher nutzen können. Sie können nicht manuell auswählen, welche Werte von der Methode allocateIds() zurückgegeben werden. Die von allocateIds() zurückgegebenen Werte werden vom Datastore-Modus zugewiesen.

Ancestor-Pfade

Entitäten in einer Datenbank im Datastore-Modus bilden einen hierarchisch strukturierten Bereich ähnlich der Verzeichnisstruktur eines Dateisystems. Wenn Sie eine Entität erstellen, können Sie optional eine weitere Entität als parent angeben. Die neue Entität ist ein parent der übergeordneten Entität. Anders als bei Dateisystemen muss die übergeordnete Entität hier nicht tatsächlich vorhanden sein. Eine Entität ohne übergeordnete Entität wird als Stammentität bezeichnet. Die Verknüpfung zwischen einer Entität und ihrer übergeordneten Entität ist permanent und kann nicht geändert werden, nachdem die Entität erstellt wurde. Im Datastore-Modus wird zwei Entitäten mit derselben übergeordneten Entität oder zwei Stammentitäten (Entitäten ohne übergeordnete Entität) niemals dieselbe numerische ID zugewiesen.

Die übergeordnete Entität einer Entität, die übergeordnete Entität der übergeordneten Entität und so weiter sind deren Ancestor. Ihre untergeordneten Entitäten, die untergeordneten Entitäten der untergeordneten Entitäten und so weiter sind ihre Nachfolger. Die Abfolge der Entitäten ab einer Stammentität, von übergeordneter zu untergeordneter Entität bis zu einer bestimmten Entität bildet den Ancestor-Pfad. Der vollständige Schlüssel, der die Entität identifiziert, besteht aus einer Abfolge von Art/Kennungs-Paaren, die den Ancestor-Pfad angeben und mit dem Paar der Entität selbst enden:

[User:alice, TaskList:default, Task:sampleTask]

Bei einer Stammentität ist der Ancestor-Pfad leer und der Schlüssel besteht ausschließlich aus der eigenen Art und der eigenen Kennung der Entität:

[User:alice]

Ebenen von übergeordneten Entitäten

Es empfiehlt sich, zum Ordnen Ihrer Daten das Prinzip übergeordneter Entitäten zu nutzen. Beispiel: Wenn Ihre Anwendung Task-Entitäten nach TaskList-Entitäten anordnet, erstellen Sie darüber (genau) eine Ebene von übergeordneten Entitäten:

C#

Key rootKey = _db.CreateKeyFactory("TaskList").CreateKey("default");
Key key = new KeyFactory(rootKey, "Task").CreateKey("sampleTask");

Go

parentKey := datastore.NameKey("TaskList", "default", nil)
taskKey := datastore.NameKey("Task", "sampleTask", parentKey)

Java

Key taskKey =
    datastore
        .newKeyFactory()
        .addAncestors(PathElement.of("TaskList", "default"))
        .setKind("Task")
        .newKey("sampleTask");

Node.js

const taskKey = datastore.key([
  'TaskList',
  'default',
  'Task',
  'sampleTask',
]);

PHP

$taskKey = $datastore->key('TaskList', 'default')
    ->pathElement('Task', 'sampleTask');

Python

from google.cloud import datastore

# For help authenticating your client, visit
# https://cloud.google.com/docs/authentication/getting-started
client = datastore.Client()

key = client.key("TaskList", "default", "Task", "sampleTask")
# Alternatively
parent_key = client.key("TaskList", "default")
key = client.key("Task", "sampleTask", parent=parent_key)

Ruby

# task_list_name = "default"
# task_name = "sampleTask"
task_key = datastore.key [["TaskList", task_list_name], ["Task", task_name]]

Wenn Ihre Anwendung Task-Entitäten zuerst nach User-Entitäten und dann nach TaskList-Entitäten anordnet, erstellen Sie mehrere Ebenen von übergeordneten Entitäten:

C#

Key rootKey = _db.CreateKeyFactory("User").CreateKey("Alice");
Key taskListKey = new KeyFactory(rootKey, "TaskList").CreateKey("default");
Key key = new KeyFactory(taskListKey, "Task").CreateKey("sampleTask");

Go

userKey := datastore.NameKey("User", "alice", nil)
parentKey := datastore.NameKey("TaskList", "default", userKey)
taskKey := datastore.NameKey("Task", "sampleTask", parentKey)

Java

KeyFactory keyFactory =
    datastore
        .newKeyFactory()
        .addAncestors(PathElement.of("User", "Alice"), PathElement.of("TaskList", "default"))
        .setKind("Task");
Key taskKey = keyFactory.newKey("sampleTask");

Node.js

const taskKey = datastore.key([
  'User',
  'alice',
  'TaskList',
  'default',
  'Task',
  'sampleTask',
]);

PHP

$taskKey = $datastore->key('User', 'alice')
    ->pathElement('TaskList', 'default')
    ->pathElement('Task', 'sampleTask');

Python

from google.cloud import datastore

# For help authenticating your client, visit
# https://cloud.google.com/docs/authentication/getting-started
client = datastore.Client()

key = client.key("User", "alice", "TaskList", "default", "Task", "sampleTask")

Ruby

# user_name = "alice"
# task_list_name = "default"
# task_name = "sampleTask"
task_key = datastore.key([
                           ["User", user_name],
                           ["TaskList", task_list_name],
                           ["Task", task_name]
                         ])

Wenn Sie eine Entität mit einer übergeordneten Entität erstellen, geben Sie den vollständigen Ancestor-Pfad der übergeordneten Entität an, wie im Beispiel oben dargestellt.

Eine Anwendung, die Nutzerprofile verwaltet, benötigt möglicherweise nur eine einzige Ebene von übergeordneten Entitäten für die Nutzerprofildaten. Beispiel: Erstellen Sie im folgenden Beispiel einen User-Ancestor-Pfad mit genau einer Ebene für Profile-Entitäten:

[User:alice, Profile:public]

Eine Anwendung zur Konferenzraumplanung kann mehrere Ebenen von übergeordneten Entitäten erfordern, beispielsweise einen Building/Floor-Ancestor-Pfad mit mehreren Ebenen für Room-Entitäten:

[Building:C, Floor:1, Room:123]

Entitätengruppen

Eine Entitätengruppe besteht aus einer Stammentität und allen Nachfolgerentitäten. Anwendungen verwenden im Allgemeinen Entitätengruppen zur Anordnung von Daten, die unmittelbar zusammenhängen. Beispiel: Eine Anwendung könnte eine Entitätengruppe zur Speicherung von Daten zu genau einem Produkt oder genau einem Nutzerprofil verwenden.

Attribute 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 mehreren Typen aufweisen, und zwei Entitäten können Werte unterschiedlichen Typs für dasselbe Attribut aufweisen. Ein Attribut kann indexiert oder nicht indexiert sein (Abfragen, die nach einem Attribut p sortieren oder filtern, ignorieren Entitäten, bei denen p nicht indexiert ist).

Hier einige Beispielattribute:

C#

Entity task = new Entity()
{
    Key = _db.CreateKeyFactory("Task").CreateKey("sampleTask"),
    ["category"] = "Personal",
    ["created"] = new DateTime(1999, 01, 01, 0, 0, 0, DateTimeKind.Utc),
    ["done"] = false,
    ["priority"] = 4,
    ["percent_complete"] = 10.0,
    ["description"] = new Value()
    {
        StringValue = "Learn Cloud Datastore",
        ExcludeFromIndexes = true
    },
};

Go

type Task struct {
	Category        string
	Done            bool
	Priority        int
	Description     string `datastore:",noindex"`
	PercentComplete float64
	Created         time.Time
}
task := &Task{
	Category:        "Personal",
	Done:            false,
	Priority:        4,
	Description:     "Learn Cloud Datastore",
	PercentComplete: 10.0,
	Created:         time.Now(),
}

Java

Entity task =
    Entity.newBuilder(taskKey)
        .set("category", "Personal")
        .set("created", Timestamp.now())
        .set("done", false)
        .set("priority", 4)
        .set("percent_complete", 10.0)
        .set(
            "description",
            StringValue.newBuilder("Learn Cloud Datastore").setExcludeFromIndexes(true).build())
        .build();

Node.js

const task = [
  {
    name: 'category',
    value: 'Personal',
  },
  {
    name: 'created',
    value: new Date(),
  },
  {
    name: 'done',
    value: false,
  },
  {
    name: 'priority',
    value: 4,
  },
  {
    name: 'percent_complete',
    value: 10.0,
  },
  {
    name: 'description',
    value: 'Learn Cloud Datastore',
    excludeFromIndexes: true,
  },
];

PHP

$task = $datastore->entity(
    $key,
    [
        'category' => 'Personal',
        'created' => new DateTime(),
        'done' => false,
        'priority' => 4,
        'percent_complete' => 10.0,
        'description' => 'Learn Cloud Datastore'
    ],
    ['excludeFromIndexes' => ['description']]
);

Python

from google.cloud import datastore

# For help authenticating your client, visit
# https://cloud.google.com/docs/authentication/getting-started
client = datastore.Client()

key = client.key("Task")
task = datastore.Entity(key, exclude_from_indexes=("description",))
task.update(
    {
        "category": "Personal",
        "description": "Learn Cloud Datastore",
        "created": datetime.datetime.now(tz=datetime.timezone.utc),
        "done": False,
        "priority": 4,
        "percent_complete": 10.5,
    }
)
client.put(task)

Ruby

task = datastore.entity "Task" do |t|
  t["category"] = "Personal"
  t["created"] = Time.now
  t["done"] = false
  t["priority"] = 4
  t["percent_complete"] = 10.0
  t["description"] = "Learn Cloud Datastore"
  t.exclude_from_indexes! "description", true
end

Array-Attribute

Eine Eigenschaft mit mehr als einem Wert wird als Arrayeigenschaft bezeichnet. Dieses Beispiel enthält zwei Array-Attribute. Das erste wurde tags genannt und hat die Werte fun und programming. Das zweite heißt collaborators und hat die Werte alice und bob.

C#

Entity task = new Entity()
{
    Key = _db.CreateKeyFactory("Task").CreateKey("sampleTask"),
    ["collaborators"] = new ArrayValue() { Values = { "alice", "bob" } },
    ["tags"] = new ArrayValue() { Values = { "fun", "programming" } }
};

Go

type Task struct {
	Tags          []string
	Collaborators []string
}
task := &Task{
	Tags:          []string{"fun", "programming"},
	Collaborators: []string{"alice", "bob"},
}

Java

Entity task =
    Entity.newBuilder(taskKey)
        .set("tags", "fun", "programming")
        .set("collaborators", ListValue.of("alice", "bob"))
        .build();

Node.js

const task = {
  tags: ['fun', 'programming'],
  collaborators: ['alice', 'bob'],
};

PHP

$task = $datastore->entity(
    $key,
    [
        'tags' => ['fun', 'programming'],
        'collaborators' => ['alice', 'bob']
    ]
);

Python

from google.cloud import datastore

# For help authenticating your client, visit
# https://cloud.google.com/docs/authentication/getting-started
client = datastore.Client()

key = client.key("Task")
task = datastore.Entity(key)
task.update({"tags": ["fun", "programming"], "collaborators": ["alice", "bob"]})

Ruby

# task_name = "sampleTask"
task = datastore.entity "Task", task_name do |t|
  t["tags"] = ["fun", "programming"]
  t["collaborators"] = ["alice", "bob"]
end

Hinweis: Array-Attribute können beispielsweise bei Abfragen mit Gleichheitsfiltern nützlich sein. Eine Entität erfüllt die Abfrage, wenn einer der Werte für ein Attribut mit dem im Filter angegebenen Wert übereinstimmt. Weitere Einzelheiten zu Array-Attributen, einschließlich Problemen, die Sie kennen sollten, finden Sie im Hilfethema Abfragen.

Unterstützte Werttypen

Attribute werden als string/value-Zuordnung gespeichert, die die Attributnamen und Werte der Entität enthält. Bei Werten werden die folgenden Typen unterstützt:

Array

REST API
- Feldname: arrayValue
- Typ: ArrayValue-Objekt, das ein Array von JSON-Wertobjekten enthält
- Sie können eine Arrayeigenschaft zuweisen, indem Sie das Feld arrayValue vom Typ ArrayValue verwenden und für das Feld values ein Array von Werten festlegen. Wenn ein Attribut nicht indexiert werden soll, legen Sie das Feld excludeFromIndexes des Wertobjekts des Attributs auf true fest.
RPC API
- Feldname: array_value
- Typ: ArrayValue-Meldung, die eine oder mehrere Value-Meldungen enthält
- Ein Array-Attribut kann mithilfe des Felds array_value vom Typ ArrayValue zugewiesen werden und das Feld values mit mehreren Value-Objekten befüllen. Damit ein Attribut nicht indexiert wird, setzen Sie das Feld exclude_from_indexes von Value auf true.
Sortierfolge: Keine
Hinweise: darf keinen anderen Arraywert enthalten. Die Wertinstanz darf nicht meaning oder exclude_from_indexes festlegen.

Boolesch

REST API
- Feldname: booleanValue
- Typ: true oder false
RPC API
- Feldname: boolean_value
- Typ: bool
Sortierfolge: false<true

Blob

REST API
- Feldname: blobValue
- Typ: String. Muss base64-codiert sein
RPC API
- Feldname: blob_value
- Typ: bytes
Sortierfolge: Bytereihenfolge
Hinweise: Bis zu 1.500 Byte, wenn das Attribut indexiert ist; sonst bis zu 1.048.487 Byte (1 MiB – 89 Byte).

Datum und Uhrzeit

REST API
- Feldname: timestampValue
- Typ: String (RFC 3339-formatiert, mit Millisekunden, z. B. 2013-05-14T00:01:00.234Z)
RPC API
- Feldname: timestamp_value
- Typ: Timestamp
Sortierfolge: Chronologisch
Hinweise:
- Im Datastore-Modus wird bis auf Mikrosekunden genau gespeichert, kleinere Zeiteinheiten werden abgerundet.
- Bei der Rückgabe als Teil einer Projektionsabfrage werden Zeitstempelwerte im Datastore-Modus in ganzzahlige Mikrosekundenwerte umgewandelt.

Eingebettete Entität

REST API
- Feldname: entityValue
- Typ: JSON-Entität
RPC API
- Feldname: entity_value
- Typ: Entity-Meldung
Sortierfolge: Keine
Hinweise: Wenn indexiert, können Sie auf Unterattribute abfragen. Wenn Sie diesen Wert aus der Indexierung ausschließen, werden alle Unterattribute ebenfalls aus der Indexierung ausgeschlossen.

Gleitkommazahl

REST API
- Feldname: doubleValue
- Typ: Zahl
RPC API
- Feldname: double_value
- Typ: double
Sortierfolge: Numerisch
Hinweis: 64-Bit mit doppelter Genauigkeit, IEEE 754

Geografischer Punkt

REST API
- Feldname: geoPointValue
- Typ: JSON-Breitengrad/Längengrad-Paar
RPC API
- Feldname: geo_point_value
- Typ: LatLng-Meldung
Sortierfolge: Nach Breitengrad, dann nach Längengrad

Integer

REST API
- Feldname: integerValue
- Typ: Zahl oder String. Verwenden Sie Strings für Ganzzahlen, die nicht exakt als Zahlen dargestellt werden können.
RPC API
- Feldname: integer_value
- Typ: int64
Sortierfolge: Numerisch

Schlüssel

REST API
- Feldname: keyValue
- Typ: JSON-Datastore-Modusschlüssel
RPC API
- Feldname: key_value
- Typ: Key-Meldung
Sortierfolge: Nach Pfadelementen (Art, Kennung, Art, Kennung...)

Null

REST API
- Feldname: nullValue
- Typ: Null
RPC API
- Feldname: null_value
- Typ: NullValue
Sortierfolge: Keine

Textstring

REST API
- Feldname: stringValue
- Typ: String
RPC API
- Feldname: string_value
- Typ: string
Sortierfolge: UTF-8-codierte Bytefolge
Hinweise: Bis zu 1.500 Byte, wenn das Attribut indexiert ist; sonst bis zu 1.048.487 Byte (1 MiB – 89 Byte).

Werttypsortierung

Enthält eine Abfrage ein Attribut mit Werten gemischter Typen, erzeugt die Datenbank im Datastore-Modus eine deterministische Reihenfolge auf der Grundlage der internen Darstellungen. Die folgende Liste zeigt diese Reihenfolge:

Nullwerte
Festkommazahlen
- Ganzzahlen
- Datums- und Uhrzeitwerte
Boolesche Werte
Bytestrings
Unicode-Strings
Gleitkommazahlen
NaN-Werte
Geografische Punkte
Datastore-Modusschlüssel