Metadatos de Datastore

Firestore en modo Datastore proporciona acceso a metadatos que incluyen información sobre grupos de entidades, espacios de nombres, categorías de entidades, propiedades y representaciones de propiedades para cada propiedad. Por ejemplo, puedes usar metadatos a fin de compilar un visualizador de almacén de datos personalizado para tu aplicación o realizar funciones administrativas de backend.

El panel de Datastore en la consola de Google Cloud también proporciona algunos metadatos sobre la aplicación, pero los datos que se muestran allí difieren de los que muestran estas funciones en algunos aspectos importantes.

Actualidad: Cuando se leen los metadatos con la API, se obtienen los datos actuales, mientras que los datos del panel se actualizan solo una vez por día.
Contenido: Algunos metadatos del panel no están disponibles mediante las API y viceversa.
Velocidad: La consulta y la obtención de metadatos se facturan de la misma forma que las del almacén de datos. Las consultas de metadatos que buscan información en espacios de nombres, tipos y propiedades son generalmente de ejecución lenta. Como regla general, puedes esperar que una consulta de metadatos que muestra N entidades demore el mismo tiempo que N consultas ordinarias que muestran una sola entidad cada una. Además, las consultas de representaciones de propiedades (consultas de propiedades no solo de claves) son más lentas que las consultas de propiedades solo de claves. La obtención de metadatos de grupos de entidad es más rápida que la de una entidad normal.

Consultas de metadatos

Hay tres tipos de entidades especiales reservados para las consultas de metadatos:

Entidad	Descripción
`__namespace__`	Se usa para encontrar todos los espacios de nombres empleados en las entidades de tu aplicación.
`__kind__`	Se usa para consultar un tipo específico.
`__property__`	Se usa para consultar según una propiedad de un tipo.

Estos tipos no entrarán en conflicto con otros que tengan el mismo nombre y que ya existan en tu aplicación. Si consultas estas categorías especiales, puedes obtener entidades que contengan los metadatos deseados.

Las entidades que muestran las consultas de metadatos se generan de forma dinámica, en función del estado actual de tu base de datos. Aunque puedes crear objetos de entidad local de las categorías __namespace__, __kind__ o __property__, cualquier intento de almacenarlos en la base de datos fallará.

Consultas de espacio de nombres

Puedes usar una consulta de espacio de nombres para encontrar todos los espacios de nombres que se usan en las entidades de la aplicación. Esto te permite realizar actividades como funciones administrativas en varios espacios de nombres.

Las consultas de espacio de nombres muestran entidades de la categoría especial __namespace__ cuyo nombre de clave es el nombre de un espacio de nombres. (Una excepción a esto es el espacio de nombres predeterminado que designa la string vacía "": como la string vacía no es un nombre de clave válido, este espacio de nombres recibe una clave con el ID numérico 1). Las consultas de este tipo admiten el filtrado solo para rangos sobre la seudopropiedad especial __key__, cuyo valor es la clave de la entidad. Los resultados se pueden ordenar por valor ascendente (pero no descendente) de __key__. Debido a que las entidades __namespace__ no tienen propiedades, las consultas solo de clave y no solo de clave muestran la misma información.

En el siguiente ejemplo, se muestra una lista de los espacios de nombres de una aplicación en el rango entre los valores asignados a las variables startNamespace y endNamespace:

C#

Para obtener información sobre cómo instalar y usar la biblioteca cliente de Cloud Datastore, consulta Bibliotecas cliente de Cloud Datastore. Si deseas obtener más información, consulta la documentación de referencia de la API de C# de Cloud Datastore.

Para autenticarte en Cloud Datastore, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo 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')

Consultas de tipos

Las consultas de categorías muestran entidades de categoría __kind__ cuyo nombre de clave es el nombre de una categoría de entidad. Las consultas de este tipo están restringidas de forma implícita al espacio de nombres actual y admiten el filtrado solo para rangos sobre la seudopropiedad __key__. Los resultados se pueden ordenar por valor ascendente (pero no descendente) de __key__. Debido a que las entidades __kind__ no tienen propiedades, las consultas solo de clave y no solo de clave muestran la misma información.

En el siguiente ejemplo, se muestra una lista de las categorías usadas en una aplicación:

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__

Consultas de propiedades

Las consultas de propiedades muestran entidades de categoría __property__ que denotan las propiedades indexadas asociadas con una categoría de entidad. (No se incluyen las propiedades no indexadas). La entidad que representa la propiedad p de la categoría k está compuesta por los siguientes elementos:

La clave de la entidad tiene la categoría __property__ y el nombre de clave p.
La clave principal de la entidad tiene la categoría __kind__ y el nombre de clave k.
La propiedad de arreglo property_representation de la entidad contiene todas las representaciones de la propiedad.

Por ejemplo, supongamos que tu base de datos contiene exactamente dos entidades Task con propiedades name y done:

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

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

entonces las dos entidades mostradas por una consulta __property__ serán las siguientes:

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

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

Las consultas de propiedades están restringidas de forma implícita al espacio de nombres actual y admiten un filtrado limitado con una principal o un rango sobre la seudopropiedad __key__.

Una consulta de propiedades keys-only es más eficiente que una consulta que no sea solo de claves, ya que no necesita recopilar las representaciones de la propiedad. El siguiente ejemplo muestra los nombres de todos los tipos de entidades de una aplicación y las propiedades asociadas a cada uno:

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__

Consultas de propiedades: representaciones de propiedades

Las consultas de propiedades que no son solo de claves, conocidas como consultas de representaciones de propiedades, muestran información adicional sobre los tipos de valores que se usan para cada propiedad. La propiedad property_representation en la entidad que representa la propiedad p de la categoría k es un arreglo que contiene todas las representaciones del valor de p en cualquier entidad de la categoría k.

Cada valor tiene la siguiente representación (algunos tipos de valores comparten representaciones):

Tipo de valor	Representación
Integer	`INT64`
Número de coma flotante	`DOUBLE`
Booleano	`BOOLEAN`
String de texto	`STRING`
String de bytes	`STRING`
Fecha y hora	`INT64`
Clave de Datastore	`REFERENCE`
Entidad incorporada	`STRING`
Arreglo	representación de los elementos del arreglo
Punto geográfico	`POINT`
Nulo	`NULL`

En el siguiente ejemplo, se encuentran todas las representaciones de propiedades de la categoría Task con una consulta de propiedad principal:

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

Consultas de propiedades: filtrado

Las consultas de propiedad admiten el filtrado de principales en una clave __kind__ o __property__ para limitar los resultados de la consulta a una sola categoría o propiedad, como se ve en la consulta de representación de propiedades anterior.

Las consultas de propiedades también se pueden filtrar con un rango sobre la seudopropiedad __key__, en la que las claves denotan entidades __kind__ o __property__. Los resultados se pueden ordenar por valor ascendente (pero no descendente) de __key__. Se aplica el filtro a los pares categoría-propiedad, ordenados primero por categoría y después por propiedad. Por ejemplo, imagina que tienes entidades con las siguientes propiedades:

categoría Task con propiedades
- created
- priority
- tags
categoría TaskList con propiedades
- created

La siguiente consulta de propiedades solo de claves:

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

No aplicable

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

No aplicable

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

No aplicable

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

Recopilará los siguientes pares de nombre de propiedad y categoría:

Task, priority
Task, tags
TaskList, created

Observa que los resultados incluyen propiedades de las categorías Task y TaskList, pero no incluyen la propiedad created de la categoría Task, porque se encuentra fuera del rango especificado para la consulta.