Tablestore filters query results on the server side before returning the results. Only rows of data that match the filter conditions are returned.

Prerequisites

  • Client is initialized. For more information, see Initialization.
  • A data table is created and data is written to the table.

Usage notes

When you call the GetRow, BatchGetRow, or GetRange operation to query data, you can use a filter to return only the rows that meet the filter conditions.

Filters include SingleColumnCondition and CompositeColumnCondition.

  • SingleColumnCondition: determines whether to filter a row based only on the values of a reference column.
  • CompositeColumnCondition: determines whether to filter a row based on a combination of the filter conditions on values of multiple reference columns.

Limits

  • A filter can consist of up to 10 conditions. Supported conditions include relational operations (=, !=, >, >=, <, and <=) and logical operations (NOT, AND, and OR).
  • The reference columns used by a filter must be included in the read data. If you specify columns from which data is read that do not include the reference columns, the filters cannot obtain the reference column values.
  • The native semantics or limits of the GetRow, BatchGetRow, and GetRange operations are not affected when you use filters.

    You can scan up to 5,000 rows and return up to 4 MB of data with a single GetRange operation.

    If no data matches the filter conditions in the scanned range, the returned rows are empty. However, next_start_primary_key may not be empty. In this case, you must use next_start_primary_key to continue reading the data until next_start_primary_key is empty.

Parameters

ParameterDescription
columnNameThe name of the reference column used by the filter.
columnValueThe value of the reference column used by the filter.
ComparatorTypeThe relational operator used by the filter. For more information, see ComparatorType.

The relational operators include EQUAL (=), NOT_EQUAL (!=), GREATER_THAN (>), GREATER_EQUAL (>=), LESS_THAN (<), and LESS_EQUA L(<=).

LogicOperatorThe logical operator used by the filter. For more information, see LogicalOperator.

The logical operators include NOT, AND, and OR.

passIfMissingSpecifies whether to return a row when a reference column in the row does not exist. The data type of the parameter value is Boolean. The default value is true, which indicates that if a reference column does not exist in a row, the row is returned.

If you set passIfMissing to false, a row is not returned if a reference column does not exist in the row.

latestVersionOnlySpecifies whether to use only the latest versions of data in the reference columns for comparison when each reference column contains data of multiple versions. The data type of the parameter value is Boolean. The default value is true, which indicates that the latest versions of data are used for comparison when each reference column contains data of multiple versions.

If you set latestVersionOnly to false, all versions of data in a reference column are used for comparison. The row is returned if one version of data in the reference column meets the condition.

Examples

  • The following code provides an example on how to construct a SingleColumnCondition:
    function getRowWithCondition() {
      // Specify that the row is returned when the value of the col1 column is Tablestore. When passIfMissing is set to true, the row is returned if this column does not exist. When passIfMissing is set to false, the row is not returned if this column does not exist.
      var condition = new TableStore.SingleColumnCondition('col1', 'Tablestore', TableStore.ComparatorType.EQUAL,true);
    
      params.columnFilter = condition;
      client.getRow(params, function (err, data) {
        if (err) {
          console.log('error:', err);
          return;
        }
        console.log('success:', data);
      });
    }
  • The following code provides an example on how to construct a CompositeCondition:
    function getRowWithCompositeCondition() {
      // Specify that the row is returned when the value of the col1 column is Tablestore, and the value of the col5 column is 123456789.
      var condition = new TableStore.CompositeCondition(TableStore.LogicalOperator.AND);
      condition.addSubCondition(new TableStore.SingleColumnCondition('col1', 'Tablestore', TableStore.ComparatorType.EQUAL));
      condition.addSubCondition(new TableStore.SingleColumnCondition('col5', Long.fromNumber(123456789), TableStore.ComparatorType.EQUAL));
    
      params.columnFilter = condition;
      client.getRow(params, function (err, data) {
        if (err) {
          console.log('error:', err);
          return;
        }
        console.log('success:', data);
      });
    }