Referensi Properti Entity

API ini didukung untuk runtime generasi pertama dan dapat digunakan saat mengupgrade ke runtime generasi kedua yang sesuai. Jika Anda mengupdate ke runtime App Engine Java 11/17, lihat panduan migrasi guna mempelajari opsi migrasi untuk layanan paket lama.

Firestore dalam mode Datastore (Datastore) mendukung berbagai jenis data untuk nilai properti. Hal ini mencakup, antara lain:

• Bilangan bulat
• Angka floating-point
• String
• Tanggal
• Data biner

Untuk mengetahui daftar lengkap dari jenis, lihat Properti dan jenis nilai.

Properti dan jenis nilai

Nilai data yang terkait dengan entity terdiri dari satu atau beberapa properti. Setiap properti memiliki nama dan satu atau beberapa nilai. Properti dapat memiliki nilai yang berisi lebih dari satu jenis, dan dua entity dapat memiliki nilai dari jenis yang berbeda untuk properti yang sama. Properti dapat diindeks atau tidak diindeks (kueri yang mengurutkan atau memfilter pada properti P akan mengabaikan entity jika P tidak diindeks). Entity dapat memiliki maksimal 20.000 properti yang diindeks.

Catatan: Properti dengan beberapa nilai dapat berguna, misalnya, saat menjalankan kueri dengan filter kesetaraan: entity memenuhi kueri jika salah satu nilainya untuk properti cocok dengan nilai yang ditentukan di filter. Untuk mengetahui detail selengkapnya tentang properti multi-nilai, termasuk masalah yang harus Anda ketahui, lihat halaman Kueri Datastore.

Jenis nilai berikut ini didukung:

Jenis nilai	Jenis Java	Tata urutan	Catatan
Bilangan Bulat	short int long java.lang.Short java.lang.Integer java.lang.Long	Angka	Disimpan sebagai bilangan bulat panjang, lalu dikonversi ke jenis kolom Nilai di luar rentang yang berlebih
Angka floating-point	float double java.lang.Float java.lang.Double	Angka	Presisi ganda 64-bit, IEEE 754
Boolean	boolean java.lang.Boolean	false<true
String teks (singkat)	java.lang.String	Unicode	Hingga 1.500 byte Nilai yang lebih besar dari 1.500 byte menampilkan IllegalArgumentException
String teks (panjang)	com.google.appengine.api.datastore.Text	Tidak ada	Hingga 1 megabyte Tidak diindeks
String byte (pendek)	com.google.appengine.api.datastore.ShortBlob	Urutan byte	Hingga 1.500 byte Nilai yang lebih panjang dari 1.500 byte menampilkan IllegalArgumentException
String byte (panjang)	com.google.appengine.api.datastore.Blob	Tidak ada	Hingga 1 megabyte Tidak diindeks
Tanggal dan waktu	java.util.Date	Kronologis
Titik geografis	com.google.appengine.api.datastore.GeoPt	Berdasarkan lintang, lalu bujur
Alamat pos	com.google.appengine.api.datastore.PostalAddress	Unicode
Nomor telepon	com.google.appengine.api.datastore.PhoneNumber	Unicode
Alamat email	com.google.appengine.api.datastore.Email	Unicode
Pengguna Akun Google	com.google.appengine.api.users.User	Alamat email berdasarkan urutan Unicode
Handle fitur pesan instan	com.google.appengine.api.datastore.IMHandle	Unicode
Link	com.google.appengine.api.datastore.Link	Unicode
Kategori	com.google.appengine.api.datastore.Category	Unicode
Rating	com.google.appengine.api.datastore.Rating	Angka
Kunci Datastore	com.google.appengine.api.datastore.Key atau objek yang direferensikan (sebagai turunan)	Menurut elemen jalur (jenis, ID, jenis, ID...)	Hingga 1.500 byte Nilai yang lebih panjang dari 1.500 byte menampilkan IllegalArgumentException
Kunci Blobstore	com.google.appengine.api.blobstore.BlobKey	Urutan byte
Entity tersemat	com.google.appengine.api.datastore.EmbeddedEntity	Tidak ada	Tidak diindeks
Null	null	Tidak ada

Penting: Sebaiknya jangan menyimpan users.User sebagai nilai properti karena nilai ini menyertakan alamat email beserta ID uniknya. Jika pengguna mengubah alamat emailnya dan Anda membandingkan user.User lamanya yang tersimpan dengan nilai user.User yang baru, nilai tersebut tidak akan cocok. Sebagai gantinya, gunakan nilai ID pengguna User sebagai ID unik stabil pengguna.

Untuk string teks dan data biner yang tidak dienkode (string byte), Datastore mendukung dua jenis nilai:

• String pendek (hingga 1.500 byte) diindeks dan dapat digunakan dalam kondisi filter kueri dan tata urutan.
• String panjang (hingga 1 megabyte) tidak diindeks serta tidak dapat digunakan dalam filter kueri dan tata urutan.

Catatan: Jenis string byte panjang diberi nama Blob di Datastore API. Jenis ini tidak terkait dengan blob seperti yang digunakan dalam Blobstore API.

Jika kueri melibatkan properti dengan nilai jenis campuran, Datastore akan menggunakan pengurutan deterministik berdasarkan representasi internal:

1. Nilai null
2. Angka fixed-point
   • Bilangan bulat
   • Tanggal dan waktu
   • Rating
3. Nilai boolean
4. Urutan byte
   • String byte
   • String Unicode
   • Kunci Blobstore
5. Angka floating-point
6. Titik geografis
7. Pengguna Akun Google
8. Kunci Datastore

Karena string teks panjang, string byte panjang, dan entitas tersemat tidak diindeks, urutannya juga tidak ditentukan.

Catatan: Bilangan bulat dan angka floating-point dianggap sebagai jenis terpisah dalam Datastore. Jika suatu entity menggunakan campuran bilangan bulat dan float untuk properti yang sama, semua bilangan bulat akan diurutkan sebelum semua float: misalnya,

7 < 3.2

Properti berulang

Anda dapat menyimpan beberapa nilai dalam satu properti.

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");

Entity tersemat

Terkadang mungkin lebih nyaman untuk menyematkan satu entity sebagai properti entity lain. Hal ini dapat berguna, misalnya, untuk membuat struktur hierarki nilai properti dalam entity. Class Java EmbeddedEntity memungkinkan Anda melakukan ini:

// 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);

Properti entity tersemat tidak diindeks dan tidak dapat digunakan dalam kueri. Anda dapat memilih untuk mengaitkan kunci dengan entity tersemat, tetapi (tidak seperti entity lengkap) kunci tersebut tidak diperlukan dan, meskipun ada, tidak dapat digunakan untuk mengambil entity.

Daripada mengisi properti entity tersemat secara manual, Anda dapat menggunakan metode setPropertiesFrom() untuk menyalinnya dari entity yang sudah ada:

// 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);

Anda dapat menggunakan metode yang sama di lain waktu untuk memulihkan entity asli dari entity tersemat:

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

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

Menggunakan daftar kosong

Datastore secara historis tidak memiliki representasi untuk properti yang mewakili daftar kosong. Java SDK mengatasi masalah ini dengan menyimpan koleksi kosong sebagai nilai null, sehingga tidak ada cara untuk membedakan antara nilai null dan daftar kosong. Untuk mempertahankan kompatibilitas mundur, perilaku ini tetap default, yang disimpulkan sebagai berikut:

• Properti null ditulis sebagai null ke Datastore
• Koleksi kosong ditulis sebagai null ke Datastore
• Null dibaca sebagai null dari Datastore
• Koleksi kosong dibaca sebagai null.

Penting: Operasi tulis operasi baca pada entity yang memiliki daftar kosong akan menyebabkan daftar tersebut diubah menjadi nilai null.

Namun, jika Anda mengubah perilaku default, Appengine Datastore Java SDK akan mendukung penyimpanan daftar kosong. Sebaiknya pertimbangkan dampak dari perubahan perilaku default aplikasi, lalu aktifkan dukungan untuk daftar kosong.

Untuk mengubah perilaku default agar Anda dapat menggunakan daftar kosong, tetapkan properti DATASTORE_EMPTY_LIST_SUPPORT selama inisialisasi aplikasi sebagai berikut:

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

Dengan properti ini ditetapkan ke true, seperti yang ditunjukkan di atas:

• Properti null ditulis sebagai null ke Datastore
• Koleksi kosong ditulis sebagai daftar kosong untuk Datastore
• Null dibaca sebagai null dari Datastore
• Saat membaca dari Datastore, daftar kosong akan ditampilkan sebagai Koleksi kosong.

Penting: Kueri Anda mungkin terpengaruh saat Anda mengaktifkan dukungan daftar kosong. Nilai null diindeks dalam Datastore, tetapi daftar kosong tidak. Jika Anda menyimpan daftar kosong sebagai null, lalu membuat kueri null untuk menemukannya, mengubah ke daftar kosong akan menyebabkan kueri ini tidak menampilkan hasil.