Tablestore Go SDK filters - Tablestore - Alibaba Cloud Documentation Center

Tablestore evaluates filters on the server to return rows that match specified conditions. Configure filters in the Go SDK as described on this page.

Prerequisites

Initialize a Tablestore client

Filter types

Tablestore provides three filter types.

Single-column value filter (SingleColumnCondition): Evaluates whether one attribute column value satisfies a condition.
Single-column value regex filter (SingleColumnValueRegexFilter): On a string attribute column, matches a substring with a regular expression, casts it to a type, then evaluates it against a condition.
Composite filter (CompositeColumnCondition): Combines multiple conditions with logical operators.

Single-column value filter

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

Parameters

Parameter	Type	Description
Comparator (Required)	ComparatorType	Relational operator. Allowed values: CT_EQUAL (equal to), CT_NOT_EQUAL (not equal to), CT_GREATER_THAN (greater than), CT_GREATER_EQUAL (greater than or equal to), CT_LESS_THAN (less than), and CT_LESS_EQUAL (less than or equal to).
ColumnName (Required)	string	Name of the attribute column to evaluate.
ColumnValue (Required)	interface{}	Value to compare.
FilterIfMissing (Optional)	bool	When false (default), rows without the attribute column are still returned. Set to true to exclude those rows.
LatestVersionOnly (Optional)	bool	When false (default), any version of the column can satisfy the condition. Set to true to evaluate only the latest version.

Sample code

Runs a range query on primary keys [`row1`, `row3`), then keeps rows whose col1 attribute equals val1.

func SingleValueFilterSample(client *tablestore.TableStoreClient) {
    // Construct the query criteria.
    rangeRowQueryCriteria := &tablestore.RangeRowQueryCriteria{}
    rangeRowQueryCriteria.TableName = "test_table"
    // Set the start primary key.
    startPK := new(tablestore.PrimaryKey)
    startPK.AddPrimaryKeyColumn("id", "row1")
    rangeRowQueryCriteria.StartPrimaryKey = startPK
    // Set the end primary key. The row with this key is not included in the result.
    endPK := new(tablestore.PrimaryKey)
    endPK.AddPrimaryKeyColumn("id", "row3")
    rangeRowQueryCriteria.EndPrimaryKey = endPK
    // Set the number of versions to query.
    rangeRowQueryCriteria.MaxVersion = 1

    // Construct a filter where col1 equals "val1".
    singleColumnCondition := tablestore.NewSingleColumnCondition("col1", tablestore.CT_EQUAL, "val1")
    rangeRowQueryCriteria.Filter = singleColumnCondition

    // Call the GetRange operation to query data.
    getRangeRequest := new(tablestore.GetRangeRequest)
    getRangeRequest.RangeRowQueryCriteria = rangeRowQueryCriteria
    getRangeResponse, err := client.GetRange(getRangeRequest)

    // Process the response.
    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")
        }
    }
}

Set FilterIfMissing to true to drop rows that omit the attribute column.
```
singleColumnCondition.FilterIfMissing = true
```
Set LatestVersionOnly to true to use only the latest version of the attribute column.
```
singleColumnCondition.LatestVersionOnly = true
```

Single-column value regex filter

Use regex filters only on string attribute columns.

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

Parameters

Parameter	Type	Description
Comparator (Required)	ComparatorType	Relational operator. Allowed values: CT_EQUAL (equal to), CT_NOT_EQUAL (not equal to), CT_GREATER_THAN (greater than), CT_GREATER_EQUAL (greater than or equal to), CT_LESS_THAN (less than), and CT_LESS_EQUAL (less than or equal to).
ColumnName (Required)	string	Name of the attribute column to evaluate.
ColumnValue (Required)	interface{}	Value to compare.
TransferRule (Required)	ValueTransferRule	Regex matching rule with these fields: Regex (Required) `string`: Pattern that matches a substring; maximum length 256 bytes. Supports Perl Compatible Regular Expressions (PCRE) and single-byte regex. Chinese characters in regex patterns are not supported. Capturing groups are allowed; the first captured substring is used. Example: column value `1aaa51bbb5`, pattern `1([a-z]+)5` yields `aaa`. Cast_type (Required) `VariantType`: Target type for the matched substring. Values: `Variant_INTEGER` (integer), `Variant_DOUBLE` (double-precision floating-point), and `Variant_STRING` (string).

Sample code

Runs a range query on primary keys [`row1`, `row3`), then keeps rows where col1 matches 1([a-z]+)5 with captured substring aaa.

func SingleRegexFilterSample(client *tablestore.TableStoreClient) {
    // Construct the query criteria.
    rangeRowQueryCriteria := &tablestore.RangeRowQueryCriteria{}
    rangeRowQueryCriteria.TableName = "test_table"
    // Set the start primary key.
    startPK := new(tablestore.PrimaryKey)
    startPK.AddPrimaryKeyColumn("id", "row1")
    rangeRowQueryCriteria.StartPrimaryKey = startPK
    // Set the end primary key. The row with this key is not included in the result.
    endPK := new(tablestore.PrimaryKey)
    endPK.AddPrimaryKeyColumn("id", "row3")
    rangeRowQueryCriteria.EndPrimaryKey = endPK
    // Set the number of versions to query.
    rangeRowQueryCriteria.MaxVersion = 1

    // Construct the filter: 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

    // Call the GetRange operation to query data.
    getRangeRequest := new(tablestore.GetRangeRequest)
    getRangeRequest.RangeRowQueryCriteria = rangeRowQueryCriteria
    getRangeResponse, err := client.GetRange(getRangeRequest)

    // Process the response.
    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")
        }
    }
}

Composite filter

Composite filters support up to 32 nested conditions.

func NewCompositeColumnCondition(lo LogicalOperator) *CompositeColumnCondition

Parameters

Parameter	Type	Description
Operator (Required)	LogicalOperator	Logical operator. Allowed values: LO_NOT (not), LO_AND (and), and LO_OR (or).
Filters (Required)	[]ColumnFilter	Child filters combined with the operator: SingleColumnCondition, SingleColumnValueRegexFilter, or nested CompositeColumnCondition.

Sample code

Runs a range query on primary keys [`row1`, `row3`) and applies a composite filter to narrow the result set.

func CompositeFilterSample(client *tablestore.TableStoreClient) {
    // Construct the query criteria.
    rangeRowQueryCriteria := &tablestore.RangeRowQueryCriteria{}
    rangeRowQueryCriteria.TableName = "test_table"
    // Set the start primary key.
    startPK := new(tablestore.PrimaryKey)
    startPK.AddPrimaryKeyColumn("id", "row1")
    rangeRowQueryCriteria.StartPrimaryKey = startPK
    // Set the end primary key. The row with this key is not included in the result.
    endPK := new(tablestore.PrimaryKey)
    endPK.AddPrimaryKeyColumn("id", "row3")
    rangeRowQueryCriteria.EndPrimaryKey = endPK
    // Set the number of versions to query.
    rangeRowQueryCriteria.MaxVersion = 1

    // Construct the first single-column value filter: col1 == "val1".
    singleColumnCondition1 := tablestore.NewSingleColumnCondition("col1", tablestore.CT_EQUAL, "val1")
    // Construct the single-column regex filter: cast<String>(reg(col2)) == "aaa".
    valueTransferRule := tablestore.NewValueTransferRule("1([a-z]+)5", tablestore.Variant_STRING)
    singleColumnValueRegexFilter2 := tablestore.NewSingleColumnValueRegexFilter("col2", tablestore.CT_EQUAL, valueTransferRule, "aaa")
    // Construct the first composite filter: col1 == "val1" OR cast<String>(reg(col2)) == "aaa".
    compositeCondition1 := tablestore.NewCompositeColumnCondition(tablestore.LO_OR)
    compositeCondition1.AddFilter(singleColumnCondition1)
    compositeCondition1.AddFilter(singleColumnValueRegexFilter2)
    // Construct the second single-column value filter: col3 == "val3".
    singleColumnCondition3 := tablestore.NewSingleColumnCondition("col3", tablestore.CT_EQUAL, "val3")
    // Construct the final composite filter: (col1 == "val1" OR cast<String>(reg(col2)) == "aaa") AND col3 == "val3".
    compositeCondition2 := tablestore.NewCompositeColumnCondition(tablestore.LO_AND)
    compositeCondition2.AddFilter(compositeCondition1)
    compositeCondition2.AddFilter(singleColumnCondition3)

    // Add the filter to the query.
    rangeRowQueryCriteria.Filter = compositeCondition2

    // Call the GetRange operation to query data.
    getRangeRequest := new(tablestore.GetRangeRequest)
    getRangeRequest.RangeRowQueryCriteria = rangeRowQueryCriteria
    getRangeResponse, err := client.GetRange(getRangeRequest)

    // Process the response.
    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")
        }
    }
}

Tablestore:Filters

Prerequisites

Filter types

Single-column value filter

Sample code

Single-column value regex filter

Sample code

Composite filter

Sample code

Related topics