elsearm

README

elsearm

elsearm is an Elasticsearch model library for Go.

Features

• Only has elastic/go-elasticsearch as a dependency.
• Easy update/remove to Elasticsearch when saving to DB.
• Can set prefix and suffix of index name.

Usage

Automatic Document Updates (with GORM)

If the ORM library support hooks, you can use Automatic Document Updates with libraries other than GORM.
This is an example of using GORM.

package models

import (
	"github.com/soranoba/elsearm"
	"gorm.io/gorm"
)

const (
	elsearmIndexerKey = "elsearm:indexer"
)

func UseElsearmIndexer(db *gorm.DB, indexer *elsearm.Indexer) *gorm.DB {
	return db.InstanceSet(elsearmIndexerKey, indexer)
}

func getElsearmIndexer(db *gorm.DB) (*elsearm.Indexer, bool) {
	val, ok := db.InstanceGet(elsearmIndexerKey)
	if !ok {
		return nil, false
	}
	indexer, ok := val.(*elsearm.Indexer)
	return indexer, ok
}

type User struct {
	ID        uint      `gorm:"primarykey" json:"id"`
	CreatedAt time.Time `json:"created_at"`
	UpdatedAt time.Time `json:"updated_at"`
}

func (u *User) AfterDelete(db *gorm.DB) error {
	if indexer, ok := getElsearmIndexer(db); ok {
		indexer.Delete(u)
	}
	return nil
}

func (u *User) AfterSave(db *gorm.DB) error {
	if indexer, ok := getElsearmIndexer(db); ok {
		indexer.Update(u)
	}
	return nil
}

func main() {
	db := (func() *gorm.DB {
		return /* do anything */
	})()
	indexer := elsearm.NewIndexer(ct.es)
	db = models.UseElsearmIndexer(db, indexer)

	/* do anyting */
	db.Create(&models.User{})
}

Using another index name with tests.

You can set prefix and/or suffix in global config.
It makes it easy to avoid overwrite to the same index when it execute testings.

elsearm.SetGlobalConfig(elsearm.GlobalConfig{
	IndexNameSuffix: "_test",
})

Documentation

Index

• func DefaultDocumentBody(model interface{}) (io.Reader, error)
• func DefaultDocumentID(model interface{}) string
• func DefaultIndexName(model interface{}) string
• func DefaultParseDocument(model interface{}, reader io.Reader) error
• func DocumentBody(model interface{}) (io.Reader, error)
• func DocumentID(model interface{}) string
• func IndexName(model interface{}) string
• func MustDocumentBody(model interface{}) io.Reader
• func ParseDocument(model interface{}, reader io.Reader) error
• func SetGlobalConfig(cfg GlobalConfig)
• func Zero() *int
• type CustomDocumentBodyModel
• type CustomDocumentIdModel
• type CustomIndexNameModel
• type ErrorResponse
  • func (err *ErrorResponse) Error() string
• type GlobalConfig
• type Indexer
  • func NewIndexer(client *elasticsearch.Client) *Indexer
  • func (indexer *Indexer) Count(model interface{}, reqFuncs ...func(*esapi.CountRequest)) (int, error)
  • func (indexer *Indexer) CreateIndex(model interface{}, reqFuncs ...func(*esapi.IndicesCreateRequest)) error
  • func (indexer *Indexer) CreateIndexIfNotExist(model interface{}, reqFuncs ...func(*esapi.IndicesCreateRequest)) error
  • func (indexer *Indexer) CreateWithoutID(model interface{}, reqFuncs ...func(*esapi.IndexRequest)) error
  • func (indexer *Indexer) Delete(model interface{}, reqFuncs ...func(*esapi.DeleteRequest)) error
  • func (indexer *Indexer) DeleteIndex(model interface{}, reqFuncs ...func(*esapi.IndicesDeleteRequest)) error
  • func (indexer *Indexer) Do(req Request, models ...interface{}) error
  • func (indexer *Indexer) Get(model interface{}, reqFuncs ...func(*esapi.GetRequest)) error
  • func (indexer *Indexer) Search(model interface{}, reqFuncs ...func(*esapi.SearchRequest)) error
  • func (indexer *Indexer) Update(model interface{}, reqFuncs ...func(*esapi.IndexRequest)) error
  • func (indexer *Indexer) WithContext(ctx context.Context) *Indexer
• type Request

Functions

func DefaultDocumentBody

func DefaultDocumentBody(model interface{}) (io.Reader, error)

DefaultDocumentBody returns a default DocumentBody. It will be executed if you do not implement CustomDocumentBodyModel.

func DefaultDocumentID

func DefaultDocumentID(model interface{}) string

DefaultDocumentID returns a default DocumentID. It will be executed if you do not implement CustomDocumentIdModel.

func DefaultIndexName

func DefaultIndexName(model interface{}) string

DefaultIndexName returns a default IndexName. It will be executed if you do not implement CustomIndexNameModel.

func DefaultParseDocument

func DefaultParseDocument(model interface{}, reader io.Reader) error

DefaultParseDocument parse the content of reader, and update the model. It will be executed if you do not implement CustomDocumentBodyModel.

func DocumentBody

func DocumentBody(model interface{}) (io.Reader, error)

DocumentBody transforms the model into a data structure that is stored in Elasticsearch. By default, it execute json.Marshal.

func DocumentID

func DocumentID(model interface{}) string

DocumentID returns a document id of the model. By default, it returns value of id or ID field in the model. Otherwise, it returns an empty string.

func IndexName

func IndexName(model interface{}) string

IndexName returns an index name of the model. By default, it returns converted to snake case the struct name of model.

func MustDocumentBody

func MustDocumentBody(model interface{}) io.Reader

MustDocumentBody is similar to DocumentBody. It will panic if the DocumentBody returns an error.

func ParseDocument

func ParseDocument(model interface{}, reader io.Reader) error

ParseDocument parses and applies the value to the model. By default, it execute json.Unmarshal.

func SetGlobalConfig

func SetGlobalConfig(cfg GlobalConfig)

SetGlobalConfig sets the config that applies globally.

func Zero

func Zero() *int

Zero returns a pointer of int. The value of address is zero.

Types

type CustomDocumentBodyModel

type CustomDocumentBodyModel interface {
	GetDocumentBody() (io.Reader, error)
	ParseDocument(io.Reader) error
}

CustomDocumentBodyModel is an interface to be implemented when customizing DocumentBody of model.

type CustomDocumentIdModel

type CustomDocumentIdModel interface {
	// GetDocumentID returns an DocumentID.
	GetDocumentID() string
}

CustomDocumentIdModel is an interface to be implemented when customizing DocumentID of model.

type CustomIndexNameModel

type CustomIndexNameModel interface {
	// GetIndexName returns an IndexName.
	GetIndexName() string
}

CustomIndexNameModel is an interface to be implemented when customizing IndexName of model.

type ErrorResponse

type ErrorResponse struct {
	Status uint `json:"status"`
	Err    struct {
		Type      string `json:"type"`
		Reason    string `json:"reason"`
		RootCause []struct {
			Type   string `json:"type"`
			Reason string `json:"reason"`
		} `json:"root_cause"`
		CausedBy struct {
			Type   string `json:"type"`
			Reason string `json:"reason"`
		} `json:"caused_by"`
	} `json:"error"`
}

ErrorResponse is an error response format of Elasticsearch.

func (*ErrorResponse) Error

func (err *ErrorResponse) Error() string

type GlobalConfig

type GlobalConfig struct {
	// A prefix of index names. It is included in the return value of elsearm.IndexName.
	IndexNamePrefix string
	// A suffix of index names. It is included in the return value of elsearm.IndexName.
	IndexNameSuffix string
}

type Indexer

type Indexer struct {
	Q *esapi.API
	// contains filtered or unexported fields
}

Indexer provides functions to update/delete document in Elasticsearch.

func NewIndexer

func NewIndexer(client *elasticsearch.Client) *Indexer

NewIndexer creates an Indexer.

func (*Indexer) Count

func (indexer *Indexer) Count(model interface{}, reqFuncs ...func(*esapi.CountRequest)) (int, error)

Count returns count of documents saved in index.

func (*Indexer) CreateIndex

func (indexer *Indexer) CreateIndex(model interface{}, reqFuncs ...func(*esapi.IndicesCreateRequest)) error

CreateIndex creates an index that to save the model. If it already exists, it returns an error.

func (*Indexer) CreateIndexIfNotExist

func (indexer *Indexer) CreateIndexIfNotExist(model interface{}, reqFuncs ...func(*esapi.IndicesCreateRequest)) error

CreateIndexIfNotExist creates an index, if it to save the model does not exist.

func (*Indexer) CreateWithoutID

func (indexer *Indexer) CreateWithoutID(model interface{}, reqFuncs ...func(*esapi.IndexRequest)) error

CreateWithoutID create a document in index without DocumentID.

func (*Indexer) Delete

func (indexer *Indexer) Delete(model interface{}, reqFuncs ...func(*esapi.DeleteRequest)) error

Delete a document from Index.

func (*Indexer) DeleteIndex

func (indexer *Indexer) DeleteIndex(model interface{}, reqFuncs ...func(*esapi.IndicesDeleteRequest)) error

DeleteIndex deletes an index that to save the model.

func (*Indexer) Do

func (indexer *Indexer) Do(req Request, models ...interface{}) error

Do execute the request. When models specified, it parses and set a model if succeeded.

func (*Indexer) Get

func (indexer *Indexer) Get(model interface{}, reqFuncs ...func(*esapi.GetRequest)) error

Get a document from Index.

func (*Indexer) Search

func (indexer *Indexer) Search(model interface{}, reqFuncs ...func(*esapi.SearchRequest)) error

Search documents in the index, and set results to the model.

func (*Indexer) Update

func (indexer *Indexer) Update(model interface{}, reqFuncs ...func(*esapi.IndexRequest)) error

Update (or create) the document in index.

func (*Indexer) WithContext

func (indexer *Indexer) WithContext(ctx context.Context) *Indexer

WithContext specifies a context to use and returns a new Indexer.

type Request

type Request interface {
	Do(ctx context.Context, transport esapi.Transport) (*esapi.Response, error)
}

A interface of Request defined by esapi.