Restrições em consultas

Nesta página, apresentamos as restrições em consultas no Cloud Datastore pelo Google App Engine. Na lista a seguir, mostramos restrições comuns que você encontrará ao desenvolver para o Cloud Datastore.

Entidades que não têm uma propriedade nomeada na consulta são ignoradas

Entidades do mesmo tipo não precisam ter as mesmas propriedades. Para ser elegível como resultado de consulta, uma entidade deve ter um valor (que pode ser nulo) para cada propriedade nomeada nos filtros da consulta e ordens de classificação. Caso contrário, ela é omitida dos índices usados para executar a consulta e, consequentemente, não é incluída nos resultados.

Filtragens de propriedades não indexadas não retornam resultados

Uma consulta não pode localizar valores de propriedade que não estão indexados e nem classificar essas propriedades. Consulte a página Índices do Datastore para uma discussão detalhada das propriedades não indexadas.

Os filtros de desigualdade são limitados a no máximo uma propriedade

Para evitar que o mecanismo de consulta verifique todo o índice, é necessário que os possíveis resultados de uma consulta estejam adjacentes um ao outro no índice. Para atender a essa restrição, uma única consulta não pode usar comparações de desigualdade (<, <=, >, >=, !=) em mais de uma propriedade em todos os filtros. Por exemplo, a consulta a seguir é válida porque os dois filtros de desigualdade se aplicam à mesma propriedade:

SELECT * FROM Person WHERE birth_year >= :min_birth_year
                       AND birth_year <= :max_birth_year

No entanto, a consulta a seguir não é válida, porque usa filtros de desigualdade em duas propriedades diferentes:

SELECT * FROM Person WHERE birth_year >= :max_birth_year
                       AND height <= :max_height          # ERROR

Uma consulta pode combinar filtros de igualdade (=) para propriedades diferentes com um ou mais filtros de desigualdade em uma única propriedade. Portanto, a consulta a seguir é válida:

SELECT * FROM Person WHERE last_name = :target_last_name
                       AND city = :target_city
                       AND birth_year >= :min_birth_year
                       AND birth_year <= :max_birth_year

A ordenação dos resultados da consulta é indefinida quando nenhuma ordem de classificação é especificada

Quando uma consulta não especifica uma ordem de classificação, os resultados são retornados na ordem em que são recuperados. À medida que a implementação do Cloud Datastore evolui (ou se os índices de um aplicativo mudarem), essa ordem pode mudar. Portanto, se o aplicativo exige que os resultados de consulta estejam em uma determinada ordem, certifique-se de especificar explicitamente essa ordem de classificação na consulta.

Pedidos de classificação são ignorados em propriedades com filtros de igualdade

As consultas que incluem um filtro de igualdade para uma determinada propriedade ignoram qualquer ordem de classificação especificada para essa propriedade. Essa é uma otimização simples para evitar o processamento desnecessário de propriedades de valor único, já que todos os resultados têm o mesmo valor para a propriedade e, portanto, nenhuma classificação adicional é necessária. As propriedades de valores múltiplos, no entanto, podem ter valores adicionais além do correspondente ao filtro de igualdade. Como esse caso de uso é raro e aplicar a ordem de classificação seria caro e exigiria índices extras, o planejador de consultas do Cloud Datastore simplesmente ignora a ordem de classificação mesmo no caso de valores múltiplos. Isso pode fazer com que os resultados da consulta sejam retornados em uma ordem diferente daquela que a ordem de classificação parece implicar.

Propriedades utilizadas em filtros de desigualdade devem ser classificadas primeiro

Para recuperar todos os resultados que correspondem a um filtro de desigualdade, uma consulta verifica o índice da primeira linha correspondente ao filtro e, em seguida, segue verificando até encontrar uma linha não correspondente. Para que as linhas consecutivas incluam todo o conjunto de resultados, elas precisam ser ordenadas pela propriedade usada no filtro de desigualdade antes de qualquer outra. Assim, se uma consulta especifica um ou mais filtros de desigualdade com uma ou mais ordens de classificação, a primeira ordem de classificação precisa se referir à mesma propriedade nomeada nos filtros de desigualdade. Veja a seguir uma consulta válida:

SELECT * FROM Person WHERE birth_year >= :min_birth_year
                     ORDER BY birth_year, last_name

A consulta a seguir não é válida, porque não classifica a propriedade usada no filtro de desigualdade:

SELECT * FROM Person WHERE birth_year >= :min_birth_year
                     ORDER BY last_name                   # ERROR

Da mesma forma, a consulta a seguir não é válida porque a propriedade usada no filtro de desigualdade não é a primeira classificada:

SELECT * FROM Person WHERE birth_year >= :min_birth_year
                     ORDER BY last_name, birth_year       # ERROR

Propriedades com vários valores podem se comportar de maneiras inesperadas

Devido à maneira como elas são indexadas, entidades com vários valores para a mesma propriedade às vezes podem interagir com filtros de consulta e ordens de classificação de maneiras inesperadas.

Se uma consulta tiver vários filtros de desigualdade para determinada propriedade, uma entidade só corresponderá à consulta se pelo menos um dos valores individuais dela satisfizer a todos os filtros. Por exemplo, se uma entidade do tipo Widget tiver os valores 1 e 2 para a propriedade x, ela não corresponderá à consulta:

SELECT * FROM Widget WHERE x > 1
                       AND x < 2

Cada um dos valores de x da entidade satisfaz a um dos filtros, mas nenhum dos dois valores satisfaz aos dois. Observe que isso não se aplica a filtros de igualdade. Por exemplo, a mesma entidade satisfará à consulta

SELECT * FROM Widget WHERE x = 1
                       AND x = 2

mesmo que nenhum dos valores de x individuais da entidade satisfaça às duas condições de filtro.

O operador de desigualdade (!=) funciona como um teste de "valor diferente de". Dessa maneira, por exemplo, a consulta

SELECT * FROM Widget WHERE x != 1

combina qualquer entidade Widget com um valor x diferente de 1.

Da mesma forma, a ordem de classificação para propriedades de múltiplos valores é incomum. Como essas propriedades aparecem uma vez no índice para cada valor exclusivo, o primeiro valor exibido no índice determina a ordem de classificação de uma entidade:

  • Se os resultados da consulta forem ordenados em ordem crescente, o menor valor da propriedade é usado para ordenação.
  • Se os resultados forem classificados por ordem decrescente, o maior valor é usado para ordenação.
  • Outros valores não afetam a ordem de classificação, nem o número de valores.

A consequência incomum disso é que uma entidade com valores de propriedade 1 e 9 precede outra com valores 4, 5, 6 e 7 na ordem crescente e decrescente.

Consultas dentro de transações precisam incluir filtros de ancestral

As transações do Cloud Datastore operam somente em entidades que pertencem ao mesmo grupo, ou seja, originadas de um ancestral comum. Para preservar essa restrição, todas as consultas realizadas em uma transação precisam incluir um filtro de ancestral que especifique um ancestral no mesmo grupo de entidades que as outras operações.

Esta página foi útil? Conte sua opinião sobre:

Enviar comentários sobre…

Ambiente padrão do App Engine para Python 2