Questa pagina è stata tradotta dall'API Cloud Translation.

Metadati Datastore

Firestore in modalità Datastore fornisce l'accesso ai metadati che includono informazioni su gruppi di entità, spazi dei nomi, tipi di entità, proprietà e rappresentazioni delle proprietà per ogni proprietà. Puoi utilizzare i metadati, ad esempio, per creare un visualizzatore di datastore personalizzato per la tua applicazione o per le funzioni amministrative di backend.

La dashboard Datastore nella console Google Cloud fornisce anche alcuni metadati sulla tua applicazione, ma i dati visualizzati differiscono per alcuni aspetti importanti da quelli restituiti da queste funzioni.

Aggiornamento. La lettura dei metadati tramite l'API recupera i dati attuali, mentre i dati nella dashboard vengono aggiornati solo una volta al giorno.
Sommario. Alcuni metadati nella dashboard non sono disponibili tramite le API; è vero anche il contrario.
Velocità. Le operazioni di recupero e le query sui metadati vengono fatturate allo stesso modo delle operazioni di recupero e delle query del datastore. Query dei metadati che recuperano informazioni su spazi dei nomi, tipi e proprietà sono generalmente lente da eseguire. Come regola generale, una query sui metadati che restituisce N entità richiede circa lo stesso tempo di N query ordinarie, ognuna delle quali restituisce una singola entità. Inoltre, le query di rappresentazione delle proprietà (query sulle proprietà non basate solo su chiavi) sono più lente delle query sulle proprietà basate solo su chiavi. I recuperi dei metadati del gruppo di entità sono leggermente più veloci rispetto al recupero di un'entità normale.

Query dei metadati

Tre tipi di entità speciali sono riservati alle query sui metadati:

Entità	Descrizione
`__namespace__`	Utilizzato per trovare tutti gli spazi dei nomi utilizzati nelle entità dell'applicazione.
`__kind__`	Utilizzato per eseguire query su un tipo specifico.
`__property__`	Utilizzato per eseguire query in base a una proprietà di un tipo.

Questi tipi non entreranno in conflitto con altri con lo stesso nome che potrebbero già esistere nella tua applicazione. Eseguendo query su questi tipi speciali, puoi recuperare le entità contenenti i metadati desiderati.

Le entità restituite dalle query sui metadati vengono generate dinamicamente in base allo stato attuale del database. Sebbene tu possa creare oggetti entità locali di tipo __namespace__, __kind__ o __property__, qualsiasi tentativo di memorizzarli nel database non andrà a buon fine.

Query dello spazio dei nomi

Puoi utilizzare una query dello spazio dei nomi per trovare tutti gli spazi dei nomi utilizzati nelle entità dell'applicazione. Ciò ti consente di eseguire attività come le funzioni amministrative in più spazi dei nomi.

Le query dello spazio dei nomi restituiscono entità del tipo speciale __namespace__ la cui chiave è il nome di uno spazio dei nomi. Un'eccezione è lo spazio dei nomi predefinito designato dalla stringa vuota "": poiché la stringa vuota non è un nome di chiave valido, questo spazio dei nomi è associato all'ID numerico 1. Le query di questo tipo supportano il filtraggio solo per intervalli nella pseudoproprietà speciale __key__, il cui valore è la chiave dell'entità. I risultati possono essere ordinati in ordine crescente (ma non decrescente) in base al valore __key__. Poiché le entità __namespace__ non hanno proprietà, sia le query basate solo su chiavi sia quelle non basate solo su chiavi restituiscono le stesse informazioni.

L'esempio seguente restituisce un elenco degli spazi dei nomi di un'applicazione nell'intervallo tra i valori assegnati alle variabili startNamespace e endNamespace:

C#

Per scoprire come installare e utilizzare la libreria client per Cloud Datastore, consulta Librerie client di Cloud Datastore. Per saperne di più, consulta la documentazione di riferimento dell'API Cloud Datastore C#.

Per eseguire l'autenticazione in Cloud Datastore, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configura l'autenticazione per un ambiente di sviluppo locale.

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

Query per tipo

Le query per tipo restituiscono entità di tipo __kind__ il cui nome della chiave è il nome di un tipo di entità. Le query di questo tipo sono implicitamente limitate allo spazio dei nomi corrente e supportano il filtro solo per gli intervalli sulla pseudoproprietà __key__. I risultati possono essere ordinati in ordine crescente (ma non decrescente) in base al valore di __key__. Poiché le entità __kind__ non hanno proprietà, sia le query solo con chiavi sia quelle senza chiavi restituiscono le stesse informazioni.

Il seguente esempio stampa un elenco dei tipi utilizzati in un'applicazione:

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__

Query sulle proprietà

Le query sulle proprietà restituiscono entità di tipo __property__ che indicano le proprietà indicizzate associate a un tipo di entità. (Le proprietà non indicizzate non sono incluse.) L'entità che rappresenta la proprietà p di tipo k è strutturata nel seguente modo:

La chiave dell'entità ha il tipo __property__ e il nome della chiave p.
La chiave padre dell'entità ha il tipo __kind__ e il nome della chiave k.
La proprietà dell'array property_representation dell'entità contiene tutte le rappresentazioni della proprietà.

Ad esempio, se il tuo database contiene esattamente due entità Task con proprietà name e done:

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

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

quindi le due entità restituite da una query __property__ saranno:

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

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

Le query sulle proprietà sono implicitamente limitate allo spazio dei nomi corrente e supportano un filtraggio limitato con un antenato o un intervallo sulla pseudoproprietà __key__.

Una query di proprietà solo chiavi è più efficiente di una query non solo chiavi, in quanto non deve raccogliere le rappresentazioni della proprietà. L'esempio seguente recupera i nomi di tutti i tipi di entità di un'applicazione e le proprietà associate a ciascuno:

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__

Query sulle proprietà: rappresentazioni delle proprietà

Le query sulle proprietà non solo sulle chiavi, note come query di rappresentazione delle proprietà, restituiscono informazioni aggiuntive sui tipi di valori utilizzati per ciascuna proprietà. La proprietà property_representation nell'entità che rappresenta la proprietà p del tipo k è un array contenente tutte le rappresentazioni del valore di p in qualsiasi entità di tipo k.

Ogni valore ha la seguente rappresentazione (tieni presente che alcuni tipi di valori condividono le rappresentazioni):

Tipo di valore	Rappresentazione
Numero intero	`INT64`
Numero in virgola mobile	`DOUBLE`
Booleano	`BOOLEAN`
Stringa di testo	`STRING`
Stringa di byte	`STRING`
Data e ora	`INT64`
Chiave Datastore	`REFERENCE`
Entità incorporata	`STRING`
Array	rappresentazione degli elementi dell'array
Punto geografico	`POINT`
Null	`NULL`

L'esempio seguente trova tutte le rappresentazioni delle proprietà di tipo Task, utilizzando una query sulla proprietà antenato:

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

Query sulle proprietà: filtro

Le query delle proprietà supportano il filtro degli antenati su una chiave __kind__ o __property__, per limitare i risultati della query a un singolo tipo o proprietà, come mostrato nella query di rappresentazione della proprietà riportata sopra.

Le query sulle proprietà possono anche essere filtrate con un intervallo sulla pseudoproprietà __key__, dove le chiavi indicano entità __kind__ o __property__. I risultati possono essere ordinati in ordine crescente (ma non decrescente) in base al valore __key__. Il filtro viene applicato alle coppie tipo-proprietà, ordinate prima per tipo e poi per proprietà. Ad esempio, supponiamo di avere entità con queste proprietà:

tipo Task con proprietà
- created
- priority
- tags
tipo TaskList con proprietà
- created

La seguente query di proprietà basata solo su chiavi:

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 applicabile

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 applicabile

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 applicabile

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

raccoglierà le seguenti coppie di tipo e nome della proprietà:

Task, priority
Task, tags
TaskList, created

Nota che i risultati includono proprietà dei tipi Task e TaskList, ma non includono la proprietà created del tipo Task, perché non rientra nell'intervallo specificato per la query.

Metadati Datastore Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

Query dei metadati

Query dello spazio dei nomi

C#

Go

Java

Node.js

PHP

Python

Ruby

GQL

Query per tipo

C#

Go

Java

Node.js

PHP

Python

Ruby

GQL

Query sulle proprietà

C#

Go

Java

Node.js

PHP

Python

Ruby

GQL

Query sulle proprietà: rappresentazioni delle proprietà

C#

Go

Java

Node.js

PHP

Python

Ruby

GQL

Query sulle proprietà: filtro

C#

Go

Java

Node.js

PHP

Python

Ruby

GQL

Metadati Datastore