Paket google.golang.org/appengine/search (v1.6.8)

Version latest

• 1.6.8 (latest)
• 1.6.7

Catatan: Untuk mendapatkan informasi selengkapnya tentang paket ini, seperti akses ke versi yang lebih lama, lihat paket ini di pkg.go.dev.

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

var Done = errors.New("search: query has no more results")

Done akan ditampilkan ketika iterasi kueri telah selesai.

Functions

func LoadStruct

func LoadStruct(dst interface{}, f []Field) error

LoadStruct memuat kolom dari f ke dst. dst harus berupa pointer struct.

Atom

type Atom string

Atom adalah kolom dokumen yang kontennya diindeks sebagai satu string yang tidak terlihat.

Kursor

type Cursor string

Kursor 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

type ErrFacetMismatch struct {
	StructType reflect.Type
	FacetName  string
	Reason     string
}

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() string

ErrFieldMismatch

type ErrFieldMismatch struct {
	FieldName string
	Reason    string
}

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() string

Faset

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) FacetSearchOption

AutoFacetDiscovery 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{}) FacetSearchOption

FacetDiscovery 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) FacetSearchOption

FacetDocumentDepth 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

func SaveStruct(src interface{}) ([]Field, error)

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 []Field

FieldList mengonversi Kolom [] untuk menerapkan FieldLoadSaver.

func (*FieldList) Load

func (l *FieldList) Load(f []Field, _ *DocumentMetadata) error

Load (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 string

HTML 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

func Open(name string) (*Index, error)

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

func (x *Index) Delete(c context.Context, id string) error

Delete (Hapus) akan menghapus dokumen dari indeks.

func (*Index) DeleteMulti

func (x *Index) DeleteMulti(c context.Context, ids []string) error

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

func (x *Index) Get(c context.Context, id string, dst interface{}) error

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) *Iterator

List (Daftar) mencantumkan semua dokumen dalam indeks. Dokumen-dokumen ditampilkan dengan urutan ID yang meningkat.

func (*Index) Put

func (x *Index) Put(c context.Context, id string, src interface{}) (string, error)

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

func (x *Index) PutMulti(c context.Context, ids []string, srcs []interface{}) ([]string, error)

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

func (x *Index) Search(c context.Context, query string, opts *SearchOptions) *Iterator

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

func (t *Iterator) Count() int

Jumlah menampilkan perkiraan jumlah dokumen yang cocok dengan kueri. Hanya valid untuk memanggil iterator yang dikembalikan oleh Penelusuran.

func (*Iterator) Cursor

func (t *Iterator) Cursor() 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

func (t *Iterator) Next(dst interface{}) (string, error)

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

func AtLeast(min float64) Range

AtLeast menampilkan Rentang yang cocok dengan nilai apa pun yang lebih besar dari, atau sama dengan, min.

func LessThan

func LessThan(max float64) Range

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.