Tablestore provides the GetRow operation to allow you to read a single row of data and provides operations such as BatchGetRow and GetRange to allow you to read multiple rows of data in a batch.
Prerequisites
- The OTSClient instance is initialized. For more information, see Initialization.
- A data table is created. Data is written to the table.
Read a single row of data
You can call the GetRow operation to read a single row of data.
- If the row exists, the primary key columns and attribute columns of the row are returned.
- If the row does not exist, no row is returned and no error is reported.
API operations
/*
* Read a single row of data based on a specified primary key.
*/
getRow(params, callback)
Parameters
Parameter | Description |
---|---|
tableName | The name of the data table. |
primaryKey | The primary key of the row.
Note The number and types of the primary key columns that you specify must be the same
as the actual number and types of primary key columns in the data table.
|
columnsToGet | The columns that you want to return. You can specify the names of primary key columns
or attribute columns.
If you do not specify a column name, all data in the row is returned. Note
|
maxVersions | The maximum number of data versions that can be returned.
Note You must configure at least one of the following parameters: maxVersions and timeRange.
|
timeRange | The range of versions or the specific version that you want to read. For more information,
see TimeRange.
Note You must configure at least one of the following parameters: maxVersions and timeRange.
Only one of specificTime and [startTime, endTime) is required. Valid values of timeRange range from 0 to Long.MAX_VALUE. Unit: milliseconds. |
columnFilter | The filter that you want to use to filter the query results on the server side. Only
rows that meet the filter conditions are returned. For more information, see Configure a filter.
Note If you configure the columnsToGet and columnFilter parameters, Tablestore queries
the columns that are specified by columnsToGet, and then returns the rows that meet
the filter conditions.
|
Examples
The following code provides an example on how to read a row of data:
var TableStore = require('../index.js');
var Long = TableStore.Long;
var client = require('./client');
var params = {
tableName: "sampleTable",
primaryKey: [{ 'gid': Long.fromNumber(20004) }, { 'uid': Long.fromNumber(20004) }],
maxVersions: 2 // Specify the maximum number of versions that can be read. A value of 2 indicates that you can read a maximum of two versions of data.
};
var condition = new TableStore.CompositeCondition(TableStore.LogicalOperator.AND);
condition.addSubCondition(new TableStore.SingleColumnCondition('name', 'john', TableStore.ComparatorType.EQUAL));
condition.addSubCondition(new TableStore.SingleColumnCondition('addr', 'china', TableStore.ComparatorType.EQUAL));
params.columnFilter = condition;
client.getRow(params, function (err, data) {
if (err) {
console.log('error:', err);
return;
}
console.log('success:', data);
});
To view the detailed sample code, visit GetRow@GitHub.
Read multiple rows of data in a batch
You can call the BatchGetRow operation to read multiple rows of data from one or more tables in a batch. The BatchGetRow operation consists of multiple GetRow operations. The process of constructing a suboperation is the same as the process of calling the GetRow operation. BatchGetRow supports filters.
Note that the BatchGetRow operation uses the same parameter configurations for all
rows. For example, if ColumnsToGet is set to [colA], only the value of the colA column
is read from all rows.
If you call the BatchGetRow operation, each GetRow operation is separately performed and the response to each GetRow operation is separately returned.
Usage notes
When you call the BatchGetRow operation to read multiple rows in a batch, some rows may fail to be read. If this happens, Tablestore does not return exceptions, but returns BatchGetRowResponse in which the indexes and error messages of the failed rows are included. Therefore, when you call the BatchGetRow operation, you must check the return values to determine whether the status of each row is successful.
Operations
/**
* Read multiple rows of data from one or more tables.
*/
batchGetRow(params, callback)
Parameters
- Hierarchies are created for tables. Data from multiple tables can be read at a time.
You can configure the tables parameter to specify information about tables and rows on which you want to perform the read operations.
- The primaryKey parameter allows you to set primary keys for multiple rows. You can use the primaryKey parameter to read data from multiple rows at a time.
Example
The following code provides an example on how to read data from multiples tables in a batch and retry the read operations if an error occurs:
var client = require('./client');
var TableStore = require('../index.js');
var Long = TableStore.Long;
var params = {
tables: [{
tableName: 'sampleTable',
primaryKey: [
[{ 'gid': Long.fromNumber(20013) }, { 'uid': Long.fromNumber(20013) }],
[{ 'gid': Long.fromNumber(20015) }, { 'uid': Long.fromNumber(20015) }]
],
startColumn: "col2",
endColumn: "col4"
},
{
tableName: 'notExistTable',
primaryKey: [
[{ 'gid': Long.fromNumber(10001) }, { 'uid': Long.fromNumber(10001) }]
]
}
],
};
var maxRetryTimes = 3;
var retryCount = 0;
function batchGetRow(params) {
client.batchGetRow(params, function (err, data) {
if (err) {
console.log('error:', err);
return;
}
var isAllSuccess = true;
var retryRequest = { tables: [] };
for (var i = 0; i < data.tables.length; i++) {
var failedRequest = { tableName: data.tables[i][0].tableName, primaryKey: [] };
for (var j = 0; j < data.tables[i].length; j++) {
if (!data.tables[i][j].isOk && null != data.tables[i][j].primaryKey) {
isAllSuccess = false;
var pks = [];
for (var k in data.tables[i][j].primaryKey) {
var name = data.tables[i][j].primaryKey[k].name;
var value = data.tables[i][j].primaryKey[k].value;
var kp = {};
kp[name] = value;
pks.push(kp);
}
failedRequest.primaryKey.push(pks);
} else {
// get success data
}
}
if (failedRequest.primaryKey.length > 0) {
retryRequest.tables.push(failedRequest);
}
}
if (!isAllSuccess && retryCount++ < maxRetryTimes) {
batchGetRow(retryRequest);
}
console.log('success:', data);
});
}
batchGetRow(params, maxRetryTimes);
For the detailed sample code, visit BatchGetRow@GitHub.
Read data whose primary key is in a specified range
You can call the GetRange operation to read data whose primary key is in a specified range.
The GetRange operation allows you to read data whose primary key is in a specified range in a forward or backward direction. You can also specify the number of rows to read. If the range is large and the number of scanned rows or the volume of scanned data exceeds the upper limit, the scan stops, and the rows that are read and information about the primary key of the next row are returned. You can initiate a request to start from where the last operation left off and read the remaining rows based on information about the primary key of the next row returned by the previous operation.
Usage notes
GetRange follows the leftmost matching principle. Tablestore compares values in sequence from the first primary key column to the last primary key column to read data whose primary key is in a specified range. For example, the primary key of a data table consists of the following primary key columns: PK1, PK2, and PK3. When data is read, Tablestore first determines whether the PK1 value of a row is in the range that is specified for the first primary key column. If the PK1 value of a row is in the range, Tablestore stops determining whether the values of other primary key columns of the row are in the ranges that are specified for each primary key column and returns the row. If the PK1 value of a row is not in the range, Tablestore continues to determine whether the values of other primary key columns of the row are in the ranges that are specified for each primary key column in the same manner as PK1.
- The amount of scanned data reaches 4 MB.
- The number of scanned rows reaches 5,000.
- The number of returned rows reaches the upper limit.
- The read throughput is insufficient to read the next row of data because all reserved read throughput is consumed.
API operations
/**
* Read data whose primary key is in the specified range.
*/
getRange(params, callback)
Parameters
Parameter | Description |
---|---|
tableName | The name of the data table. |
direction | The order in which you want to sort the rows in the response.
For example, if you set the direction parameter to FORWARD for a table that contains two primary keys A and B, and the value of A is smaller than the value of B, the rows whose primary key values are greater than or equal to the value of A but smaller than the value of B are returned in ascending order from A to B. If you set the direction parameter to BACKWARD, the rows whose primary key values are smaller than or equal to the value of B and greater than the value of A are returned in descending order from B to A. |
inclusiveStartPrimaryKey | The start primary key and end primary key of the range that you want to read. The
start primary key and end primary key must be valid primary keys or virtual points
that contain data of the INF_MIN type and INF_MAX type. The number of columns for
each virtual point must be the same as the number of columns of each primary key.
INF_MIN indicates an infinitely small value. All values of other types are greater than the INF_MIN type value. INF_MAX indicates an infinitely great value. All values of other types are smaller than the INF_MAX type value.
The rows in the data table are sorted in ascending order based on the primary key values. The range that is used to read data is a left-closed, right-open interval. If data is read in the forward direction, the rows whose primary keys are greater than or equal to the start primary key but smaller than the end primary key are returned. |
exclusiveEndPrimaryKey | |
limit | The maximum number of rows that can be returned. The value of this parameter must
be greater than 0.
An operation stops after the maximum number of rows that can be returned in the forward or backward direction is reached, even if some rows in the specified range are not returned. You can use the value of nextStartPrimaryKey returned in the response to read data in the next request. |
columnsToGet | The columns that you want to return. You can specify the names of primary key columns
or attribute columns.
If you do not specify a column name, all data in the row is returned. Note
|
maxVersions | The maximum number of data versions that can be returned.
Note You must configure at least one of the following parameters: maxVersions and timeRange.
|
timeRange | The range of versions or the specific version that you want to read. For more information,
see TimeRange.
Note You must configure at least one of the following parameters: maxVersions and timeRange.
Only one of specificTime and [startTime, endTime) is required. Valid values of timeRange range from 0 to Long.MAX_VALUE. Unit: milliseconds. |
columnFilter | The filter that you want to use to filter the query results on the server side. Only
rows that meet the filter conditions are returned. For more information, see Configure a filter.
Note If you configure the columnsToGet and columnFilter parameters, Tablestore queries
the columns that are specified by columnsToGet, and then returns the rows that meet
the filter conditions.
|
nextStartPrimaryKey | The start primary key of the next read request. The value of nextStartPrimaryKey can
be used to determine whether all data is read.
|
Examples
The following code provides an example on how to read data whose primary key is in a specified range:
var Long = TableStore.Long;
var client = require('./client');
var params = {
tableName: "sampleTable",
direction: TableStore.Direction.FORWARD,
inclusiveStartPrimaryKey: [{ "gid": TableStore.INF_MIN }, { "uid": TableStore.INF_MIN }],
exclusiveEndPrimaryKey: [{ "gid": TableStore.INF_MAX }, { "uid": TableStore.INF_MAX }],
limit: 50
};
client.getRange(params, function (err, data) {
if (err) {
console.log('error:', err);
return;
}
// If the value of data.next_start_primary_key is not empty, the system continues to read data.
if (data.next_start_primary_key) {
}
console.log('success:', data);
});
To view the detailed sample code, visit GetRange@GitHub.