表格存储 Go SDK 过滤器-表格存储 Tablestore(Tablestore)-阿里云帮助中心

表格存储支持在查询数据时使用过滤器在服务端按指定条件进行数据过滤，本文介绍如何在 Go SDK 中使用过滤器。

前提条件

过滤器类型

表格存储的过滤器类型包括以下 3 种。

单属性列值过滤器（SingleColumnCondition）：判断单个属性列的值是否符合条件。
单属性列正则过滤器（SingleColumnValueRegexFilter）：将 String 类型的属性列按照指定的正则表达式匹配子字符串后转换成指定的数据类型，再判断是否符合条件。
组合过滤器（CompositeColumnCondition）：将多个条件组合进行数据过滤。

单属性列值过滤器

func NewSingleColumnCondition(columnName string, comparator ComparatorType, value interface{}) *SingleColumnCondition

参数说明

名称	类型	说明
Comparator（必选）	*ComparatorType	关系运算符，包括 CT_EQUAL（等于）、CT_NOT_EQUAL（不等于）、CT_GREATER_THAN（大于）、CT_GREATER_EQUAL（大于等于）、CT_LESS_THAN（小于）、CT_LESS_EQUAL（小于等于）。
ColumnName（必选）	*string	判断的属性列名称。
ColumnValue（必选）	interface{}	判断的值。
FilterIfMissing（可选）	bool	行数据不包含判断的属性列时，是否过滤该行，默认值为 false，即返回该行数据。
LatestVersionOnly（可选）	bool	是否只判断查询结果中最新的数据版本，默认值为 false，即当参考的属性列存在多个数据版本时，任一数据版本符合条件即视为满足要求。

示例代码

以下示例代码以范围查询为例查询主键值为 [row1, row3) 的行数据，并在查询后进行过滤，返回 col1 属性列的值等于 val1 的行数据。

func SingleValueFilterSample(client *tablestore.TableStoreClient) {
    // 构建查询条件
    rangeRowQueryCriteria := &tablestore.RangeRowQueryCriteria{}
    rangeRowQueryCriteria.TableName = "test_table"
    // 设置查询起始主键
    startPK := new(tablestore.PrimaryKey)
    startPK.AddPrimaryKeyColumn("id", "row1")
    rangeRowQueryCriteria.StartPrimaryKey = startPK
    // 设置查询结束主键（返回结果不包含结束主键）
    endPK := new(tablestore.PrimaryKey)
    endPK.AddPrimaryKeyColumn("id", "row3")
    rangeRowQueryCriteria.EndPrimaryKey = endPK
    // 设置查询版本
    rangeRowQueryCriteria.MaxVersion = 1

    // 构造过滤器，条件为 col1 == "val1"
    singleColumnCondition := tablestore.NewSingleColumnCondition("col1", tablestore.CT_EQUAL, "val1")
    rangeRowQueryCriteria.Filter = singleColumnCondition

    // 调用 GetRange 方法查询数据
    getRangeRequest := new(tablestore.GetRangeRequest)
    getRangeRequest.RangeRowQueryCriteria = rangeRowQueryCriteria
    getRangeResponse, err := client.GetRange(getRangeRequest)

    // 返回结果处理
    if err != nil {
        fmt.Println("Range get failed with error: ", err)
    } else {
        fmt.Printf("* RequestId: %s \n", getRangeResponse.RequestId)
        fmt.Printf("* Read CU Cost: %d \n", getRangeResponse.ConsumedCapacityUnit.Read)
        fmt.Printf("* Write CU Cost: %d \n", getRangeResponse.ConsumedCapacityUnit.Write)
        fmt.Println("* Rows Data:")
        for _, row := range getRangeResponse.Rows {
            fmt.Printf("PrimaryKey: %v; Columns: ", row.PrimaryKey.PrimaryKeys)
            for _, column := range row.Columns {
                fmt.Printf("%v ", column)
            }
            fmt.Printf("\n")
        }
    }
}

设置行数据不包含判断的属性列时，不返回该行。
```
singleColumnCondition.FilterIfMissing = true
```
设置只判断查询结果中属性列最新的数据版本。
```
singleColumnCondition.LatestVersionOnly = true
```

单属性列正则过滤器

只有 String 类型的属性列支持使用正则过滤器。

func NewSingleColumnValueRegexFilter(columnName string, comparator ComparatorType, rule *ValueTransferRule, value interface{}) *SingleColumnCondition

参数说明

名称	类型	说明
Comparator（必选）	ComparatorType	关系运算符，包括 CT_EQUAL（等于）、CT_NOT_EQUAL（不等于）、CT_GREATER_THAN（大于）、CT_GREATER_EQUAL（大于等于）、CT_LESS_THAN（小于）、CT_LESS_EQUAL（小于等于）。
ColumnName（必选）	string	判断的属性列名称。
ColumnValue（必选）	interface{}	判断的值。
TransferRule（必选）	*ValueTransferRule	正则匹配规则，包含以下参数。 Regex（必选）`string`：正则表达式，用于匹配子字符串，长度不能超过 256 个字节。支持 Perl 正则表达式和单字节正则表达式。不支持中文正则匹配。支持分组语法，当正则表达式中包含分组时，将返回第一个匹配的子字符串。例如待匹配列值为 `1aaa51bbb5`，正则表达式为 `1([a-z]+)5`，返回结果为 `aaa`。 Cast_type（必选）`VariantType`：子字符串转换的类型，包括 Variant_INTEGER（整型）、Variant_DOUBLE（双精度浮点型）和 Variant_STRING（字符串）。

示例代码

以下示例代码以范围查询为例查询主键值为 [row1, row3) 的行数据，并在查询后进行正则匹配过滤，返回 col1 属性列的值满足正则表达式 1([a-z]+)5 且匹配到的子字符串为 aaa 的行数据。

func SingleRegexFilterSample(client *tablestore.TableStoreClient) {
    // 构建查询条件
    rangeRowQueryCriteria := &tablestore.RangeRowQueryCriteria{}
    rangeRowQueryCriteria.TableName = "test_table"
    // 设置查询起始主键
    startPK := new(tablestore.PrimaryKey)
    startPK.AddPrimaryKeyColumn("id", "row1")
    rangeRowQueryCriteria.StartPrimaryKey = startPK
    // 设置查询结束主键（返回结果不包含结束主键）
    endPK := new(tablestore.PrimaryKey)
    endPK.AddPrimaryKeyColumn("id", "row3")
    rangeRowQueryCriteria.EndPrimaryKey = endPK
    // 设置查询版本
    rangeRowQueryCriteria.MaxVersion = 1

    // 构造过滤器，条件为 cast<String>(reg(col1)) == “aaa”
    valueTransferRule := tablestore.NewValueTransferRule("1([a-z]+)5", tablestore.Variant_STRING)
    singleColumnValueRegexFilter := tablestore.NewSingleColumnValueRegexFilter("col1", tablestore.CT_EQUAL, valueTransferRule, "aaa")
    rangeRowQueryCriteria.Filter = singleColumnValueRegexFilter

    // 调用 GetRange 方法查询数据
    getRangeRequest := new(tablestore.GetRangeRequest)
    getRangeRequest.RangeRowQueryCriteria = rangeRowQueryCriteria
    getRangeResponse, err := client.GetRange(getRangeRequest)

    // 返回结果处理
    if err != nil {
        fmt.Println("Range get failed with error: ", err)
    } else {
        fmt.Printf("* RequestId: %s \n", getRangeResponse.RequestId)
        fmt.Printf("* Read CU Cost: %d \n", getRangeResponse.ConsumedCapacityUnit.Read)
        fmt.Printf("* Write CU Cost: %d \n", getRangeResponse.ConsumedCapacityUnit.Write)
        fmt.Println("* Rows Data:")
        for _, row := range getRangeResponse.Rows {
            fmt.Printf("PrimaryKey: %v; Columns: ", row.PrimaryKey.PrimaryKeys)
            for _, column := range row.Columns {
                fmt.Printf("%v ", column)
            }
            fmt.Printf("\n")
        }
    }
}

组合过滤器

最多支持 32 个条件的组合。

func NewCompositeColumnCondition(lo LogicalOperator) *CompositeColumnValueFilter

参数说明

名称	类型	说明
Operator（必选）	LogicalOperator	逻辑运算符，包括 LO_NOT（非）、LO_AND（与）、LO_OR（或）。
Filters（必选）	[]ColumnFilter	参与逻辑运算的过滤器，包括单属性列值过滤器和单属性列正则过滤器，也可以是组合过滤器本身。

示例代码

以下示例代码以范围查询为例查询主键值为 [row1, row3) 的行数据，并使用组合过滤器进行数据过滤。

func CompositeFilterSample(client *tablestore.TableStoreClient) {
    // 构建查询条件
    rangeRowQueryCriteria := &tablestore.RangeRowQueryCriteria{}
    rangeRowQueryCriteria.TableName = "test_table"
    // 设置查询起始主键
    startPK := new(tablestore.PrimaryKey)
    startPK.AddPrimaryKeyColumn("id", "row1")
    rangeRowQueryCriteria.StartPrimaryKey = startPK
    // 设置查询结束主键（返回结果不包含结束主键）
    endPK := new(tablestore.PrimaryKey)
    endPK.AddPrimaryKeyColumn("id", "row3")
    rangeRowQueryCriteria.EndPrimaryKey = endPK
    // 设置查询版本
    rangeRowQueryCriteria.MaxVersion = 1

    // 构造单属性列值过滤器1，条件为 col1 == "val1"
    singleColumnCondition1 := tablestore.NewSingleColumnCondition("col1", tablestore.CT_EQUAL, "val1")
    // 构造单属性列正则过滤器2，条件为 cast<String>(reg(col2)) == "aaa"
    valueTransferRule := tablestore.NewValueTransferRule("1([a-z]+)5", tablestore.Variant_STRING)
    singleColumnValueRegexFilter2 := tablestore.NewSingleColumnValueRegexFilter("col2", tablestore.CT_EQUAL, valueTransferRule, "aaa")
    // 构造组合过滤器1，条件为 col1 == "val1" or cast<String>(reg(col2)) == "aaa"
    compositeCondition1 := tablestore.NewCompositeColumnCondition(tablestore.LO_OR)
    compositeCondition1.AddFilter(singleColumnCondition1)
    compositeCondition1.AddFilter(singleColumnValueRegexFilter2)
    // 构造单属性列值过滤器2，条件为 col3 == "val3"
    singleColumnCondition3 := tablestore.NewSingleColumnCondition("col3", tablestore.CT_EQUAL, "val3")
    // 构造组合过滤器2，条件为 组合过滤器1 and 单属性列值过滤器2，即 (col1 == "val1" or cast<String>(reg(col2)) == "aaa") and col3 == "val3"
    compositeCondition2 := tablestore.NewCompositeColumnCondition(tablestore.LO_AND)
    compositeCondition2.AddFilter(compositeCondition1)
    compositeCondition2.AddFilter(singleColumnCondition3)

    // 查询结果添加过滤器
    rangeRowQueryCriteria.Filter = compositeCondition2

    // 调用 GetRange 方法查询数据
    getRangeRequest := new(tablestore.GetRangeRequest)
    getRangeRequest.RangeRowQueryCriteria = rangeRowQueryCriteria
    getRangeResponse, err := client.GetRange(getRangeRequest)

    // 返回结果处理
    if err != nil {
        fmt.Println("Range get failed with error: ", err)
    } else {
        fmt.Printf("* RequestId: %s \n", getRangeResponse.RequestId)
        fmt.Printf("* Read CU Cost: %d \n", getRangeResponse.ConsumedCapacityUnit.Read)
        fmt.Printf("* Write CU Cost: %d \n", getRangeResponse.ConsumedCapacityUnit.Write)
        fmt.Println("* Rows Data:")
        for _, row := range getRangeResponse.Rows {
            fmt.Printf("PrimaryKey: %v; Columns: ", row.PrimaryKey.PrimaryKeys)
            for _, column := range row.Columns {
                fmt.Printf("%v ", column)
            }
            fmt.Printf("\n")
        }
    }
}

前提条件

过滤器类型

单属性列值过滤器

示例代码

单属性列正则过滤器

示例代码

组合过滤器

示例代码

相关文档