表格存储 Go SDK 通配符查询-表格存储 Tablestore(Tablestore)-阿里云帮助中心

使用 Tablestore Go SDK 的通配符查询通过星号（*）和问号（?）匹配字段值或分词词条。

前提条件

安装Tablestore Go SDK并初始化客户端。

功能说明

通配符查询支持使用星号（*）匹配零个或多个字符，使用问号（?）匹配单个字符。对于 Text 字段，查询对象是分词后的词条。匹配区分大小写，查询字符串长度不能超过 32 个字符。

func (client *tablestore.TableStoreClient) Search(request *tablestore.SearchRequest) (*tablestore.SearchResponse, error)

以下示例查询数据并返回最多 10 行数据及匹配总行数。

tableName := "example_table"
indexName := "example_index"

query := &search.WildcardQuery{FieldName: "category", Value: "book-*"}
searchQuery := search.NewSearchQuery().
    SetQuery(query).
    SetLimit(10).
    SetGetTotalCount(true)

response, err := client.Search(&tablestore.SearchRequest{
    TableName:   tableName,
    IndexName:   indexName,
    SearchQuery: searchQuery,
    ColumnsToGet: &tablestore.ColumnsToGet{
        ReturnAllFromIndex: true,
    },
})
if err != nil {
    log.Fatal(err)
}

fmt.Println(response.TotalCount)
fmt.Println(response.Rows)

参数说明

查询请求

request 的类型为 tablestore.SearchRequest，包含以下参数。

名称	类型	说明
TableName（必选）	string	数据表名称。
IndexName（必选）	string	多元索引名称。
SearchQuery（必选）	search.SearchQuery	查询条件和通用查询配置。
ColumnsToGet（可选）	*tablestore.ColumnsToGet	返回列配置。未设置时只返回主键列。
RoutingValues（可选）	[]*tablestore.PrimaryKey	自定义路由字段对应的主键值列表。未配置自定义路由时无需设置。
TimeoutMs（可选）	*int32	请求级超时时间，单位为毫秒。

查询配置

通过 search.NewSearchQuery() 创建查询配置，并使用以下方法设置参数。

名称	类型	说明
SetQuery（必选）	search.Query	设置查询条件。
SetOffset（可选）	int32	设置本次查询的起始位置，默认值为 0。使用 Offset 翻页时，Offset + Limit 不能超过 100000。
SetLimit（可选）	int32	设置本次查询返回的最大行数，默认值为 10，最大值为 100。设置为 0 时不返回具体行。
SetHighlight（可选）	*search.Highlight	设置 Text 字段的摘要与高亮。配置方法请参见摘要与高亮。
SetCollapse（可选）	*search.Collapse	设置结果折叠。配置方法请参见折叠（去重）。
SetSort（可选）	*search.Sort	设置返回结果的排序方式。配置方法请参见排序和翻页。
SetGetTotalCount（可选）	bool	是否统计匹配总行数，默认值为 false。
SetToken（可选）	[]byte	设置上一次响应返回的 NextToken，以继续读取后续数据。调用该方法会清除 Sort，因为 Token 已包含上一页的排序条件。使用 Token 翻页时不能设置 Offset。
SetSearchFilter（可选）	*search.SearchFilter	对查询结果执行后过滤。配置方法请参见查询后过滤。
Aggregation（可选）	...search.Aggregation	设置统计聚合。配置方法请参见统计聚合。
GroupBy（可选）	...search.GroupBy	设置分组。配置方法请参见统计聚合。

查询条件

查询类型为 search.WildcardQuery，包含以下参数。

名称	类型	说明
FieldName（必选）	string	要查询的索引字段名称。
Value（必选）	string	包含通配符的查询字符串，长度不超过 32 个字符。

返回列

request.ColumnsToGet 的类型为 tablestore.ColumnsToGet，包含以下参数。

名称	类型	说明
Columns（可选）	[]string	要返回的属性列名称。仅 ReturnAll 和 ReturnAllFromIndex 均为 false 时生效。
ReturnAll（可选）	bool	是否返回数据表中的全部属性列，默认值为 false。
ReturnAllFromIndex（可选）	bool	是否返回已建立索引的全部属性列，默认值为 false。不能与 ReturnAll 同时设置为 true。

返回值

Search 方法返回 tablestore.SearchResponse。核心业务字段如下。

名称	类型	说明
TotalCount	int64	匹配总行数。返回值取决于 SetGetTotalCount 配置。
Rows	[]*tablestore.Row	本次查询返回的行数据，数量不超过 SetLimit 指定的值。
SearchHits	[]*tablestore.SearchHit	查询命中结果。配置摘要与高亮、嵌套 InnerHits 或需要相关性评分时，从该字段读取结果。
NextToken	[]byte	下一页凭证。值非空时，将其传入下一次查询继续读取。
IsAllSuccess	bool	是否已成功查询全部索引分区。值为 false 时返回的是部分结果，TotalCount 可能小于实际匹配行数。
AggregationResults	search.AggregationResults	统计聚合结果。
GroupByResults	search.GroupByResults	分组结果。

场景示例

优化任意位置匹配的查询性能

对于查询模式为 *word* 的场景，可在创建多元索引时为 Text 字段配置模糊分词，并在查询时使用短语匹配查询。与直接执行通配符查询相比，该方式通常具有更好的查询性能。有关匹配规则和限制，请参见基于分词的通配符查询。

以下示例创建包含 file_name 字段的多元索引，并为该字段配置模糊分词。

analyzer := tablestore.Analyzer_Fuzzy
fieldSchema := &tablestore.FieldSchema{
    FieldName:         proto.String("file_name"),
    FieldType:         tablestore.FieldType_TEXT,
    Index:             proto.Bool(true),
    Analyzer:          &analyzer,
    AnalyzerParameter: tablestore.FuzzyAnalyzerParameter{},
}

request := &tablestore.CreateSearchIndexRequest{
    TableName: "example_table",
    IndexName: "example_index",
    IndexSchema: &tablestore.IndexSchema{
        FieldSchemas: []*tablestore.FieldSchema{fieldSchema},
    },
}

_, err := client.CreateSearchIndex(request)
if err != nil {
    log.Fatal(err)
}

索引数据同步完成后，使用 MatchPhraseQuery 查询 file_name 字段中任意位置包含 word 的数据。

query := &search.MatchPhraseQuery{
    FieldName: "file_name",
    Text:      "word",
}
searchQuery := search.NewSearchQuery().
    SetQuery(query).
    SetLimit(10)

response, err := client.Search(&tablestore.SearchRequest{
    TableName:   "example_table",
    IndexName:   "example_index",
    SearchQuery: searchQuery,
    ColumnsToGet: &tablestore.ColumnsToGet{
        ReturnAllFromIndex: true,
    },
})
if err != nil {
    log.Fatal(err)
}

fmt.Println(response.Rows)

排除匹配通配符的数据

如需实现类似 SQL NOT LIKE 的查询，将 WildcardQuery 配置为 BoolQuery.MustNotQueries 的子查询。

wildcardQuery := &search.WildcardQuery{
    FieldName: "category",
    Value:     "book-*",
}
query := &search.BoolQuery{
    MustNotQueries: []search.Query{wildcardQuery},
}
searchQuery := search.NewSearchQuery().
    SetQuery(query).
    SetLimit(10)

response, err := client.Search(&tablestore.SearchRequest{
    TableName:   "example_table",
    IndexName:   "example_index",
    SearchQuery: searchQuery,
    ColumnsToGet: &tablestore.ColumnsToGet{
        ReturnAllFromIndex: true,
    },
})
if err != nil {
    log.Fatal(err)
}

fmt.Println(response.Rows)