Como usar o SDK para .NET para ler uma única linha de dados, ler várias linhas de dados por vez ou ler dados cujos valores de chave primária estão no intervalo especificado? - Tablestore: Central de Documentação do Alibaba Cloud

Tablestore oferece operações para leitura de dados em tabelas: leitura de uma única linha, leitura de múltiplas linhas em lote, varredura de um intervalo de chaves primárias ou iteração sobre um intervalo com um iterador.

Métodos de consulta

O Tablestore disponibiliza três operações para leitura de dados: GetRow, BatchGetRow e GetRange. Escolha a operação adequada conforme o cenário de consulta.

Importante

Para ler dados de uma tabela com coluna de chave primária autoincremental, recupere primeiro todos os valores das colunas de chave primária, incluindo o valor autoincremental. Para mais informações, consulte Coluna de chave primária autoincremental. Caso o valor autoincremental não esteja disponível, use GetRange para realizar a varredura com base na primeira coluna de chave primária.

Operação	Descrição	Quando usar
Ler uma única linha de dados	Lê uma única linha pela chave primária usando a operação GetRow.	Todas as colunas de chave primária são conhecidas e é necessário ler um pequeno número de linhas.
Ler várias linhas de dados por vez	Lê múltiplas linhas de uma ou mais tabelas em uma única chamada usando a operação BatchGetRow. Cada linha é lida independentemente e retorna seu próprio resultado.	Todas as colunas de chave primária são conhecidas e é necessário ler um grande número de linhas ou ler de várias tabelas.
Ler dados cujos valores de chave primária estão dentro de um intervalo específico	Varre linhas cujos valores de chave primária se enquadram em um intervalo especificado usando a operação GetRange. Suporta varredura direta e reversa, limites de linhas e paginação automática via `nextStartPrimaryKey`.	É possível determinar o intervalo de valores de chave primária ou um prefixo de chave primária. Importante Se nenhum prefixo for conhecido, defina a chave inicial como INF_MIN e a chave final como INF_MAX para varrer toda a tabela. Isso consome recursos computacionais significativos — proceda com cautela.
Ler dados cujos valores de chave primária estão dentro de um intervalo específico usando um iterador	Lê linhas em um intervalo de chave primária usando um iterador, que gerencia a paginação automaticamente.	O intervalo ou prefixo de chave primária pode ser determinado e você deseja iterar sobre os resultados sem gerenciar a paginação manualmente.

Pré-requisitos

Antes de começar, certifique-se de ter:

Uma instância OTSClient inicializada. Para mais informações, consulte Inicializar uma instância OTSClient.
Uma tabela de dados criada com dados gravados nela. Para mais informações, consulte Criar tabelas de dados e Gravar dados.

Ler uma única linha de dados

Chame a operação GetRow para ler uma única linha pela chave primária.

Operação da API

/// <summary>
/// Read a single row based on the specified primary key.
/// </summary>
/// <param name="request">Data query request</param>
/// <returns>Response of GetRow</returns>
public GetRowResponse GetRow(GetRowRequest request);

/// <summary>
/// Asynchronous version of GetRow.
/// </summary>
public Task<GetRowResponse> GetRowAsync(GetRowRequest request);

Parâmetros

Parâmetro	Descrição
tableName	Nome da tabela.
primaryKey	Chave primária da linha a ser lida, especificada como nome da coluna, tipo e valor. Importante A quantidade e os tipos das colunas de chave primária devem corresponder exatamente ao esquema da tabela.
columnsToGet	Colunas a serem retornadas — colunas de chave primária ou colunas de atributo. Se omitido, todas as colunas são retornadas. Se não for especificado, todos os dados da linha serão retornados. Caso as colunas especificadas estejam ausentes na linha, `null` será retornado para essas colunas. Se apenas algumas das colunas especificadas existirem, somente os valores disponíveis serão retornados. Nota Por padrão, todas as colunas são retornadas. Use `columnsToGet` para limitar a resposta a colunas específicas. Por exemplo, adicionar `col0` e `col1` retorna apenas essas duas colunas. Se tanto `columnsToGet` quanto `filter` estiverem definidos, o Tablestore busca primeiro as colunas especificadas e depois aplica o filtro.
maxVersions	Número máximo de versões de dados a serem retornadas. Importante Especifique pelo menos um entre `maxVersions` ou `timeRange`. Apenas `maxVersions`: retorna o número especificado de versões, da mais recente para a mais antiga. Apenas `timeRange`: retorna todas as versões no intervalo de tempo especificado ou a versão em um timestamp específico. Ambos especificados: retorna até `maxVersions` versões dentro do intervalo de tempo, da mais recente para a mais antiga.
timeRange	Intervalo de tempo da versão ou versão específica a ser lida. Para mais informações, consulte TimeRange. Importante Especifique pelo menos um entre `maxVersions` ou `timeRange`. Apenas `maxVersions`: retorna o número especificado de versões, da mais recente para a mais antiga. Apenas `timeRange`: retorna todas as versões no intervalo de tempo especificado ou a versão em um timestamp específico. Ambos especificados: retorna até `maxVersions` versões dentro do intervalo de tempo, da mais recente para a mais antiga. Para consultar um intervalo de versões, defina `start_time` e `end_time`. O intervalo é fechado à esquerda e aberto à direita: `[start_time, end_time)`. Para consultar uma versão específica, defina `specific_time` com o timestamp exato. Apenas um entre `specific_time` ou `[start_time, end_time)` é necessário. Intervalo válido: 0 a `Int64.MaxValue`, em milissegundos.
filter	Filtro aplicado no servidor após a recuperação dos dados. Apenas as linhas correspondentes às condições do filtro são retornadas. Para mais informações, consulte Filtros. Nota Se tanto `columnsToGet` quanto `filter` estiverem definidos, o Tablestore busca primeiro as colunas especificadas e depois aplica o filtro.

Código de exemplo

Ler uma linha de dados

O código de exemplo a seguir demonstra como ler uma linha de dados:

    // Specify the primary key. The columns and types must match the table schema.
    PrimaryKey primaryKey = new PrimaryKey();
    primaryKey.Add("pk0", new ColumnValue(0));
    primaryKey.Add("pk1", new ColumnValue("abc"));

    try
    {
        // Build the request. Omitting columnsToGet returns the entire row.
        var request = new GetRowRequest(TableName, primaryKey);

        // Call GetRow.
        var response = otsClient.GetRow(request);

        // Process the returned row data.
        // (Omitted here—see the GitHub sample for the full implementation.)

        Console.WriteLine("Get row succeeded.");
    }
    catch (Exception ex)
    {
        Console.WriteLine("Update table failed, exception:{0}", ex.Message);
    }

Para visualizar o código de exemplo detalhado, visite GetRow@GitHub.

Ler uma linha de dados usando um filtro

O exemplo a seguir lê col0 e col1 e retorna a linha apenas se o valor de col0 for 5 ou se o valor de col1 não for ff.

    // Specify the primary key. The columns and types must match the table schema.
    PrimaryKey primaryKey = new PrimaryKey();
    primaryKey.Add("pk0", new ColumnValue(0));
    primaryKey.Add("pk1", new ColumnValue("abc"));

    var rowQueryCriteria = new SingleRowQueryCriteria("SampleTable");
    rowQueryCriteria.RowPrimaryKey = primaryKey;

    // Condition 1: col0 == 5
    var filter1 = new RelationalCondition("col0",
                RelationalCondition.CompareOperator.EQUAL,
                new ColumnValue(5));

    // Condition 2: col1 != "ff"
    var filter2 = new RelationalCondition("col1", RelationalCondition.CompareOperator.NOT_EQUAL, new ColumnValue("ff"));

    // Combine with OR: return the row if either condition is met.
    var filter = new CompositeCondition(CompositeCondition.LogicOperator.OR);
    filter.AddCondition(filter1);
    filter.AddCondition(filter2);

    rowQueryCriteria.Filter = filter;

    // Fetch only col0 and col1, then apply the filter.
    rowQueryCriteria.AddColumnsToGet("col0");
    rowQueryCriteria.AddColumnsToGet("col1");

    var request = new GetRowRequest(rowQueryCriteria);

    try
    {
        var response = otsClient.GetRow(request);

        // Process the returned row data.
        // (Omitted here—see the GitHub sample for the full implementation.)

        Console.WriteLine("Get row with filter succeeded.");
    }
    catch (Exception ex)
    {
        Console.WriteLine("Get row with filter failed, exception:{0}", ex.Message);
    }

Para visualizar o código de exemplo detalhado, visite GetRowWithFilter@GitHub.

Ler várias linhas de dados por vez

Chame a operação BatchGetRow para ler múltiplas linhas de uma ou mais tabelas em uma única solicitação. Cada linha é processada como uma chamada GetRow independente — o Tablestore retorna um resultado separado para cada linha.

Observações de uso

Algumas linhas em uma solicitação em lote podem falhar individualmente. Os erros dessas linhas aparecem no BatchGetRowResponse em vez de serem lançados como exceções. Sempre inspecione a resposta para confirmar que cada linha foi lida com sucesso.
Os mesmos parâmetros se aplicam a todas as linhas da solicitação. Por exemplo, definir ColumnsToGet=[colA] faz com que apenas colA seja lido de cada linha.
Uma única solicitação BatchGetRow pode ler no máximo 100 linhas.

Operação da API

/// <summary>
/// Read multiple rows from one or more tables in a single call.
/// Each row is read and billed independently, but batching reduces
/// round-trip overhead compared to multiple GetRow calls.
/// </summary>
/// <param name="request">Request instance</param>
/// <returns>Response instance</returns>
public BatchGetRowResponse BatchGetRow(BatchGetRowRequest request);

/// <summary>
/// Asynchronous version of BatchGetRow.
/// </summary>
public Task<BatchGetRowResponse> BatchGetRowAsync(BatchGetRowRequest request);

Código de exemplo

O exemplo a seguir lê 10 linhas em uma única chamada BatchGetRow:

// Build primary keys for 10 rows.
List<PrimaryKey> primaryKeys = new List<PrimaryKey>();
for (int i = 0; i < 10; i++)
{
    PrimaryKey primaryKey = new PrimaryKey();
    primaryKey.Add("pk0", new ColumnValue(i));
    primaryKey.Add("pk1", new ColumnValue("abc"));
    primaryKeys.Add(primaryKey);
}

try
{
    BatchGetRowRequest request = new BatchGetRowRequest();
    request.Add(TableName, primaryKeys);

    var response = otsClient.BatchGetRow(request);
    var tableRows = response.RowDataGroupByTable;
    var rows = tableRows[TableName];

    // Inspect each row's result individually—some rows may have failed.
    // (Omitted here—see the GitHub sample for the full implementation.)
}
catch (Exception ex)
{
    Console.WriteLine("Batch get row failed, exception:{0}", ex.Message);
}

Para visualizar o código de exemplo detalhado, visite BatchGetRow@GitHub.

Ler dados cujos valores de chave primária estão dentro de um intervalo específico

Chame a operação GetRange para varrer linhas cujos valores de chave primária se enquadram em um intervalo especificado. A varredura pode ser direta ou reversa, e é possível limitar o número de linhas retornadas. Se a varredura atingir um limite (volume de dados, contagem de linhas ou throughput reservado), ela será interrompida antecipadamente e retornará um valor nextStartPrimaryKey. Utilize esse valor como chave inicial em uma solicitação subsequente para ler as linhas restantes.

Nota

Todas as linhas em uma tabela do Tablestore são ordenadas pela chave primária composta completa, e não por qualquer coluna individual de chave primária.

Observações de uso

GetRange utiliza o princípio de correspondência mais à esquerda: o Tablestore compara os valores das colunas de chave primária da esquerda para a direita. Quando o valor de uma linha para a primeira coluna de chave primária (PK1) está dentro do intervalo especificado, a linha é retornada sem avaliar as demais colunas. Quando PK1 está fora do intervalo, o Tablestore continua avaliando as colunas restantes da mesma maneira.

Uma operação GetRange é interrompida antecipadamente quando qualquer um dos seguintes limites é atingido:

Os dados varridos atingem 4 MB.
O número de linhas varridas atinge 5.000.
O número de linhas retornadas atinge o limit especificado.
O throughput de leitura reservado se esgota antes que a próxima linha possa ser lida.

Operação da API

/// <summary>
/// Read rows whose primary key values are within the specified range.
/// </summary>
/// <param name="request">Request instance</param>
/// <returns>Response instance</returns>
public GetRangeResponse GetRange(GetRangeRequest request);

/// <summary>
/// Asynchronous version of GetRange.
/// </summary>
/// <param name="request"></param>
/// <returns></returns>
public Task<GetRangeResponse> GetRangeAsync(GetRangeRequest request);

Parâmetros

Parâmetro	Descrição
tableName	Nome da tabela.
direction	Direção da varredura. FORWARD: a chave inicial deve ser menor que a chave final; as linhas são retornadas em ordem crescente. BACKWARD: a chave inicial deve ser maior que a chave final; as linhas são retornadas em ordem decrescente. Por exemplo, dados os valores de chave primária A e B onde A < B: definir direction como FORWARD com o intervalo `[A, B)` retorna linhas com chaves ≥ A e < B em ordem crescente. Definir direction como BACKWARD com o intervalo `[B, A)` retorna linhas com chaves ≤ B e > A em ordem decrescente.
inclusiveStartPrimaryKey	Chaves primárias inicial e final do intervalo. Ambas devem ser colunas de chave primária válidas ou colunas virtuais do tipo INF_MIN ou INF_MAX. O número de colunas deve corresponder ao esquema de chave primária da tabela. INF_MIN é menor que todos os outros valores. INF_MAX é maior que todos os outros valores. `inclusiveStartPrimaryKey`: linhas com esta chave são incluídas nos resultados. `exclusiveEndPrimaryKey`: linhas com esta chave são excluídas dos resultados. O intervalo é fechado à esquerda e aberto à direita. Na direção direta, linhas com chaves ≥ início e < fim são retornadas.
exclusiveEndPrimaryKey
limit	Número máximo de linhas a serem retornadas. Deve ser maior que 0. Quando o limite é atingido, a varredura para e retorna `nextStartPrimaryKey`. Use esse valor como chave inicial na próxima solicitação para continuar a leitura.
columnsToGet	Colunas a serem retornadas — colunas de chave primária ou colunas de atributo. Se omitido, todas as colunas são retornadas. Se não for especificado, todos os dados da linha serão retornados. Caso as colunas especificadas estejam ausentes na linha, `null` será retornado para essas colunas. Se apenas algumas das colunas especificadas existirem, somente os valores disponíveis serão retornados. Nota Por padrão, todas as colunas são retornadas. Use `columnsToGet` para limitar a resposta a colunas específicas. Por exemplo, adicionar `col0` e `col1` retorna apenas essas duas colunas. Se uma linha no intervalo não contiver nenhuma das colunas especificadas, ela será excluída da resposta. Se tanto `columnsToGet` quanto `filter` estiverem definidos, o Tablestore busca primeiro as colunas especificadas e depois aplica o filtro.
maxVersions	Número máximo de versões de dados a serem retornadas. Importante Especifique pelo menos um entre `maxVersions` ou `timeRange`. Apenas `maxVersions`: retorna o número especificado de versões, da mais recente para a mais antiga. Apenas `timeRange`: retorna todas as versões no intervalo de tempo especificado ou a versão em um timestamp específico. Ambos especificados: retorna até `maxVersions` versões dentro do intervalo de tempo, da mais recente para a mais antiga.
timeRange	Intervalo de tempo da versão ou versão específica a ser lida. Para mais informações, consulte TimeRange. Importante Especifique pelo menos um entre `maxVersions` ou `timeRange`. Apenas `maxVersions`: retorna o número especificado de versões, da mais recente para a mais antiga. Apenas `timeRange`: retorna todas as versões no intervalo de tempo especificado ou a versão em um timestamp específico. Ambos especificados: retorna até `maxVersions` versões dentro do intervalo de tempo, da mais recente para a mais antiga. Para consultar um intervalo de versões, defina `start_time` e `end_time`. O intervalo é fechado à esquerda e aberto à direita: `[start_time, end_time)`. Para consultar uma versão específica, defina `specific_time` com o timestamp exato. Apenas um entre `specific_time` ou `[start_time, end_time)` é necessário. Intervalo válido: 0 a `Int64.MaxValue`, em milissegundos.
filter	Filtro aplicado no servidor após a recuperação dos dados. Apenas as linhas correspondentes às condições do filtro são retornadas. Para mais informações, consulte Configurar filtro. Nota Se tanto `columnsToGet` quanto `filter` estiverem definidos, o Tablestore busca primeiro as colunas especificadas e depois aplica o filtro.
nextStartPrimaryKey	Chave inicial para a próxima solicitação de leitura, retornada quando a resposta é paginada. Se `nextStartPrimaryKey` não for nulo, use-o como `inclusiveStartPrimaryKey` na próxima solicitação GetRange para continuar a leitura. Se `nextStartPrimaryKey` for nulo, todos os dados no intervalo foram retornados.

Código de exemplo

O exemplo a seguir varre todas as linhas com valores de chave primária entre (0, INF_MIN) e (100, INF_MAX), gerenciando a paginação automaticamente:

// Define the key range: pk0 from 0 (inclusive) to 100 (exclusive).
var inclusiveStartPrimaryKey = new PrimaryKey();
inclusiveStartPrimaryKey.Add("pk0", new ColumnValue(0));
inclusiveStartPrimaryKey.Add("pk1", ColumnValue.INF_MIN);

var exclusiveEndPrimaryKey = new PrimaryKey();
exclusiveEndPrimaryKey.Add("pk0", new ColumnValue(100));
exclusiveEndPrimaryKey.Add("pk1", ColumnValue.INF_MAX);

try
{
    var request = new GetRangeRequest(TableName, GetRangeDirection.Forward,
                    inclusiveStartPrimaryKey, exclusiveEndPrimaryKey);

    var response = otsClient.GetRange(request);

    // Collect all rows, paginating until nextStartPrimaryKey is null.
    var rows = response.RowDataList;
    var nextStartPrimaryKey = response.NextPrimaryKey;
    while (nextStartPrimaryKey != null)
    {
        request = new GetRangeRequest(TableName, GetRangeDirection.Forward,
                        nextStartPrimaryKey, exclusiveEndPrimaryKey);
        response = otsClient.GetRange(request);
        nextStartPrimaryKey = response.NextPrimaryKey;
        foreach (RowDataFromGetRange row in response.RowDataList)
        {
            rows.Add(row);
        }
    }

    // Process all collected rows.
    // (Omitted here—see the GitHub sample for the full implementation.)

    Console.WriteLine("Get range succeeded");
}
catch (Exception ex)
{
    Console.WriteLine("Get range failed, exception:{0}", ex.Message);
}

Para visualizar o código de exemplo detalhado, visite GetRange@GitHub.

Ler dados cujos valores de chave primária estão dentro de um intervalo específico usando um iterador

Chame a operação GetRangeIterator para varrer um intervalo de chave primária usando um iterador. Diferentemente do GetRange, o iterador gerencia a paginação automaticamente — não há necessidade de verificar nextStartPrimaryKey e emitir solicitações subsequentes manualmente.

Operação da API

/// <summary>
/// Scan rows whose primary key values are within the specified range.
/// Returns an iterator that yields one row at a time, handling pagination internally.
/// </summary>
/// <param name="request"><see cref="GetIteratorRequest"/></param>
/// <returns>An iterator of <see cref="RowDataFromGetRange"/>.</returns>
public IEnumerable<RowDataFromGetRange> GetRangeIterator(GetIteratorRequest request);

Código de exemplo

O exemplo a seguir lê todas as linhas com valores de chave primária entre (0, "a") e (1000, "xyz"):

PrimaryKey inclusiveStartPrimaryKey = new PrimaryKey();
inclusiveStartPrimaryKey.Add("pk0", new ColumnValue(0));
inclusiveStartPrimaryKey.Add("pk1", new ColumnValue("a"));

PrimaryKey exclusiveEndPrimaryKey = new PrimaryKey();
exclusiveEndPrimaryKey.Add("pk0", new ColumnValue(1000));
exclusiveEndPrimaryKey.Add("pk1", new ColumnValue("xyz"));

// Track capacity units consumed during iteration.
var cu = new CapacityUnit(0, 0);

try
{
    // Filters are supported on GetIteratorRequest.
    var request = new GetIteratorRequest(TableName, GetRangeDirection.Forward, inclusiveStartPrimaryKey,
                                                exclusiveEndPrimaryKey, cu);

    var iterator = otsClient.GetRangeIterator(request);
    foreach (var row in iterator)
    {
        // Process each row.
    }

    Console.WriteLine("Iterate row succeeded");
}
catch (Exception ex)
{
    Console.WriteLine("Iterate row failed, exception:{0}", ex.Message);
}

Para visualizar o código de exemplo detalhado, visite GetRangeIterator@GitHub.