表格存储 Node.js SDK 范围读取数据-表格存储 Tablestore(Tablestore)-阿里云帮助中心

本文介绍如何通过 Node.js SDK 范围读取表格存储中的数据。

前提条件

方法说明

getRange: function getRange(params, callback)

params参数说明

名称	类型	说明
tableName（必选）	string	数据表名称。
inclusiveStartPrimaryKey（必选）	Array	起始主键信息，包括主键列名称和主键值。返回数据包含起始主键。主键个数和类型必须与数据表的主键保持一致。正向读取数据时，起始主键必须小于结束主键。反向读取数据时，起始主键必须大于结束主键。 TableStore.INF_MIN 表示无限小，TableStore.INF_MAX 表示无限大。
exclusiveEndPrimaryKey（必选）	Array	结束主键信息，包括主键列名称和主键值。返回数据不包含结束主键。主键个数和类型必须与数据表的主键保持一致。 TableStore.INF_MIN 表示无限小，TableStore.INF_MAX 表示无限大。
direction（可选）	string	读取方向。 TableStore.Direction.FORWARD：默认值，正向读取数据。 TableStore.Direction.BACKWARD：反向读取数据。
maxVersions（可选）	number	最大版本数，默认值为1。如果符合查询条件的数据版本数量超过设置的最大版本数，按从新到旧的顺序返回指定版本数量的数据。
timeRange（可选）	object	数据版本范围。表格存储数据表的每个属性列可以有不同的数据版本，设置版本范围后，仅返回版本范围内的数据。
limit（可选）	number	单次返回最大行数，必须大于 0。如果符合查询条件的数据行数大于设置的值，将返回指定的最大行数和用于下一次查询的起始主键值。
columnsToGet（可选）	Array	指定读取的数据列，可以是主键列或属性列。不设置columnsToGet时，返回整行数据。设置columnsToGet时，如果读取的行数据不包含任何指定的数据列，将返回 null。
columnFilter（可选）	TableStore.ColumnCondition	过滤条件，详情请参见过滤器。如果同时设置columnsToGet和columnFilter，先按columnsToGet筛选符合条件的数据行，再按columnFilter条件过滤数据。
transactionId（可选）	string	局部事务ID，用于唯一标识局部事务，详情请参见局部事务。

示例代码

以下示例代码用于读取 test_table 表中主键值大于 row1 的数据。

var params = {
    tableName: 'test_table',
    // 设置查询起始主键
    inclusiveStartPrimaryKey: [{ 'id': 'row1' }],
    // 设置查询结束主键（返回结果不包含结束主键）
    exclusiveEndPrimaryKey: [{ 'id': TableStore.INF_MAX }]
};

// 调用 getRange 方法查询数据
client.getRange(params, function (err, data) {
    if (err) {
        console.log('Get range failed with error: ', err);
        return;
    }

    console.log('* RequestId: ', data.RequestId);
    console.log('* Read CU Cost: ', data.consumed.capacityUnit.read);
    console.log('* Write CU Cost: ', data.consumed.capacityUnit.write);
    console.log('* Rows Data: ');
    data.rows.forEach(function (row) {
         console.log(row);
    });
});

单次范围扫描数据上限为 5000 行或者 4 MB，超出限制部分的数据将返回用于下一次读取的起始主键值，您可以参考以下代码进行迭代查询。

async function getRangeSample() {
    try {
        while (true) {
            // 调用 getRange 方法查询数据
            const data = await client.getRange(params);

            // 返回结果处理
            console.log('* RequestId: ', data.RequestId);
            console.log('* Read CU Cost: ', data.consumed.capacityUnit.read);
            console.log('* Write CU Cost: ', data.consumed.capacityUnit.write);
            console.log('* Rows Data: ');
            data.rows.forEach(function (row) {
                console.log(row);
            });

            // 设置下一次读取数据起始主键
            if (data.nextStartPrimaryKey) {
                params.inclusiveStartPrimaryKey = data.nextStartPrimaryKey.map(item => {
                    return {
                        [item.name]: item.value
                    };
                });
            } else {
                break;
            }
        }
    } catch (err) {
        console.log('Range get failed with error: ', err);
    }
}

getRangeSample();

您也可以在查询数据时参考示例代码进行以下设置。

设置数据读取方向。

var params = {
    tableName: 'test_table',
    // 设置查询起始主键（反向读取数据时，起始主键要大于结束主键）
    inclusiveStartPrimaryKey: [{ 'id': TableStore.INF_MAX }],
    // 设置查询结束主键（返回结果不包含结束主键）
    exclusiveEndPrimaryKey: [{ 'id': 'row1' }],
    // 设置反向读取数据
    direction: TableStore.Direction.BACKWARD
};

设置读取的数据版本范围，结果只返回版本范围内的数据。

// 设置查询的数据版本范围为当前时间往前一天
params.timeRange = {
    startTime: (Date.now() - 86400 * 1000).toString(),
    endTime: Date.now().toString()
}

指定读取的属性列。
```
params.columnsToGet = ['col2']
```
设置单次返回最大行数。
```
params.limit = 10
```

前提条件

方法说明

示例代码

相关文档