Penelusuran paket menyediakan klien untuk layanan penelusuran App Engine.
Operasi Dasar
Indeks berisi dokumen. Setiap indeks diidentifikasi dengan namanya: string ASCII yang dapat dibaca manusia.
Dalam sebuah indeks, dokumen dikaitkan dengan ID, yang juga merupakan string ASCII yang dapat dibaca manusia. Isi dokumen adalah pemetaan dari nama kolom yang peka huruf besar/kecil ke nilai. Jenis yang valid untuk nilai kolom adalah:
- string,
- search.Atom,
- search.HTML,
- time.Time (disimpan dengan presisi milidetik),
- float64 (nilai antara -2.147.483.647 dan 2.147.483.647 inklusif),
- appengine.GeoPoint.
Metode Get dan Put pada Indeks memuat dan menyimpan dokumen. Konten dokumen biasanya direpresentasikan oleh pointer struct.
Contoh kode:
type Doc struct {
Author string
Comment string
Creation time.Time
}
index, err := search.Open("comments")
if err != nil {
return err
}
newID, err := index.Put(ctx, "", &Doc{
Author: "gopher",
Comment: "the truth of the matter",
Creation: time.Now(),
})
if err != nil {
return err
}
Satu dokumen dapat diambil melalui ID-nya. Teruskan struct tujuan ke Get untuk menyimpan dokumen yang dihasilkan.
var doc Doc
err := index.Get(ctx, id, &doc)
if err != nil {
return err
}
Menelusuri dan Mencantumkan Dokumen
Indeks memiliki dua metode untuk mengambil beberapa dokumen sekaligus: Penelusuran dan Daftar.
Menelusuri indeks untuk sebuah kueri akan menghasilkan iterator. Seperti halnya iterator dari datastore paket, teruskan struct tujuan ke Next untuk mendekode hasil berikutnya. Next akan menampilkan Done ketika iterator habis.
for t := index.Search(ctx, "Comment:truth", nil); ; {
var doc Doc
id, err := t.Next(&doc)
if err == search.Done {
break
}
if err != nil {
return err
}
fmt.Fprintf(w, "%s -> %#v\n", id, doc)
}
Penelusuran menggunakan kueri string untuk menentukan dokumen mana yang akan ditampilkan. Kueri bisa sederhana, seperti satu kata yang akan dicocokkan, atau kompleks. Bahasa kueri dijelaskan di https://cloud.google.com/appengine/docs/standard/go/search/query_strings
Penelusuran juga menggunakan struct SearchOptions opsional yang memberikan kontrol lebih besar atas cara hasil dihitung dan ditampilkan.
Panggil Daftar untuk melakukan iterasi pada semua dokumen dalam indeks.
for t := index.List(ctx, nil); ; {
var doc Doc
id, err := t.Next(&doc)
if err == search.Done {
break
}
if err != nil {
return err
}
fmt.Fprintf(w, "%s -> %#v\n", id, doc)
}
Kolom dan Faset
Isi dokumen dapat diwakili oleh berbagai jenis. Ini biasanya merupakan pointer struct, tetapi juga dapat direpresentasikan oleh jenis apa pun yang menerapkan antarmuka FieldLoadSaver. Dengan FieldLoadSaver, metadata dapat ditetapkan untuk dokumen dengan jenis DocumentMetadata. Pointer struct diketik dengan lebih kuat dan lebih mudah digunakan; FieldLoadSavers lebih fleksibel.
Isi dokumen dapat dinyatakan dengan dua cara: kolom dan faset.
Kolom adalah cara paling umum dalam memberikan konten untuk dokumen. Kolom dapat menyimpan data dalam beberapa jenis dan dapat dicocokkan dalam penelusuran menggunakan string kueri.
Faset memberikan cara untuk melampirkan informasi kategoris ke dokumen. Satu-satunya jenis yang valid untuk faset adalah search.Atom dan float64. Faset memungkinkan hasil penelusuran berisi ringkasan kategori yang cocok dalam suatu penelusuran, dan membatasi penelusuran agar hanya cocok dengan kategori tertentu.
Secara default, untuk pointer struct, semua kolom struct digunakan sebagai kolom dokumen, dan nama kolom yang digunakan sama dengan yang ada pada struct (sehingga harus diawali dengan huruf besar). Kolom struct mungkin memiliki tag search:"name,options". Nama harus diawali dengan huruf dan
hanya terdiri dari karakter kata. Nama tag "-" berarti kolom tersebut akan diabaikan. Jika opsinya adalah "faset", maka kolom struct akan digunakan sebagai faset dokumen. Jika opsinya adalah "" maka koma dapat dihilangkan. Tidak ada opsi lain yang dikenali.
Contoh kode:
// A and B are renamed to a and b.
// A, C and I are facets.
// D's tag is equivalent to having no tag at all (E).
// F and G are ignored entirely by the search package.
// I has tag information for both the search and json packages.
type TaggedStruct struct {
A float64 `search:"a,facet"`
B float64 `search:"b"`
C float64 `search:",facet"`
D float64 `search:""`
E float64
F float64 `search:"-"`
G float64 `search:"-,facet"`
I float64 `search:",facet" json:"i"`
}
Antarmuka FieldLoadSaver
Konten dokumen juga dapat direpresentasikan oleh jenis apa pun yang mengimplementasikan antarmuka FieldLoadSaver. Jenis ini mungkin berupa pointer struct, tetapi sebenarnya tidak demikian. Paket penelusuran akan memanggil Muat saat memuat konten dokumen, dan Simpan saat menyimpannya. Selain bagian Kolom, metode Muat and Simpan juga menggunakan jenis DocumentMetadata untuk memberikan informasi tambahan tentang dokumen (seperti Peringkat, atau kumpulan Faset). Kemungkinan penggunaan antarmuka ini meliputi mendapatkan kolom yang tidak disimpan, memverifikasi kolom, atau menetapkan bahasa tertentu untuk kolom string dan HTML.
Contoh kode:
type CustomFieldsExample struct {
// Item's title and which language it is in.
Title string
Lang string
// Mass, in grams.
Mass int
}
func (x *CustomFieldsExample) Load(fields []search.Field, meta *search.DocumentMetadata) error {
// Load the title field, failing if any other field is found.
for _, f := range fields {
if f.Name != "title" {
return fmt.Errorf("unknown field %q", f.Name)
}
s, ok := f.Value.(string)
if !ok {
return fmt.Errorf("unsupported type %T for field %q", f.Value, f.Name)
}
x.Title = s
x.Lang = f.Language
}
// Load the mass facet, failing if any other facet is found.
for _, f := range meta.Facets {
if f.Name != "mass" {
return fmt.Errorf("unknown facet %q", f.Name)
}
m, ok := f.Value.(float64)
if !ok {
return fmt.Errorf("unsupported type %T for facet %q", f.Value, f.Name)
}
x.Mass = int(m)
}
return nil
}
func (x *CustomFieldsExample) Save() ([]search.Field, *search.DocumentMetadata, error) {
fields := []search.Field{
{Name: "title", Value: x.Title, Language: x.Lang},
}
meta := &search.DocumentMetadata{
Facets: {
{Name: "mass", Value: float64(x.Mass)},
},
}
return fields, meta, nil
}
Variabel
ErrInvalidDocumentType, ErrNoSuchDocument, ErrTooManyDocuments
var (
// ErrInvalidDocumentType is returned when methods like Put, Get or Next
// are passed a dst or src argument of invalid type.
ErrInvalidDocumentType = errors.New("search: invalid document type")
// ErrNoSuchDocument is returned when no document was found for a given ID.
ErrNoSuchDocument = errors.New("search: no such document")
// ErrTooManyDocuments is returned when the user passes too many documents to
// PutMulti or DeleteMulti.
ErrTooManyDocuments = fmt.Errorf("search: too many documents given to put or delete (max is %d)", maxDocumentsPerPutDelete)
)Selesai
Done akan ditampilkan ketika iterasi kueri telah selesai.
Functions
func LoadStruct
LoadStruct memuat kolom dari f ke dst. dst harus berupa pointer struct.
Atom
type Atom stringAtom adalah kolom dokumen yang kontennya diindeks sebagai satu string yang tidak terlihat.
Kursor
type Cursor stringKursor mewakili posisi iterator.
Nilai string kursor aman untuk web. Data tersebut dapat disimpan dan dipulihkan untuk digunakan nanti.
DocumentMetadata
type DocumentMetadata struct {
// Rank is an integer specifying the order the document will be returned in
// search results. If zero, the rank will be set to the number of seconds since
// 2011-01-01 00:00:00 UTC when being Put into an index.
Rank int
// Facets is the set of facets for this document.
Facets []Facet
}DocumentMetadata adalah struct yang berisi informasi yang mendeskripsikan dokumen tertentu.
ErrFacetMismatch
ErrFacetMismatch ditampilkan saat suatu faset akan dimuat ke dalam jenis yang berbeda dengan tempat penyimpanannya, atau saat kolom tidak ada atau tidak diekspor dalam struktur tujuan. StructType adalah jenis struct yang ditunjuk oleh argumen tujuan yang diteruskan ke Iterator.Next.
func (*ErrFacetMismatch) Error
func (e *ErrFacetMismatch) Error() stringErrFieldMismatch
ErrFieldMismatch ditampilkan saat kolom akan dimuat ke dalam yang berbeda dengan tempat asalnya disimpan, atau saat kolom tidak ada atau tidak diekspor di struktur tujuan.
func (*ErrFieldMismatch) Error
func (e *ErrFieldMismatch) Error() stringFaset
type Facet struct {
// Name is the facet name. A valid facet name matches /[A-Za-z][A-Za-z0-9_]*/.
// A facet name cannot be longer than 500 characters.
Name string
// Value is the facet value.
//
// When being used in documents (for example, in
// DocumentMetadata.Facets), the valid types are:
// - search.Atom,
// - float64.
//
// When being used in SearchOptions.Refinements or being returned
// in FacetResult, the valid types are:
// - search.Atom,
// - search.Range.
Value interface{}
}Faset adalah pasangan nama/nilai yang digunakan untuk menambahkan informasi kategoris ke dokumen.
FacetResult
type FacetResult struct {
Facet
// Count is the number of times this specific facet and value appeared in the
// matching documents.
Count int
}FacetResult mewakili berapa kali faset dan nilai tertentu muncul dalam dokumen yang cocok dengan permintaan penelusuran.
FacetSearchOption
type FacetSearchOption interface {
// contains filtered or unexported methods
}FacetSearchOption mengontrol informasi faset yang ditampilkan dalam hasil penelusuran.
func AutoFacetDiscovery
func AutoFacetDiscovery(facetLimit, valueLimit int) FacetSearchOptionAutoFacetDiscovery menampilkan FacetSearchOption yang memungkinkan penemuan faset otomatis untuk penelusuran. Penemuan faset otomatis mencari faset yang paling sering muncul secara agregat dalam dokumen yang cocok.
Jumlah maksimum faset yang ditampilkan dikontrol oleh facetLimit, dan jumlah nilai maksimum per faset menurut facetLimit. Batas nol menunjukkan batas default harus digunakan.
func FacetDiscovery
func FacetDiscovery(name string, value ...interface{}) FacetSearchOptionFacetDiscovery menampilkan FacetSearchOption yang memilih faset yang akan ditampilkan bersama hasil penelusuran. Secara default, nilai yang paling sering terjadi untuk faset tersebut akan ditampilkan. Namun, Anda juga dapat menentukan daftar Atom tertentu atau Rentang tertentu yang akan ditampilkan.
func FacetDocumentDepth
func FacetDocumentDepth(depth int) FacetSearchOptionFacetDocumentDepth menampilkan FacetSearchOption yang mengontrol jumlah dokumen yang akan dievaluasi dengan menyiapkan hasil faset.
Kolom
type Field struct {
// Name is the field name. A valid field name matches /[A-Za-z][A-Za-z0-9_]*/.
Name string
// Value is the field value. The valid types are:
// - string,
// - search.Atom,
// - search.HTML,
// - time.Time (stored with millisecond precision),
// - float64,
// - GeoPoint.
Value interface{}
// Language is a two-letter ISO 639-1 code for the field's language,
// defaulting to "en" if nothing is specified. It may only be specified for
// fields of type string and search.HTML.
Language string
// Derived marks fields that were calculated as a result of a
// FieldExpression provided to Search. This field is ignored when saving a
// document.
Derived bool
}Kolom adalah pasangan nama/nilai. Dokumen indeks penelusuran dapat dimuat dan disimpan sebagai urutan Kolom.
func SaveStruct
SaveStruct menampilkan kolom dari src sebagai bagian dari Kolom. src harus berupa pointer struct.
FieldExpression
type FieldExpression struct {
// Name is the name to use for the computed field.
Name string
// Expr is evaluated to provide a custom content snippet for each document.
// See https://cloud.google.com/appengine/docs/standard/go/search/options for
// the supported expression syntax.
Expr string
}FieldExpression menentukan ekspresi kustom yang akan dievaluasi untuk setiap hasil.
FieldList
type FieldList []FieldFieldList mengonversi Kolom [] untuk menerapkan FieldLoadSaver.
func (*FieldList) Load
func (l *FieldList) Load(f []Field, _ *DocumentMetadata) errorLoad (Muat) akan memuat semua kolom yang tersedia ke dalam l. Load ini tidak terlebih dahulu mereset *l ke slice kosong.
func (*FieldList) Save
func (l *FieldList) Save() ([]Field, *DocumentMetadata, error)Save (Simpan) menampilkan semua kolom l sebagai bagian dari Kolom.
FieldLoadSaver
type FieldLoadSaver interface {
Load([]Field, *DocumentMetadata) error
Save() ([]Field, *DocumentMetadata, error)
}FieldLoadSaver dapat dikonversi dari dan menjadi bagian dari Kolom dengan metadata dokumen tambahan.
HTML
type HTML stringHTML adalah kolom dokumen yang kontennya diindeks sebagai HTML. Hanya node teks yang diindeks: "foobar" akan diperlakukan sebagai "foobar".
Indeks
type Index struct {
// contains filtered or unexported fields
}Indeks adalah indeks dokumen.
func Open
Open (Buka) membuka indeks dengan nama yang diberikan. Indeks akan dibuat jika belum ada.
Nama ini adalah string ASCII yang dapat dibaca manusia. Ini tidak boleh berisi karakter spasi kosong dan tidak boleh diawali dengan "!".
func (*Index) Delete
Delete (Hapus) akan menghapus dokumen dari indeks.
func (*Index) DeleteMulti
DeleteMulti menghapus beberapa dokumen dari indeks.
Error yang ditampilkan dapat berupa instance appengine.MultiError, yang dalam hal ini berukuran sama dengan srcs dan setiap error di dalamnya akan sesuai dengan item di srcs.
func (*Index) Get
Get memuat dokumen dengan ID yang diberikan ke dst.
ID adalah string ASCII yang dapat dibaca manusia. Elemen ini tidak boleh kosong, tidak berisi karakter spasi kosong, dan tidak diawali dengan "!".
dst harus berupa pointer struct non-nil atau menerapkan antarmuka FieldLoadSaver.
ErrFieldMismatch ditampilkan saat sebuah kolom akan dimuat ke dalam jenis yang berbeda dengan tempat penyimpanannya, atau ketika kolom tidak ada atau tidak diekspor dalam struktur tujuan. ErrFieldMismatch hanya ditampilkan jika dst adalah pointer struct. Penerima dapat memutuskan apakah error ini bersifat fatal, dapat dipulihkan, atau dapat diabaikan.
func (*Index) List
func (x *Index) List(c context.Context, opts *ListOptions) *IteratorList (Daftar) mencantumkan semua dokumen dalam indeks. Dokumen-dokumen ditampilkan dengan urutan ID yang meningkat.
func (*Index) Put
Masukkan file src ke indeks. Jika ID kosong, ID baru akan dialokasikan oleh layanan dan ditampilkan. Jika ID tidak kosong, entri indeks yang ada untuk ID tersebut akan diganti.
ID adalah string ASCII yang dapat dibaca manusia. Ini tidak boleh berisi karakter spasi kosong dan tidak boleh diawali dengan "!".
src harus berupa pointer struct non-nil atau menerapkan antarmuka FieldLoadSaver.
func (*Index) PutMulti
PutMulti mirip dengan Put, tetapi lebih efisien untuk menambahkan beberapa dokumen ke indeks sekaligus.
Hingga 200 dokumen dapat ditambahkan sekaligus. ErrTooManyDocuments ditampilkan jika Anda mencoba menambahkan lebih banyak.
ID dapat berupa irisan kosong (yang berarti ID baru akan dialokasikan untuk setiap dokumen yang ditambahkan) atau irisan yang berukuran sama dengan srcs.
Error dapat berupa instance appengine.MultiError, yang dalam hal ini berukuran sama dengan srcs dan setiap error di dalamnya akan sesuai dengan item di srcs.
func (*Index) Search
Penelusuran menelusuri indeks untuk kueri tertentu.
Iterator
type Iterator struct {
// contains filtered or unexported fields
}Iterator adalah hasil penelusuran indeks untuk kueri atau daftar indeks.
func (*Iterator) Count
Jumlah menampilkan perkiraan jumlah dokumen yang cocok dengan kueri. Hanya valid untuk memanggil iterator yang dikembalikan oleh Penelusuran.
func (*Iterator) Cursor
Kursor menampilkan kursor yang terkait dengan dokumen saat ini (yaitu, dokumen yang baru saja ditampilkan oleh panggilan ke Next).
Meneruskan kursor ini pada panggilan berikutnya ke Penelusuran akan menyebabkan hasil tersebut dimulai dengan dokumen pertama setelah dokumen saat ini.
func (*Iterator) Facets
func (t *Iterator) Facets() ([][]FacetResult, error)Faset menampilkan faset yang ditemukan dalam hasil penelusuran, jika ada faset yang diminta di SearchOptions.
func (*Iterator) Next
Next menampilkan ID hasil berikutnya. Jika tidak ada hasil lagi, Done ditampilkan sebagai error.
dst harus berupa pointer struct non-nil, menerapkan antarmuka FieldLoadSaver, atau berupa nilai antarmuka dengan nilai nil. Jika diberikan, dst non-nil akan diisi dengan kolom yang diindeks. dst diabaikan jika iterator ini dibuat dengan opsi IDOnly.
ListOptions
type ListOptions struct {
// StartID is the inclusive lower bound for the ID of the returned
// documents. The zero value means all documents will be returned.
StartID string
// Limit is the maximum number of documents to return. The zero value
// indicates no limit.
Limit int
// IDsOnly indicates that only document IDs should be returned for the list
// operation; no document fields are populated.
IDsOnly bool
}ListOptions adalah opsi untuk membuat daftar dokumen dalam indeks. Meneruskan *ListOptions nil sama dengan menggunakan nilai default.
Rentang
type Range struct {
Start, End float64
}Rentang menyatakan rentang numerik dengan awal yang inklusif dan akhir eksklusif. Start dapat ditentukan sebagai matematika.Inf(-1) untuk menunjukkan tidak ada nilai minimum, dan End juga dapat ditentukan sebagai matematika.Inf(1); setidaknya salah satu dari Start atau End harus berupa angka yang terbatas.
func AtLeast
AtLeast menampilkan Rentang yang cocok dengan nilai apa pun yang lebih besar dari, atau sama dengan, min.
func LessThan
LessThan menampilkan Rentang yang cocok dengan nilai apa pun yang kurang dari maks.
Scorer
type Scorer interface {
// contains filtered or unexported methods
}Scorer mendefinisikan bagaimana sebuah dokumen diberi skor.
MatchScorer, RescoringMatchScorer
var (
// MatchScorer assigns a score based on term frequency in a document.
MatchScorer Scorer = enumScorer{pb.ScorerSpec_MATCH_SCORER}
// RescoringMatchScorer assigns a score based on the quality of the query
// match. It is similar to a MatchScorer but uses a more complex scoring
// algorithm based on match term frequency and other factors like field type.
// Please be aware that this algorithm is continually refined and can change
// over time without notice. This means that the ordering of search results
// that use this scorer can also change without notice.
RescoringMatchScorer Scorer = enumScorer{pb.ScorerSpec_RESCORING_MATCH_SCORER}
)SearchOptions
type SearchOptions struct {
// Limit is the maximum number of documents to return. The zero value
// indicates no limit.
Limit int
// IDsOnly indicates that only document IDs should be returned for the search
// operation; no document fields are populated.
IDsOnly bool
// Sort controls the ordering of search results.
Sort *SortOptions
// Fields specifies which document fields to include in the results. If omitted,
// all document fields are returned. No more than 100 fields may be specified.
Fields []string
// Expressions specifies additional computed fields to add to each returned
// document.
Expressions []FieldExpression
// Facets controls what facet information is returned for these search results.
// If no options are specified, no facet results will be returned.
Facets []FacetSearchOption
// Refinements filters the returned documents by requiring them to contain facets
// with specific values. Refinements are applied in conjunction for facets with
// different names, and in disjunction otherwise.
Refinements []Facet
// Cursor causes the results to commence with the first document after
// the document associated with the cursor.
Cursor Cursor
// Offset specifies the number of documents to skip over before returning results.
// When specified, Cursor must be nil.
Offset int
// CountAccuracy specifies the maximum result count that can be expected to
// be accurate. If zero, the count accuracy defaults to 20.
CountAccuracy int
}SearchOptions adalah opsi untuk menelusuri indeks. Meneruskan *SearchOptions nil sama dengan menggunakan nilai default.
SortExpression
type SortExpression struct {
// Expr is evaluated to provide a sorting value for each document.
// See https://cloud.google.com/appengine/docs/standard/go/search/options for
// the supported expression syntax.
Expr string
// Reverse causes the documents to be sorted in ascending order.
Reverse bool
// The default value to use when no field is present or the expresion
// cannot be calculated for a document. For text sorts, Default must
// be of type string; for numeric sorts, float64.
Default interface{}
}SortExpression menentukan dimensi tunggal untuk mengurutkan dokumen.
SortOptions
type SortOptions struct {
// Expressions is a slice of expressions representing a multi-dimensional
// sort.
Expressions []SortExpression
// Scorer, when specified, will cause the documents to be scored according to
// search term frequency.
Scorer Scorer
// Limit is the maximum number of objects to score and/or sort. Limit cannot
// be more than 10,000. The zero value indicates a default limit.
Limit int
}SortOptions mengontrol pengurutan dan penilaian hasil penelusuran.