Questa pagina è stata tradotta dall'API Cloud Translation.

Query Datastore

Una query recupera le entità da Firestore in modalità Datastore che soddisfano un insieme specificato di condizioni.

La query opera su entità di un determinato tipo; può specificare filtri sui valori delle proprietà, sulle chiavi e sugli antenati delle entità e può restituire zero o più entità come risultati. Una query può anche specificare ordini di ordinamento per sequenziare i risultati in base ai valori delle proprietà. I risultati includono tutte le entità che hanno almeno un valore per ogni proprietà denominata nei filtri e negli ordini di ordinamento e i cui valori delle proprietà soddisfano tutti i criteri di filtro specificati. La query può restituire entità intere, entità proiettate o solo chiavi di entità.

Una query tipica include quanto segue:

Un tipo di entità a cui si applica la query
Zero o più filtri basati sui valori delle proprietà, sulle chiavi e sugli antenati delle entità
Zero o più ordini di ordinamento per sequenziare i risultati

Quando viene eseguita, la query recupera tutte le entità del tipo specificato che soddisfano tutti i filtri specificati, ordinate nell'ordine specificato. Le query vengono eseguite in modalità di sola lettura.

Nota:per risparmiare memoria e migliorare le prestazioni, una query deve, se possibile, specificare un limite al numero di risultati restituiti.

Ogni query calcola i risultati utilizzando uno o più indici, che contengono chiavi di entità in una sequenza specificata dalle proprietà dell'indice e, facoltativamente, gli antenati dell'entità. Gli indici vengono aggiornati in modo incrementale per riflettere le modifiche apportate dall'applicazione alle relative entità, in modo che i risultati corretti di tutte le query siano disponibili senza ulteriori calcoli necessari.

Il meccanismo di query basato su indice supporta un'ampia gamma di query ed è adatto alla maggior parte delle applicazioni, ad eccezione delle query non scalabili, come le query di join. Per ulteriori informazioni sulle limitazioni delle query in modalità Datastore, consulta Limitazioni delle query.

Interfaccia di query

Puoi eseguire una query su un database in modalità Datastore. L'esempio seguente mostra come recuperare tutte le attività non ancora completate con priorità maggiore o uguale a 4, ordinate in ordine decrescente di priorità:

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.

Query query = new Query("Task")
{
    Filter = Filter.And(Filter.Equal("done", false),
        Filter.GreaterThanOrEqual("priority", 4)),
    Order = { { "priority", PropertyOrder.Types.Direction.Descending } }
};

Go

query := datastore.NewQuery("Task").
	FilterField("Done", "=", false).
	FilterField("Priority", ">=", 4).
	Order("-Priority")

Java

Query<Entity> query =
    Query.newEntityQueryBuilder()
        .setKind("Task")
        .setFilter(
            CompositeFilter.and(
                PropertyFilter.eq("done", false), PropertyFilter.ge("priority", 4)))
        .setOrderBy(OrderBy.desc("priority"))
        .build();

Node.js

const query = datastore
  .createQuery('Task')
  .filter(
    and([
      new PropertyFilter('done', '=', false),
      new PropertyFilter('priority', '>=', 4),
    ]),
  )
  .order('priority', {
    descending: true,
  });

PHP

$query = $datastore->query()
    ->kind('Task')
    ->filter('done', '=', false)
    ->filter('priority', '>=', 4)
    ->order('priority', Query::ORDER_DESCENDING);

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="Task")
query.add_filter(filter=datastore.query.PropertyFilter("done", "=", False))
query.add_filter(filter=datastore.query.PropertyFilter("priority", ">=", 4))
query.order = ["-priority"]

Ruby

query = datastore.query("Task")
                 .where("done", "=", false)
                 .where("priority", ">=", 4)
                 .order("priority", :desc)

GQL

SELECT * FROM Task
WHERE done = FALSE AND priority >= 4
ORDER BY priority DESC

Il seguente esempio mostra come eseguire una query:

C#

Query query = new Query("Task");
DatastoreQueryResults tasks = _db.RunQuery(query);

Go

it := client.Run(ctx, query)
for {
	var task Task
	_, err := it.Next(&task)
	if err == iterator.Done {
		break
	}
	if err != nil {
		log.Fatalf("Error fetching next task: %v", err)
	}
	fmt.Printf("Task %q, Priority %d\n", task.Description, task.Priority)
}

Java

QueryResults<Entity> tasks = datastore.run(query);

Node.js

const [tasks] = await datastore.runQuery(query);
console.log('Tasks:');
tasks.forEach(task => console.log(task));

PHP

$result = $datastore->runQuery($query);

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()
results = list(query.fetch())

Ruby

tasks = datastore.run query

GQL

Non applicabile

Struttura della query

Una query può specificare un tipo di entità, zero o più filtri e zero o più ordini di ordinamento.

Filtri

I filtri di una query impostano vincoli su proprietà, chiavi e antenati delle entità da recuperare.

Filtri delle proprietà

Un filtro proprietà specifica quanto segue:

Un nome di proprietà
Un operatore di confronto
Un valore della proprietà

Il seguente esempio restituisce le entità delle attività contrassegnate come non completate:

C#

Query query = new Query("Task")
{
    Filter = Filter.Equal("done", false)
};

Go

query := datastore.NewQuery("Task").FilterField("Done", "=", false)

Java

Query<Entity> query =
    Query.newEntityQueryBuilder()
        .setKind("Task")
        .setFilter(PropertyFilter.eq("done", false))
        .build();

Node.js

const query = datastore
  .createQuery('Task')
  .filter(new PropertyFilter('done', '=', false));

PHP

$query = $datastore->query()
    ->kind('Task')
    ->filter('done', '=', false);

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="Task")
query.add_filter(filter=datastore.query.PropertyFilter("done", "=", False))

Ruby

query = datastore.query("Task")
                 .where("done", "=", false)

GQL

SELECT * FROM Task WHERE done = FALSE

Il valore della proprietà deve essere fornito dall'applicazione; non può fare riferimento ad altre proprietà o essere calcolato in termini di altre proprietà. Un'entità soddisfa il filtro se ha una proprietà con il nome specificato il cui valore viene confrontato con il valore specificato nel filtro nel modo descritto dall'operatore di confronto. Se la proprietà del nome specificato è un array, l'entità soddisfa il filtro se uno qualsiasi dei valori viene confrontato con il valore specificato nel filtro nel modo descritto dall'operatore di confronto.

L'operatore di confronto può essere uno dei seguenti:

Operatore	Significato
`EQUAL`	Uguale a
`LESS_THAN`	Minore di
`LESS_THAN_OR_EQUAL`	Minore o uguale a
`GREATER_THAN`	Maggiore di
`GREATER_THAN_OR_EQUAL`	Maggiore o uguale a
`NOT_EQUAL`	Diverso da
`IN`	Membro dell'elenco specificato. Uguale a uno qualsiasi dei valori in un elenco specificato.
`NOT_IN`	Non è membro dell'elenco specificato. Non è uguale a nessuno dei valori in un elenco specificato.

Filtri compositi

Un filtro composito è composto da più di un filtro delle proprietà. Puoi combinare i filtri con AND e OR. Il seguente esempio restituisce Task entità contrassegnate come non completate e con priorità 4:

C#

Query query = new Query("Task")
{
    Filter = Filter.And(Filter.Equal("done", false),
        Filter.Equal("priority", 4)),
};

Go

query := datastore.NewQuery("Task").
	FilterField("Done", "=", false).
	FilterField("Priority", "=", 4)

Java

Query<Entity> query =
    Query.newEntityQueryBuilder()
        .setKind("Task")
        .setFilter(
            CompositeFilter.and(
                PropertyFilter.eq("done", false), PropertyFilter.eq("priority", 4)))
        .build();

Node.js

const query = datastore
  .createQuery('Task')
  .filter(
    and([
      new PropertyFilter('done', '=', false),
      new PropertyFilter('priority', '=', 4),
    ]),
  );

PHP

$query = $datastore->query()
    ->kind('Task')
    ->filter('done', '=', false)
    ->filter('priority', '=', 4);

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="Task")
query.add_filter(filter=datastore.query.PropertyFilter("done", "=", False))
query.add_filter(filter=datastore.query.PropertyFilter("priority", "=", 4))

Ruby

query = datastore.query("Task")
                 .where("done", "=", false)
                 .where("priority", "=", 4)

GQL

SELECT * FROM Task WHERE done = FALSE AND priority = 4

L'esempio seguente combina i filtri con un OR logico:

C#

Snippet non disponibile.

Vai

Snippet non disponibile.

Java

Per scoprire come installare e utilizzare la libreria client per la modalità Datastore, consulta la pagina Librerie client della modalità Datastore. Per saperne di più, consulta la documentazione di riferimento dell'API Java in modalità Datastore.

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

import com.google.cloud.datastore.Datastore;
import com.google.cloud.datastore.DatastoreOptions;
import com.google.cloud.datastore.Entity;
import com.google.cloud.datastore.Query;
import com.google.cloud.datastore.QueryResults;
import com.google.cloud.datastore.StructuredQuery.CompositeFilter;
import com.google.cloud.datastore.StructuredQuery.Filter;
import com.google.cloud.datastore.StructuredQuery.PropertyFilter;

public class OrFilterQuery {
  public static void invoke() throws Exception {

    // Instantiates a client
    Datastore datastore = DatastoreOptions.getDefaultInstance().getService();
    String propertyName = "description";

    // Create the two filters
    Filter orFilter =
        CompositeFilter.or(
            PropertyFilter.eq(propertyName, "Feed cats"),
            PropertyFilter.eq(propertyName, "Buy milk"));

    // Build the query
    Query<Entity> query = Query.newEntityQueryBuilder().setKind("Task").setFilter(orFilter).build();

    // Get the results back from Datastore
    QueryResults<Entity> results = datastore.run(query);

    if (!results.hasNext()) {
      throw new Exception("query yielded no results");
    }

    while (results.hasNext()) {
      Entity entity = results.next();
      System.out.printf("Entity: %s%n", entity);
    }
  }
}

Node.js

/**
 * TODO(developer): Uncomment these variables before running the sample.
 */
// const projectId = "your Google Cloud project id";

// Imports the Cloud Datastore
const {Datastore, PropertyFilter, or} = require('@google-cloud/datastore');

async function queryFilterOr() {
  // Instantiate the Datastore
  const datastore = new Datastore();
  const query = datastore
    .createQuery('Task')
    .filter(
      or([
        new PropertyFilter('description', '=', 'Buy milk'),
        new PropertyFilter('description', '=', 'Feed cats'),
      ]),
    );

  const [entities] = await datastore.runQuery(query);
  for (const entity of entities) {
    console.log(`Entity found: ${entity['description']}`);
  }
}

queryFilterOr();

PHP

Snippet non disponibile.

Python

from google.cloud import datastore
from google.cloud.datastore import query


def query_filter_or(project_id: str) -> None:
    """Builds a union of two queries (OR) filter.

    Arguments:
        project_id: your Google Cloud Project ID
    """
    client = datastore.Client(project=project_id)

    or_query = client.query(kind="Task")
    or_filter = query.Or(
        [
            query.PropertyFilter("description", "=", "Buy milk"),
            query.PropertyFilter("description", "=", "Feed cats"),
        ]
    )

    or_query.add_filter(filter=or_filter)

    results = list(or_query.fetch())
    for result in results:
        print(result["description"])

Ruby

Snippet non disponibile.

GQL

Snippet non disponibile.

Firestore in modalità Datastore supporta la combinazione di filtri con gli operatori AND e OR. Il seguente esempio restituisce le entità Task contrassegnate con una stella o contrassegnate come non completate e con una priorità pari a 4:

C#

Snippet non disponibile.

Vai

Snippet non disponibile.

Java

Query<Entity> query =
    Query.newEntityQueryBuilder()
        .setKind("Task")
        .setFilter(CompositeFilter.or(
            PropertyFilter.eq("starred", true)),
            CompositeFilter.and(
                PropertyFilter.eq("done", false),
                PropertyFilter.eq("priority", 4)))
        .build();

Node.js

Snippet non disponibile.

PHP

Snippet non disponibile.

Python

and_or_query = client.query(kind="Task")

query_filter = query.Or(
    [
        query.PropertyFilter("starred", "=", True),
        query.And([query.PropertyFilter("done", "=", False),
                    query.PropertyFilter("priority", "=", 4,),
        ]
        )
    ]
)

and_or_query.add_filter(filter=query_filter)

results = and_or_query.fetch()
for result in results:
    print(result["description"])

Ruby

Snippet non disponibile.

GQL

Snippet non disponibile.

Filtri principali

Per filtrare in base al valore della chiave di un'entità, utilizza la proprietà speciale __key__:

C#

Query query = new Query("Task")
{
    Filter = Filter.GreaterThan("__key__", _keyFactory.CreateKey("aTask"))
};

Go

key := datastore.NameKey("Task", "someTask", nil)
query := datastore.NewQuery("Task").FilterField("__key__", ">", key)

Java

Query<Entity> query =
    Query.newEntityQueryBuilder()
        .setKind("Task")
        .setFilter(PropertyFilter.gt("__key__", keyFactory.newKey("someTask")))
        .build();

Node.js

const query = datastore
  .createQuery('Task')
  .filter(
    new PropertyFilter('__key__', '>', datastore.key(['Task', 'someTask'])),
  );

PHP

$query = $datastore->query()
    ->kind('Task')
    ->filter('__key__', '>', $datastore->key('Task', 'someTask'));

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="Task")
first_key = client.key("Task", "first_task")
# key_filter(key, op) translates to add_filter('__key__', op, key).
query.key_filter(first_key, ">")

Ruby

query = datastore.query("Task")
                 .where("__key__", ">", datastore.key("Task", "someTask"))

GQL

SELECT * FROM Task WHERE __key__ > KEY(Task, 'someTask')

Quando si confrontano le chiavi per la disuguaglianza, queste vengono ordinate in base ai seguenti criteri, in ordine:

Percorso antenato
Tipo di entità
Identificatore (nome della chiave o ID numerico)

Gli elementi del percorso predecessore vengono confrontati in modo simile: per tipo (stringa), poi per nome della chiave o ID numerico. I tipi e i nomi delle chiavi sono stringhe e sono ordinati in base al valore dei byte; gli ID numerici sono numeri interi e sono ordinati numericamente. Se le entità con lo stesso elemento principale e tipo utilizzano un mix di stringhe di nomi delle chiavi e ID numerici, quelle con ID numerici precedono quelle con nomi delle chiavi.

Le query sulle chiavi utilizzano gli indici proprio come le query sulle proprietà e richiedono indici personalizzati negli stessi casi. Le seguenti eccezioni non richiedono un indice personalizzato:

Filtri di disuguaglianza
Ordine crescente della chiave

Un ordine di ordinamento decrescente sulla chiave richiede un indice personalizzato. Come per tutte le query, il server di sviluppo crea le voci appropriate nel file di configurazione dell'indice quando nell'ambiente di sviluppo viene utilizzata una query che richiede un indice personalizzato.

Ordinare gli ordini

Un ordine di ordinamento della query specifica quanto segue:

Un nome della proprietà.
Una direzione di ordinamento (crescente o decrescente). Per impostazione predefinita, l'ordine di ordinamento è crescente.

Questo esempio ordina le entità Attività in base all'ora di creazione in ordine crescente:

C#

Query query = new Query("Task")
{
    Order = { { "created", PropertyOrder.Types.Direction.Ascending } }
};

Go

query := datastore.NewQuery("Task").Order("created")

Java

Query<Entity> query =
    Query.newEntityQueryBuilder().setKind("Task").setOrderBy(OrderBy.asc("created")).build();

Node.js

const query = datastore.createQuery('Task').order('created');

PHP

$query = $datastore->query()
    ->kind('Task')
    ->order('created');

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="Task")
query.order = ["created"]

Ruby

query = datastore.query("Task")
                 .order("created", :asc)

GQL

SELECT * FROM Task ORDER BY created ASC

Questo esempio ordina le entità Attività in base alla data di creazione in ordine decrescente:

C#

Query query = new Query("Task")
{
    Order = { { "created", PropertyOrder.Types.Direction.Descending } }
};

Go

query := datastore.NewQuery("Task").Order("-created")

Java

Query<Entity> query =
    Query.newEntityQueryBuilder().setKind("Task").setOrderBy(OrderBy.desc("created")).build();

Node.js

const query = datastore.createQuery('Task').order('created', {
  descending: true,
});

PHP

$query = $datastore->query()
    ->kind('Task')
    ->order('created', Query::ORDER_DESCENDING);

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="Task")
query.order = ["-created"]

Ruby

query = datastore.query("Task")
                 .order("created", :desc)

GQL

SELECT * FROM Task ORDER BY created DESC

Se una query include più criteri di ordinamento, questi vengono applicati nella sequenza specificata. L'esempio seguente ordina prima in base alla priorità decrescente e poi in base alla data di creazione crescente:

C#

Query query = new Query("Task")
{
    Order = { { "priority", PropertyOrder.Types.Direction.Descending },
        { "created", PropertyOrder.Types.Direction.Ascending } }
};

Go

query := datastore.NewQuery("Task").Order("-priority").Order("created")

Java

Query<Entity> query =
    Query.newEntityQueryBuilder()
        .setKind("Task")
        .setOrderBy(OrderBy.desc("priority"), OrderBy.asc("created"))
        .build();

Node.js

const query = datastore
  .createQuery('Task')
  .order('priority', {
    descending: true,
  })
  .order('created');

PHP

$query = $datastore->query()
    ->kind('Task')
    ->order('priority', Query::ORDER_DESCENDING)
    ->order('created');

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="Task")
query.order = ["-priority", "created"]

Ruby

query = datastore.query("Task")
                 .order("priority", :desc)
                 .order("created", :asc)

GQL

SELECT * FROM Task ORDER BY priority DESC, created ASC

Se non vengono specificati ordini di ordinamento, i risultati vengono restituiti nell'ordine in cui vengono recuperati dalla modalità Datastore.

Limitazioni

Ordinamenti presenta le seguenti limitazioni:

A causa del modo in cui la modalità Datastore esegue le query, se una query specifica filtri di disuguaglianza su una proprietà e ordini di ordinamento su altre proprietà, la proprietà utilizzata nei filtri di disuguaglianza deve essere ordinata prima delle altre proprietà.
Se viene specificato l'ordinamento, l'insieme di proprietà specificato nella clausola distinct on deve essere visualizzato prima di qualsiasi proprietà non distinct on negli ordini di ordinamento . Per maggiori informazioni, consulta la sezione Raggruppamento delle query.
Gli ordinamenti delle proprietà con filtri di uguaglianza vengono tutti ignorati.

Tipi di query speciali

Alcuni tipi specifici di query meritano una menzione speciale:

`!= Not equal`

Utilizza l'operatore diverso da (!=) per restituire le entità in cui la proprietà specificata esiste e non corrisponde al valore di confronto.

C#

Non applicabile

Go

package datastore_snippets

import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/datastore"
	"google.golang.org/api/iterator"
)

func queryNotEquals(w io.Writer, projectId string) error {
	ctx := context.Background()
	client, err := datastore.NewClient(ctx, projectId)
	if err != nil {
		return fmt.Errorf("NewClient: %w", err)
	}
	defer client.Close()

	q := datastore.NewQuery("TaskList")
	q.FilterField("Task", "!=", []string{"notASimpleTask"})

	it := client.Run(ctx, q)
	for {
		var dst struct {
			Task string
		}
		key, err := it.Next(&dst)
		if err == iterator.Done {
			break
		}

		if err != nil {
			return err
		}
		fmt.Fprintf(w, "Key retrieved: %v\n", key)
	}

	return nil
}

Java

Query<Entity> query =
    Query.newEntityQueryBuilder()
        .setKind("Task")
        .setFilter(PropertyFilter.neq("category", "Work"))
        .build();

Node.js

Non applicabile

PHP

Non applicabile

Python

query = client.query(kind="Task")
query.add_filter("category", "!=", "work")

Ruby

Non applicabile

GQL

SELECT * FROM Task WHERE category != 'work'

Questa query restituisce ogni entità Task in cui esiste la proprietà category ed è impostata su un valore diverso da Work.

Questa query non restituisce entità in cui la proprietà category non esiste. Le query diverso da (!=) e NOT_IN escludono le entità in cui la proprietà specificata non esiste o in cui la proprietà è esclusa dall'indicizzazione. Una proprietà esiste quando è impostata su un valore qualsiasi, inclusa una stringa vuota o null.

Limitazioni

Tieni presenti le seguenti limitazioni per le query !=:

Solo le entità in cui esiste la proprietà specificata possono corrispondere alla query.
È consentito un solo NOT_IN o != per query.

`IN`

Utilizza l'operatore IN per combinare fino a 30 clausole di uguaglianza (==) sulla stessa proprietà con un OR logico. Una query IN restituisce le entità in cui la proprietà specificata corrisponde a uno qualsiasi dei valori di confronto.

C#

Non applicabile

Go

package datastore_snippets

import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/datastore"
	"google.golang.org/api/iterator"
)

func queryIn(w io.Writer, projectId string) error {
	ctx := context.Background()
	client, err := datastore.NewClient(ctx, projectId)
	if err != nil {
		return fmt.Errorf("NewClient: %w", err)
	}
	defer client.Close()

	q := datastore.NewQuery("TaskList")
	q.FilterField("Task", "in", []string{"simpleTask", "easyTask"})

	it := client.Run(ctx, q)
	for {
		var dst struct {
			Task string
		}
		key, err := it.Next(&dst)
		if err == iterator.Done {
			break
		}

		if err != nil {
			return err
		}
		fmt.Fprintf(w, "Key retrieved: %v\n", key)
	}

	return nil
}

Java

Query<Entity> query =
    Query.newEntityQueryBuilder()
        .setKind("Task")
        .setFilter(PropertyFilter.in("tag", ListValue.of("learn", "study")))
        .build();

Node.js

Non applicabile

PHP

Non applicabile

Python

query = client.query(kind="Task")
query.add_filter("tag", "IN", ["learn", "study"])

Ruby

Non applicabile

GQL

SELECT * FROM Task WHERE tag IN ARRAY('learn', 'study')

Questa query restituisce ogni entità Task in cui la proprietà tag è impostata su learn o study. Sono incluse le entità Task in cui la proprietà tag include uno di questi valori, ma non l'altro.

`NOT_IN`

Utilizza l'operatore NOT_IN per combinare fino a 10 clausole di disuguaglianza (!=) nella stessa proprietà con un operatore logico AND. Una query NOT_IN restituisce entità in cui la proprietà specificata esiste e non corrisponde a nessuno dei valori di confronto.

C#

Non applicabile

Go

package datastore_snippets

import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/datastore"
	"google.golang.org/api/iterator"
)

func queryNotIn(w io.Writer, projectId string) error {
	ctx := context.Background()
	client, err := datastore.NewClient(ctx, projectId)
	if err != nil {
		return fmt.Errorf("NewClient: %w", err)
	}
	defer client.Close()

	q := datastore.NewQuery("TaskList")
	q.FilterField("Task", "not-in", []string{"notASimpleTask", "notAnEasyTask"})

	it := client.Run(ctx, q)
	for {
		var dst struct {
			Task string
		}
		key, err := it.Next(&dst)
		if err == iterator.Done {
			break
		}

		if err != nil {
			return err
		}
		fmt.Fprintf(w, "Key retrieved: %v\n", key)
	}

	return nil
}

Java

Query<Entity> query =
    Query.newEntityQueryBuilder()
        .setKind("Task")
        .setFilter(PropertyFilter.not_in("category", ListValue.of("Work", "Chores", "School")))
        .build();

Node.js

Non applicabile

PHP

Non applicabile

Python

query = client.query(kind="Task")
query.add_filter("category", "NOT_IN", ["work", "chores", "school"])

Ruby

Non applicabile

GQL

SELECT * FROM Task WHERE category NOT IN ARRAY('work', 'chores', 'school')

Questa query non restituisce entità in cui l'entità category non esiste. Le query diverso da (!=) e NOT_IN escludono le entità in cui la proprietà specificata non esiste. Una proprietà esiste quando è impostata su un valore qualsiasi, inclusa una stringa vuota o null.

Limitazioni

Tieni presenti le seguenti limitazioni per le query NOT_IN:

Solo le entità in cui esiste la proprietà specificata possono corrispondere alla query.
È consentito un solo NOT_IN o != per query.

Query da predecessore

Una query da predecessore limita i risultati all'entità specificata e ai relativi discendenti. Questo esempio restituisce tutte le entità Task che hanno l'entità TaskList specificata come antenato:

C#

Query query = new Query("Task")
{
    Filter = Filter.HasAncestor(_db.CreateKeyFactory("TaskList")
        .CreateKey(keyName))
};

Go

ancestor := datastore.NameKey("TaskList", "default", nil)
query := datastore.NewQuery("Task").Ancestor(ancestor)

Java

Query<Entity> query =
    Query.newEntityQueryBuilder()
        .setKind("Task")
        .setFilter(
            PropertyFilter.hasAncestor(
                datastore.newKeyFactory().setKind("TaskList").newKey("default")))
        .build();

Node.js

const ancestorKey = datastore.key(['TaskList', 'default']);

const query = datastore.createQuery('Task').hasAncestor(ancestorKey);

PHP

$ancestorKey = $datastore->key('TaskList', 'default');
$query = $datastore->query()
    ->kind('Task')
    ->hasAncestor($ancestorKey);

Python

from google.cloud import datastore

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

# Query filters are omitted in this example as any ancestor queries with a
# non-key filter require a composite index.
ancestor = client.key("TaskList", "default")
query = client.query(kind="Task", ancestor=ancestor)

Ruby

# task_list_name = "default"
ancestor_key = datastore.key "TaskList", task_list_name

query = datastore.query("Task")
                 .ancestor(ancestor_key)

GQL

SELECT * FROM Task WHERE __key__ HAS ANCESTOR KEY(TaskList, 'default')

Limitazioni delle query da predecessore

Tieni presenti le seguenti limitazioni per le query Ancestor:

Tutte le disgiunzioni valutate devono avere lo stesso filtro antenato.

Query senza tipo

Una query senza tipo e senza antenato recupera tutte le entità di un'applicazione dalla modalità Datastore. Queste query senza tipo non possono includere filtri o ordinamenti sui valori delle proprietà. Tuttavia, possono filtrare in base alle chiavi delle entità e utilizzare i filtri degli antenati. I filtri chiave possono essere utilizzati specificando __key__ come nome della proprietà:

C#

Query query = new Query()
{
    Filter = Filter.GreaterThan("__key__",
        _keyFactory.CreateKey("aTask"))
};

Go

query := datastore.NewQuery("").FilterField("__key__", ">", lastSeenKey)

Java

Query<Entity> query =
    Query.newEntityQueryBuilder().setFilter(PropertyFilter.gt("__key__", lastSeenKey)).build();

Node.js

const query = datastore
  .createQuery()
  .filter(new PropertyFilter('__key__', '>', lastSeenKey))
  .limit(1);

PHP

$query = $datastore->query()
    ->filter('__key__', '>', $lastSeenKey);

Python

from google.cloud import datastore

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

last_seen_key = client.key("Task", "a")
query = client.query()
query.key_filter(last_seen_key, ">")

Ruby

query = Google::Cloud::Datastore::Query.new
query.where "__key__", ">", last_seen_key

GQL

SELECT * WHERE __key__ > KEY(Task, 'someTask')

Query di proiezione

La maggior parte delle query restituisce entità intere come risultati, ma spesso un'applicazione è interessata solo ad alcune delle proprietà dell'entità. Le query di proiezione ti consentono di eseguire query solo per le proprietà specifiche di un'entità di cui hai effettivamente bisogno, con latenza e costi inferiori rispetto al recupero dell'intera entità.

Le query di proiezione richiedono l'indicizzazione delle proprietà specificate.

Query basate solo su chiavi

Una query basata solo su chiavi (che è un tipo di query di proiezione) restituisce solo le chiavi delle entità risultato anziché le entità stesse, con latenza e costi inferiori rispetto al recupero di entità intere.

Spesso è più economico eseguire prima una query solo con le chiavi e poi recuperare un sottoinsieme di entità dai risultati, anziché eseguire una query generale che potrebbe recuperare più entità di quelle di cui hai effettivamente bisogno.

Ecco come creare una query basata solo su chiavi:

C#

Query query = new Query("Task")
{
    Projection = { "__key__" }
};

Go

query := datastore.NewQuery("Task").KeysOnly()

Java

Query<Key> query = Query.newKeyQueryBuilder().setKind("Task").build();

Node.js

const query = datastore.createQuery().select('__key__').limit(1);

PHP

$query = $datastore->query()
    ->keysOnly();

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()
query.keys_only()

Ruby

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

GQL

SELECT __key__ FROM Task

Una query basata solo su chiavi è un'operazione ridotta e viene conteggiata come una singola lettura di entità per la query stessa.

Proiezioni

Le query di proiezione sono simili alle query SQL del modulo:

SELECT priority, percent_complete FROM Task

Puoi utilizzare tutte le funzionalità di filtro e ordinamento disponibili per le query standard sulle entità, ma tieni presente queste limitazioni.

La query SQL di esempio restituisce risultati abbreviati con solo le proprietà specificate, priority e percent_complete, compilate con valori; tutte le altre proprietà non sono compilate. Ecco come creare questa query di proiezione:

C#

Query query = new Query("Task")
{
    Projection = { "priority", "percent_complete" }
};

Go

query := datastore.NewQuery("Task").Project("Priority", "PercentComplete")

Java

Query<ProjectionEntity> query =
    Query.newProjectionEntityQueryBuilder()
        .setKind("Task")
        .setProjection("priority", "percent_complete")
        .build();

Node.js

const query = datastore
  .createQuery('Task')
  .select(['priority', 'percent_complete']);

PHP

$query = $datastore->query()
    ->kind('Task')
    ->projection(['priority', 'percent_complete']);

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="Task")
query.projection = ["priority", "percent_complete"]

Ruby

query = datastore.query("Task")
                 .select("priority", "percent_complete")

GQL

SELECT priority, percent_complete FROM Task

Ecco come eseguire la query di proiezione:

C#

Query query = new Query("Task")
{
    Projection = { "priority", "percent_complete" }
};
List<long> priorities = new List<long>();
List<double> percentCompletes = new List<double>();
foreach (var entity in _db.RunQuery(query).Entities)
{
    priorities.Add((long)entity["priority"]);
    percentCompletes.Add((double)entity["percent_complete"]);
}

Go

var priorities []int
var percents []float64
it := client.Run(ctx, query)
for {
	var task Task
	if _, err := it.Next(&task); err == iterator.Done {
		break
	} else if err != nil {
		log.Fatal(err)
	}
	priorities = append(priorities, task.Priority)
	percents = append(percents, task.PercentComplete)
}

Java

List<Long> priorities = new LinkedList<>();
List<Double> percentCompletes = new LinkedList<>();
QueryResults<ProjectionEntity> tasks = datastore.run(query);
while (tasks.hasNext()) {
  ProjectionEntity task = tasks.next();
  priorities.add(task.getLong("priority"));
  percentCompletes.add(task.getDouble("percent_complete"));
}

Node.js

async function runProjectionQuery() {
  const priorities = [];
  const percentCompletes = [];
  const [tasks] = await datastore.runQuery(query);
  tasks.forEach(task => {
    priorities.push(task.priority);
    percentCompletes.push(task.percent_complete);
  });

  return {
    priorities: priorities,
    percentCompletes: percentCompletes,
  };
}

PHP

$priorities = array();
$percentCompletes = array();
$result = $datastore->runQuery($query);
/* @var Entity $task */
foreach ($result as $task) {
    $priorities[] = $task['priority'];
    $percentCompletes[] = $task['percent_complete'];
}

Python

priorities = []
percent_completes = []

for task in query.fetch():
    priorities.append(task["priority"])
    percent_completes.append(task["percent_complete"])

Ruby

priorities = []
percent_completes = []
datastore.run(query).each do |task|
  priorities << task["priority"]
  percent_completes << task["percent_complete"]
end

GQL

Non applicabile

Una query di proiezione che non utilizza la clausola distinct on è una piccola operazione e viene conteggiata come una sola lettura di entità per la query stessa.

Raggruppamento

Le query di proiezione possono utilizzare la clausola distinct on per garantire che venga restituito solo il primo risultato per ogni combinazione distinta di valori per le proprietà specificate. Verrà restituito solo il primo risultato per le entità che hanno gli stessi valori per le proprietà proiettate.

C#

Query query = new Query("Task")
{
    Projection = { "category", "priority" },
    DistinctOn = { "category" },
    Order = {
        { "category", PropertyOrder.Types.Direction.Ascending},
        {"priority", PropertyOrder.Types.Direction.Ascending }
    }
};

Go

query := datastore.NewQuery("Task").
	Project("Priority", "Category").
	DistinctOn("Category").
	Order("Category").Order("Priority")

Java

Query<ProjectionEntity> query =
    Query.newProjectionEntityQueryBuilder()
        .setKind("Task")
        .setProjection("category", "priority")
        .setDistinctOn("category")
        .setOrderBy(OrderBy.asc("category"), OrderBy.asc("priority"))
        .build();

Node.js

const query = datastore
  .createQuery('Task')
  .groupBy('category')
  .order('category')
  .order('priority');

PHP

$query = $datastore->query()
    ->kind('Task')
    ->order('category')
    ->order('priority')
    ->projection(['category', 'priority'])
    ->distinctOn('category');

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="Task")
query.distinct_on = ["category"]
query.order = ["category", "priority"]

Ruby

query = datastore.query("Task")
                 .select("category", "priority")
                 .distinct_on("category")
                 .order("category")
                 .order("priority")

GQL

SELECT DISTINCT ON (category) category, priority FROM Task
ORDER BY category, priority

L'insieme di proprietà specificate nella clausola distinct on deve essere visualizzato prima di qualsiasi proprietà non distinct on nella clausola order by se order by è specificato.

Query di aggregazione

Firestore in modalità Datastore supporta la query di aggregazione count(). Consulta Query di aggregazione.

Filtri per intervallo e disuguaglianza su più proprietà

Firestore in modalità Datastore supporta più filtri di disuguaglianza in una query composta. Consulta Query che utilizza filtri per intervallo e disuguaglianza su più proprietà.

Valori di array

La modalità Datastore indicizza ogni valore di proprietà dell'array univoco una volta per indice. Pertanto, per eseguire una query per verificare se un array contiene un valore, utilizza un filtro di uguaglianza.

Tieni presente quanto segue quando la query include proprietà con valori di array.

Filtri di disuguaglianza

A causa del modo in cui vengono indicizzate, le entità con più valori per la stessa proprietà a volte possono interagire con i filtri query e gli ordinamenti in modi inaspettati e sorprendenti.

Se una query ha più filtri di disuguaglianza su una determinata proprietà, un'entità corrisponderà alla query solo se almeno uno dei suoi singoli valori per la proprietà soddisfa tutti i filtri. Ad esempio, se un'entità di tipo Task ha i valori fun e programming per la proprietà tag, non corrisponderà alla query:

C#

Query query = new Query("Task")
{
    Filter = Filter.And(Filter.GreaterThan("tag", "learn"),
        Filter.LessThan("tag", "math"))
};

Go

query := datastore.NewQuery("Task").
	FilterField("Tag", ">", "learn").
	FilterField("Tag", "<", "math")

Java

Query<Entity> query =
    Query.newEntityQueryBuilder()
        .setKind("Task")
        .setFilter(
            CompositeFilter.and(
                PropertyFilter.gt("tag", "learn"), PropertyFilter.lt("tag", "math")))
        .build();

Node.js

const query = datastore
  .createQuery('Task')
  .filter(
    and([
      new PropertyFilter('tag', '>', 'learn'),
      new PropertyFilter('tag', '<', 'math'),
    ]),
  );

PHP

$query = $datastore->query()
    ->kind('Task')
    ->filter('tag', '>', 'learn')
    ->filter('tag', '<', 'math');

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="Task")
query.add_filter(filter=datastore.query.PropertyFilter("tag", ">", "learn"))
query.add_filter(filter=datastore.query.PropertyFilter("tag", "<", "math"))

Ruby

query = datastore.query("Task")
                 .where("tag", ">", "learn")
                 .where("tag", "<", "math")

GQL

SELECT * FROM Task WHERE tag > 'learn' AND tag < 'math'

Ciascuno dei valori tag dell'entità soddisfa uno dei filtri, ma nessuno dei singoli valori li soddisfa entrambi.

Più filtri di uguaglianza

È possibile utilizzare più filtri di uguaglianza per eseguire query per le entità che contengono un insieme di valori. Ad esempio, un'entità di tipo Task con valori fun e programming per la proprietà tag soddisferà la query

C#

Query query = new Query("Task")
{
    Filter = Filter.And(Filter.Equal("tag", "fun"),
        Filter.Equal("tag", "programming"))
};

Go

query := datastore.NewQuery("Task").
	FilterField("Tag", "=", "fun").
	FilterField("Tag", "=", "programming")

Java

Query<Entity> query =
    Query.newEntityQueryBuilder()
        .setKind("Task")
        .setFilter(
            CompositeFilter.and(
                PropertyFilter.eq("tag", "fun"), PropertyFilter.eq("tag", "programming")))
        .build();

Node.js

const query = datastore
  .createQuery('Task')
  .filter(
    and([
      new PropertyFilter('tag', '=', 'fun'),
      new PropertyFilter('tag', '=', 'programming'),
    ]),
  );

PHP

$query = $datastore->query()
    ->kind('Task')
    ->filter('tag', '=', 'fun')
    ->filter('tag', '=', 'programming');

Python

Per eseguire l'autenticazione in Cloud Datastore, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta

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

Interfaccia di query

C#

Go

Java

Node.js

PHP

Python

Ruby

GQL

C#

Go

Java

Node.js

PHP

Python

Ruby

GQL

Struttura della query

Filtri

Filtri delle proprietà

C#

Go

Java

Node.js

PHP

Python

Ruby

GQL

Filtri compositi

C#

Go

Java

Node.js

PHP

Python

Ruby

GQL

C#

Vai

Java

Node.js

PHP

Python

Ruby

GQL

C#

Vai

Java

Node.js

PHP

Python

Ruby

GQL

Filtri principali

C#

Go

Java

Node.js

PHP

Python

Ruby

GQL

Ordinare gli ordini

C#

Go

Java

Node.js

PHP

Python

Ruby

GQL

C#

Go

Java

Node.js

PHP

Python

Ruby

GQL

Query Datastore

`!= Not equal`

`IN`

`NOT_IN`