Consultas de projeção

A maioria das consultas do Datastore devolve entidades inteiras como resultados, mas, muitas vezes, uma aplicação está realmente interessada apenas em algumas das propriedades da entidade. As consultas de projeção permitem-lhe consultar o Datastore apenas para as propriedades específicas de uma entidade de que realmente precisa, com uma latência e um custo inferiores aos da obtenção da entidade completa.

As consultas de projeção são semelhantes às consultas SQL do seguinte formulário:

SELECT name, email, phone FROM CUSTOMER

Pode usar todas as funcionalidades de filtragem e ordenação disponíveis para consultas de entidades padrão, sujeitas às limitações descritas abaixo. A consulta devolve resultados reduzidos com apenas as propriedades especificadas (name, email e phone no exemplo) preenchidas com valores. Todas as outras propriedades não têm dados.

Usar consultas de projeção no Python 2

Considere o seguinte modelo:

class Article(ndb.Model):
    title = ndb.StringProperty()
    author = ndb.StringProperty()
    tags = ndb.StringProperty(repeated=True)

Especifica uma projeção desta forma:

def print_author_tags():
    query = Article.query()
    articles = query.fetch(20, projection=[Article.author, Article.tags])
    for article in articles:
        print(article.author)
        print(article.tags)
        # article.title will raise a ndb.UnprojectedPropertyError

Processa os resultados destas consultas da mesma forma que faria com uma consulta de entidade padrão, por exemplo, iterando os resultados.

for article in articles:
        print(article.author)
        print(article.tags)
        # article.title will raise a ndb.UnprojectedPropertyError

Pode projetar subpropriedades indexadas a partir de uma propriedade estruturada. Para obter apenas a propriedade city de uma propriedade estruturada address de um contacto, pode usar uma projeção como:

class Address(ndb.Model):
    type = ndb.StringProperty()  # E.g., 'home', 'work'
    street = ndb.StringProperty()
    city = ndb.StringProperty()
... 
class Contact(ndb.Model):
    name = ndb.StringProperty()
    addresses = ndb.StructuredProperty(Address, repeated=True)
... 
Contact.query().fetch(projection=["name", "addresses.city"])
Contact.query().fetch(projection=[Contact.name, Contact.addresses.city])

Agrupamento(experimental)

As consultas de projeção podem usar a palavra-chave distinct para garantir que apenas são devolvidos resultados completamente únicos num conjunto de resultados. Isto só devolve o primeiro resultado para entidades que têm os mesmos valores para as propriedades que estão a ser projetadas.

Article.query(projection=[Article.author], group_by=[Article.author])
Article.query(projection=[Article.author], distinct=True)

Ambas as consultas são equivalentes e produzem o nome de cada autor apenas uma vez.

Limitações nas projeções

As consultas de projeção estão sujeitas às seguintes limitações:

  • Só é possível projetar propriedades indexadas.

    A projeção não é suportada para propriedades que não estão indexadas, quer de forma explícita ou implícita. As strings de texto longas (Text) e as strings de bytes longas (Blob) não são indexadas.

  • Não é possível projetar a mesma propriedade mais do que uma vez.

  • Não é possível projetar propriedades referenciadas num filtro de igualdade (=) ou de associação (IN).

    Por exemplo,

    SELECT A FROM kind WHERE B = 1

    É válido (a propriedade projetada não é usada no filtro de igualdade), tal como

    SELECT A FROM kind WHERE A > 1

    (não é um filtro de igualdade), mas

    SELECT A FROM kind WHERE A = 1

    (projected property used in equality filter) is not.

  • Não é possível guardar novamente no Datastore os resultados devolvidos por uma consulta de projeção.

    Uma vez que a consulta devolve resultados que estão apenas parcialmente preenchidos, não pode escrevê-los novamente no Datastore.

Projeções e propriedades com vários valores

A projeção de uma propriedade com vários valores não preenche todos os valores dessa propriedade. Em alternativa, é devolvida uma entidade separada para cada combinação única de valores projetados que corresponda à consulta. Por exemplo, suponhamos que tem uma entidade do tipo Foo com duas propriedades de vários valores, A e B:

entity = Foo(A=[1, 1, 2, 3], B=['x', 'y', 'x'])

Em seguida, a consulta de projeção

SELECT A, B FROM Foo WHERE A < 3

devolve quatro entidades com as seguintes combinações de valores:

A = 1, B = 'x'
A = 1, B = 'y'
A = 2, B = 'x'
A = 2, B = 'y'

Tenha em atenção que, se uma entidade tiver uma propriedade com vários valores sem valores, não são incluídas entradas no índice, e não são devolvidos resultados para essa entidade a partir de uma consulta de projeção que inclua essa propriedade.

Índices para projeções

As consultas de projeção requerem que todas as propriedades especificadas na projeção sejam incluídas num índice do Datastore. O servidor de desenvolvimento do App Engine gera automaticamente os índices necessários no ficheiro de configuração de índices, index.yaml, que é carregado com a sua aplicação.

Uma forma de minimizar o número de índices necessários é projetar as mesmas propriedades de forma consistente, mesmo quando nem todas são sempre necessárias. Por exemplo, estas consultas requerem dois índices separados:

SELECT A, B FROM Kind
SELECT A, B, C FROM Kind

No entanto, se projetar sempre as propriedades A, B e C, mesmo quando C não é obrigatório, só é necessário um índice.

A conversão de uma consulta existente numa consulta de projeção pode exigir a criação de um novo índice se as propriedades na projeção ainda não estiverem incluídas noutra parte da consulta. Por exemplo, suponha que tinha uma consulta existente como

SELECT * FROM Kind WHERE A > 1 ORDER BY A, B

que requer o índice

Index(Kind, A, B)

Converter isto numa das consultas de projeção

SELECT C FROM Kind WHERE A > 1 ORDER BY A, B
SELECT A, B, C FROM Kind WHERE A > 1 ORDER BY A, B

introduz uma nova propriedade (C) e, por isso, vai exigir a criação de um novo índice Index(Kind, A, B, C). Tenha em atenção que a consulta de projeção

SELECT A, B FROM Kind WHERE A > 1 ORDER BY A, B

não alteraria o índice necessário, uma vez que as propriedades projetadas A e B já estavam incluídas na consulta existente.