search

type BM25Parameters struct {
	K1 float32
	B  float32
}

type Dictionary struct {
	Root           Node     // 根节点
	MaxTokenLength int      // 词典中最长的分词
	NumTokens      int      // 词典中分词数目
	Tokens         []*Token // 词典中所有的分词，方便遍历
	TotalFrequency int64    // 词典中所有分词的频率之和
}

type DocumentIndex struct {
	// 文本的DocId
	DocId uint64

	// 文本的关键词长
	TokenLength float32

	// 加入的索引键
	Keywords []KeywordIndex
}

type DocumentIndexData struct {
	// 文档全文（必须是UTF-8格式），用于生成待索引的关键词
	Content string

	// 文档的关键词
	// 当Content不为空的时候，优先从Content中分词得到关键词。
	// Tokens存在的意义在于绕过内置的分词器，在引擎外部
	// 进行分词和预处理。
	Tokens []TokenData

	// 文档标签（必须是UTF-8格式），比如文档的类别属性等，这些标签并不出现在文档文本中
	Labels []string

	// 文档的评分字段，可以接纳任何类型的结构体
	Fields interface{}
}

type Engine struct {
	// contains filtered or unexported fields
}

type EngineInitOptions struct {
	// 半角逗号分隔的字典文件，具体用法见
	// sego.Segmenter.LoadDictionary函数的注释
	Segmenter SearchSegmenter

	// 停用词文件
	StopTokenFile string

	// 分词器线程数
	NumSegmenterThreads int

	// 索引器和排序器的shard数目
	// 被检索/排序的文档会被均匀分配到各个shard中
	NumShards int

	// 索引器的信道缓冲长度
	IndexerBufferLength int

	// 索引器每个shard分配的线程数
	NumIndexerThreadsPerShard int

	// 排序器的信道缓冲长度
	RankerBufferLength int

	// 排序器每个shard分配的线程数
	NumRankerThreadsPerShard int

	// 索引器初始化选项
	IndexerInitOptions *IndexerInitOptions

	// 是否使用持久数据库，以及数据库文件保存的目录和裂分数目
	UsePersistentStorage bool

	//索引存储接口对接
	SearchPipline SearchPipline

	//索引器生成方法
	CreateIndexer func() SearchIndexer

	//排序器生成方法
	CreateRanker func() SearchRanker

	//打分器设置
	SearchScorer SearchScorer
}

type IndexedDocument struct {
	DocId uint64

	// BM25，仅当索引类型为FrequenciesIndex或者LocationsIndex时返回有效值
	BM25 float32

	// 关键词在文档中的紧邻距离，紧邻距离的含义见computeTokenProximity的注释。
	// 仅当索引类型为LocationsIndex时返回有效值。
	TokenProximity int32

	// 紧邻距离计算得到的关键词位置，和Lookup函数输入tokens的长度一样且一一对应。
	// 仅当索引类型为LocationsIndex时返回有效值。
	TokenSnippetLocations []int

	// 关键词在文本中的具体位置。
	// 仅当索引类型为LocationsIndex时返回有效值。
	TokenLocations [][]int
}

type IndexerInitOptions struct {
	// 索引表的类型，见上面的常数
	IndexType int

	// BM25参数
	BM25Parameters *BM25Parameters
}

type Jumper struct {
	MinDistance float32
	Token       *Token
}

type KeywordIndex struct {
	// 搜索键的UTF-8文本
	Text string

	// 搜索键词频
	Frequency float32

	// 搜索键在文档中的起始字节位置，按照升序排列
	Starts []int
}

type Node struct {
	Word     Text    // 该节点对应的字元
	Token    *Token  // 当此节点没有对应的分词时值为nil
	Children []*Node // 该字元后继的所有可能字元，当为叶子节点时为空
}

type RankOptions struct {
	// 文档的评分规则，值为nil时使用Engine初始化时设定的规则
	SearchScorer SearchScorer

	// 默认情况下（ReverseOrder=false）按照分数从大到小排序，否则从小到大排序
	ReverseOrder bool

	// 从第几条结果开始输出
	OutputOffset int

	// 最大输出的搜索结果数，为0时无限制
	MaxOutputs int
}

type ScoredDocument struct {
	DocId uint64

	// 文档的打分值
	// 搜索结果按照Scores的值排序，先按照第一个数排，如果相同则按照第二个数排序，依次类推。
	Scores []float32

	// 用于生成摘要的关键词在文本中的字节位置，该切片长度和SearchResponse.Tokens的长度一样
	// 只有当IndexType == LocationsIndex时不为空
	TokenSnippetLocations []int

	// 关键词出现的位置
	// 只有当IndexType == LocationsIndex时不为空
	TokenLocations [][]int
}

type ScoredDocuments []ScoredDocument

type SearchIndexer interface {
	// 初始化索引器
	Init(options IndexerInitOptions)
	// 向反向索引表中加入一个文档
	AddDocument(document *DocumentIndex)
	// 查找包含全部搜索键(AND操作)的文档
	// 当docIds不为nil时仅从docIds指定的文档中查找
	Lookup(tokens []string, labels []string, docIds []uint64) (docs []IndexedDocument)
}

type SearchPipline interface {
	//初始化存储器, shard为初始化的集合编号
	Init()
	//获取存储集合数量, 集合数量可以提高并行计算效率
	GetStorageShards() int
	//连接数据库
	Conn(shard int)
	//关闭数据库连接
	Close(shard int)
	//将数据从shard DB恢复到内存
	Recover(shard int, internalIndexDocument func(docId uint64, data DocumentIndexData)) error
	//存储索引
	Set(shard int, key, value []byte)
	//从DB删除索引
	Delete(shard int, key []byte)
}

type SearchRanker interface {
	//排序起初始化
	Init()
	// 给某个文档添加评分字段
	AddScoringFields(docId uint64, fields interface{})
	// 删除某个文档的评分字段
	RemoveScoringFields(docId uint64)
	// 给文档评分并排序
	Rank(docs []IndexedDocument, options RankOptions) (outputDocs ScoredDocuments)
}

type SearchRequest struct {
	// 搜索的短语（必须是UTF-8格式），会被分词
	// 当值为空字符串时关键词会从下面的Tokens读入
	Text string

	// 关键词（必须是UTF-8格式），当Text不为空时优先使用Text
	// 通常你不需要自己指定关键词，除非你运行自己的分词程序
	Tokens []string

	// 文档标签（必须是UTF-8格式），标签不存在文档文本中，但也属于搜索键的一种
	Labels []string

	// 当不为空时，仅从这些文档中搜索
	DocIds []uint64

	// 排序选项
	RankOptions *RankOptions

	// 超时，单位毫秒（千分之一秒）。此值小于等于零时不设超时。
	// 搜索超时的情况下仍有可能返回部分排序结果。
	Timeout int
}

type SearchResponse struct {
	// 搜索用到的关键词
	Tokens []string

	// 搜索到的文档，已排序
	Docs []ScoredDocument

	// 搜索是否超时。超时的情况下也可能会返回部分结果
	Timeout bool
}

type SearchScorer interface {
	// 给一个文档评分，文档排序时先用第一个分值比较，如果
	// 分值相同则转移到第二个分值，以此类推。
	// 返回空切片表明该文档应该从最终排序结果中剔除。
	Score(doc IndexedDocument, fields interface{}) []float32
}

type SearchSegmenter interface {
	// 返回分词器使用的词典
	Dictionary() *Dictionary
	// 从文件中载入词典
	// 可以载入多个词典文件，文件名用","分隔，排在前面的词典优先载入分词，比如
	// 	"用户词典.txt,通用词典.txt"
	// 当一个分词既出现在用户词典也出现在通用词典中，则优先使用用户词典。
	// 词典的格式为（每个分词一行）：
	//	分词文本 频率 词性
	LoadDictionary(files string)
	// 对文本分词
	// 输入参数：
	//	bytes	UTF8文本的字节数组
	// 输出：
	//	[]Segment	划分的分词
	Cut(bytes []byte, model bool) []Segment
}

type Segment struct {
	// 分词在文本中的起始字节位置
	Start int
	// 分词在文本中的结束字节位置（不包括该位置）
	End int
	// 分词信息
	Token *Token
}

type StopTokens struct {
	// contains filtered or unexported fields
}

type Text []byte

type Token struct {
	// 分词的字串，这实际上是个字元数组
	TextList []Text
	// 分词在语料库中的词频
	Frequency int
	// log2(总词频/该分词词频)，这相当于log2(1/p(分词))，用作动态规划中
	// 该分词的路径长度。求解prod(p(分词))的最大值相当于求解
	// sum(distance(分词))的最小值，这就是“最短路径”的来历。
	Distance float32
	// 词性标注
	Pos string
	// 该分词文本的进一步分词划分，见Segments函数注释。
	Segments []*Segment
}

type TokenData struct {
	// 关键词的字符串
	Text string

	// 关键词的首字节在文档中出现的位置
	Locations []int
}