Batasan pada kueri

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.

Halaman ini membahas pembatasan dalam membuat kueri Datastore dari Google App Engine. Daftar berikut adalah batasan umum yang akan Anda temui saat mengembangkan Datastore.

Entity yang tidak memiliki properti yang disebutkan dalam kueri akan diabaikan

Entity dengan jenis yang sama tidak harus memiliki properti yang sama. Agar memenuhi syarat sebagai hasil kueri, entity harus memiliki nilai (mungkin null) untuk setiap properti yang disebutkan dalam filter dan tata urutan kueri. Jika tidak, entity akan dihilangkan dari indeks yang digunakan untuk mengeksekusi kueri dan akibatnya tidak akan disertakan dalam hasil kueri.

Catatan: Anda tidak dapat membuat kueri untuk entity yang secara khusus tidak memiliki properti tertentu. Salah satu alternatifnya adalah menggunakan null untuk nilai properti default, lalu memfilter entity dengan null sebagai nilai properti tersebut.

Pemfilteran pada properti yang tidak diindeks tidak menampilkan hasil

Kueri tidak dapat menemukan nilai properti yang tidak diindeks, serta tidak dapat mengurutkan properti tersebut. Lihat halaman Indeks Datastore untuk mengetahui pembahasan mendetail tentang properti yang tidak diindeks.

Filter ketidaksetaraan dibatasi maksimal satu properti

Agar tidak perlu memindai seluruh indeks, mekanisme kueri bergantung pada semua hasil potensial kueri yang berdekatan satu sama lain dalam indeks. Untuk memenuhi batasan ini, satu kueri tidak boleh menggunakan perbandingan ketidaksetaraan (LESS_THAN, LESS_THAN_OR_EQUAL, GREATER_THAN, GREATER_THAN_OR_EQUAL, NOT_EQUAL) di lebih dari satu properti di semua filternya. Misalnya, kueri berikut valid karena kedua filter ketidaksetaraan berlaku untuk properti yang sama:

Filter birthYearMinFilter =
    new FilterPredicate("birthYear", FilterOperator.GREATER_THAN_OR_EQUAL, minBirthYear);

Filter birthYearMaxFilter =
    new FilterPredicate("birthYear", FilterOperator.LESS_THAN_OR_EQUAL, maxBirthYear);

Filter birthYearRangeFilter =
    CompositeFilterOperator.and(birthYearMinFilter, birthYearMaxFilter);

Query q = new Query("Person").setFilter(birthYearRangeFilter);

Namun, kueri ini tidak valid karena menggunakan filter ketidaksetaraan pada dua properti yang berbeda:

Filter birthYearMinFilter =
    new FilterPredicate("birthYear", FilterOperator.GREATER_THAN_OR_EQUAL, minBirthYear);

Filter heightMaxFilter =
    new FilterPredicate("height", FilterOperator.LESS_THAN_OR_EQUAL, maxHeight);

Filter invalidFilter = CompositeFilterOperator.and(birthYearMinFilter, heightMaxFilter);

Query q = new Query("Person").setFilter(invalidFilter);

Perhatikan bahwa kueri dapat menggabungkan filter kesetaraan (EQUAL) untuk berbagai properti, bersamaan dengan satu atau beberapa filter ketidaksetaraan di satu properti. Dengan demikian, berikut adalah kueri yang valid:

Filter lastNameFilter = new FilterPredicate("lastName", FilterOperator.EQUAL, targetLastName);

Filter cityFilter = new FilterPredicate("city", FilterOperator.EQUAL, targetCity);

Filter birthYearMinFilter =
    new FilterPredicate("birthYear", FilterOperator.GREATER_THAN_OR_EQUAL, minBirthYear);

Filter birthYearMaxFilter =
    new FilterPredicate("birthYear", FilterOperator.LESS_THAN_OR_EQUAL, maxBirthYear);

Filter validFilter =
    CompositeFilterOperator.and(
        lastNameFilter, cityFilter, birthYearMinFilter, birthYearMaxFilter);

Query q = new Query("Person").setFilter(validFilter);

Pengurutan hasil kueri tidak ditentukan jika tidak ada tata urutan yang ditentukan

Jika sebuah kueri tidak menentukan tata urutan, hasilnya akan ditampilkan sesuai urutan pengambilannya. Seiring berkembangnya implementasi Datastore (atau jika indeks aplikasi berubah), urutan ini dapat berubah. Oleh karena itu, jika aplikasi Anda memerlukan hasil kueri dalam urutan tertentu, pastikan untuk menentukan tata urutan tersebut secara eksplisit dalam kueri.

Tata urutan diabaikan pada properti dengan filter kesetaraan

Kueri yang menyertakan filter kesetaraan untuk properti tertentu akan mengabaikan tata urutan yang ditentukan untuk properti tersebut. Ini adalah pengoptimalan sederhana untuk menyimpan pemrosesan yang tidak perlu untuk properti bernilai tunggal, karena semua hasil memiliki nilai yang sama untuk properti tersebut sehingga tidak perlu penyortiran lebih lanjut. Namun, properti dengan beberapa nilai dapat memiliki nilai tambahan selain yang cocok dengan filter kesetaraan. Karena kasus penggunaan ini jarang terjadi dan penerapan tata urutan akan mahal serta memerlukan indeks tambahan, perencana kueri Datastore mengabaikan tata urutan bahkan dalam kasus multinilai. Hal ini dapat menyebabkan hasil kueri ditampilkan dalam urutan yang berbeda dari yang disiratkan oleh tata urutan.

Properti yang digunakan dalam filter ketidaksetaraan harus diurutkan terlebih dahulu

Untuk mengambil semua hasil yang cocok dengan filter ketidaksetaraan, kueri memindai indeks untuk mencari baris pertama yang cocok dengan filter, lalu memindainya hingga menemukan baris yang tidak cocok. Agar baris berurutan mencakup kumpulan hasil lengkap, baris tersebut harus diurutkan berdasarkan properti yang digunakan dalam filter ketidaksetaraan sebelum properti lainnya. Jadi, jika kueri menentukan satu atau beberapa filter ketidaksetaraan beserta satu atau beberapa tata urutan, tata urutan pertama harus merujuk ke properti yang sama yang dinamai dalam filter ketidaksetaraan. Berikut ini adalah kueri yang valid:

Filter birthYearMinFilter =
    new FilterPredicate("birthYear", FilterOperator.GREATER_THAN_OR_EQUAL, minBirthYear);

Query q =
    new Query("Person")
        .setFilter(birthYearMinFilter)
        .addSort("birthYear", SortDirection.ASCENDING)
        .addSort("lastName", SortDirection.ASCENDING);

Kueri ini tidak valid, karena tidak mengurutkan properti yang digunakan dalam filter ketidaksetaraan:

Filter birthYearMinFilter =
    new FilterPredicate("birthYear", FilterOperator.GREATER_THAN_OR_EQUAL, minBirthYear);

// Not valid. Missing sort on birthYear.
Query q =
    new Query("Person")
        .setFilter(birthYearMinFilter)
        .addSort("lastName", SortDirection.ASCENDING);

Demikian pula, kueri ini tidak valid karena properti yang digunakan dalam filter ketidaksetaraan bukan yang pertama diurutkan:

Filter birthYearMinFilter =
    new FilterPredicate("birthYear", FilterOperator.GREATER_THAN_OR_EQUAL, minBirthYear);

// Not valid. Sort on birthYear needs to be first.
Query q =
    new Query("Person")
        .setFilter(birthYearMinFilter)
        .addSort("lastName", SortDirection.ASCENDING)
        .addSort("birthYear", SortDirection.ASCENDING);

Properti dengan beberapa nilai dapat berperilaku secara mengejutkan

Karena cara pengindeksannya, entity dengan beberapa nilai untuk properti yang sama terkadang dapat berinteraksi dengan filter kueri dan mengurutkan urutan dengan cara yang tidak terduga dan mengejutkan.

Jika kueri memiliki beberapa filter ketidaksetaraan di properti tertentu, entity akan cocok dengan kueri tersebut hanya jika setidaknya salah satu nilai individunya untuk properti tersebut memenuhi semua filter. Misalnya, jika suatu entity jenis Widget memiliki nilai 1 dan 2 untuk properti x, entity tersebut tidak akan cocok dengan kueri:

Query q =
    new Query("Widget")
        .setFilter(
            CompositeFilterOperator.and(
                new FilterPredicate("x", FilterOperator.GREATER_THAN, 1),
                new FilterPredicate("x", FilterOperator.LESS_THAN, 2)));

Setiap nilai x entity memenuhi salah satu filter, tetapi tidak ada nilai tunggal yang memenuhi keduanya. Perhatikan bahwa ini tidak berlaku untuk filter kesetaraan. Misalnya, entity yang sama akan memenuhi kueri

Query q =
    new Query("Widget")
        .setFilter(
            CompositeFilterOperator.and(
                new FilterPredicate("x", FilterOperator.EQUAL, 1),
                new FilterPredicate("x", FilterOperator.EQUAL, 2)));

meskipun tidak satu pun nilai x individual dari entity tersebut memenuhi kedua kondisi filter.

Operator NOT_EQUAL berfungsi sebagai pengujian "nilai selain". Misalnya, kueri

Query q = new Query("Widget").setFilter(new FilterPredicate("x", FilterOperator.NOT_EQUAL, 1));

cocok dengan entity Widget dengan nilai x selain 1.

Di Java, Anda juga dapat menggunakan kueri seperti

Query q =
    new Query("Widget")
        .setFilter(
            CompositeFilterOperator.and(
                new FilterPredicate("x", FilterOperator.NOT_EQUAL, 1),
                new FilterPredicate("x", FilterOperator.NOT_EQUAL, 2)));

yang bertindak seperti

x < 1 OR (x > 1 AND x < 2) OR x > 2

jadi entity Widget dengan nilai x 1, 2, dan 3 cocok, tetapi entity dengan nilai 1 dan 2 tidak.

Demikian pula, tata urutan untuk properti dengan banyak nilai adalah hal yang tidak biasa. Karena properti tersebut muncul sekali dalam indeks untuk setiap nilai unik, nilai pertama yang terlihat di indeks akan menentukan tata urutan entity:

• Jika hasil kueri diurutkan dalam urutan menaik, nilai terkecil dari properti akan digunakan untuk pengurutan.
• Jika hasil diurutkan dalam urutan menurun, nilai terbesar digunakan untuk pengurutan.
• Nilai lainnya tidak memengaruhi tata urutan, begitu juga jumlah nilai.

Hal ini memiliki konsekuensi yang tidak biasa, yaitu entity dengan nilai properti 1 dan 9 mendahului satu dengan nilai 4, 5, 6, dan 7 dalam urutan menaik dan menurun.

Kueri dalam transaksi harus menyertakan filter ancestor

Transaksi Datastore hanya beroperasi pada entity yang termasuk dalam entity group yang sama (turunan dari ancestor yang sama). Untuk mempertahankan batasan ini, semua kueri yang dilakukan dalam transaksi harus menyertakan filter ancestor yang menentukan ancestor dalam entity group yang sama dengan operasi lain dalam transaksi.