Use filters - Tablestore SDK for Go - Tablestore - Alibaba Cloud Documentation Center

Prerequisites

Install the Tablestore SDK for Go and initialize the client.

Description

A filter screens read results on the server and does not reduce the consumed read CUs. You can specify a filter in the query criteria of GetRow, GetRange, or BatchGetRow. The Tablestore SDK for Go supports the following filter types:

Single-column value filter (SingleColumnCondition): evaluates the value of an attribute column.
Single-column value regex filter (SingleColumnValueRegexFilter): extracts a substring from a STRING attribute column, converts the substring, and compares the result.
Composite filter (CompositeColumnCondition): combines filters by using AND, OR, or NOT. A composite filter can contain up to 32 conditions.
Column pagination filter (PaginationFilter): returns attribute columns based on an offset and count without evaluating column values.

The following sample uses a single-column value filter to return only rows for which score >= 60.

filter := tablestore.NewSingleColumnCondition(
    "score",
    tablestore.CT_GREATER_EQUAL,
    int64(60),
)

request.RangeRowQueryCriteria.Filter = filter
response, err := client.GetRange(request)
if err != nil {
    log.Fatal(err)
}
fmt.Println(response.Rows)

Parameters

Single-column value filter

Call NewSingleColumnCondition(columnName, comparator, value) to create a single-column value filter. SingleColumnCondition contains the following parameters.

Name	Type	Description
ColumnName (required)	`*string`	The attribute column to evaluate.
Comparator (required)	`*ComparatorType`	The comparison operator. Valid values: `CT_EQUAL`, `CT_NOT_EQUAL`, `CT_GREATER_THAN`, `CT_GREATER_EQUAL`, `CT_LESS_THAN`, and `CT_LESS_EQUAL`.
ColumnValue (required)	`interface{}`	The value to compare against.
FilterIfMissing (optional)	`bool`	Specifies whether to filter out the row if the column is missing. Default value: `false`, which returns the row.
LatestVersionOnly (optional)	`bool`	Specifies whether to evaluate only the latest version. Default value: `false`, which returns the row if any version meets the condition.

Single-column value regex filter

Call NewSingleColumnValueRegexFilter(columnName, comparator, rule, value) to create a regex filter. Only STRING attribute columns support regex filters.

In addition to the parameters of a single-column value filter, specify a ValueTransferRule with the following parameters.

Name

Type

Description

Regex (required)

string

The regular expression used to extract a substring. Maximum length: 256 bytes.

Perl Compatible Regular Expressions (PCRE) and single-byte regular expressions are supported.
Regex patterns cannot contain Chinese characters.
Capturing groups are supported. If a regex contains capturing groups, the substring captured by the first group is used. For example, if the attribute column value is 1aaa51bbb5 and the regex is 1([a-z]+)5, the extracted substring is aaa.

Cast_type (required)

VariantType

The type to which the extracted substring is converted. Valid values: Variant_INTEGER, Variant_DOUBLE, and Variant_STRING.

Composite filter

Call NewCompositeColumnCondition(lo) to create a composite filter, and call AddFilter to add subfilters.

Name

Type

Description

Operator (required)

LogicalOperator

The logical operator. Valid values: LO_NOT, LO_AND, and LO_OR.

Filters (required)

[]ColumnFilter

The subfilters to combine. The following types are supported:

Single-column value filters created by using NewSingleColumnCondition.
Single-column value regex filters created by using NewSingleColumnValueRegexFilter.
Composite filters created by using NewCompositeColumnCondition. A composite filter can contain nested subfilters.

Column pagination filter

PaginationFilter contains the following parameters.

Name	Type	Description
Limit (required)	`int32`	The number of attribute columns to return. The value must be greater than 0.
Offset (optional)	`int32`	The number of attribute columns to skip. The value must be greater than or equal to 0. Default value: `0`.

Examples

Regex filter

The following sample extracts active from a profile column value in the level:active format and compares the result with a specified value.

rule := tablestore.NewValueTransferRule(
    `level:([a-z]+)`,
    tablestore.Variant_STRING,
)
filter := tablestore.NewSingleColumnValueRegexFilter(
    "profile",
    tablestore.CT_EQUAL,
    rule,
    "active",
)
request.SingleRowQueryCriteria.Filter = filter

Composite filter

The following sample returns rows for which score >= 60 and status is active.

filter := tablestore.NewCompositeColumnCondition(tablestore.LO_AND)
filter.AddFilter(
    tablestore.NewSingleColumnCondition("score", tablestore.CT_GREATER_EQUAL, int64(60)),
)
filter.AddFilter(
    tablestore.NewSingleColumnCondition("status", tablestore.CT_EQUAL, "active"),
)
request.RangeRowQueryCriteria.Filter = filter

Paginate returned attribute columns

The following sample skips the first attribute column and returns the next two attribute columns.

request.SingleRowQueryCriteria.Filter = &tablestore.PaginationFilter{
    Offset: 1,
    Limit:  2,
}