Métadonnées Datastore

Firestore en mode Datastore offre un accès à des métadonnées qui incluent des informations sur les groupes d'entités, les espaces de noms, les genres d'entités, les propriétés et les représentations de chaque propriété. Les métadonnées vous permettent, par exemple, de créer un lecteur Datastore personnalisé pour votre application ou pour des fonctions d'administration de backend.

Le tableau de bord Datastore de la console Google Cloud fournit également des métadonnées sur votre application, mais les données affichées diffèrent nettement à certains égards de celles renvoyées par ces fonctions.

Actualisation. La lecture des métadonnées à l'aide de l'API permet d'obtenir les données actuelles, tandis que les données du tableau de bord ne sont actualisées qu'une fois par jour.
Contenus. Certaines métadonnées du tableau de bord ne sont pas disponibles via les API, et vice versa.
Rapidité. Les opérations d'obtention et de requête de métadonnées sont facturées de la même manière que celles appliquées à un datastore. L'exécution de requêtes de métadonnées qui extraient des informations sur les espaces de noms, les genres et les propriétés est habituellement lente. En règle générale, partez du principe qu'une requête de métadonnées renvoyant N entités va prendre à peu près le même temps que N requêtes ordinaires renvoyant chacune une seule entité. De plus, les requêtes de représentation de propriété (requêtes de propriété ne contenant pas que des clés) sont plus lentes que les requêtes de propriété ne contenant que des clés. L'obtention des métadonnées d'un groupe d'entités est légèrement plus rapide que pour les métadonnées d'une entité standard.

Requêtes de métadonnées

Trois genres d'entités spéciaux sont réservés aux requêtes de métadonnées :

Entité	Description
`__namespace__`	Permet de rechercher tous les espaces de noms employés dans les entités de l'application.
`__kind__`	Permet d'interroger un genre spécifique.
`__property__`	Permet d'exécuter une requête en fonction d'une propriété d'un genre.

Ces genres ne seront pas en conflit avec d'autres du même nom pouvant déjà exister dans l'application. En exécutant des requêtes sur ces genres spéciaux, vous pouvez récupérer des entités contenant les métadonnées souhaitées.

Les entités renvoyées par les requêtes de métadonnées sont générées de manière dynamique, en fonction de l'état actuel de votre base de données. Vous pouvez créer des objets d'entité locaux du genre __namespace__, __kind__ ou __property__, mais toute tentative de stockage de ces objets dans la base de données échouera.

Requêtes d'espace de noms

Vous pouvez utiliser une requête d'espace de noms pour rechercher tous les espaces de noms employés dans les entités de l'application. Cela vous permet par exemple d'effectuer des tâches d'administration sur plusieurs espaces de noms.

Les requêtes d'espace de noms renvoient des entités du genre spécial __namespace__, dont le nom de clé correspond à celui d'un espace de noms. (L'espace de noms par défaut désigné par la chaîne vide "" constitue une exception : comme la chaîne vide n'est pas un nom de clé valide, cet espace de noms est associé à l'ID numérique 1 à la place.) Les requêtes de ce type n'acceptent le filtrage que pour les plages définies pour la pseudo-propriété spéciale __key__, dont la valeur est la clé de l'entité. Les résultats peuvent être triés par ordre croissant (mais pas décroissant) de valeur __key__. Comme les entités __namespace__ n'ont pas de propriétés, les requêtes renvoient les mêmes informations, qu'elles contiennent exclusivement des clés ou non.

L'exemple suivant renvoie la liste des espaces de noms d'une application compris entre les valeurs attribuées aux variables startNamespace et endNamespace :

C#

Pour savoir comment installer et utiliser la bibliothèque cliente pour Cloud Datastore, consultez la page Bibliothèques clientes Cloud Datastore. Pour plus d'informations, consultez la documentation de référence de l'API Cloud Datastore C#.

Pour vous authentifier auprès de Cloud Datastore, configurez les Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.

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')

Requêtes de genre

Les requêtes de genre renvoient des entités du genre __kind__, dont le nom de clé correspond à celui d'un genre d'entité. Les requêtes de ce type sont implicitement restreintes à l'espace de noms actuel et n'acceptent le filtrage que pour les plages définies pour la pseudo-propriété __key__. Les résultats peuvent être triés par ordre croissant (mais pas décroissant) de valeur __key__. Comme les entités __kind__ n'ont pas de propriétés, les requêtes renvoient les mêmes informations, qu'elles contiennent exclusivement des clés ou non.

L'exemple suivant affiche la liste des genres employés dans une application :

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__

Requêtes de propriété

Les requêtes de propriété renvoient des entités du genre __property__ indiquant les propriétés indexées associées à un genre d'entité. (Les propriétés non indexées ne sont pas incluses.) L'entité représentant la propriété p du genre k est conçue comme suit :

La clé de l'entité est du genre __property__ et porte le nom p.
La clé parente de l'entité est du genre __kind__ et porte le nom k.
La propriété de tableau property_representation de l'entité contient toutes les représentations de la propriété.

Par exemple, si votre base de données contient exactement deux entités Task avec les propriétés name et done :

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

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

alors les deux entités renvoyées par une requête __property__ sont les suivantes :

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

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

Les requêtes de propriété sont implicitement restreintes à l'espace de noms actuel et n'acceptent le filtrage partiel qu'avec un ancêtre ou une plage définie pour la pseudo-propriété __key__.

Une requête de propriété keys-only est plus efficace qu'une requête ne contenant pas que des clés, car elle n'a pas besoin de collecter les représentations de la propriété. L'exemple suivant récupère les noms de tous les genres d'entités d'une application et les propriétés associées à chacun d'eux :

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__

Requêtes de propriété : représentations de propriété

Les requêtes de propriété ne contenant pas que des clés, appelées requêtes de représentation de propriété, renvoient des informations supplémentaires sur les types de valeurs employés pour chaque propriété. La propriété property_representation de l'entité qui représente la propriété p du genre k est un tableau contenant toutes les représentations de la valeur de p dans toute entité du genre k.

Chaque valeur a la représentation suivante (sachez que certains types de valeurs partagent des représentations) :

Type de valeur	Représentation
Integer	`INT64`
Nombre à virgule flottante	`DOUBLE`
Booléen	`BOOLEAN`
Chaîne de texte	`STRING`
Chaîne d'octets	`STRING`
Date et heure	`INT64`
Clé Datastore	`REFERENCE`
Entité intégrée	`STRING`
Tableau	représentation des éléments du tableau
Point géographique	`POINT`
Null	`NULL`

L'exemple suivant trouve toutes les représentations des propriétés du genre Task à l'aide d'une requête de propriété d'ancêtre :

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')

Requêtes de propriété : filtrage

Les requêtes de propriété acceptent le filtrage en fonction des ancêtres sur une clé __kind__ ou __property__, afin de limiter les résultats à un seul genre ou à une seule propriété, comme indiqué dans la requête de représentation de propriété ci-dessus.

Les requêtes de propriété peuvent également être filtrées en fonction d'une plage définie pour la pseudo-propriété __key__, où les clés désignent des entités __kind__ ou __property__. Les résultats peuvent être triés par ordre croissant (mais pas décroissant) de valeur __key__. Le filtrage est appliqué aux paires genre-propriété. Celles-ci sont triées d'abord par genre, puis par propriété. Par exemple, supposons que vous ayez des entités dotées de ces propriétés :

genre Task avec propriétés
- created
- priority
- tags
genre TaskList avec propriétés
- created

La requête de propriété ne contenant que des clés serait la suivante :

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

Non applicable

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

Non applicable

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

Non applicable

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')

Cette requête va donc collecter les paires genre-propriété suivantes :

Task, priority
Task, tags
TaskList, created

Notez que les résultats incluent des propriétés des genres Task et TaskList, mais pas la propriété created du genre Task, car celle-ci n'est pas comprise dans la plage spécifiée pour la requête.