Observação: é altamente recomendável a desenvolvedores que criam novos aplicativos usar a biblioteca de cliente NDB, porque ela oferece diversos benefícios em comparação com esta biblioteca de cliente, como armazenamento em cache automático de entidades por meio da API Memcache. Se você estiver usando a antiga biblioteca de cliente DB, leia o Guia de migração de DB para NDB.
O App Engine Datastore aceita um conjunto fixo de tipos de valores para as propriedades nas entidades de dados.
As classes
Property
podem definir novos tipos que são convertidos em/de tipos de valor subjacentes, e os tipos de valor podem ser usados diretamente com propriedades dinâmicas
Expando
e modelos de propriedade agregada
ListProperty
.
A tabela abaixo descreve as classes Property com valores diretamente correspondentes aos tipos de dados subjacentes. Qualquer um desses tipos de valor pode ser usado em uma propriedade dinâmica Expando ou um tipo agregado ListProperty.
Tipos de valor do armazenamento de dados
Os valores de propriedade da entidade do armazenamento de dados podem ser de um dos tipos abaixo. Acima, uma lista de classes Property
correspondentes a serem usadas com definições Model
.
Além dos tipos padrão Python e users.User
, todas as classes descritas nesta seção são fornecidas pelo módulo google.appengine.ext.db
.
str
ouunicode
-
Uma string curta (1.500 bytes ou menos).
Um valor
str
é considerado como texto codificado com o codecascii
, e é convertido em um valorunicode
antes de ser armazenado. O valor é retornado pelo armazenamento de dados como um valorunicode
. Para strings curtas utilizando outros codecs, use um valorunicode
.As strings curtas são indexadas pelo armazenamento de dados e podem ser usadas em filtros e ordens de classificação. Para strings de texto com mais de 1.500 bytes (que não estão indexadas), use uma instância de
Text
. Para strings de bytes não codificadas com mais de 1.500 bytes (também não indexadas), use uma instância deBlob
. Para strings de bytes não textuais e não codificadas de até 1.500 bytes (não caracteres) que precisam ser indexadas, use uma instância deByteString
.Propriedade de modelo:
StringProperty
bool
-
Um valor booleano (
True
ouFalse
).Propriedade de modelo:
BooleanProperty
int
oulong
-
Um valor inteiro de até 64 bits.
Os valores Python
int
são convertidos em valores Pythonlong
antes do armazenamento. Um valor armazenado comoint
será retornado comolong
.Se for atribuído um
long
maior que 64 bits, apenas os 64 bits menos significativos serão armazenados.Propriedade de modelo:
IntegerProperty
float
-
Um número de ponto flutuante.
Propriedade de modelo:
FloatProperty
datetime.datetime
-
Data e hora. Consulte a documentação do módulo
datetime
.Se o valor
datetime
tiver um atributotzinfo
, ele será convertido no fuso horário UTC para armazenamento. Os valores são retornados do armazenamento de dados como UTC, comtzinfo
deNone
. Um aplicativo que precisa de valores de data e hora para estar em um fuso horário específico precisa definirtzinfo
corretamente ao atualizar o valor e converter valores no fuso horário ao acessar o valor.Algumas bibliotecas usam a variável de ambiente
TZ
para controlar o fuso horário aplicado aos valores de data e hora. O App Engine define essa variável de ambiente como"UTC"
. A alteração desta variável em um aplicativo não altera o comportamento de alguma funções de data e hora, porque as alterações nas variáveis de ambiente não são visíveis fora do código Python.Se você apenas converter valores em/de um fuso horário específico, poderá implementar um
datetime.tzinfo
personalizado para converter valores do armazenamento de dados:import datetime import time class Pacific_tzinfo(datetime.tzinfo): """Implementation of the Pacific timezone.""" def utcoffset(self, dt): return datetime.timedelta(hours=-8) + self.dst(dt) def _FirstSunday(self, dt): """First Sunday on or after dt.""" return dt + datetime.timedelta(days=(6-dt.weekday())) def dst(self, dt): # 2 am on the second Sunday in March dst_start = self._FirstSunday(datetime.datetime(dt.year, 3, 8, 2)) # 1 am on the first Sunday in November dst_end = self._FirstSunday(datetime.datetime(dt.year, 11, 1, 1)) if dst_start <= dt.replace(tzinfo=None) < dst_end: return datetime.timedelta(hours=1) else: return datetime.timedelta(hours=0) def tzname(self, dt): if self.dst(dt) == datetime.timedelta(hours=0): return "PST" else: return "PDT" pacific_time = datetime.datetime.fromtimestamp(time.mktime(utc_time.timetuple()), Pacific_tzinfo())
Consulte a
datetime
documentação do módulo (incluindodatetime.tzinfo
), bem como o módulo de terceirospytz
, mas observe que a distribuiçãopytz
tem muitos arquivos.A classe de propriedade de modelo
DateTimeProperty
inclui recursos como a capacidade de usar automaticamente a data e a hora do armazenamento de uma instância de modelo. Esses recursos são do modelo e não estão disponíveis no valor bruto do armazenamento de dados (como em uma propriedade dinâmicaExpando
).Propriedades de modelo:
DateTimeProperty
,DateProperty
,TimeProperty
list
-
Uma lista de valores, cada um sendo um dos tipos de dados compatíveis.
Quando
list
é usada como o valor de uma propriedade dinâmicaExpando
, ela não pode ser uma lista vazia. Isto se deve ao modo como os valores de lista são armazenados. Quando uma propriedade de lista não contém valores, ela não tem representação no armazenamento de dados. É possível usar uma propriedade estática e a classeListProperty
para representar um valor de lista vazio de uma propriedade.Propriedade de modelo:
ListProperty
-
db.Key
-
A chave de outra entidade de armazenamento de dados.
Observação: as strings de chave são limitadas a 1.500 bytes ou menos.
m = Employee(name="Susan", key_name="susan5") m.put() e = Employee(name="Bob", manager=m.key()) e.put() m_key = db.Key.from_path("Employee", "susan5") e = Employee(name="Jennifer", manager=m_key)
Propriedades de modelo:
ReferenceProperty
,SelfReferenceProperty
-
blobstore.BlobKey
-
A chave de um valor do Blobstore gerada por ele quando o valor é enviado.
Propriedades de modelo:
blobstore.BlobReferenceProperty
-
users.User
-
Um usuário com uma conta do Google.
Um valor
user.User
no armazenamento de dados não é atualizado quando o usuário altera o próprio endereço de e-mail. Por esse motivo, é altamente recomendável evitar armazenar umusers.User
como um valorUserProperty
, porque isso inclui o endereço de e-mail e o ID exclusivo. Se um usuário alterar o endereço de e-mail e você comparar ouser.User
antigo armazenado com o novo valor deuser.User
, eles não serão correspondentes. Em vez disso, use ouser_id()
do valor deuser.User
como o identificador estável exclusivo do usuário.Propriedade de modelo:
UserProperty
- class Blob(arg=None)
-
Dados binários, como uma string de bytes. É uma subclasse do tipo
str
integrado.As propriedades Blob não são indexadas e não podem ser usadas em filtros ou ordens de classificação.
Blob é para dados binários, como imagens. Ele usa um valor
str
, mas esse valor é armazenado como uma string de bytes e não é codificado como texto. Use uma instância deText
para dados de texto grandes.Propriedade de modelo:
BlobProperty
class MyModel(db.Model): blob = db.BlobProperty() m = MyModel() m.blob = db.Blob(open("image.png", "rb").read())
Em XML, os blobs tem codificação base64 independentemente de conterem ou não dados binários.
- class ByteString(arg)
-
Um valor de blob curto (uma "string de bytes") de 1.500 bytes ou menos. ByteString é uma subclasse de
str
, e usa um valorstr
não codificado como argumento para o construtor.As ByteStrings são indexadas pelo armazenamento de dados e podem ser usadas em filtros e ordens de classificação. Para strings de bytes com mais de 1.500 bytes (não indexadas), use uma instância de
Blob
. Para dados de texto codificados, usestr
(curto, indexado) ouText
(longo, não indexado).Propriedade de modelo:
ByteStringProperty
- class Text(arg=None, encoding=None)
-
Uma string longa. É uma subclasse do tipo
unicode
integrado.arg um valor de
unicode
oustr
. Se arg for umstr
, então ele será analisado com a codificação especificada por encoding, ouascii
se nenhuma codificação for especificada. Consulte a lista de codificações padrão (em inglês) para possíveis valores de encoding.Ao contrário de uma propriedade de entidade com valor igual a um
str
ouunicode
, uma propriedade Text pode ter mais de 1.500 bytes de comprimento. Entretanto, as propriedades Text não são indexadas e não podem ser usadas em filtros ou ordens de classificação.Propriedade de modelo:
TextProperty
class MyModel(db.Model): text = db.TextProperty() m = MyModel() m.text = db.Text(u"kittens") m.text = db.Text("kittens", encoding="latin-1")
- class Category(tag)
-
Uma categoria ou "tag". É uma subclasse do tipo
unicode
integrado.Propriedade de modelo:
CategoryProperty
class MyModel(db.Model): category = db.CategoryProperty() m = MyModel() m.category = db.Category("kittens")
Em XML, é um elemento
Category
do Atom. - class Email(email)
-
Um endereço de e-mail. É uma subclasse do tipo
unicode
integrado.Os endereços de e-mail não são validados pela classe de propriedade nem pela classe de valor. Elas apenas armazenam o valor.
Propriedade de modelo:
EmailProperty
class MyModel(db.Model): email_address = db.EmailProperty() m = MyModel() m.email_address = db.Email("larry@example.com")
Em XML, este é um elemento
gd:email
. - class GeoPt(lat, lat=None)
-
Um ponto geográfico representado por coordenadas de latitude e longitude com ponto flutuante.
Propriedade de modelo:
GeoPtProperty
Em XML, este é um elemento
georss:point
. - class IM(protocol, address=None)
-
Um gerenciador de mensagens instantâneas.
Protocol é o URL canônico do serviço de mensagens instantâneas. Alguns valores possíveis:
Protocolo Descrição sip SIP/SIMPLE xmpp XMPP/Jabber http://aim.com/ AIM http://icq.com/ ICQ http://messenger.msn.com/ MSN Messenger http://messenger.yahoo.com/ Yahoo Messenger http://sametime.com/ Lotus Sametime http://gadu-gadu.pl/ Gadu-Gadu desconhecido Desconhecido ou não especificado address é o endereço do gerenciador.
Propriedade de modelo:
IMProperty
class MyModel(db.Model): im = db.IMProperty() m = MyModel() m.im = db.IM("http://example.com/", "Larry97")
Em XML, este é um elemento
gd:im
. - class Link(link)
-
Um URL totalmente qualificado. É uma subclasse do tipo
unicode
integrado.Propriedade de modelo:
LinkProperty
class MyModel(db.Model): link = db.LinkProperty() m = MyModel() m.link = db.Link("http://www.google.com/")
Em XML, isso é um elemento
Link
(em inglês) do Atom. - class PhoneNumber(phone)
-
Um número de telefone legível por seres humanos. É uma subclasse do tipo
unicode
integrado.Propriedade de modelo:
PhoneNumberProperty
class MyModel(db.Model): phone = db.PhoneNumberProperty() m = MyModel() m.phone = db.PhoneNumber("1 (206) 555-1212")
Em XML, este é um elemento
gd.phoneNumber
. - class PostalAddress(address)
-
Um endereço postal. É uma subclasse do tipo
unicode
integrado.Propriedade de modelo:
PostalAddressProperty
class MyModel(db.Model): address = db.PostalAddressProperty() m = MyModel() m.address = db.PostalAddress("1600 Ampitheater Pkwy., Mountain View, CA")
Em XML, este é um elemento
gd:postalAddress
. - class Rating(rating)
-
Uma classificação fornecida pelo usuário para uma parte de conteúdo, como um inteiro entre 0 e 100. É uma subclasse do tipo
long
integrado. A classe confirma que o valor é um número inteiro entre 0 e 100, bem como gera umBadValueError
quando o valor é inválido.Propriedade de modelo:
RatingProperty
class MyModel(db.Model): rating = db.RatingProperty() m = MyModel() m.rating = db.Rating(97)
Em XML, este é um elemento
gd:rating
.
Classes Property
Todas as classes de propriedade de modelo fornecidas por google.appengine.ext.db
são subclasses da classe de base Property
, e aceitam todos os argumentos do construtor de base. Consulte a documentação da classe de base para informações sobre esses argumentos.
O pacote google.appengine.ext.db
fornece as seguintes classes propriedade de modelo:
- class BlobProperty(...)
-
Uma coleção não interpretada de dados binários.
Os dados do blob são uma string de bytes. Para dados de texto, que podem envolver codificação, use
TextProperty
.Tipo de valor:
Blob
- class BooleanProperty(...)
-
Um valor booleano (
True
ouFalse
).Tipo de valor:
bool
- class ByteStringProperty(verbose_name=None, ...)
-
Um valor de blob curto (uma "string de bytes") de 1.500 bytes ou menos.
Os valores
ByteStringProperty
são indexados e podem ser usados em filtros e ordens de classificação.Como
StringProperty
, exceto que o valor não é codificado de forma alguma. Os bytes são armazenados literalmente.ISe
ByteStringProperty
for obrigatório, o valor não poderá ser uma string vazia.Tipo de valor:
ByteString
- class CategoryProperty(...)
-
Uma categoria ou "tag", uma palavra ou frase descritiva.
Tipo de valor:
Category
- class DateProperty(verbose_name=None, verbose_name=False, verbose_name=False, ...)
-
Uma data sem hora. Consulte
DateTimeProperty
para mais informações.Tipo de valor:
datetime.date
; convertido internamente emdatetime.datetime
- class DateTimeProperty(verbose_name=None, verbose_name=False, verbose_name=False, ...)
-
Data e hora.
Se auto_now for
True
, o valor da propriedade será definido com a hora atual sempre que a instância do modelo for armazenada no armazenamento de dados, substituindo o valor anterior da propriedade. Isso é útil para rastrear a data e a hora da "última modificação" de uma instância de modelo.Se auto_now_add for
True
, o valor da propriedade será definido com a hora atual na primeira vez em que a instância do modelo for armazenada no armazenamento de dados, a menos que a propriedade já tenha recebido um valor. Isso é útil para armazenar data e hora de "criação" de uma instância de modelo.Os valores de data e hora são armazenados e retornados com o fuso horário UTC. Consulte
datetime.datetime
para uma discussão sobre como gerenciar fusos horários.Tipo de valor:
datetime.datetime
- class EmailProperty(...)
-
Um endereço de e-mail.
Os endereços de e-mail não são validados pela classe de propriedade nem pela classe de valor. Elas apenas armazenam o valor.
Tipo de valor:
Email
- class FloatProperty(...)
-
Um número de ponto flutuante.
Tipo de valor:
float
- class GeoPtProperty(...)
-
Um ponto geográfico representado por coordenadas de latitude e longitude com ponto flutuante.
Tipo de valor:
GeoPt
- class IMProperty(...)
-
Um gerenciador de mensagens instantâneas.
Tipo de valor:
IM
- class IntegerProperty(...)
-
Um valor inteiro de até 64 bits.
Os valores Python
int
são convertidos em valores Pythonlong
antes do armazenamento. Um valor armazenado comoint
será retornado comolong
.Se for atribuído um
long
maior que 64 bits, apenas os 64 bits menos significativos serão armazenados. - class LinkProperty(...)
-
Um URL totalmente qualificado.
Tipo de valor:
Link
- class ListProperty(item_type, item_type=None, item_type=None, ...)
-
Uma lista de valores do tipo especificado por item_type.
Em uma consulta, a comparação de uma propriedade de lista com um valor realiza o teste em relação aos membros da lista:
list_property
=
value
testa se o valor aparece em qualquer lugar da lista,list_property
<
value
testa se algum dos membros da lista é menor que o valor fornecido e assim por diante.Uma consulta não pode comparar dois valores de lista. Não há como testar a igualdade de duas listas sem testar a presença de cada elemento separadamente.
item_type é o tipo dos itens da lista, como um tipo ou classe Python. Todos os itens no valor da lista precisam ser do tipo especificado. item_type precisa ser um dos tipos de valor do armazenamento de dados, e não pode ser
list
.O valor de um
ListProperty
não pode serNone
. Entretanto, pode ser uma lista vazia. QuandoNone
é especificado para o argumento padrão (ou quando o argumento padrão não é especificado), o valor padrão da propriedade é a lista vazia.Dica: como os tipos agregados
ListProperty
não usam as classesProperty
, recursos da classeProperty
, como valores automáticos e validação, não são aplicados automaticamente aos membros do valor da lista. Se você quiser validar um valor de membro usando uma classeProperty
class, you can instantiate the class poderá instanciar a classe e chamar o respectivo métodovalidate()
no valor.default é o valor padrão da propriedade de lista. Se
None
, o padrão será uma lista vazia. Uma propriedade de lista pode definir um validator personalizado para proibir a lista vazia.Consulte a página Modelagem de dados para mais informações sobre propriedades e valores de lista.
Tipo de valor: um
list
Python de valores do tipo especificado - class PhoneNumberProperty(...)
-
Um número de telefone legível por seres humanos.
Tipo de valor:
PhoneNumber
- class PostalAddressProperty(...)
-
Um endereço postal.
Tipo de valor:
PostalAddress
- class RatingProperty()
-
Uma classificação fornecida pelo usuário para uma parte de conteúdo, como um inteiro entre 0 e 100.
Tipo de valor:
Rating
- class ReferenceProperty(reference_class=None, reference_class=None, reference_class=None, ...)
-
Uma referência a outra instância de modelo. Por exemplo, uma referência pode indicar um relacionamento de vários para um entre o modelo com a propriedade e o modelo referenciado pela propriedade.
reference_class é a classe de modelo da instância de modelo referenciada. Se especificada, somente instâncias de modelo da classe poderão ser atribuídas a essa propriedade. Se
None
, qualquer instância de modelo poderá ser o valor desta propriedade.collection_name é o nome da propriedade a ser dado à classe de modelo referenciada. O valor da propriedade é um
Query
de todas as entidades que referenciam a entidade. Se nenhum collection_name for definido, será usadomodelname_set
(com o nome do modelo referenciado em letras minúsculas e_set
adicionado).Observação: collection_name precisará ser definido se houver várias propriedades no mesmo modelo que referenciam a mesma classe de modelo. Caso contrário, um
DuplicatePropertyError
será gerado quando os nomes padrão forem gerados.ReferenceProperty
automaticamente referencia e desreferencia as instâncias de modelo como valores de propriedade: uma instância de modelo pode ser atribuída diretamente a uma propriedade de referência e a respectiva chave será usada. O valorReferenceProperty
pode ser usado como uma instância de modelo, e a entidade do armazenamento de dados será buscada e a instância de modelo criada quando for usada pela primeira vez dessa forma. Propriedades de referência não utilizadas não fazem consultas de dados desnecessários.class Author(db.Model): name = db.StringProperty() class Story(db.Model): author = db.ReferenceProperty(Author) story = db.get(story_key) author_name = story.author.name author = db.get(author_key) stories_by_author = author.story_set.get()
Como no caso de um valor
Key
, é possível que um valor de propriedade referencie uma entidade de dados que não existe. Se uma entidade referenciada for excluída do armazenamento de dados, as referências à entidade não serão atualizadas. Acessar uma entidade que não existe gera umReferencePropertyResolveError
.A exclusão de uma entidade não remove as entidades referenciadas por uma propriedade de referência.
Tipo de valor:
db.Key
- class SelfReferenceProperty(verbose_name=None, verbose_name=None, ...)
-
Uma referência a outra instância de modelo da mesma classe (consulte
ReferenceProperty
).Tipo de valor:
db.Key
- class StringListProperty(verbose_name=None, verbose_name=None, ...)
-
Semelhante a uma propriedade de lista de valores Python
str
ouunicode
(basestring
). - class StringProperty(verbose_name=None, verbose_name=False, ...)
-
Uma string curta. Usa um valor Python
str
ouunicode
(basestring
) de 1.500 bytes ou menos.Os valores
StringProperty
são indexados e podem ser usados em filtros e ordens de classificação.Se multiline for
False
, o valor não poderá incluir caracteres de alimentação de linha. A bibliotecadjangoforms
usa isso para impor uma diferença entre campos de texto e campos de área de texto no modelo de dados, e outros podem usá-lo para finalidade semelhante.Se a propriedade string for necessária, o valor correspondente não poderá ser uma string vazia.
- class TextProperty()
-
Uma string longa.
Ao contrário de
StringProperty
, um valorTextProperty
pode ter mais de 1.500 bytes de comprimento. Entretanto, os valoresTextProperty
não são indexados e não podem ser usados em filtros ou ordens de classificação.Os valores de
TextProperty
armazenam texto com codificação de texto. Para dados binários, useBlobProperty
.Se a propriedade texto for necessária, o valor correspondente não poderá ser uma string vazia.
Tipo de valor:
Text
- class TimeProperty(verbose_name=None, verbose_name=False, verbose_name=False, ...)
-
Uma hora do dia sem data. Usa um valor
datetime.time
da biblioteca padrão do Python. ConsulteDateTimeProperty
para mais informações.Tipo de valor:
datetime.time
; convertido internamente emdatetime.datetime
- class UserProperty(verbose_name=None, verbose_name=False, verbose_name=False, ...)
-
Importante: é altamente recomendável não armazenar um
UserProperty
, porque ele inclui o endereço de e-mail e o código exclusivo do usuário. Se um usuário alterar o endereço de e-mail e você comparar oUser
antigo armazenado com o novo valor deUser
, eles não serão correspondentes.Um usuário com uma conta do Google.
Se auto_current_user for
True
, o valor da propriedade será definido com o usuário atualmente conectado sempre que a instância de modelo for armazenada no armazenamento de dados, substituindo o valor anterior da propriedade. Isso é útil para rastrear qual usuário modifica uma instância de modelo.Se auto_current_user_add for
True
, o valor da propriedade será definido com o usuário atualmente conectado na primeira vez que a instância de modelo for armazenada no armazenamento de dados, a menos que a propriedade já tenha recebido um valor. Isso é útil para rastrear qual usuário cria uma instância de modelo, que pode não ser o mesmo usuário que a modificará posteriormente.UserProperty não aceita um valor padrão. Os valores padrão são definidos na primeira importação da classe de modelo. O cache de importação pode não ser o usuário conectado no momento.
Tipo de valor:
users.User