Esta página se ha traducido con Cloud Translation API.

Consultas de Datastore

Una consulta obtiene entidades de Firestore en modo Datastore que cumplen un conjunto de condiciones especificado.

La consulta opera en entidades de un tipo determinado. Puede especificar filtros en los valores de las propiedades, las claves y los antecesores de las entidades, y puede devolver cero o más entidades como resultados. Una consulta también puede especificar órdenes de clasificación para secuenciar los resultados por los valores de sus propiedades. Los resultados incluyen todas las entidades que tienen al menos un valor para cada propiedad cuyo nombre se indica en los filtros y los criterios de ordenación, y cuyos valores de propiedad cumplen todos los criterios de filtro especificados. La consulta puede devolver entidades completas, entidades proyectadas o solo claves de entidad.

Una consulta típica incluye lo siguiente:

Un tipo de entidad al que se aplica la consulta.
Cero o más filtros basados en los valores de las propiedades, las claves y los antecesores de las entidades
Cero o más órdenes de clasificación para secuenciar los resultados

Cuando se ejecuta, la consulta obtiene todas las entidades del tipo indicado que cumplen todos los filtros especificados, ordenadas según el orden especificado. Las consultas se ejecutan como de solo lectura.

Nota: Para ahorrar memoria y mejorar el rendimiento, las consultas deben especificar, siempre que sea posible, un límite en el número de resultados devueltos.

Cada consulta calcula sus resultados mediante uno o varios índices, que contienen claves de entidad en una secuencia especificada por las propiedades del índice y, opcionalmente, los ancestros de la entidad. Los índices se actualizan de forma incremental para reflejar los cambios que la aplicación haga en sus entidades, de modo que los resultados correctos de todas las consultas estén disponibles sin necesidad de realizar más cálculos.

El mecanismo de consulta basado en índices admite una amplia gama de consultas y es adecuado para la mayoría de las aplicaciones, excepto para las consultas que no se pueden escalar, como las consultas de combinación. Para obtener más información sobre las limitaciones de las consultas en el modo Datastore, consulta Restricciones de las consultas.

Interfaz de consulta

Puedes enviar una consulta a una base de datos en modo Datastore. En el siguiente ejemplo se muestra cómo obtener todas las tareas que aún no se han completado y que tienen una prioridad igual o superior a 4, ordenadas de forma descendente por prioridad:

C#

Para saber cómo instalar y usar la biblioteca de cliente de Cloud Datastore, consulta las bibliotecas de cliente de Cloud Datastore. Para obtener más información, consulta la documentación de referencia de la API C# de Cloud Datastore.

Para autenticarte en Cloud Datastore, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación en un entorno de desarrollo local.

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

En el siguiente ejemplo se muestra cómo ejecutar una consulta:

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

No aplicable

Estructura de las consultas

Una consulta puede especificar un tipo de entidad, cero o más filtros y cero o más órdenes de clasificación.

Filtros

Los filtros de una consulta definen restricciones en las propiedades, las claves y los antecesores de las entidades que se van a recuperar.

Filtros de propiedad

Un filtro de propiedad especifica lo siguiente:

Nombre de una propiedad
Un operador de comparación
Un valor de propiedad

En el siguiente ejemplo se devuelven entidades de tareas marcadas como no completadas:

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

La aplicación debe proporcionar el valor de la propiedad. No puede hacer referencia a otras propiedades ni calcularse en función de ellas. Una entidad cumple el filtro si tiene una propiedad con el nombre indicado cuyo valor se compara con el valor especificado en el filtro de la forma descrita por el operador de comparación. Si la propiedad del nombre indicado tiene un valor de matriz, la entidad cumple el filtro si alguno de los valores se compara con el valor especificado en el filtro de la forma descrita por el operador de comparación.

El operador de comparación puede ser cualquiera de los siguientes:

Operador	Significado
`EQUAL`	Igual a
`LESS_THAN`	Inferior a
`LESS_THAN_OR_EQUAL`	Inferior o igual a
`GREATER_THAN`	Superior a
`GREATER_THAN_OR_EQUAL`	Superior o igual a
`NOT_EQUAL`	No igual a
`IN`	Miembro de la lista especificada. Igual a cualquiera de los valores de una lista especificada.
`NOT_IN`	No es miembro de la lista especificada. No es igual a ninguno de los valores de una lista especificada.

Filtros compuestos

Un filtro compuesto consta de más de un filtro de propiedad. Puedes combinar filtros con AND y OR. En el siguiente ejemplo, se devuelven Task entidades que están marcadas como no completadas y tienen una prioridad de 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

En el siguiente ejemplo se combinan filtros con un OR lógico:

C#

El fragmento no está disponible.

Go

El fragmento no está disponible.

Java

Para saber cómo instalar y usar la biblioteca de cliente del modo Datastore, consulta Bibliotecas de cliente del modo Datastore. Para obtener más información, consulta la documentación de referencia de la API del modo Datastore Java.

Para autenticarte en el modo Datastore, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación en un entorno de desarrollo local.

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

El fragmento no está disponible.

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

El fragmento no está disponible.

GQL

El fragmento no está disponible.

Firestore en modo Datastore admite la combinación de filtros con los operadores AND y OR. En el siguiente ejemplo, se devuelven las entidades Task que tienen una estrella o que no se han completado y tienen una prioridad de 4:

C#

El fragmento no está disponible.

Go

El fragmento no está disponible.

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

El fragmento no está disponible.

PHP

El fragmento no está disponible.

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

El fragmento no está disponible.

GQL

El fragmento no está disponible.

Filtros clave

Para filtrar por el valor de la clave de una entidad, usa la propiedad especial __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')

Al comparar desigualdades, las claves se ordenan según los siguientes criterios:

Ruta de ancestro
Tipo de entidad
Identificador (nombre de clave o ID numérico)

Los elementos de la ruta de ancestros se comparan de forma similar: por tipo (cadena) y, a continuación, por nombre de clave o ID numérico. Los tipos y los nombres de clave son cadenas y se ordenan por valor de byte. Los IDs numéricos son números enteros y se ordenan numéricamente. Si las entidades con el mismo elemento superior y tipo usan una combinación de cadenas de nombres de clave e IDs numéricos, las que tienen IDs numéricos preceden a las que tienen nombres de clave.

Las consultas de claves usan índices al igual que las consultas de propiedades y requieren índices personalizados en los mismos casos. Las siguientes excepciones no requieren un índice personalizado:

Filtros de desigualdad
Orden ascendente de la clave

Para ordenar de forma descendente por la clave, se necesita un índice personalizado. Al igual que con todas las consultas, el servidor de desarrollo crea las entradas adecuadas en el archivo de configuración del índice cuando se usa en el entorno de desarrollo una consulta que necesita un índice personalizado.

Ordenar pedidos

El orden de clasificación de una consulta especifica lo siguiente:

Nombre de la propiedad.
El sentido de ordenación (ascendente o descendente). De forma predeterminada, el orden es ascendente.

En este ejemplo, se ordenan las entidades Task por hora de creación en orden ascendente:

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

En este ejemplo, se ordenan las entidades Task por hora de creación en orden descendente:

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

Si una consulta incluye varios criterios de ordenación, se aplican en la secuencia especificada. En el ejemplo siguiente, se ordena primero por prioridad descendente y, después, por hora de creación ascendente:

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

Si no se especifica ningún orden, los resultados se devuelven en el orden en que se recuperan del modo Datastore.

Restricciones

Los órdenes de clasificación tienen las siguientes restricciones:

Debido a la forma en que el modo Datastore ejecuta las consultas, si una consulta especifica filtros de desigualdad en una propiedad y órdenes de clasificación en otras propiedades, la propiedad utilizada en los filtros de desigualdad debe ordenarse antes que las demás propiedades.
Si se especifica un orden, el conjunto de propiedades indicado en la cláusula distinct on debe aparecer antes que cualquier propiedad que no sea distinct on en los órdenes de clasificación . Para obtener más información, consulta cómo agrupar consultas.
Se ignoran todos los criterios de ordenación de las propiedades con filtros de igualdad.

Tipos de consultas especiales

Merece la pena mencionar algunos tipos de consultas concretos:

`!= Not equal`

Use el operador distinto de (!=) para devolver las entidades en las que la propiedad dada existe y no coincide con el valor de comparación.

C#

No aplicable

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

No aplicable

PHP

No aplicable

Python

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

Ruby

No aplicable

GQL

SELECT * FROM Task WHERE category != 'work'

Esta consulta devuelve todas las entidades Task en las que existe la propiedad category y se le ha asignado un valor distinto de Work.

Esta consulta no devuelve entidades donde no existe la propiedad category. Las consultas de desigualdad (!=) y NOT_IN excluyen las entidades en las que no existe la propiedad dada o en las que la propiedad se excluye de la indexación. Una propiedad existe cuando se le asigna cualquier valor, incluida una cadena vacía o null.

Limitaciones

Ten en cuenta las siguientes limitaciones de las consultas de !=:

Solo las entidades en las que exista la propiedad dada pueden coincidir con la consulta.
Solo se permite un NOT_IN o un != por consulta.

`IN`

Usa el operador IN para combinar hasta 30 cláusulas de igualdad (==) en la misma propiedad con un OR lógico. Una consulta IN devuelve las entidades en las que la propiedad dada coincide con cualquiera de los valores de comparación.

C#

No aplicable

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

No aplicable

PHP

No aplicable

Python

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

Ruby

No aplicable

GQL

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

Esta consulta devuelve todas las entidades Task en las que la propiedad tag tiene el valor learn o study. Esto incluye las entidades Task en las que la propiedad tag incluye uno de estos valores, pero no el otro.

`NOT_IN`

Usa el operador NOT_IN para combinar hasta 10 cláusulas de desigualdad (!=) en la misma propiedad con un operador lógico AND. Una consulta NOT_IN devuelve las entidades en las que existe la propiedad dada y no coincide con ninguno de los valores de comparación.

C#

No aplicable

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

No aplicable

PHP

No aplicable

Python

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

Ruby

No aplicable

GQL

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

Esta consulta no devuelve entidades donde no existe la entidad category. Las consultas de desigualdad (!=) y NOT_IN excluyen las entidades en las que no existe la propiedad indicada. Una propiedad existe cuando se le asigna cualquier valor, incluida una cadena vacía o null.

Limitaciones

Ten en cuenta las siguientes limitaciones de las consultas de NOT_IN:

Solo las entidades en las que exista la propiedad dada pueden coincidir con la consulta.
Solo se permite un NOT_IN o un != por consulta.

Consultas de ancestros

Una consulta de ancestro limita sus resultados a la entidad especificada y a sus descendientes. En este ejemplo se devuelven todas las entidades Task que tienen la entidad TaskList especificada como ancestro:

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

Limitaciones de las consultas de ancestros

Ten en cuenta las siguientes limitaciones de las consultas de Ancestor:

Todas las disyunciones evaluadas deben tener el mismo filtro de ancestro.

Consultas independientes del tipo

Una consulta sin tipo ni ancestro recupera todas las entidades de una aplicación del modo Datastore. Estas consultas sin tipo no pueden incluir filtros ni criterios de ordenación en los valores de las propiedades. Sin embargo, pueden filtrar por claves de entidad y usar filtros de ancestro. Para usar filtros de clave, especifica __key__ como nombre de propiedad:

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

Consultas de proyección

La mayoría de las consultas devuelven entidades completas como resultados, pero a menudo una aplicación solo está interesada en algunas de las propiedades de la entidad. Las consultas de proyección te permiten consultar solo las propiedades específicas de una entidad que necesitas, con una latencia y un coste inferiores a los de recuperar la entidad completa.

Las consultas de proyección requieren que las propiedades especificadas estén indexadas.

Consultas para obtener solo las claves

Una consulta de solo claves (que es un tipo de consulta de proyección) devuelve solo las claves de las entidades de resultado en lugar de las entidades en sí, con una latencia y un coste inferiores a los de la recuperación de entidades completas.

A menudo es más económico hacer primero una consulta solo de claves y, a continuación, obtener un subconjunto de entidades de los resultados, en lugar de ejecutar una consulta general que puede obtener más entidades de las que realmente necesitas.

Para crear una consulta para obtener solo las claves, sigue estos pasos:

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 consulta de solo claves es una operación pequeña y se contabiliza como una sola lectura de entidad en la propia consulta.

Proyecciones

Las consultas de proyección son similares a las consultas de SQL con el siguiente formato:

SELECT priority, percent_complete FROM Task

Puede usar todas las funciones de filtrado y ordenación disponibles para las consultas de entidades estándar, pero tenga en cuenta estas limitaciones.

La consulta SQL de ejemplo devuelve resultados abreviados con solo las propiedades especificadas, priority y percent_complete, rellenadas con valores. El resto de las propiedades no se rellenan. A continuación, se muestra cómo crear esta consulta de proyección:

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

Para ejecutar la consulta de proyección, sigue estos pasos:

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

No aplicable

Una consulta de proyección que no usa la cláusula distinct on es una operación pequeña y se considera una sola lectura de entidad en la propia consulta.

Agrupación

Las consultas de proyección pueden usar la cláusula distinct on para asegurarse de que solo se devuelva el primer resultado de cada combinación distinta de valores de las propiedades especificadas. De esta forma, solo se devolverá el primer resultado de las entidades que tengan los mismos valores en las propiedades que se proyectan.

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

El conjunto de propiedades especificado en la cláusula distinct on debe aparecer antes de cualquier propiedad que no sea distinct on en la cláusula order by si se especifica order by.

Consultas de agregación

Firestore en el modo de Datastore admite la count()consulta de agregación. Consulta Consultas de agregación.

Filtros de intervalo y de desigualdad en varias propiedades

Firestore en el modo de Datastore admite varios filtros de desigualdad en una consulta compuesta. Consulta Consultar con filtros de intervalo y de desigualdad en varias propiedades.

Valores de matriz

El modo Datastore indexa cada valor de propiedad de matriz único una vez por índice. Por lo tanto, para consultar si una matriz contiene un valor, usa un filtro de igualdad.

Tenga en cuenta lo siguiente cuando su consulta incluya propiedades con valores de matriz.

Filtros de desigualdad

Debido a la forma en que se indexan, las entidades con varios valores para la misma propiedad a veces pueden interactuar con los filtros de consulta y los criterios de ordenación de formas inesperadas y sorprendentes.

Si una consulta tiene varios filtros de desigualdad en una propiedad determinada, una entidad coincidirá con la consulta solo si al menos uno de sus valores individuales de la propiedad cumple todos los filtros. Por ejemplo, si una entidad de tipo Task tiene los valores fun y programming para la propiedad tag, no coincidirá con la consulta:

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'

Cada uno de los valores de tag de la entidad cumple uno de los filtros, pero ningún valor cumple ambos.

Varios filtros de igualdad

Se pueden usar varios filtros de igualdad para consultar las entidades que contienen un conjunto de valores. Por ejemplo, una entidad de tipo Task con los valores fun y programming para la propiedad tag cumplirá la consulta

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

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

Ruby

query = datastore.query("Task")
                 .where("tag", "=", "fun")
                 .where("tag", "=", "programming")

GQL

SELECT * FROM Task WHERE tag = 'fun' AND tag = 'programming'

aunque ninguno de los valores tag individuales de la entidad cumpla ambas condiciones del filtro.

Orden de clasificación

Del mismo modo, el orden de clasificación de las propiedades con varios valores es inusual. Como estas propiedades aparecen una vez en el índice por cada valor único, el primer valor que se ve en el índice determina el orden de clasificación de una entidad.

Si no se usa una propiedad de varios valores en ningún filtro:

y los resultados de la consulta se ordenan de forma ascendente por la propiedad. Para ello, se usa el valor más pequeño de la propiedad.
y los resultados de la consulta se ordenan de forma descendente por la propiedad, se usa el valor más alto para el orden.
Los demás valores no afectan al orden, ni tampoco el número de valores.

Esto tiene la consecuencia inusual de que una entidad con los valores de propiedad 1 y 9 precede a una entidad con los valores 4, 5, 6 y 7 tanto en orden ascendente como descendente.

Si se usa una propiedad con varios valores en un filtro de igualdad, se ignora cualquier orden de clasificación de esa propiedad.

Si se usa una propiedad de varios valores en una desigualdad o en un filtro NOT_IN:

y los resultados de la consulta se ordenan de forma ascendente por la propiedad, se usa el valor más pequeño que cumpla todos los filtros de desigualdad de la consulta para ordenar.
y los resultados de la consulta se ordenan de forma descendente por la propiedad, se usa el valor más alto que cumpla todos los filtros de desigualdad de la consulta para ordenar los resultados.

Tenga en cuenta que, si un conjunto de filtros de desigualdad de una propiedad se traduce en un filtro de igualdad, como

WHERE tag >= 'math' AND tag <= 'math'

se ignora cualquier orden de clasificación de esa propiedad, ya que los filtros se evalúan igual que el filtro de igualdad

WHERE tag = 'math'

Proyecciones y propiedades con valores de matriz

Si proyecta una propiedad con valores de array, no se rellenarán todos los valores de esa propiedad. En su lugar, se devolverá una entidad independiente por cada combinación única de valores proyectados que coincida con la consulta. Por ejemplo, supongamos que tienes una entidad de tipo Task con dos propiedades de varios valores, tag y collaborators:

C#

Entity task = new Entity()
{
    Key = _db.CreateKeyFactory("Task").CreateKey("sampleTask"),
    ["collaborators"] = new ArrayValue() { Values = { "alice", "bob" } },
    ["tags"] = new ArrayValue() { Values = { "fun", "programming" } }
};

Go

type Task struct {
	Tags          []string
	Collaborators []string
}
task := &Task{
	Tags:          []string{"fun", "programming"},
	Collaborators: []string{"alice", "bob"},
}

Java

Entity task =
    Entity.newBuilder(taskKey)
        .set("tags", "fun", "programming")
        .set("collaborators", ListValue.of("alice", "bob"))
        .build();

Node.js

const task = {
  tags: ['fun', 'programming'],
  collaborators: ['alice', 'bob'],
};

PHP

$task = $datastore->entity(
    $key,
    [
        'tags' => ['fun', 'programming'],
        'collaborators' => ['alice', 'bob']
    ]
);

Python

from google.cloud import datastore

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

key = client.key("Task")
task = datastore.Entity(key)
task.update({"tags": ["fun", "programming"], "collaborators": ["alice", "bob"]})

Ruby

# task_name = "sampleTask"
task = datastore.entity "Task", task_name do |t|
  t["tags"] = ["fun", "programming"]
  t["collaborators"] = ["alice", "bob"]
end

GQL

No aplicable

A continuación, la consulta de proyección

SELECT tag, collaborators FROM Task WHERE collaborators < 'charlie'

devolverá cuatro entidades con las siguientes combinaciones de valores:

tag = 'fun', collaborators = 'alice'
tag = 'fun', collaborators = 'bob'
tag = 'programming', collaborators = 'alice'
tag = 'programming', collaborators = 'bob'

Cursores, límites y desplazamientos

Puedes especificar un límite para tu consulta y controlar el número máximo de resultados que se devuelven en un lote. En el siguiente ejemplo se recuperan cinco entidades Task como máximo:

C#

Query query = new Query("Task")
{
    Limit = 5,
};

Go

query := datastore.NewQuery("Task").Limit(5)

Java

Query<Entity> query = Query.newEntityQueryBuilder().setKind("Task").setLimit(5).build();

Node.js

const query = datastore.createQuery('Task').limit(5);

PHP

$query = $datastore->query()
    ->kind('Task')
    ->limit(5);

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()
tasks = list(query.fetch(limit=5))

Ruby

query = datastore.query("Task")
                 .limit(5)

GQL

SELECT * FROM Task LIMIT 5

Los cursores de consulta permiten que una aplicación recupere los resultados de una consulta en lotes cómodos sin incurrir en la sobrecarga de un desplazamiento de consulta. Después de realizar una operación de recuperación, la aplicación puede obtener un cursor, que es una cadena de bytes opaca que marca la posición del índice del último resultado recuperado. La aplicación puede guardar esta cadena (por ejemplo, en tu base de datos en modo Datastore, en una caché o insertada en una página web como parámetro HTTP GET o POST codificado en Base64) y, a continuación, usar el cursor como punto de partida para una operación de recuperación posterior con el fin de obtener el siguiente lote de resultados desde el punto en el que finalizó la recuperación anterior. En una recuperación también se puede especificar un cursor final para limitar el alcance del conjunto de resultados devuelto.

En el siguiente ejemplo se muestra el uso de cursores para la paginación:

C#

Query query = new Query("Task")
{
    Limit = pageSize,
};
if (!string.IsNullOrEmpty(pageCursor))
    query.StartCursor = ByteString.FromBase64(pageCursor);

return _db.RunQuery(query).EndCursor?.ToBase64();

Go

// cursorStr is a cursor to start querying at.
cursorStr := ""

const pageSize = 5
query := datastore.NewQuery("Tasks").Limit(pageSize)
if cursorStr != "" {
	cursor, err := datastore.DecodeCursor(cursorStr)
	if err != nil {
		log.Fatalf("Bad cursor %q: %v", cursorStr, err)
	}
	query = query.Start(cursor)
}

// Read the tasks.
it := client.Run(ctx, query)
var tasks []Task
for {
	var task Task
	_, err := it.Next(&task)
	if err == iterator.Done {
		break
	}
	if err != nil {
		log.Fatalf("Failed fetching results: %v", err)
	}
	tasks = append(tasks, task)
}

// Get the cursor for the next page of results.
// nextCursor.String can be used as the next page's token.
nextCursor, err := it.Cursor()

Java

EntityQuery.Builder queryBuilder =
    Query.newEntityQueryBuilder().setKind("Task").setLimit(pageSize);
if (pageCursor != null) {
  queryBuilder.setStartCursor(pageCursor);
}
QueryResults<Entity> tasks = datastore.run(queryBuilder.build());
while (tasks.hasNext()) {
  Entity task = tasks.next();
  // do something with the task
}
Cursor nextPageCursor = tasks.getCursorAfter();

Node.js

// By default, google-cloud-node will automatically paginate through all of
// the results that match a query. However, this sample implements manual
// pagination using limits and cursor tokens.
async function runPageQuery(pageCursor) {
  let query = datastore.createQuery('Task').limit(pageSize);

  if (pageCursor) {
    query = query.start(pageCursor);
  }
  const results = await datastore.runQuery(query);
  const entities = results[0];
  const info = results[1];

  if (info.moreResults !== Datastore.NO_MORE_RESULTS) {
    // If there are more results to retrieve, the end cursor is
    // automatically set on `info`. To get this value directly, access
    // the `endCursor` property.
    const results = await runPageQuery(info.endCursor);

    // Concatenate entities
    results[0] = entities.concat(results[0]);
    return results;
  }

  return [entities, info];
}

PHP

/**
 * Fetch a query cursor.
 *
 * @param int $pageSize
 * @param string $pageCursor
 * @param string $namespaceId
 */
function cursor_paging(int $pageSize, string $pageCursor = '', string $namespaceId = null)
{
    $datastore = new DatastoreClient(['namespaceId' => $namespaceId]);
    $query = $datastore->query()
        ->kind('Task')
        ->limit($pageSize)
        ->start($pageCursor);
    $result = $datastore->runQuery($query);
    $nextPageCursor = '';
    $entities = [];
    /* @var Entity $entity */
    foreach ($result as $entity) {
        $nextPageCursor = $entity->cursor();
        $entities[] = $entity;
    }

    printf('Found %s entities', count($entities));

    $entities = [];
    if (!empty($nextPageCursor)) {
        $query = $datastore->query()
          ->kind('Task')
          ->limit($pageSize)
          ->start($nextPageCursor);
        $result = $datastore->runQuery($query);

        foreach ($result as $entity) {
            $entities[] = $entity;
        }

        printf('Found %s entities with next page cursor', count($entities));
    }
}

Python

from google.cloud import datastore

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


def get_one_page_of_tasks(cursor=None):
    query = client.query(kind="Task")
    query_iter = query.fetch(start_cursor=cursor, limit=5)
    page = next(query_iter.pages)

    tasks = list(page)
    next_cursor = query_iter.next_page_token

    return tasks, next_cursor

Ruby

page_size = 2
query = datastore.query("Task")
                 .limit(page_size)
tasks = datastore.run query

page_cursor = tasks.cursor

query = datastore.query("Task")
                 .limit(page_size)
                 .start(page_cursor)

GQL

No aplicable

Aunque las bases de datos en modo Datastore admiten desplazamientos de números enteros, te recomendamos que no los uses. En su lugar, usa cursores. Si usas un desplazamiento, solo evitarás que se devuelvan las entidades omitidas a tu aplicación, pero estas entidades se seguirán obteniendo internamente. Las entidades omitidas afectan a la latencia de la consulta y se te cobrarán las operaciones de lectura necesarias para recuperarlas. Si utilizas cursores en lugar de desplazamientos, puedes evitar todos estos costes.

Limitaciones de los cursores

Los cursores están sujetos a las siguientes limitaciones:

Un cursor solo puede utilizarlo el mismo proyecto que realizó la consulta original y solo para continuar la misma consulta. No es posible obtener resultados mediante un cursor sin configurar la misma consulta a partir de la que se generó originalmente.
Si se cambia alguno de los siguientes elementos, se puede seguir usando un cursor para las recuperaciones posteriores.
- Cursor de inicio
- Cursor final
- offset
- límite
Si se cambia alguno de los siguientes elementos, no se podrá usar un cursor para las recuperaciones posteriores.
- proyección
- kind
- antecedente
- filtrar
- distintivo en
- Orden de clasificación La excepción es si el orden de clasificación final de la consulta original era __key__. En ese caso, puedes usar el cursor en una consulta inversa, que es la consulta original con el orden de cada campo invertido. La consulta inversa puede modificar el cursor de inicio, el cursor de finalización, el desplazamiento y el límite.
Los cursores no siempre funcionan como se espera con una consulta que usa un filtro de desigualdad o un orden de clasificación en una propiedad con varios valores. La lógica de eliminación de duplicados de estas propiedades de varios valores no se mantiene entre las recuperaciones, lo que puede provocar que se devuelva el mismo resultado más de una vez.
Las nuevas versiones del modo Datastore pueden cambiar los detalles de implementación internos, lo que invalida los cursores que dependen de ellos. Si una aplicación intenta usar un cursor que ya no es válido, Firestore en el modo Datastore genera una excepción.

Cursores y actualizaciones de datos

El cursor representa la ubicación en la lista de resultados después del último resultado devuelto. Un cursor no es una posición relativa en la lista (no es un desplazamiento), sino un marcador al que puede saltar una base de datos en modo Datastore al iniciar una búsqueda de índice para obtener resultados. Si los resultados de una consulta cambian entre los usos de un cursor, la consulta detecta únicamente los cambios de los resultados que se encuentran después del cursor. Si aparece un resultado nuevo antes de la posición del cursor de la consulta, no se devolverá cuando se obtengan los resultados posteriores al cursor. Del mismo modo, si una entidad ya no es un resultado de una consulta, pero había aparecido antes del cursor, los resultados que aparecen después del cursor no cambian. Aunque el último resultado que se devuelve se elimine del conjunto de resultados, el cursor sabe cómo localizar el siguiente resultado.

Al recuperar los resultados de una consulta, puedes usar un cursor inicial y un cursor final para devolver un grupo continuo de resultados. Cuando utilizas un cursor inicial y otro final para recuperar los resultados, no se garantiza que el tamaño de estos sea el mismo que al generar los cursores. Se pueden añadir o eliminar entidades de la base de datos entre el momento en que se generan los cursores y cuando se usan en una consulta.

Restricciones de las consultas

La naturaleza del mecanismo de consulta de índice impone ciertas restricciones sobre lo que puede hacer una consulta. Las consultas en modo Datastore no admiten coincidencias de subcadenas, coincidencias que no distinguen entre mayúsculas y minúsculas ni búsquedas de texto completo. Además, se aplican las siguientes restricciones:

Las entidades que no tengan una propiedad con el nombre indicado en la consulta se ignorarán

No es necesario que las entidades del mismo tipo tengan las mismas propiedades. Para poder ser un resultado de una consulta, una entidad debe tener un valor (que puede ser nulo) para cada propiedad cuyo nombre se indique en los filtros y los criterios de ordenación de la consulta. Si no es así, la entidad se omite de los índices utilizados para ejecutar la consulta y, por lo tanto, no se incluirá en los resultados de la consulta.

Filtrar por propiedades sin indexar no devuelve ningún resultado

Una consulta no puede encontrar valores de propiedades que no estén indexados ni ordenar por esas propiedades. Para obtener más información, consulta el artículo Propiedades no indexadas.

Límites de los filtros de desigualdad

Para evitar que las consultas sean demasiado caras, Firestore en el modo de Datastore limita el número de propiedades de intervalo o de desigualdad a 10. Para obtener más información sobre las consultas con filtros de desigualdad, consulta Consultar con filtros de intervalo y de desigualdad en varias propiedades.

No puedes usar `NOT_EQUAL` y `NOT_IN`s a la vez

Si usas NOT_IN, no puedes añadir una cláusula NOT_EQUAL.

El orden de los resultados de la consulta no está definido cuando no se especifica ningún orden

Cuando una consulta no especifica un orden, los resultados se devuelven en el orden en el que se recuperan. A medida que evoluciona la implementación del modo Datastore (o si cambian los índices de un proyecto), este orden puede cambiar. Por lo tanto, si tu aplicación requiere que los resultados de la consulta se muestren en un orden concreto, asegúrate de especificarlo explícitamente en la consulta.

Los criterios de ordenación no se tienen en cuenta en las propiedades con filtros de igualdad

Las consultas que incluyen un filtro de igualdad para una propiedad determinada ignoran cualquier orden especificado para esa propiedad. Se trata de una optimización para ahorrar procesamiento innecesario en el caso de las propiedades de un solo valor. Como todos los resultados tienen el mismo valor en la propiedad, no es necesario ordenarlos más. Sin embargo, las propiedades con varios valores pueden tener valores adicionales además del que coincide con el filtro de igualdad. Dado que este caso práctico es poco habitual y que aplicar el orden de clasificación sería costoso y requeriría índices adicionales, el planificador de consultas del modo Datastore ignora el orden de clasificación incluso en el caso de valores múltiples. Esto puede provocar que los resultados de la consulta se devuelvan en un orden diferente al que parece implicar el orden de clasificación. Por ejemplo, el orden de clasificación se ignora en la siguiente consulta:

C#

No aplicable

Go

No aplicable

Java

Query<Entity> query =
    Query.newEntityQueryBuilder()
        .setKind("Task")
        .setFilter(PropertyFilter.eq("tag", "learn"))
        .setOrderBy(OrderBy.asc("tag"))
        .build();

Node.js

No aplicable

PHP

No aplicable

Python

No aplicable

Ruby

No aplicable

GQL

# Sort order on an equality filter is ignored
SELECT * FROM Task WHERE tag = 'learn' ORDER BY tag ASC

Esto no se aplica a las consultas que incluyen un filtro IN. Usa el operador IN para combinar hasta 10 cláusulas de igualdad (==) en la misma propiedad con un OR lógico. Si añade un orden de clasificación para esa propiedad, se aplicará al conjunto de resultados.

C#

No aplicable

Go

No aplicable

Java

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

Node.js

No aplicable

PHP

No aplicable

Python

No aplicable

Ruby

No aplicable

GQL

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

En el caso del orden ascendente, se usa el valor más pequeño que cumple el filtro para ordenar.
En el caso del orden descendente, se usa el valor más alto que cumple el filtro para ordenar.
Otros valores no afectan al orden y tampoco lo hace el número de valores de la propiedad.

Las propiedades usadas en filtros de desigualdad deben ordenarse primero

Para obtener todos los resultados que coincidan con un filtro de desigualdad, una consulta analiza el índice para buscar la primera fila que coincida con el filtro y, a continuación, analiza hacia delante hasta que encuentra una fila que no coincide. Para que las filas consecutivas abarquen el conjunto de resultados completo, deben ordenarse por la propiedad utilizada en el filtro de desigualdad antes que por cualquier otra propiedad. Por lo tanto, si una consulta especifica uno o varios filtros de desigualdad junto con uno o varios criterios de ordenación, el primer criterio de ordenación debe hacer referencia a la misma propiedad que se indica en los filtros de desigualdad. La siguiente consulta es válida:

C#

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

Go

query := datastore.NewQuery("Task").
	FilterField("Priority", ">", 3).
	Order("Priority").
	Order("Created")

Java

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

Node.js

const query = datastore
  .createQuery('Task')
  .filter(new PropertyFilter('priority', '>', 3))
  .order('priority')
  .order('created');

PHP

$query = $datastore->query()
    ->kind('Task')
    ->filter('priority', '>', 3)
    ->order('priority')
    ->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.add_filter(filter=datastore.query.PropertyFilter("priority", ">", 3))
query.order = ["priority", "created"]

Ruby

query = datastore.query("Task")
                 .where("priority", ">", 3)
                 .order("priority")
                 .order("created")

GQL

SELECT * FROM Task WHERE priority > 3 ORDER BY priority, created

Esta consulta no es válida porque no ordena por la propiedad usada en el filtro de desigualdad:

C#

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

Go

query := datastore.NewQuery("Task").
	FilterField("Priority", ">", 3).
	Order("Created")

Java

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

Node.js

const query = datastore
  .createQuery('Task')
  .filter(new PropertyFilter('priority', '>', 3))
  .order('created');

PHP

$query = $datastore->query()
    ->kind('Task')
    ->filter('priority', '>', 3)
    ->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.add_filter(filter=datastore.query.PropertyFilter("priority", ">", 3))
    query.order = ["created"]

Ruby

query = datastore.query("Task")
                 .where("priority", ">", 3)
                 .order("created")

GQL

# Invalid query!
SELECT * FROM Task WHERE priority > 3 ORDER BY created

Del mismo modo, esta consulta no es válida porque la propiedad utilizada en el filtro de desigualdad no es la primera que se ordena:

C#

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

Go

query := datastore.NewQuery("Task").
	FilterField("Priority", ">", 3).
	Order("Created").
	Order("Priority")

Java

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

Node.js

const query = datastore
  .createQuery('Task')
  .filter(new PropertyFilter('priority', '>', 3))
  .order('created')
  .order('priority');

PHP

$query = $datastore->query()
    ->kind('Task')
    ->filter('priority', '>', 3)
    ->order('created')
    ->order('priority');

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

Ruby

query = datastore.query("Task")
                 .where("priority", ">", 3)
                 .order("created")
                 .order("priority")

GQL

# Invalid query!
SELECT * FROM Task WHERE priority > 3 ORDER BY created, priority

`OrderBy` y existencia

Cuando ordenas una consulta por una propiedad determinada, la consulta solo puede devolver las entidades en las que existe la propiedad de ordenación.

Por ejemplo, la siguiente consulta no devolvería ninguna entidad en la que no se haya definido la propiedad priority, aunque cumplan los filtros de la consulta.

Java

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

Se aplica un efecto similar a las desigualdades. Una consulta con un filtro de desigualdad en una propiedad también implica ordenar por esa propiedad. La siguiente consulta no devuelve entidades sin la propiedad priority, aunque starred = true esté en esa entidad. Como solución alternativa, puedes ejecutar consultas independientes para cada orden o asignar un valor a todas las propiedades por las que ordenes.

Java

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

La consulta anterior incluye una ordenación implícita en la desigualdad, como la siguiente. La dirección de la ordenación implícita depende de los índices disponibles:

Java

Query<Entity> query =
    Query.newEntityQueryBuilder()
        .setKind("Task")
        .setFilter(CompositeFilter.or(
            PropertyFilter.eq("starred", true)),
            PropertyFilter.ge("priority", 4)
        )
        .setOrderBy(OrderBy.asc("priority"))
        .build();

Limitaciones de las proyecciones

Las consultas de proyección están sujetas a las siguientes limitaciones:

Solo se pueden proyectar las propiedades indexadas.

Esto significa que todas las propiedades utilizadas en una consulta (proyectadas o filtros) deben existir en el mismo índice. Por lo tanto, select tag from Task where priority = 1 requiere un índice compuesto en priority y, a continuación, en tag.

No se admite la proyección de cadenas de más de 1500 bytes, matrices de bytes con más de 1500 elementos y otras propiedades marcadas explícitamente como no indexadas.
La misma propiedad no se puede proyectar más de una vez.
Las propiedades a las que se hace referencia en un filtro de igualdad no se pueden proyectar.

Por ejemplo,
```
SELECT tag FROM Task WHERE priority = 1
```
es válido (la propiedad proyectada no se usa en el filtro de igualdad), al igual que
```
SELECT tag FROM Task WHERE tag > 'fun`
```
no es un filtro de igualdad, sino
```
SELECT tag FROM Task WHERE tag = 'fun`
```
(propiedad proyectada usada en el filtro de igualdad) no lo es.
Los resultados devueltos por una consulta de proyección no se deben guardar en tu base de datos en modo Datastore.

Como la consulta devuelve resultados que solo se rellenan parcialmente, no debes volver a escribirlos en la base de datos del modo Datastore.
Las consultas de proyección convierten las marcas de tiempo en números enteros.

En los resultados de una consulta de proyección, el modo Datastore convierte los valores de marca de tiempo en valores enteros de microsegundos.

Siguientes pasos

Consulta información sobre las transacciones.

Consultas de Datastore Organízate con las colecciones Guarda y clasifica el contenido según tus preferencias.

Interfaz de consulta

C#

Go

Java

Node.js

PHP

Python

Ruby

GQL

C#

Go

Java

Node.js

PHP

Python

Ruby

GQL

Estructura de las consultas

Filtros

Filtros de propiedad

C#

Go

Java

Node.js

PHP

Python

Ruby

GQL

Filtros compuestos

C#

Go

Java

Node.js

PHP

Python

Ruby

GQL

C#

Go

Java

Node.js

PHP

Python

Ruby

GQL

C#

Go

Java

Node.js

PHP

Python

Ruby

GQL

Filtros clave

C#

Go

Java

Node.js

PHP

Python

Ruby

GQL

Ordenar pedidos

C#

Go

Java

Node.js

PHP

Python

Ruby

GQL

C#

Go

Java

Node.js

PHP

Python

Ruby

GQL

Consultas de Datastore

`!= Not equal`

`IN`

`NOT_IN`