Search API untuk layanan paket lama

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.

Search API menyediakan model untuk mengindeks dokumen yang berisi data terstruktur. Anda dapat mencari indeks, dan mengatur serta menyajikan hasil penelusuran. API ini mendukung pencocokan teks lengkap pada kolom string. Dokumen dan indeks disimpan di penyimpanan persisten terpisah yang dioptimalkan untuk operasi penelusuran. Search API dapat mengindeks sejumlah dokumen. App Engine Datastore mungkin lebih cocok untuk aplikasi yang perlu mengambil kumpulan hasil yang sangat besar.

Ringkasan

Search API didasarkan pada empat konsep utama: dokumen, indeks, kueri, dan hasil.

Dokumen

Dokumen adalah objek dengan ID unik dan daftar kolom yang berisi data pengguna. Setiap kolom memiliki nama dan jenis. Ada beberapa jenis kolom, yang diidentifikasi berdasarkan jenis nilai yang ada di dalamnya:

• Kolom Atom - string karakter yang tidak dapat dibagi.
• Kolom Teks - string teks biasa yang dapat ditelusuri kata demi kata.
• Kolom HTML - string yang berisi tag markup HTML, hanya teks di luar tag markup yang dapat ditelusuri.
• Kolom Angka - angka floating point.
• Kolom Tanggal - objek tanggal.
• Kolom Geopoint - objek data dengan koordinat lintang dan bujur.

Ukuran maksimum dokumen adalah 1 MB.

Indeks

Indeks menyimpan dokumen untuk diambil. Anda dapat mengambil satu dokumen berdasarkan ID-nya, serangkaian dokumen dengan ID berurutan, atau semua dokumen dalam suatu indeks. Anda juga dapat menelusuri indeks untuk mengambil dokumen yang memenuhi kriteria tertentu pada kolom dan nilainya, yang ditetapkan sebagai string kueri. Anda dapat mengelola grup dokumen dengan menempatkannya ke dalam indeks terpisah.

Tidak ada batasan jumlah dokumen dalam indeks atau jumlah indeks yang dapat Anda gunakan. Ukuran total semua dokumen dalam satu indeks dibatasi hingga 10 GB secara default. Orang yang memiliki peran Admin App Engine dapat mengirimkan permintaan dari halaman App Engine Search di konsol Google Cloud untuk meningkatkan ukuran hingga 200 GB.

Kueri

Untuk menelusuri indeks, Anda harus membuat kueri, yang memiliki string kueri dan mungkin beberapa opsi tambahan. String kueri menentukan kondisi untuk nilai dari satu atau beberapa kolom dokumen. Saat menelusuri indeks, Anda hanya akan menampilkan dokumen dalam indeks dengan kolom yang memenuhi kueri.

Kueri paling sederhana, terkadang disebut "penelusuran global" adalah string yang hanya berisi nilai kolom. Penelusuran ini menggunakan string yang menelusuri dokumen yang berisi kata "mawar" dan "air":

index.search("rose water");

Fungsi ini menelusuri dokumen dengan kolom tanggal yang berisi tanggal 4 Juli 1776, atau kolom teks yang menyertakan string "1776-07-04":

index.search("1776-07-04");

String kueri juga bisa lebih spesifik. Kolom ini dapat berisi satu atau beberapa istilah, masing-masing memberi nama kolom dan batasan pada nilai kolom. Bentuk istilah yang tepat tergantung pada jenis kolom. Misalnya, dengan anggapan ada kolom teks yang disebut "produk", dan kolom angka yang disebut "harga", berikut adalah string kueri dengan dua istilah:

// search for documents with pianos that cost less than $5000
index.search("product = piano AND price < 5000");

Opsi kueri, seperti namanya, tidak diperlukan. Fitur ini mengaktifkan berbagai fitur:

• Mengontrol berapa banyak dokumen yang ditampilkan di hasil penelusuran.
• Menentukan kolom dokumen yang akan disertakan dalam hasil. Defaultnya adalah menyertakan semua kolom dari dokumen asli. Anda dapat menentukan bahwa hasilnya hanya menyertakan subset kolom (dokumen asli tidak terpengaruh).
• Mengurutkan hasil.
• Membuat "kolom komputasi" untuk dokumen menggunakan FieldExpressions dan kolom teks ringkas menggunakan cuplikan.
• Mendukung penomoran halaman melalui hasil penelusuran dengan hanya menampilkan sebagian dokumen yang cocok di setiap kueri (menggunakan offset dan kursor)

Sebaiknya lakukan logging string kueri dalam aplikasi Anda jika Anda ingin menyimpan data kueri yang telah dieksekusi.

Hasil penelusuran

Panggilan ke search() hanya dapat menampilkan dokumen yang cocok dalam jumlah terbatas. Penelusuran Anda mungkin akan menemukan lebih banyak dokumen daripada yang dapat ditampilkan dalam satu panggilan. Setiap panggilan penelusuran menampilkan instance class Results, yang berisi informasi tentang jumlah dokumen yang ditemukan dan jumlah dokumen ditampilkan, bersama dengan daftar dokumen yang ditampilkan. Anda dapat mengulangi penelusuran yang sama, menggunakan kursor atau offset untuk mengambil kumpulan lengkap dokumen yang cocok.

Materi pelatihan tambahan

Selain dokumentasi ini, Anda dapat membaca kelas pelatihan dua bagian tentang Search API di Akademi Google Developer. (Meskipun class menggunakan Python API, Anda bisa mendapatkan diskusi tambahan tentang konsep Penelusuran yang berguna.)

Dokumen dan kolom

Class Document mewakili dokumen. Setiap dokumen memiliki ID dokumen dan daftar kolom.

ID dokumen

Setiap dokumen dalam indeks harus memiliki ID dokumen yang unik, atau doc_id. ID dapat digunakan untuk mengambil dokumen dari indeks tanpa melakukan penelusuran. Secara default, Search API otomatis membuat doc_id saat dokumen dibuat. Anda juga dapat menentukan doc_id sendiri saat membuat dokumen. doc_id hanya boleh berisi karakter ASCII yang terlihat dan dapat dicetak (termasuk kode ASCII 33 hingga 126) dan tidak lebih dari 500 karakter. ID dokumen tidak dapat diawali dengan tanda seru ('!'), dan tidak boleh diawali serta diakhiri dengan garis bawah ganda ("__").

Meskipun mudah membuat ID dokumen unik yang dapat dibaca dan bermakna, Anda tidak dapat menyertakan doc_id dalam penelusuran. Pertimbangkan skenario ini: Anda memiliki indeks dengan dokumen yang mewakili bagian-bagian, menggunakan nomor seri bagian tersebut sebagai doc_id. Akan sangat efisien untuk mengambil dokumen untuk satu bagian mana pun. Namun, mustahil untuk menelusuri rentang nomor seri beserta nilai kolom lainnya, seperti tanggal pembelian. Menyimpan nomor seri dalam kolom atom akan memecahkan masalah.

Kolom dokumen

Dokumen berisi kolom yang memiliki nama, jenis, dan satu nilai dari jenis tersebut. Dua kolom atau lebih dapat memiliki nama yang sama, tetapi jenisnya berbeda. Misalnya, Anda dapat menentukan dua kolom dengan nama "usia": satu dengan jenis teks (nilai "dua puluh dua"), satunya lagi dengan jenis angka (nilai 22).

Nama kolom

Nama kolom peka huruf besar/kecil dan hanya dapat berisi karakter ASCII. Nama ini harus diawali dengan huruf dan dapat berisi huruf, angka, atau garis bawah. Nama kolom tidak boleh lebih dari 500 karakter.

Kolom multinilai

Kolom hanya boleh berisi satu nilai, yang harus cocok dengan jenis kolom. Nama kolom tidak harus unik. Dokumen dapat memiliki beberapa kolom dengan nama dan jenis yang sama, yang merupakan cara untuk menampilkan kolom dengan beberapa nilai. (Namun, kolom tanggal dan angka dengan nama yang sama tidak dapat diulang.) Dokumen juga dapat berisi beberapa kolom dengan nama yang sama dan jenis kolom yang berbeda.

Jenis kolom

Ada tiga jenis kolom yang menyimpan string karakter java.lang.String; secara kolektif kami menyebutnya sebagai kolom string:

• Kolom Teks: String dengan panjang maksimum 1024**2 karakter.
• Kolom HTML: String berformat HTML dengan panjang maksimum 1024**2 karakter.
• Kolom Atom: String dengan panjang maksimum 500 karakter.

Ada juga tiga jenis kolom yang menyimpan data non-tekstual:

• Kolom Angka: Nilai floating point presisi ganda antara -2.147.483.647 dan 2.147.483.647.
• Kolom Tanggal: java.util.Date .
• Kolom Geopoint: Titik di bumi yang dideskripsikan dengan koordinat lintang dan bujur.

Jenis kolom ditentukan menggunakan enum Field.FieldType TEXT, HTML, ATOM, NUMBER, DATE, dan GEO_POINT.

Perlakuan khusus pada kolom string dan tanggal

Jika dokumen dengan kolom tanggal, teks, atau HTML ditambahkan ke indeks, beberapa penanganan khusus akan terjadi. Akan sangat membantu untuk memahami apa yang terjadi "di balik layar" agar dapat menggunakan Search API secara efektif.

Membuat token kolom string

Saat HTML atau kolom teks diindeks, kontennya akan dibuat token. String ini dibagi menjadi token di mana pun spasi kosong atau karakter khusus (tanda baca, tanda hash, garis miring terbalik, dsb.) muncul. Indeks akan menyertakan entri untuk setiap token. Dengan ini Anda dapat menelusuri kata kunci dan frasa yang hanya terdiri dari sebagian nilai kolom. Misalnya, penelusuran "gelap" akan cocok dengan dokumen dengan kolom teks yang berisi string "malam yang gelap dan penuh badai", dan penelusuran "waktu" akan cocok dengan dokumen dengan teks yang berisi string "ini adalah sistem real-time" (sistem real-time).

Di kolom HTML, teks dalam tag markup tidak dibuat token, sehingga dokumen dengan kolom HTML yang berisi it was a <strong>dark</strong> night akan cocok dengan penelusuran untuk "night", tetapi bukan untuk "strong". Jika Anda ingin dapat menelusuri teks markup, simpan di kolom teks.

Kolom Atom tidak diberi token. Dokumen dengan kolom atom yang memiliki nilai "bad weather" hanya akan cocok dengan penelusuran untuk seluruh string "bad weather". Hasil ini tidak akan cocok dengan penelusuran "buruk" atau "cuaca" saja.

Aturan Pembuatan Token

• Karakter garis bawah (_) dan ampersand (&) tidak mengurai kata menjadi token.

• Karakter spasi kosong ini selalu mengurai kata menjadi token: spasi, enter, feed baris, tab horizontal, tab vertikal, feed formulir, dan NULL.

• Karakter ini diperlakukan sebagai tanda baca, dan akan mengurai kata-kata menjadi token:

  !	"	%	(	)
  *	,	-	|	/
  [	]	]	^	`
  :	=	>	?	@
  {	}	~	$

• Karakter dalam tabel berikut biasanya mengurai kata menjadi token, tetapi dapat ditangani secara berbeda tergantung pada konteks kemunculannya:

  Berbasis karakter	Aturan
  <	Di kolom HTML, tanda "kurang dari" menunjukkan awal tag HTML yang diabaikan.
  +	String dari satu atau beberapa tanda "plus" diperlakukan sebagai bagian dari kata jika muncul di akhir kata (C++).
  #	Tanda "hash" diperlakukan sebagai bagian dari kata jika diawali dengan a, b, c, d, e, f, g, j, atau x (a# - g# adalah not balok; j# dan x# adalah bahasa pemrograman, c# adalah keduanya.) Jika istilah diawali dengan '#' (#google), istilah tersebut diperlakukan sebagai hashtag dan hash menjadi bagian dari kata.
  '	Apostrof adalah huruf yang diawali huruf "s" diikuti dengan pemutusan kata, seperti dalam kata "Topi Joni".
  .	Jika titik desimal muncul di antara digit, ini adalah bagian dari angka (yaitu, pemisah desimal). Ini juga bisa menjadi bagian dari sebuah kata jika digunakan dalam akronim (ABC).
  -	Tanda hubung adalah bagian dari sebuah kata jika digunakan dalam akronim (IBM).

• Semua karakter 7-bit lainnya selain huruf dan angka ('AZ', 'az', '0-9') ditangani sebagai tanda baca dan memecah kata menjadi token.

• Sisanya diurai sebagai karakter UTF-8.

Catatan: Bahasa non-barat, seperti Jepang dan China, menggunakan aturan tokenisasi lainnya.

Akronim

Tokenisasi menggunakan aturan khusus untuk mengenali akronim (string seperti "IBM", "a-b-c", atau "C I A"). Akronim adalah string yang terdiri dari satu karakter alfabet, dengan karakter pemisah yang sama di antara semuanya. Pemisah yang valid adalah titik, tanda hubung, atau sejumlah spasi. Karakter pemisah akan dihapus dari string jika akronim diberi token. Jadi, contoh string yang disebutkan di atas menjadi token "ibm", "abc", dan "cia". Teks asli akan tetap berada di kolom dokumen.

Saat menangani akronim, perhatikan bahwa:

• Akronim tidak boleh berisi lebih dari 21 huruf. String akronim yang valid dengan lebih dari 21 huruf akan dipecah menjadi serangkaian akronim, masing-masing terdiri dari 21 huruf atau kurang.
• Jika huruf dalam akronim dipisahkan dengan spasi, semua huruf harus dalam kapitalisasi yang sama. Akronim yang dibuat dengan titik dan tanda hubung dapat menggunakan huruf besar/kecil campuran.
• Saat menelusuri akronim, Anda dapat memasukkan bentuk kanonis akronim (string tanpa pemisah), atau akronim yang diberi tanda hubung dengan tanda hubung atau titik (tetapi tidak keduanya) di antara hurufnya. Jadi, teks "IBM" dapat diambil dengan istilah pencarian "I-B-M", "I.B.M", atau "IBM".

Akurasi kolom tanggal

Saat membuat kolom tanggal dalam dokumen, Anda menetapkan nilainya ke java.util.Date . Untuk tujuan pengindeksan dan penelusuran kolom tanggal, komponen waktu apa pun diabaikan dan tanggal dikonversi ke jumlah hari sejak 1/1/1970 UTC. Artinya, meskipun kolom tanggal dapat berisi nilai waktu yang tepat, kueri tanggal hanya dapat menentukan nilai kolom tanggal dalam format yyyy-mm-dd. Hal ini juga berarti urutan kolom tanggal yang diurutkan dengan tanggal yang sama tidak ditentukan dengan baik.

Properti dokumen lainnya

Peringkat dokumen adalah bilangan bulat positif yang menentukan pengurutan default dokumen yang ditampilkan dari penelusuran. Secara default, peringkat ditetapkan pada saat dokumen dibuat ke jumlah detik sejak 1 Januari 2011. Anda dapat menetapkan peringkat secara eksplisit saat membuat dokumen. Menetapkan peringkat yang sama ke banyak dokumen adalah ide yang buruk, dan Anda tidak boleh memberikan lebih dari 10000 dokumen dengan peringkat yang sama. Jika menentukan opsi pengurutan, Anda dapat menggunakan peringkat sebagai kunci pengurutan. Perhatikan bahwa saat peringkat digunakan dalam ekspresi urutan atau ekspresi kolom, ini disebut sebagai _rank.

Properti lokalitas menentukan bahasa yang digunakan untuk mengenkode kolom.

Lihat halaman referensi class Document untuk mengetahui detail selengkapnya tentang atribut ini.

Menautkan dari dokumen ke resource lainnya

Anda dapat menggunakan doc_id dokumen dan kolom lainnya sebagai link ke resource lain dalam aplikasi Anda. Misalnya, jika menggunakan Blobstore, Anda dapat mengaitkan dokumen ke blob tertentu dengan menetapkan doc_id atau nilai kolom Atom ke BlobKey data.

Membuat dokumen

Untuk membuat dokumen, minta builder baru menggunakan metode Document.newBuilder(). Setelah memiliki akses ke builder, aplikasi dapat menentukan ID dokumen opsional dan menambahkan kolom.

Kolom, seperti dokumen, dibuat menggunakan builder. Metode Field.newBuilder() menampilkan builder kolom yang memungkinkan Anda menentukan nama dan nilai kolom. Jenis kolom secara otomatis ditentukan dengan memilih metode yang ditetapkan. Misalnya, untuk menunjukkan bahwa kolom menyimpan teks biasa, panggil setText(). Kode berikut membuat dokumen dengan kolom yang merepresentasikan sambutan buku tamu.

User currentUser = UserServiceFactory.getUserService().getCurrentUser();
String userEmail = currentUser == null ? "" : currentUser.getEmail();
String userDomain = currentUser == null ? "" : currentUser.getAuthDomain();
String myDocId = "PA6-5000";
Document doc =
    Document.newBuilder()
        // Setting the document identifer is optional.
        // If omitted, the search service will create an identifier.
        .setId(myDocId)
        .addField(Field.newBuilder().setName("content").setText("the rain in spain"))
        .addField(Field.newBuilder().setName("email").setText(userEmail))
        .addField(Field.newBuilder().setName("domain").setAtom(userDomain))
        .addField(Field.newBuilder().setName("published").setDate(new Date()))
        .build();

Catatan: Saat membuat dokumen, Anda harus menentukan semua atributnya menggunakan metode class Document.Builder. Anda tidak dapat menambah, membuang, atau menghapus kolom, maupun mengubah ID atau atribut lainnya setelah dokumen dibuat. Kolom tanggal dan geopoint harus diberi nilai bukan null. Kolom Atom, teks, HTML, dan angka boleh kosong.

Untuk mengakses kolom dalam dokumen, gunakan getOnlyField():

String coverLetter = document.getOnlyField("coverLetter").getText();
String resume = document.getOnlyField("resume").getHTML();
String fullName = document.getOnlyField("fullName").getAtom();
Date submissionDate = document.getOnlyField("submissionDate").getDate();

Bekerja dengan indeks

Menempatkan dokumen ke dalam indeks

Saat Anda memasukkan dokumen ke dalam indeks, dokumen tersebut akan disalin ke penyimpanan persisten dan setiap kolomnya akan diindeks sesuai dengan nama, jenis, dan doc_id-nya.

Contoh kode berikut menunjukkan cara mengakses Indeks dan memasukkan dokumen ke dalamnya. Langkah-langkahnya adalah:

• Buat IndexSpec
• Buat SearchService
• Panggil SearchService.getIndex() untuk membuat instance Indeks.
• Panggil Index.put() untuk menambahkan dokumen ke indeks.

public static void indexADocument(String indexName, Document document)
    throws InterruptedException {
  IndexSpec indexSpec = IndexSpec.newBuilder().setName(indexName).build();
  Index index = SearchServiceFactory.getSearchService().getIndex(indexSpec);

  final int maxRetry = 3;
  int attempts = 0;
  int delay = 2;
  while (true) {
    try {
      index.put(document);
    } catch (PutException e) {
      if (StatusCode.TRANSIENT_ERROR.equals(e.getOperationResult().getCode())
          && ++attempts < maxRetry) { // retrying
        Thread.sleep(delay * 1000);
        delay *= 2; // easy exponential backoff
        continue;
      } else {
        throw e; // otherwise throw
      }
    }
    break;
  }
}

Anda dapat meneruskan hingga 200 dokumen sekaligus ke metode put(). Batching puts lebih efisien daripada menambahkan dokumen satu per satu.

Jika Anda memasukkan dokumen ke dalam indeks, dan indeks sudah berisi dokumen dengan doc_id yang sama, dokumen baru akan menggantikan dokumen lama. Peringatan tidak diberikan. Anda dapat memanggil Index.get(id) sebelum membuat atau menambahkan dokumen ke indeks untuk memeriksa apakah doc_id tertentu sudah ada.

Perhatikan bahwa membuat instance class Index tidak menjamin bahwa indeks persisten benar-benar ada. Indeks persisten dibuat saat pertama kali Anda menambahkan dokumen ke dalamnya dengan metode put. Jika Anda ingin memeriksa apakah suatu indeks benar-benar ada atau tidak sebelum mulai menggunakannya, gunakan metode SearchService.getIndexes().

Mengupdate dokumen

Dokumen tidak dapat diubah setelah Anda menambahkannya ke indeks. Anda tidak dapat menambahkan atau menghapus kolom, atau mengubah nilai kolom. Namun, Anda dapat mengganti dokumen dengan dokumen baru yang memiliki doc_id yang sama.

Mengambil dokumen dengan doc_id

Ada dua cara untuk mengambil dokumen dari indeks menggunakan ID dokumen:

• Gunakan Index.get() untuk mengambil satu dokumen berdasarkan doc_id-nya.
• Gunakan Index.getRange() untuk mengambil sekelompok dokumen berurutan yang diurutkan berdasarkan doc_id.

Setiap panggilan ditunjukkan dalam contoh di bawah.

IndexSpec indexSpec = IndexSpec.newBuilder().setName(INDEX).build();
Index index = SearchServiceFactory.getSearchService().getIndex(indexSpec);

// Fetch a single document by its  doc_id
Document doc = index.get("AZ125");

// Fetch a range of documents by their doc_ids
GetResponse<Document> docs =
    index.getRange(GetRequest.newBuilder().setStartId("AZ125").setLimit(100).build());

Menelusuri dokumen berdasarkan isinya

Untuk mengambil dokumen dari indeks, buat string kueri dan panggil Index.search(). String kueri dapat langsung diteruskan sebagai argumen, atau Anda dapat menyertakan string dalam objek Kueri yang diteruskan sebagai argumen. Secara default, search() menampilkan dokumen yang cocok dan diurutkan dalam urutan menurun. Untuk mengontrol jumlah dokumen yang ditampilkan, cara pengurutannya, atau menambahkan kolom komputasi ke hasil, Anda perlu menggunakan objek Query, yang berisi string kueri dan juga dapat menentukan opsi pencarian dan pengurutan lainnya.

final int maxRetry = 3;
int attempts = 0;
int delay = 2;
while (true) {
  try {
    String queryString = "product = piano AND price < 5000";
    Results<ScoredDocument> results = getIndex().search(queryString);

    // Iterate over the documents in the results
    for (ScoredDocument document : results) {
      // handle results
      out.print("maker: " + document.getOnlyField("maker").getText());
      out.println(", price: " + document.getOnlyField("price").getNumber());
    }
  } catch (SearchException e) {
    if (StatusCode.TRANSIENT_ERROR.equals(e.getOperationResult().getCode())
        && ++attempts < maxRetry) {
      // retry
      try {
        Thread.sleep(delay * 1000);
      } catch (InterruptedException e1) {
        // ignore
      }
      delay *= 2; // easy exponential backoff
      continue;
    } else {
      throw e;
    }
  }
  break;
}

Menghapus indeks

Setiap indeks terdiri dari dokumen yang diindeks dan skema indeks. Untuk menghapus indeks, hapus semua dokumen dalam indeks, lalu hapus skema indeks tersebut.

Anda dapat menghapus dokumen dalam indeks dengan menentukan doc_id dari satu atau beberapa dokumen yang ingin dihapus ke metode delete(). Anda harus menghapus dokumen dalam batch untuk meningkatkan efisiensi. Anda dapat meneruskan hingga 200 ID dokumen sekaligus ke metode delete().

try {
  // looping because getRange by default returns up to 100 documents at a time
  while (true) {
    List<String> docIds = new ArrayList<>();
    // Return a set of doc_ids.
    GetRequest request = GetRequest.newBuilder().setReturningIdsOnly(true).build();
    GetResponse<Document> response = getIndex().getRange(request);
    if (response.getResults().isEmpty()) {
      break;
    }
    for (Document doc : response) {
      docIds.add(doc.getId());
    }
    getIndex().delete(docIds);
  }
} catch (RuntimeException e) {
  LOG.log(Level.SEVERE, "Failed to delete documents", e);
}

Anda dapat meneruskan hingga 200 dokumen sekaligus ke metode delete(). Membuat batch penghapusan lebih efisien daripada menanganinya satu per satu.

Konsistensi tertunda

Saat Anda memasukkan, memperbarui, atau menghapus dokumen di indeks, perubahan akan diterapkan di beberapa pusat data. Ini biasanya terjadi dengan cepat, tetapi waktu yang dibutuhkan dapat bervariasi. Search API menjamin konsistensi tertunda. Artinya, dalam beberapa kasus, penelusuran atau pengambilan satu atau beberapa dokumen mungkin menampilkan hasil yang tidak merefleksikan perubahan terbaru.

Menentukan ukuran indeks

Indeks menyimpan dokumen untuk diambil. Anda dapat mengambil satu dokumen berdasarkan ID-nya, serangkaian dokumen dengan ID berurutan, atau semua dokumen dalam suatu indeks. Anda juga dapat menelusuri indeks untuk mengambil dokumen yang memenuhi kriteria tertentu pada kolom dan nilainya, yang ditetapkan sebagai string kueri. Anda dapat mengelola grup dokumen dengan menempatkannya ke dalam indeks terpisah. Tidak ada batasan jumlah dokumen dalam indeks atau jumlah indeks yang dapat Anda gunakan. Secara default, ukuran total semua dokumen dalam satu indeks dibatasi hingga 10 GB, tetapi dapat ditingkatkan hingga 200 GB dengan mengirimkan permintaan dari halaman App Engine Search konsol Google Cloud. Metode Index.getStorageLimit() menampilkan ukuran indeks maksimum yang diizinkan.

Metode Index.getStorageUsage() adalah perkiraan jumlah ruang penyimpanan yang digunakan oleh indeks. Angka ini merupakan perkiraan karena sistem pemantauan indeks tidak berjalan secara berkelanjutan; penggunaan sebenarnya dihitung secara berkala. storage_usage disesuaikan di antara titik pengambilan sampel dengan memperhitungkan penambahan dokumen, tetapi tidak penghapusan.

Skema indeks

Setiap indeks memiliki skema yang menunjukkan semua nama kolom dan jenis kolom yang muncul dalam dokumen yang ada di dalamnya. Anda tidak dapat menetapkan skema sendiri. Skema dipertahankan secara dinamis; skema tersebut diupdate ketika dokumen ditambahkan ke indeks. Skema sederhana mungkin terlihat seperti ini, dalam bentuk yang menyerupai JSON:

{'comment': ['TEXT'], 'date': ['DATE'], 'author': ['TEXT'], 'count': ['NUMBER']}

Setiap kunci dalam kamus adalah nama dari kolom dokumen. Nilai kunci adalah daftar jenis kolom yang digunakan dengan nama kolom tersebut. Jika Anda telah menggunakan nama kolom yang sama dengan jenis kolom yang berbeda, skema akan mencantumkan lebih dari satu jenis kolom untuk satu nama kolom, seperti ini:

{'ambiguous-integer': ['TEXT', 'NUMBER', 'ATOM']}

Setelah muncul dalam skema, kolom tidak dapat dihapus. Tidak ada cara untuk menghapus kolom, meskipun indeks tidak lagi berisi dokumen dengan nama kolom tersebut.

Anda dapat melihat skema untuk indeks Anda seperti ini:

GetResponse<Index> response =
    SearchServiceFactory.getSearchService()
        .getIndexes(GetIndexesRequest.newBuilder().setSchemaFetched(true).build());

// List out elements of each Schema
for (Index index : response) {
  Schema schema = index.getSchema();
  for (String fieldName : schema.getFieldNames()) {
    List<FieldType> typesForField = schema.getFieldTypes(fieldName);
    // Just printing out the field names and types
    for (FieldType type : typesForField) {
      out.println(index.getName() + ":" + fieldName + ":" + type.name());
    }
  }
}

Perhatikan bahwa panggilan ke GetIndexes() tidak dapat menampilkan lebih dari 1.000 indeks. Untuk mengambil lebih banyak indeks, panggil metode tersebut berulang kali, menggunakan setStartIndexName() beserta GetIndexesRequest.Builder.

Skema tidak mendefinisikan "class" dalam arti pemrograman objek. Sejauh Search API berkaitan, setiap dokumen bersifat unik dan indeks dapat berisi berbagai jenis dokumen. Jika ingin memperlakukan kumpulan objek dengan daftar kolom yang sama seperti instance class, ini merupakan abstraksi yang harus Anda terapkan dalam kode. Misalnya, Anda dapat memastikan bahwa semua dokumen dengan kumpulan kolom yang sama disimpan di indeksnya sendiri. Skema indeks dapat dilihat sebagai definisi class, dan setiap dokumen dalam indeks akan menjadi instance class.

Melihat indeks di Konsol Google Cloud

Di Konsol Google Cloud, Anda dapat melihat informasi tentang indeks aplikasi dan dokumen yang terdapat di dalamnya. Mengklik nama indeks akan menampilkan dokumen yang ada di indeks. Anda akan melihat semua kolom skema yang ditentukan untuk indeks tersebut; untuk setiap dokumen dengan kolom nama tersebut, Anda akan melihat nilai kolom. Anda juga dapat menerbitkan kueri pada data indeks langsung dari konsol.

Kuota Search API

Search API memiliki beberapa kuota gratis:

Panggilan API atau resource	Kuota Gratis
Total penyimpanan (dokumen dan indeks)	0,25 GB
Kueri	1000 kueri per hari
Menambahkan dokumen ke indeks	0,01 GB per hari

Search API menerapkan batas ini untuk memastikan keandalan layanan. Ini berlaku untuk aplikasi gratis dan berbayar:

Resource	Kuota Keamanan
Penggunaan kueri maksimum	100 menit gabungan waktu eksekusi kueri per menit
Jumlah maksimum dokumen yang ditambahkan atau dihapus	15000 per menit
Ukuran maksimum per indeks (jumlah indeks tak terbatas yang diizinkan)	10 GB

Penggunaan API dihitung dengan cara yang berbeda, bergantung pada jenis panggilan:

• Index.search(): Setiap panggilan API dihitung sebagai satu kueri; waktu eksekusinya setara dengan latensi panggilan.
• Index.put(): Saat Anda menambahkan dokumen untuk mengindeks ukuran setiap dokumen dan jumlah dokumen diperhitungkan dalam kuota pengindeksan.
• Semua panggilan Search API lainnya dihitung berdasarkan jumlah operasi yang dilibatkan:
  • SearchService.getIndexes() : 1 operasi dihitung untuk setiap indeks yang benar-benar ditampilkan, atau 1 operasi jika tidak ada yang ditampilkan.
  • Index.get() dan Index.getRange() : 1 operasi dihitung untuk setiap dokumen yang benar-benar ditampilkan, atau 1 operasi jika tidak ada yang ditampilkan.
  • Index.delete() : 1 operasi dihitung untuk setiap dokumen dalam permintaan, atau 1 operasi jika permintaan kosong.

Kuota pada throughput kueri diberlakukan sehingga satu pengguna tidak dapat memonopoli layanan penelusuran. Karena kueri dapat dieksekusi secara bersamaan, setiap aplikasi diizinkan untuk menjalankan kueri yang memakai hingga 100 menit waktu eksekusi per satu menit waktu jam Jika menjalankan banyak kueri singkat, Anda mungkin tidak akan mencapai batas ini. Setelah Anda melebihi kuota, kueri berikutnya akan gagal hingga irisan waktu berikutnya, yaitu saat kuota dipulihkan. Kuota tidak diberlakukan secara ketat dalam irisan satu menit; variasi algoritma kebocoran bucket digunakan untuk mengontrol bandwidth penelusuran dalam kelipatan lima detik.

Informasi selengkapnya tentang kuota dapat ditemukan di halaman Kuota. Jika aplikasi mencoba melebihi jumlah ini, error kuota tidak mencukupi akan muncul.

Perhatikan bahwa meskipun batasan ini diterapkan berdasarkan menit, konsol menampilkan total harian untuk setiap batas. Pelanggan dengan dukungan Silver, Gold, atau Platinum dapat meminta batas throughput yang lebih tinggi dengan menghubungi perwakilan dukungan mereka.

Harga Search API

Biaya berikut dikenakan untuk penggunaan di luar kuota gratis:

Resource	Biaya
Total penyimpanan (dokumen dan indeks)	$0,18 per GB per bulan
Kueri	$0,50 per 10 ribu kueri
Pengindeksan dokumen yang dapat ditelusuri	$2,00 per GB

Informasi tambahan tentang harga ada di halaman Harga.