Esta página aborda as restrições nas consultas do Datastore a partir do Google App Engine. Segue-se uma lista de restrições comuns que vai encontrar quando desenvolver para o Datastore.
As entidades que não têm uma propriedade com o nome indicado na consulta são ignoradas
As entidades do mesmo tipo não têm de ter as mesmas propriedades. Para ser elegível como resultado de uma consulta, uma entidade tem de ter um valor (possivelmente nulo) para cada propriedade com nome nos filtros e nas ordens de ordenação da consulta. Caso contrário, a entidade é omitida dos índices usados para executar a consulta e, consequentemente, não é incluída nos resultados da consulta.
A filtragem em propriedades não indexadas não devolve resultados
Uma consulta não consegue encontrar valores de propriedades que não estejam indexados, nem consegue ordenar por essas propriedades. Consulte a página Índices do Datastore para uma discussão detalhada das propriedades não indexadas.
Os filtros de desigualdade estão limitados a, no máximo, uma propriedade
Para evitar ter de analisar todo o índice, o mecanismo de consulta baseia-se no facto de todos os potenciais resultados de uma consulta estarem adjacentes entre si no índice. Para satisfazer esta restrição, uma única consulta não pode usar comparações de desigualdade (<, <=, >, >=, !=) em mais de uma propriedade em todos os respetivos filtros. Por exemplo, a seguinte consulta é válida, porque ambos os filtros de desigualdade se aplicam à mesma propriedade:
SELECT * FROM Person WHERE birth_year >= :min_birth_year
AND birth_year <= :max_birth_year
No entanto, esta consulta 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
Tenha em atenção que uma consulta pode combinar filtros de igualdade (=) para diferentes propriedades, juntamente com um ou mais filtros de desigualdade numa única propriedade. Assim, o seguinte é uma consulta válida:
A ordenação dos resultados da consulta não está definida quando não é especificada nenhuma ordem de ordenação
Quando uma consulta não especifica uma ordem de ordenação, os resultados são devolvidos na ordem em que são obtidos. À medida que a implementação do Datastore evolui (ou se os índices de uma aplicação mudarem), esta ordem pode mudar. Por conseguinte, se a sua aplicação exigir que os resultados da consulta estejam numa ordem específica, certifique-se de que especifica essa ordem de classificação explicitamente na consulta.
As ordens de ordenação são ignoradas em propriedades com filtros de igualdade
As consultas que incluem um filtro de igualdade para uma determinada propriedade ignoram qualquer ordem de ordenação especificada para essa propriedade. Esta é uma otimização simples para poupar processamento desnecessário para propriedades de valor único, uma vez que todos os resultados têm o mesmo valor para a propriedade e, por isso, não é necessária qualquer ordenação adicional. No entanto, as propriedades com vários valores podem ter valores adicionais além do valor correspondente ao filtro de igualdade. Uma vez que este exemplo de utilização é raro e a aplicação da ordem de ordenação seria dispendiosa e exigiria índices adicionais, o planeador de consultas do Datastore ignora simplesmente a ordem de ordenação, mesmo no caso de vários valores. Isto pode fazer com que os resultados da consulta sejam devolvidos numa ordem diferente da que a ordem de ordenação parece implicar.
As propriedades usadas em filtros de desigualdade têm de ser ordenadas primeiro
Para obter todos os resultados que correspondem a um filtro de desigualdade, uma consulta analisa o índice da primeira linha que corresponde ao filtro e, em seguida, analisa para a frente até encontrar uma linha sem correspondência. Para que as linhas consecutivas abranjam o conjunto de resultados completo, têm de ser ordenadas pela propriedade usada no filtro de desigualdade antes de quaisquer outras propriedades. Assim, se uma consulta especificar um ou mais filtros de desigualdade juntamente com uma ou mais ordens de ordenação, a primeira ordem de ordenação tem de fazer referência à mesma propriedade mencionada nos filtros de desigualdade. Segue-se uma consulta válida:
SELECT * FROM Person WHERE birth_year >= :min_birth_year ORDER BY birth_year, last_nameEsta consulta não é válida porque não ordena pela propriedade usada no filtro de desigualdade:
SELECT * FROM Person WHERE birth_year >= :min_birth_year ORDER BY last_name # ERRORDa mesma forma, esta consulta não é válida porque a propriedade usada no filtro de desigualdade não é a primeira a ser ordenada:
SELECT * FROM Person WHERE birth_year >= :min_birth_year
ORDER BY last_name, birth_year # ERROR
As propriedades com vários valores podem ter comportamentos surpreendentes
Devido à forma como são indexadas, as entidades com vários valores para a mesma propriedade podem, por vezes, interagir com filtros de consulta e ordens de ordenação de formas inesperadas e surpreendentes.
Se uma consulta tiver vários filtros de desigualdade numa determinada propriedade, uma entidade só corresponde à consulta se, pelo menos, um dos seus valores individuais para a propriedade satisfizer todos os filtros. Por exemplo, se uma entidade do tipo Widget tiver os valores 1 e 2 para a propriedade x, não vai corresponder à consulta:
SELECT * FROM Widget WHERE x > 1
AND x < 2
Cada um dos valores x da entidade satisfaz um dos filtros, mas nenhum valor único satisfaz ambos. Tenha em atenção que isto não se aplica a filtros de igualdade. Por exemplo, a mesma entidade vai satisfazer a consulta
SELECT * FROM Widget WHERE x = 1
AND x = 2
Embora nenhum dos valores x individuais da entidade satisfaça ambas as condições do filtro.
O operador diferente de (!=) funciona como um teste "o valor é diferente de". Por exemplo, a consulta
SELECT * FROM Widget WHERE x != 1
corresponde a qualquer entidade Widget com um valor x diferente de 1.
Da mesma forma, a ordem de ordenação das propriedades com vários valores é invulgar. Uma vez que estas propriedades aparecem uma vez no índice para cada valor único, o primeiro valor visto no índice determina a ordem de ordenação de uma entidade:
- Se os resultados da consulta estiverem ordenados por ordem ascendente, é usado o valor mais pequeno da propriedade para a ordenação.
- Se os resultados estiverem ordenados por ordem descendente, é usado o valor mais elevado para a ordenação.
- Os outros valores não afetam a ordem de ordenação, nem o número de valores.
Isto tem a consequência invulgar de que uma entidade com os valores de propriedade 1 e 9 precede uma com os valores 4, 5, 6 e 7 por ordem ascendente e descendente.
As consultas dentro de transações têm de incluir filtros de antepassados
As transações do Datastore operam apenas em entidades pertencentes ao mesmo grupo de entidades (descendentes de um antepassado comum). Para preservar esta restrição, todas as consultas realizadas numa transação têm de incluir um filtro de antepassados que especifique um antepassado no mesmo grupo de entidades que as outras operações na transação.