Datastore-Metadaten

Firestore im Datastore-Modus bietet Zugriff auf Metadaten mit Informationen über die Entitätengruppen, Namespaces, Entitätsarten und Attribute, die Ihre Anwendung verwendet, sowie die Attributdarstellungen für die einzelnen Attribute. Sie können Metadaten verwenden, um beispielsweise einen benutzerdefinierten Datastore-Viewer für Ihre Anwendung oder für Back-End-Verwaltungsfunktionen zu erstellen.

Das Datastore-Dashboard in der Google Cloud Console stellt auch einige Metadaten zu Ihrer Anwendung bereit. Die hier angezeigten Daten unterscheiden sich jedoch in einigen wichtigen Bereichen von den Daten, die von diesen Funktionen zurückgegeben werden.

Aktualität. Wenn Metadaten mit der API gelesen werden, werden aktuelle Daten abgerufen. Daten im Dashboard werden nur einmal täglich aktualisiert.
Inhalt. Einige Metadaten im Dashboard sind über die APIs nicht verfügbar und umgekehrt.
Geschwindigkeit. Metadatenabrufe und -abfragen werden wie Datenspeicherabrufe und -abfragen abgerechnet. Die Ausführung von Metadatenabfragen, die Informationen zu Namespaces, Arten und Properties abrufen, ist im Allgemeinen langsam. Als Faustregel gehen Sie davon aus, dass eine Metadatenabfrage, die n Entitäten zurückgibt, etwa genauso lange dauert wie n normale Abfragen, die jeweils eine einzelne Entität zurückgeben. Außerdem sind Attribut-Darstellungsabfragen (nicht ausschließlich schlüsselbasierte Attributabfragen) langsamer als ausschließlich schlüsselbasierte Attributabfragen. Metadatenabfragen von Entitätsgruppenmetadaten sind etwas schneller als Abrufe einer regulären Entität.

Metadatenabfragen

Drei besondere Entitätsarten sind speziell für Metadatenabfragen reserviert:

Entität	Beschreibung
`__namespace__`	Dient zum Suchen aller Namespaces in Ihren Anwendungsentitäten.
`__kind__`	Dient zur Abfrage einer bestimmten Art.
`__property__`	Wird zur Abfrage nach einer Property einer Art verwendet.

Diese Arten stehen nicht in Konflikt mit anderen Arten desselben Namens, die möglicherweise bereits in Ihrer Anwendung vorhanden sind. Durch Abfrage dieser besonderen Arten können Sie Entitäten abrufen, die die gewünschten Metadaten enthalten.

Die von Metadatenabfragen zurückgegebenen Entitäten werden basierend auf dem aktuellen Status Ihrer Datenbank dynamisch generiert. Sie können zwar lokale Entitätsobjekte der Arten __namespace__, __kind__ oder __property__ erstellen, aber jeder Versuch, sie in der Datenbank zu speichern, schlägt fehl.

Namespace-Abfragen

Mit einer Namespace-Abfrage können Sie alle Namespaces suchen, die in den Entitäten der Anwendung verwendet werden. So können Sie Aktivitäten, wie administrative Funktionen, über mehrere Namespaces hinweg ausführen.

Namespace-Abfragen geben Entitäten der speziellen Art __namespace__ zurück, deren Schlüsselname der Name eines Namespace ist. Eine Ausnahme bildet der Standard-Namespace, der mit dem leeren String "" angegeben wird. Weil der leere String kein gültiger Schlüsselname ist, wird dieser Namespace stattdessen mit der numerischen ID 1 eingegeben. Bei Abfragen dieses Typs wird die Filterung nur für Bereiche über dem speziellen Pseudoattribut __key__ unterstützt, dessen Wert der Schlüssel der Entität ist. Die Ergebnisse können nach aufsteigendem (nicht jedoch nach absteigendem) __key__-Wert sortiert werden. Weil __namespace__-Entitäten keine Attribute haben, geben sowohl ausschließlich schlüsselbasierte als auch nicht ausschließlich schlüsselbasierte Abfragen dieselben Informationen zurück.

Im folgenden Beispiel wird eine Liste der Namespaces einer Anwendung im Bereich zwischen den Werten zurückgegeben, die den Variablen startNamespace und endNamespace zugewiesen sind:

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.

KeyFactory keyFactory = _db.CreateKeyFactory("__namespace__");
// List all the namespaces between a lower and upper bound.
string lowerBound = _db.NamespaceId.Substring(0,
    _db.NamespaceId.Length - 1);
string upperBound = _db.NamespaceId + "z";
Key startNamespace = keyFactory.CreateKey(lowerBound);
Key endNamespace = keyFactory.CreateKey(upperBound);
Query query = new Query("__namespace__")
{
    Filter = Filter.And(
        Filter.GreaterThan("__key__", startNamespace),
        Filter.LessThan("__key__", endNamespace))
};
var namespaces = new List<string>();
foreach (Entity entity in _db.RunQuery(query).Entities)
{
    namespaces.Add(entity.Key.Path[0].Name);
};

Go


func metadataNamespaces(w io.Writer, projectID string) error {
	// projectID := "my-project"

	ctx := context.Background()
	client, err := datastore.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("datastore.NewClient: %w", err)
	}
	defer client.Close()

	start := datastore.NameKey("__namespace__", "g", nil)
	end := datastore.NameKey("__namespace__", "h", nil)
	query := datastore.NewQuery("__namespace__").
		FilterField("__key__", ">=", start).
		FilterField("__key__", "<", end).
		KeysOnly()
	keys, err := client.GetAll(ctx, query, nil)
	if err != nil {
		return fmt.Errorf("client.GetAll: %w", err)
	}

	fmt.Fprintln(w, "Namespaces:")
	for _, k := range keys {
		fmt.Fprintf(w, "\t%v", k.Name)
	}
	return nil
}

Java

KeyFactory keyFactory = datastore.newKeyFactory().setKind("__namespace__");
Key startNamespace = keyFactory.newKey("g");
Key endNamespace = keyFactory.newKey("h");
Query<Key> query =
    Query.newKeyQueryBuilder()
        .setKind("__namespace__")
        .setFilter(
            CompositeFilter.and(
                PropertyFilter.gt("__key__", startNamespace),
                PropertyFilter.lt("__key__", endNamespace)))
        .build();
List<String> namespaces = new ArrayList<>();
QueryResults<Key> results = datastore.run(query);
while (results.hasNext()) {
  namespaces.add(results.next().getName());
}

Node.js

async function runNamespaceQuery(startNamespace, endNamespace) {
  const startKey = datastore.key(['__namespace__', startNamespace]);
  const endKey = datastore.key(['__namespace__', endNamespace]);

  const query = datastore
    .createQuery('__namespace__')
    .select('__key__')
    .filter(
      and([
        new PropertyFilter('__key__', '>=', startKey),
        new PropertyFilter('__key__', '<', endKey),
      ])
    );

  const [entities] = await datastore.runQuery(query);
  const namespaces = entities.map(entity => entity[datastore.KEY].name);

  console.log('Namespaces:');
  namespaces.forEach(namespace => console.log(namespace));

  return namespaces;
}

PHP

$query = $datastore->query()
    ->kind('__namespace__')
    ->projection(['__key__'])
    ->filter('__key__', '>=', $datastore->key('__namespace__', $start))
    ->filter('__key__', '<', $datastore->key('__namespace__', $end));
$result = $datastore->runQuery($query);
/* @var array<string> $namespaces */
$namespaces = [];
foreach ($result as $namespace) {
    $namespaces[] = $namespace->key()->pathEnd()['name'];
}

Python

from google.cloud import datastore

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

# All namespaces
query = client.query(kind="__namespace__")
query.keys_only()

all_namespaces = [entity.key.id_or_name for entity in query.fetch()]

# Filtered namespaces
start_namespace = client.key("__namespace__", "g")
end_namespace = client.key("__namespace__", "h")
query = client.query(kind="__namespace__")
query.key_filter(start_namespace, ">=")
query.key_filter(end_namespace, "<")

filtered_namespaces = [entity.key.id_or_name for entity in query.fetch()]

Ruby

query = datastore.query("__namespace__")
                 .select("__key__")
                 .where("__key__", ">=", datastore.key("__namespace__", "g"))
                 .where("__key__", "<", datastore.key("__namespace__", "h"))

namespaces = datastore.run(query).map do |entity|
  entity.key.name
end

GQL


SELECT __key__ FROM __namespace__
WHERE __key__ >= KEY(__namespace__, 'namespace-a')
  AND __key__ <  KEY(__namespace__, 'namespace-b')

Artabfragen

Artabfragen geben Entitäten der Art __kind__ zurück, deren Schlüsselname der Name einer Entitätsart ist. Abfragen dieses Typs sind implizit auf den aktuellen Namespace begrenzt und unterstützen die Filterung nur für Bereiche über dem Pseudoattribut __key__. Die Ergebnisse können nach aufsteigendem (nicht jedoch nach absteigendem) __key__-Wert sortiert werden. Weil __kind__-Entitäten keine Attribute haben, geben sowohl ausschließlich schlüsselbasierte als auch nicht ausschließlich schlüsselbasierte Abfragen dieselben Informationen zurück.

Das folgende Beispiel druckt eine Liste der Arten aus, die in einer Anwendung verwendet werden:

C#

Query query = new Query("__kind__");
var kinds = new List<string>();
foreach (Entity entity in _db.RunQuery(query).Entities)
{
    kinds.Add(entity.Key.Path[0].Name);
};

Go

query := datastore.NewQuery("__kind__").KeysOnly()
keys, err := client.GetAll(ctx, query, nil)
if err != nil {
	log.Fatalf("client.GetAll: %v", err)
}

kinds := make([]string, 0, len(keys))
for _, k := range keys {
	kinds = append(kinds, k.Name)
}

Java

Query<Key> query = Query.newKeyQueryBuilder().setKind("__kind__").build();
List<String> kinds = new ArrayList<>();
QueryResults<Key> results = datastore.run(query);
while (results.hasNext()) {
  kinds.add(results.next().getName());
}

Node.js

async function runKindQuery() {
  const query = datastore.createQuery('__kind__').select('__key__');

  const [entities] = await datastore.runQuery(query);
  const kinds = entities.map(entity => entity[datastore.KEY].name);

  console.log('Kinds:');
  kinds.forEach(kind => console.log(kind));

  return kinds;
}

PHP

$query = $datastore->query()
    ->kind('__kind__')
    ->projection(['__key__']);
$result = $datastore->runQuery($query);
/* @var array<string> $kinds */
$kinds = [];
foreach ($result as $kind) {
    $kinds[] = $kind->key()->pathEnd()['name'];
}

Python

from google.cloud import datastore

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

query = client.query(kind="__kind__")
query.keys_only()

kinds = [entity.key.id_or_name for entity in query.fetch()]

Ruby

query = datastore.query("__kind__")
                 .select("__key__")

kinds = datastore.run(query).map do |entity|
  entity.key.name
end

GQL


SELECT __key__ FROM __kind__

Attributabfragen

Attributabfragen geben Entitäten der Art __property__ zurück. Diese kennzeichnen die indexierten Attribute, die mit einer Entitätsart verknüpft sind. Nicht indexierte Attribute werden nicht einbezogen. Die Entität zur Darstellung des Attributs p der Art k wird so erstellt:

Der Entitätsschlüssel hat die Art __property__ und den Schlüsselnamen p.
Der übergeordnete Schlüssel der Entität hat die Art __kind__ und den Schlüsselnamen k.
Das Array-Attribut property_representation der Entität enthält alle Darstellungen des Attributs.

Wenn Ihre Datenbank beispielsweise genau zwei Task-Entitäten mit name- und done-Attributen enthält,

Key: 'Task:1'
name: 'Read some properties'
done: true

Key: 'Task:2'
name: 'Climb'
done: null

werden die beiden folgenden Entitäten von einer __property__-Abfrage zurückgegeben:

Key: '__kind__:Task/__property__:name'
property_representation: [ 'STRING' ]

Key: '__kind__:Task/__property__:done'
property_representation: [ 'BOOLEAN', 'NULL' ]

Attributabfragen sind implizit auf den aktuellen Namespace begrenzt und unterstützen eine begrenzte Filterung mit einem Ancestor oder einem Bereich über dem Pseudoattribut __key__.

Eine keys-only Attributabfrage ist effizienter als eine nicht ausschließlich schlüsselbasierte Abfrage, weil sie die Darstellungen des Attributs nicht erfassen muss. Das folgende Beispiel ruft die Namen aller Entitätsarten einer Anwendung und die mit jeder Art verknüpften Properties ab:

C#

Query query = new Query("__property__");
var properties = new List<string>();
foreach (Entity entity in _db.RunQuery(query).Entities)
{
    string kind = entity.Key.Path[0].Name;
    string property = entity.Key.Path[1].Name;
    if (kind == "Task")
        properties.Add(property);
};

Go

query := datastore.NewQuery("__property__").KeysOnly()
keys, err := client.GetAll(ctx, query, nil)
if err != nil {
	log.Fatalf("client.GetAll: %v", err)
}

props := make(map[string][]string) // Map from kind to slice of properties.
for _, k := range keys {
	prop := k.Name
	kind := k.Parent.Name
	props[kind] = append(props[kind], prop)
}

Java

Query<Key> query = Query.newKeyQueryBuilder().setKind("__property__").build();
QueryResults<Key> keys = datastore.run(query);
Map<String, Collection<String>> propertiesByKind = new HashMap<>();
while (keys.hasNext()) {
  Key key = keys.next();
  String kind = key.getParent().getName();
  String propertyName = key.getName();
  Collection<String> properties = propertiesByKind.get(kind);
  if (properties == null) {
    properties = new HashSet<>();
    propertiesByKind.put(kind, properties);
  }
  properties.add(propertyName);
}

Node.js

async function runPropertyQuery() {
  const query = datastore.createQuery('__property__').select('__key__');
  const [entities] = await datastore.runQuery(query);
  // @TODO convert below object to map
  const propertiesByKind = {};

  entities.forEach(entity => {
    const key = entity[datastore.KEY];
    const kind = key.path[1];
    const property = key.path[3];

    propertiesByKind[kind] = propertiesByKind[kind] || [];
    propertiesByKind[kind].push(property);
  });

  console.log('Properties by Kind:');
  for (const key in propertiesByKind) {
    console.log(key, propertiesByKind[key]);
  }

  return propertiesByKind;
}

PHP

$query = $datastore->query()
    ->kind('__property__')
    ->projection(['__key__']);
$result = $datastore->runQuery($query);
/* @var array<string> $properties */
$properties = [];
/* @var Entity $entity */
foreach ($result as $entity) {
    $kind = $entity->key()->path()[0]['name'];
    $propertyName = $entity->key()->path()[1]['name'];
    $properties[] = "$kind.$propertyName";
}

Python

from google.cloud import datastore

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

query = client.query(kind="__property__")
query.keys_only()

properties_by_kind = defaultdict(list)

for entity in query.fetch():
    kind = entity.key.parent.name
    property_ = entity.key.name

    properties_by_kind[kind].append(property_)

Ruby

query = datastore.query("__property__")
                 .select("__key__")

entities = datastore.run query
properties_by_kind = entities.each_with_object({}) do |entity, memo|
  kind = entity.key.parent.name
  prop = entity.key.name
  memo[kind] ||= []
  memo[kind] << prop
end

GQL


SELECT __key__ FROM __property__

Attributabfragen: Attributdarstellungen

Nicht ausschließlich schlüsselbasierte Attributabfragen, die als Attributdarstellungsabfragen bezeichnet werden, geben zusätzliche Informationen zu den Werttypen zurück, die für jedes Attribut verwendet werden. Das Attribut property_representation in der Entität, die das Attribut p der Art k darstellt, ist ein Array, das alle Darstellungen des Werts von p in einer Entität der Art k enthält.

Jeder Wert hat die folgende Darstellung (beachten Sie, dass für einige Werttypen dieselbe Darstellung verwendet wird):

Werttyp	Darstellung
Integer	`INT64`
Gleitkommazahl	`DOUBLE`
Boolesch	`BOOLEAN`
Textstring	`STRING`
Bytestring	`STRING`
Datum und Uhrzeit	`INT64`
Datenspeicherschlüssel	`REFERENCE`
Eingebettete Entität	`STRING`
Array	Darstellung der Elemente des Arrays
Geografischer Punkt	`POINT`
Null	`NULL`

Im folgenden Beispiel werden alle Darstellungen von Attributen der Art Task mit einer Ancestor-Attribut-Abfrage gesucht:

C#

Key key = _db.CreateKeyFactory("__kind__").CreateKey("Task");
Query query = new Query("__property__")
{
    Filter = Filter.HasAncestor(key)
};
var properties = new List<string>();
foreach (Entity entity in _db.RunQuery(query).Entities)
{
    string kind = entity.Key.Path[0].Name;
    string property = entity.Key.Path[1].Name;
    var representations = entity["property_representation"]
        .ArrayValue.Values.Select(x => x.StringValue)
        .OrderBy(x => x);
    properties.Add($"{property}:" +
        string.Join(",", representations));
};

Go

kindKey := datastore.NameKey("__kind__", "Task", nil)
query := datastore.NewQuery("__property__").Ancestor(kindKey)

type Prop struct {
	Repr []string `datastore:"property_representation"`
}

var props []Prop
keys, err := client.GetAll(ctx, query, &props)

Java

Key key = datastore.newKeyFactory().setKind("__kind__").newKey("Task");
Query<Entity> query =
    Query.newEntityQueryBuilder()
        .setKind("__property__")
        .setFilter(PropertyFilter.hasAncestor(key))
        .build();
QueryResults<Entity> results = datastore.run(query);
Map<String, Collection<String>> representationsByProperty = new HashMap<>();
while (results.hasNext()) {
  Entity result = results.next();
  String propertyName = result.getKey().getName();
  List<StringValue> representations = result.getList("property_representation");
  Collection<String> currentRepresentations = representationsByProperty.get(propertyName);
  if (currentRepresentations == null) {
    currentRepresentations = new HashSet<>();
    representationsByProperty.put(propertyName, currentRepresentations);
  }
  for (StringValue value : representations) {
    currentRepresentations.add(value.get());
  }
}

Node.js

async function runPropertyByKindQuery() {
  const ancestorKey = datastore.key(['__kind__', 'Account']);

  const query = datastore
    .createQuery('__property__')
    .hasAncestor(ancestorKey);
  const [entities] = await datastore.runQuery(query);

  const representationsByProperty = {};

  entities.forEach(entity => {
    const key = entity[datastore.KEY];
    const propertyName = key.name;
    const propertyType = entity.property_representation;

    representationsByProperty[propertyName] = propertyType;
  });

  console.log('Task property representations:');
  for (const key in representationsByProperty) {
    console.log(key, representationsByProperty[key]);
  }

  return representationsByProperty;
}

PHP

$ancestorKey = $datastore->key('__kind__', 'Task');
$query = $datastore->query()
    ->kind('__property__')
    ->hasAncestor($ancestorKey);
$result = $datastore->runQuery($query);
/* @var array<string,string> $properties */
$properties = [];
/* @var Entity $entity */
foreach ($result as $entity) {
    $propertyName = $entity->key()->path()[1]['name'];
    $propertyType = $entity['property_representation'];
    $properties[$propertyName] = $propertyType;
}
// Example values of $properties: ['description' => ['STRING']]

Python

from google.cloud import datastore

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

ancestor = client.key("__kind__", "Task")
query = client.query(kind="__property__", ancestor=ancestor)

representations_by_property = {}

for entity in query.fetch():
    property_name = entity.key.name
    property_types = entity["property_representation"]

    representations_by_property[property_name] = property_types

Ruby

ancestor_key = datastore.key "__kind__", "Task"
query = datastore.query("__property__")
                 .ancestor(ancestor_key)

entities = datastore.run query
representations = entities.each_with_object({}) do |entity, memo|
  property_name = entity.key.name
  property_types = entity["property_representation"]
  memo[property_name] = property_types
end

GQL


SELECT * FROM __property__
WHERE __key__ HAS ANCESTOR KEY(__kind__, 'Task')

Attributabfragen: Filterung

Attributabfragen unterstützen die Ancestor-Filterung nach einem __kind__- oder __property__-Schlüssel, um die Abfrageergebnisse auf eine einzige Art oder ein einziges Attribut zu begrenzen, wie in der obigen Attributabfrage dargestellt.

Attributabfragen können auch mit einem Bereich über das Pseudoattribut __key__ gefiltert werden, wobei die Schlüssel __kind__- oder __property__-Entitäten kennzeichnen. Die Ergebnisse können nach aufsteigendem (nicht jedoch nach absteigendem) __key__-Wert sortiert werden. Die Filterung wird auf Art/Attribut-Paare angewendet, die zuerst nach Art und dann nach Attribut sortiert sind. Beispiel: Es sind Entitäten mit folgenden Attributen vorhanden:

Art Task mit Attributen
- created
- priority
- tags
Art TaskList mit Attributen
- created

Die folgende ausschließlich schlüsselbasierte Attributabfrage:

C#

Key key = _db.CreateKeyFactory("__kind__").CreateKey("Task");
Key startKey = new KeyFactory(key, "__property__")
    .CreateKey("priority");
Query query = new Query("__property__")
{
    Filter = Filter.GreaterThanOrEqual("__key__", startKey)
};
var properties = new List<string>();
foreach (Entity entity in _db.RunQuery(query).Entities)
{
    string kind = entity.Key.Path[0].Name;
    string property = entity.Key.Path[1].Name;
    properties.Add($"{kind}.{property}");
};

Go

Nicht zutreffend

Java

Key startKey =
    datastore
        .newKeyFactory()
        .setKind("__property__")
        .addAncestors(PathElement.of("__kind__", "Task"))
        .newKey("priority");
Query<Key> query =
    Query.newKeyQueryBuilder()
        .setKind("__property__")
        .setFilter(PropertyFilter.ge("__key__", startKey))
        .build();
Map<String, Collection<String>> propertiesByKind = new HashMap<>();
QueryResults<Key> keys = datastore.run(query);
while (keys.hasNext()) {
  Key key = keys.next();
  String kind = key.getParent().getName();
  String propertyName = key.getName();
  Collection<String> properties = propertiesByKind.get(kind);
  if (properties == null) {
    properties = new HashSet<String>();
    propertiesByKind.put(kind, properties);
  }
  properties.add(propertyName);
}

Node.js

Nicht zutreffend

PHP

$ancestorKey = $datastore->key('__kind__', 'Task');
$startKey = $datastore->key('__property__', 'priority')
    ->ancestorKey($ancestorKey);
$query = $datastore->query()
    ->kind('__property__')
    ->filter('__key__', '>=', $startKey);
$result = $datastore->runQuery($query);
/* @var array<string> $properties */
$properties = [];
/* @var Entity $entity */
foreach ($result as $entity) {
    $kind = $entity->key()->path()[0]['name'];
    $propertyName = $entity->key()->path()[1]['name'];
    $properties[] = "$kind.$propertyName";
}

Python

Nicht zutreffend

Ruby

start_key = datastore.key [["__kind__", "Task"], ["__property__", "priority"]]
query = datastore.query("__property__")
                 .select("__key__")
                 .where("__key__", ">=", start_key)

entities = datastore.run query
properties_by_kind = entities.each_with_object({}) do |entity, memo|
  kind = entity.key.parent.name
  prop = entity.key.name
  memo[kind] ||= []
  memo[kind] << prop
end

GQL


SELECT __key__ FROM __property__
WHERE __key__ >= KEY(__kind__, 'Task', __property__, 'priority')

erfasst die folgenden Paare von Art-/Attributnamen:

Task, priority
Task, tags
TaskList, created

Die Ergebnisse schließen Attribute der Arten Task und TaskList ein, enthalten das Attribut created der Art Task aber nicht, weil es außerhalb des für die Abfrage angegebenen Bereichs liegt.