Search API untuk layanan paket lama

Go Java PHP Python

Search API menyediakan model untuk mengindeks dokumen yang berisi data terstruktur. Anda dapat menelusuri indeks, serta mengatur dan 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.

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 Python , lihat halaman Mengupgrade ke runtime generasi kedua untuk mempelajari opsi migrasi untuk layanan paket lama.

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 dengan tahun/bulan/hari dan waktu opsional.
• 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":

def simple_search(index):
    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":

def search_date(index):
    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:

def search_terms(index):
    # 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 SearchResults , yang berisi informasi tentang jumlah dokumen yang ditemukan dan jumlah dokumen yang 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. Kelas ini menyertakan contoh aplikasi Python.

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. Sebuah dokumen dapat memiliki beberapa field dengan nama yang sama dan jenis yang sama, yang merupakan cara untuk mewakili field dengan beberapa masing-masing. (Namun, kolom tanggal dan angka dengan nama yang sama tidak dapat diulang.) Dokumen juga dapat berisi beberapa kolom dengan nama yang sama dan berbeda jenis kolom.

Jenis kolom

Ada tiga jenis kolom yang menyimpan string karakter; 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: datetime.date atau datetime.datetime .
• Kolom Geopoint: Titik di bumi yang dideskripsikan dengan koordinat lintang dan bujur.

Jenis kolom ditentukan oleh class TextField, HtmlField, AtomField, NumberField, DateField, dan GeoField.

Perlakuan khusus string dan tanggal ladang

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 bergantung 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 datetime.date atau datetime.datetime . Perhatikan bahwa hanya objek tanggal dan waktu "naif" pada Python yang dapat digunakan. Objek "Aware" tidak diizinkan. Untuk tujuan pengindeksan dan penelusuran kolom tanggal waktu