Referência da propriedade da entidade

Esta API é suportada para runtimes de primeira geração e pode ser usada quando atualizar para runtimes de segunda geração correspondentes. Se estiver a fazer a atualização para o tempo de execução do App Engine Java 11/17, consulte o guia de migração para saber mais sobre as suas opções de migração para serviços agrupados antigos.

O Firestore no modo Datastore (Datastore) suporta uma variedade de tipos de dados para valores de propriedades. Estas incluem, entre outras:

• Números inteiros
• Números de vírgula flutuante
• Strings
• Datas
• Dados binários

Para ver uma lista completa de tipos, consulte Propriedades e tipos de valores.

Propriedades e tipos de valores

Os valores de dados associados a uma entidade consistem numa ou mais propriedades. Cada propriedade tem um nome e um ou mais valores. Uma propriedade pode ter valores de mais do que um tipo, e duas entidades podem ter valores de tipos diferentes para a mesma propriedade. As propriedades podem ser indexadas ou não indexadas (as consultas que ordenam ou filtram uma propriedade P ignoram as entidades em que P não está indexada). Uma entidade pode ter, no máximo, 20 000 propriedades indexadas.

Nota: as propriedades com vários valores podem ser úteis, por exemplo, quando executa consultas com filtros de igualdade: uma entidade satisfaz a consulta se algum dos respetivos valores para uma propriedade corresponder ao valor especificado no filtro. Para mais detalhes sobre propriedades com vários valores, incluindo problemas de que deve ter conhecimento, consulte a página Consultas da base de dados.

São suportados os seguintes tipos de valores:

Tipo de valor	Tipos de Java	Ordenação	Notas
Número inteiro	short int long java.lang.Short java.lang.Integer java.lang.Long	Numérico	Armazenado como número inteiro longo e, em seguida, convertido no tipo de campo Os valores fora do intervalo transbordam
Número de vírgula flutuante	float double java.lang.Float java.lang.Double	Numérico	Precisão dupla de 64 bits, IEEE 754
Booleano	boolean java.lang.Boolean	false<true
String de texto (curta)	java.lang.String	Unicode	Até 1500 bytes Os valores superiores a 1500 bytes geram IllegalArgumentException
String de texto (longa)	com.google.appengine.api.datastore.Text	Nenhum	Até 1 megabyte Não indexado
String de bytes (curta)	com.google.appengine.api.datastore.ShortBlob	Ordem dos bytes	Até 1500 bytes Os valores superiores a 1500 bytes geram um erro IllegalArgumentException
String de bytes (longa)	com.google.appengine.api.datastore.Blob	Nenhum	Até 1 megabyte Não indexado
Data e hora	java.util.Date	Cronológico
Ponto geográfico	com.google.appengine.api.datastore.GeoPt	Por latitude, depois longitude
Morada	com.google.appengine.api.datastore.PostalAddress	Unicode
Número de telefone	com.google.appengine.api.datastore.PhoneNumber	Unicode
Endereço de email	com.google.appengine.api.datastore.Email	Unicode
Utilizador da Conta Google	com.google.appengine.api.users.User	Endereço de email por ordem Unicode
Identificador de mensagens instantâneas	com.google.appengine.api.datastore.IMHandle	Unicode
Link	com.google.appengine.api.datastore.Link	Unicode
Categoria	com.google.appengine.api.datastore.Category	Unicode
Classificação	com.google.appengine.api.datastore.Rating	Numérico
Chave do armazenamento de dados	com.google.appengine.api.datastore.Key ou o objeto referenciado (como secundário)	Por elementos de caminho (tipo, identificador, tipo, identificador...)	Até 1500 bytes Os valores superiores a 1500 bytes geram um erro IllegalArgumentException
Chave do Blobstore	com.google.appengine.api.blobstore.BlobKey	Ordem dos bytes
Entidade incorporada	com.google.appengine.api.datastore.EmbeddedEntity	Nenhum	Não indexada
Nulo	null	Nenhum

Importante: recomendamos vivamente que evite armazenar um users.User como valor de propriedade, uma vez que inclui o endereço de email juntamente com o ID exclusivo. Se um utilizador alterar o respetivo endereço de email e comparar o valor user.User antigo armazenado com o novo valor user.User, não vai haver correspondência. Em alternativa, use o User valor do ID do utilizador como identificador exclusivo estável do utilizador.

Para strings de texto e dados binários não codificados (strings de bytes), o Datastore suporta dois tipos de valores:

• As strings curtas (até 1500 bytes) são indexadas e podem ser usadas em condições de filtro de consultas e ordens de ordenação.
• As strings longas (até 1 megabyte) não são indexadas e não podem ser usadas em filtros de consultas nem ordens de ordenação.

Nota: o tipo de string de bytes longo é denominado Blob na API Datastore. Este tipo não está relacionado com blobs usados na API Blobstore.

Quando uma consulta envolve uma propriedade com valores de tipos mistos, o Datastore usa uma ordenação determinística com base nas representações internas:

1. Valores nulos
2. Números de ponto fixo
   • Números inteiros
   • Datas e horas
   • Classificações
3. Valores booleanos
4. Sequências de bytes
   • String de bytes
   • String Unicode
   • Chaves do Blobstore
5. Números de vírgula flutuante
6. Pontos geográficos
7. Utilizadores de Contas Google
8. Chaves do Datastore

Uma vez que as strings de texto longas, as strings de bytes longas e as entidades incorporadas não são indexadas, não têm uma ordenação definida.

Nota: os números inteiros e os números de vírgula flutuante são considerados tipos separados no Datastore. Se uma entidade usar uma combinação de números inteiros e de vírgula flutuante para a mesma propriedade, todos os números inteiros são ordenados antes de todos os números de vírgula flutuante: por exemplo,

7 < 3.2

Propriedades repetidas

Pode armazenar vários valores numa única propriedade.

Entity employee = new Entity("Employee");
ArrayList<String> favoriteFruit = new ArrayList<String>();
favoriteFruit.add("Pear");
favoriteFruit.add("Apple");
employee.setProperty("favoriteFruit", favoriteFruit);
datastore.put(employee);

// Sometime later
employee = datastore.get(employee.getKey());
@SuppressWarnings("unchecked") // Cast can't verify generic type.
    ArrayList<String> retrievedFruits = (ArrayList<String>) employee
    .getProperty("favoriteFruit");

Entidades incorporadas

Por vezes, pode ser conveniente incorporar uma entidade como propriedade de outra entidade. Isto pode ser útil, por exemplo, para criar uma estrutura hierárquica de valores de propriedades numa entidade. A classe Java EmbeddedEntity permite-lhe fazer o seguinte:

// Entity employee = ...;
EmbeddedEntity embeddedContactInfo = new EmbeddedEntity();

embeddedContactInfo.setProperty("homeAddress", "123 Fake St, Made, UP 45678");
embeddedContactInfo.setProperty("phoneNumber", "555-555-5555");
embeddedContactInfo.setProperty("emailAddress", "[e-mail]");

employee.setProperty("contactInfo", embeddedContactInfo);

As propriedades de uma entidade incorporada não são indexadas e não podem ser usadas em consultas. Opcionalmente, pode associar uma chave a uma entidade incorporada, mas (ao contrário de uma entidade completa) a chave não é necessária e, mesmo que esteja presente, não pode ser usada para obter a entidade.

Em vez de preencher manualmente as propriedades da entidade incorporada, pode usar o método setPropertiesFrom() para as copiar de uma entidade existente:

// Entity employee = ...;
// Entity contactInfo = ...;
EmbeddedEntity embeddedContactInfo = new EmbeddedEntity();

embeddedContactInfo.setKey(contactInfo.getKey()); // Optional, used so we can recover original.
embeddedContactInfo.setPropertiesFrom(contactInfo);

employee.setProperty("contactInfo", embeddedContactInfo);

Posteriormente, pode usar o mesmo método para recuperar a entidade original da entidade incorporada:

Entity employee = datastore.get(employeeKey);
EmbeddedEntity embeddedContactInfo = (EmbeddedEntity) employee.getProperty("contactInfo");

Key infoKey = embeddedContactInfo.getKey();
Entity contactInfo = new Entity(infoKey);
contactInfo.setPropertiesFrom(embeddedContactInfo);

Usar uma lista vazia

Historicamente, o Datastore não tinha uma representação para uma propriedade que representasse uma lista vazia. O SDK Java contornou esta situação armazenando coleções vazias como valores nulos, pelo que não existe forma de distinguir entre valores nulos e listas vazias. Para manter a retrocompatibilidade, este continua a ser o comportamento predefinido, resumido da seguinte forma:

• As propriedades nulas são escritas como nulas no Datastore
• As coleções vazias são escritas como nulas no Datastore
• Um valor nulo é lido como nulo do Armazenamento de dados
• Uma coleção vazia é lida como nula.

Importante: uma operação de leitura, modificação e escrita de uma entidade com uma lista vazia faz com que essa lista se transforme num valor nulo.

No entanto, se alterar o comportamento predefinido, o SDK Java do Appengine Datastore suporta o armazenamento de listas vazias. Recomendamos que considere as implicações de alterar o comportamento predefinido da sua aplicação e, em seguida, ative o suporte para listas vazias.

Para alterar o comportamento predefinido para que possa usar listas vazias, defina a propriedade DATASTORE_EMPTY_LIST_SUPPORT durante a inicialização da app da seguinte forma:

System.setProperty(DatastoreServiceConfig.DATASTORE_EMPTY_LIST_SUPPORT, Boolean.TRUE.toString());

Com esta propriedade definida como true, conforme mostrado acima:

• As propriedades nulas são escritas como nulas no Datastore
• As coleções vazias são escritas como uma lista vazia no Datastore
• Um valor nulo é lido como nulo do Armazenamento de dados
• Quando lê a partir do Datastore, é devolvida uma lista vazia como uma coleção vazia.

Importante: as suas consultas podem ser afetadas quando ativa o suporte de listas vazias. Os valores nulos são indexados no Datastore, mas as listas vazias não. Se estava a armazenar listas vazias como nulas e, em seguida, a consultar nulas para as encontrar, a alteração para listas vazias fará com que estas consultas não devolvam resultados.