Esta página foi traduzida pela API Cloud Translation.

Metadados do armazenamento de dados

O Firestore no modo Datastore fornece acesso a metadados que incluem informações sobre grupos de entidades, espaços de nomes, tipos de entidades, propriedades e representações de propriedades para cada propriedade. Pode usar metadados, por exemplo, para criar um visualizador de repositório de dados personalizado para a sua aplicação ou para funções administrativas de back-end.

O painel de controlo do Datastore na consola também fornece alguns metadados sobre a sua aplicação, mas os dados apresentados aí diferem em alguns aspetos importantes dos devolvidos por estas funções. Google Cloud

Atualidade. A leitura de metadados através da API obtém dados atuais, enquanto os dados no painel de controlo são atualizados apenas uma vez por dia.
Conteúdo. Alguns metadados no painel de controlo não estão disponíveis através das APIs. O inverso também é verdadeiro.
Velocidade. As obtenções e as consultas de metadados são faturadas da mesma forma que as obtenções e as consultas da base de dados. As consultas de metadados que obtêm informações sobre espaços de nomes, tipos e propriedades são, geralmente, lentas de executar. Como regra geral, espere que uma consulta de metadados que devolve N entidades demore aproximadamente o mesmo tempo que N consultas comuns, cada uma das quais devolve uma única entidade. Além disso, as consultas de representação de propriedades (consultas de propriedades que não são apenas chaves) são mais lentas do que as consultas de propriedades que são apenas chaves. As obtenções de metadados de metadados de grupos de entidades são ligeiramente mais rápidas do que a obtenção de uma entidade normal.

Consultas de metadados

Existem três tipos de entidades especiais reservados para consultas de metadados:

Entidade	Descrição
`__namespace__`	Usado para encontrar todos os espaços de nomes usados nas entidades da sua aplicação.
`__kind__`	Usado para consultar um tipo específico.
`__property__`	Usado para consultar por uma propriedade de um tipo.

Estes tipos não entram em conflito com outros do mesmo nome que possam já existir na sua aplicação. Ao consultar estes tipos especiais, pode obter entidades que contêm os metadados pretendidos.

As entidades devolvidas pelas consultas de metadados são geradas dinamicamente com base no estado atual da sua base de dados. Embora possa criar objetos de entidades locais dos tipos __namespace__, __kind__ ou __property__, qualquer tentativa de os armazenar na base de dados falha.

Consultas de espaços de nomes

Pode usar uma consulta de espaço de nomes para encontrar todos os espaços de nomes usados nas entidades da aplicação. Isto permite-lhe realizar atividades como funções administrativas em vários espaços de nomes.

As consultas de espaço de nomes devolvem entidades do tipo especial __namespace__ cuja chave é o nome de um espaço de nomes. (Uma exceção é o espaço de nomes predefinido designado pela string vazia "": uma vez que a string vazia não é um nome de chave válido, este espaço de nomes é indexado com o ID numérico 1.) As consultas deste tipo suportam a filtragem apenas para intervalos sobre a pseudopropriedade especial __key__, cujo valor é a chave da entidade. Os resultados podem ser ordenados por valor __key__ ascendente (mas não descendente). Uma vez que as entidades __namespace__ não têm propriedades, as consultas apenas com chaves e sem chaves devolvem as mesmas informações.

O exemplo seguinte devolve uma lista dos espaços de nomes de uma aplicação no intervalo entre os valores atribuídos às variáveis startNamespace e endNamespace:

C#

Para saber como instalar e usar a biblioteca cliente do Cloud Datastore, consulte as bibliotecas cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API C# Cloud Datastore.

Para se autenticar no Cloud Datastore, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para um ambiente de desenvolvimento 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 tipo

As consultas de tipo devolvem entidades do tipo __kind__ cujo nome da chave é o nome de um tipo de entidade. As consultas deste tipo estão implicitamente restritas ao espaço de nomes atual e suportam a filtragem apenas para intervalos sobre a pseudopropriedade __key__. Os resultados podem ser ordenados pelo valor de __key__ por ordem ascendente (mas não descendente). Uma vez que as entidades __kind__ não têm propriedades, as consultas apenas com chaves e sem chaves devolvem as mesmas informações.

O exemplo seguinte imprime uma lista dos tipos usados numa aplicação:

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 propriedades

As consultas de propriedades devolvem entidades do tipo __property__ que denotam as propriedades indexadas associadas a um tipo de entidade. (As propriedades não indexadas não estão incluídas.) A entidade que representa a propriedade p do tipo k é criada da seguinte forma:

A chave da entidade tem o tipo __property__ e o nome da chave p.
A chave principal da entidade tem o tipo __kind__ e o nome da chave k.
A propriedade da matriz property_representation da entidade contém todas as representações da propriedade.

Por exemplo, se a sua base de dados contiver exatamente duas entidades Task com as propriedades name e done:

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

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

As duas entidades devolvidas por uma consulta __property__ são:

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

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

As consultas de propriedades estão implicitamente restritas ao espaço de nomes atual e suportam a filtragem limitada com um antepassado ou um intervalo sobre a pseudopropriedade __key__.

Uma consulta de propriedade apenas com chaves é mais eficiente do que uma consulta sem ser apenas com chaves, uma vez que não precisa de recolher as representações da propriedade. O exemplo seguinte obtém os nomes de todos os tipos de entidades de uma aplicação e as propriedades associadas a cada um:

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

from collections import defaultdict

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 propriedades: representações de propriedades

As consultas de propriedades que não são apenas de chaves, conhecidas como consultas de representação de propriedades, devolvem informações adicionais sobre os tipos de valores usados para cada propriedade. A propriedade property_representation na entidade que representa a propriedade p de tipo k é uma matriz que contém todas as representações do valor de p em qualquer entidade de tipo k.

Cada valor tem a representação seguinte (tenha em atenção que alguns tipos de valores partilham representações):

Tipo de valor	Representação
Número inteiro	`INT64`
Número de vírgula flutuante	`DOUBLE`
Booleano	`BOOLEAN`
String de texto	`STRING`
String de bytes	`STRING`
Data e hora	`INT64`
Chave do armazenamento de dados	`REFERENCE`
Entidade incorporada	`STRING`
Matriz	Representação dos elementos da matriz
Ponto geográfico	`POINT`
Nulo	`NULL`

O exemplo seguinte encontra todas as representações de propriedades do tipo Task, usando uma consulta de propriedade 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 propriedades: filtragem

As consultas de propriedades suportam a filtragem de antecessores numa chave __kind__ ou __property__, para limitar os resultados da consulta a um único tipo ou propriedade, conforme visto na consulta de representação de propriedade acima.

As consultas de propriedades também podem ser filtradas com um intervalo sobre a pseudopropriedade __key__, em que as chaves denotam entidades __kind__ ou __property__. Os resultados podem ser ordenados por ordem ascendente (mas não descendente) do valor de __key__. A filtragem é aplicada a pares de tipo-propriedade, ordenados primeiro por tipo e, em segundo lugar, por propriedade. Por exemplo, suponha que tem entidades com as seguintes propriedades:

kind Task com propriedades
- created
- priority
- tags
kind TaskList com propriedades
- created

A seguinte consulta de propriedade apenas com chaves:

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

Não aplicável

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

Não aplicável

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

Não aplicável

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

Recolhe os seguintes pares de tipo e nome da propriedade:

Task, priority
Task, tags
TaskList, created

Repare que os resultados incluem propriedades dos tipos Task e TaskList, mas não incluem a propriedade created do tipo Task, porque está fora do intervalo especificado para a consulta.

Metadados do armazenamento de dados Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Consultas de metadados

Consultas de espaços de nomes

C#

Go

Java

Node.js

PHP

Python

Ruby

GQL

Consultas de tipo

C#

Go

Java

Node.js

PHP

Python

Ruby

GQL

Consultas de propriedades

C#

Go

Java

Node.js

PHP

Python

Ruby

GQL

Consultas de propriedades: representações de propriedades

C#

Go

Java

Node.js

PHP

Python

Ruby

GQL

Consultas de propriedades: filtragem

C#

Go

Java

Node.js

PHP

Python

Ruby

GQL

Metadados do armazenamento de dados