Todos os produtos
Search
Central de documentação

Tablestore:Criar uma tabela de dados

Última atualização: Jul 03, 2026

Chame o método createTable para criar uma tabela de dados no Tablestore e configurar seu esquema, opções, índices e definições de criptografia.

Método

public CreateTableResponse createTable(CreateTableRequest createTableRequest) throws TableStoreException, ClientException

Parâmetros de CreateTableRequest

  • tableMeta (obrigatório) TableMeta: Esquema da tabela. Este parâmetro contém os seguintes subparâmetros.

    Nome

    Tipo

    Descrição

    tableName (obrigatório)

    String

    Nome da tabela de dados.

    primaryKey (obrigatório)

    List<PrimaryKeySchema>

    Esquema de chave primária da tabela de dados.

    • Aceita de uma a quatro colunas de chave primária. Os dados são classificados em ordem crescente por padrão. A primeira coluna de chave primária funciona como chave de partição.

    • Tipos de dados compatíveis: STRING, INTEGER e BINARY. Uma coluna de chave primária do tipo inteiro que não seja chave de partição pode ser definida como coluna de chave primária com incremento automático.

    definedColumns (opcional)

    List<DefinedColumnSchema>

    Colunas predefinidas da tabela de dados.

  • tableOptions (obrigatório) TableOptions: Configuração da tabela de dados. Este parâmetro contém os seguintes subparâmetros.

    Nome

    Tipo

    Descrição

    timeToLive (obrigatório)

    OptionalValue<Integer>

    Tempo de vida (TTL) dos dados. Unidade: segundos.

    • Defina este parâmetro como -1 para desativar a expiração. O valor mínimo válido é 86400 (um dia). Dados que excedem o TTL são removidos automaticamente.

    • Para usar índices de pesquisa ou secundários, defina o TTL como -1 ou configure o parâmetro allowUpdate como false.

    maxVersions (obrigatório)

    OptionalValue<Integer>

    Número máximo de versões de dados a reter.

    • Para usar um índice de pesquisa ou secundário, defina este parâmetro como 1.

    maxTimeDeviation (opcional)

    OptionalValue<Long>

    Desvio máximo de versão. Unidade: segundos. Valor padrão: 86400 (um dia).

    • A diferença entre o timestamp dos dados gravados e a hora atual do sistema deve estar dentro do desvio máximo de versão. Caso contrário, a operação de gravação falhará.

    • O intervalo de versões válidas para dados de colunas de atributo é [max(Hora da gravação dos dados - Desvio máximo de versão, Hora da gravação dos dados - Tempo de vida), Hora da gravação dos dados + Desvio máximo de versão).

    allowUpdate (opcional)

    OptionalValue<Boolean>

    Indica se as atualizações são permitidas. Valor padrão: true.

    • Quando definido como false, não é possível atualizar os dados pelo método updateRow.

  • indexMeta (opcional) List<IndexMeta>: Índices secundários a criar junto com a tabela de dados. Cada índice contém os seguintes parâmetros.

    Nome

    Tipo

    Descrição

    indexName (obrigatório)

    String

    Nome do índice.

    primaryKey (obrigatório)

    List<String>

    Colunas de chave primária do índice.

    • Composto por colunas de chave primária e colunas predefinidas da tabela de dados.

    • Para um índice secundário local, a primeira coluna de chave primária do índice deve corresponder à primeira coluna de chave primária da tabela de dados.

    definedColumns (opcional)

    List<String>

    Colunas predefinidas do índice.

    • Composto por colunas predefinidas da tabela de dados.

    indexType (opcional)

    IndexType

    Tipo do índice. Valores válidos:

    • IT_GLOBAL_INDEX (padrão): índice secundário global.

    • IT_LOCAL_INDEX: índice secundário local.

    indexUpdateMode (opcional)

    IndexUpdateMode

    Modo de atualização do índice. Valores válidos:

    • IUM_ASYNC_INDEX (padrão): atualização assíncrona. O modo de atualização para um índice secundário global deve ser assíncrono.

    • IUM_SYNC_INDEX: atualização síncrona. O modo de atualização para um índice secundário local deve ser síncrono.

  • streamSpecification (opcional) OptionalValue<StreamSpecification>: Configuração do stream. Este parâmetro contém os seguintes subparâmetros.

    Nome

    Tipo

    Descrição

    enableStream (obrigatório)

    boolean

    Indica se o stream deve ser ativado. Valor padrão: false.

    expirationTime (opcional)

    OptionalValue<Integer>

    Período de retenção para dados de log incrementais no stream. Unidade: horas. Valor máximo: 168 (7 dias).

    • O parâmetro expirationTime é obrigatório se enableStream estiver definido como true.

  • enableLocalTxn (opcional) OptionalValue<Boolean>: Indica se as transações locais devem ser ativadas. Valor padrão: false.

    • Compatível apenas com Java SDK 5.11.0 ou posterior.

    • Transações locais e colunas de chave primária com incremento automático são mutuamente exclusivas. Se houver uma coluna de chave primária com incremento automático configurada, as transações locais não terão efeito mesmo quando ativadas.

    • Para ativar transações locais em uma tabela de dados existente, envie um ticket para solicitar o recurso.

  • sseSpecification (opcional) OptionalValue<SSESpecification>: Configurações de criptografia de dados. A tabela a seguir descreve os parâmetros de sseSpecification.

    Importante

    A criptografia de dados só pode ser ativada e configurada durante a criação da tabela. Não é possível desativá-la após a criação da tabela.

    Nome

    Tipo

    Descrição

    enable (obrigatório)

    boolean

    Indica se a criptografia de dados deve ser ativada. Valor padrão: false.

    keyType (opcional)

    OptionalValue<SSEKeyType>

    Tipo de criptografia. Valores válidos:

    • SSE_KMS_SERVICE: Criptografia KMS.

    • SSE_BYOK: Criptografia Bring-Your-Own-Key (BYOK).

    keyId (opcional)

    OptionalValue<String>

    ID da chave mestra do cliente (CMK). Este parâmetro é necessário apenas se keyType estiver definido como SSE_BYOK.

    roleArn (opcional)

    OptionalValue<String>

    Alibaba Cloud Resource Name (ARN) da função do Resource Access Management (RAM). Este parâmetro é necessário apenas se keyType estiver definido como SSE_BYOK.

  • reservedThroughput (opcional) ReservedThroughput: Throughput reservado de leitura/gravação. Unidade: unidade de capacidade (CU). Valor padrão: 0. Aplica-se apenas a instâncias otimizadas para computação no modo CU.

Código de exemplo

Uso básico

O exemplo a seguir cria uma tabela de dados chamada test_table com uma coluna de chave primária do tipo String.

Após criar uma tabela de dados, aguarde o carregamento da tabela antes de executar operações de dados. O carregamento geralmente leva alguns segundos.
Importante

Não é possível alterar o método de criptografia após a criação da tabela. Para criar uma tabela criptografada, consulte Definir criptografia da tabela de dados.

package org.example.ots;

import com.alicloud.openservices.tablestore.SyncClient;
import com.alicloud.openservices.tablestore.core.ResourceManager;
import com.alicloud.openservices.tablestore.core.auth.CredentialsProvider;
import com.alicloud.openservices.tablestore.core.auth.DefaultCredentialProvider;
import com.alicloud.openservices.tablestore.core.auth.DefaultCredentials;
import com.alicloud.openservices.tablestore.core.auth.V4Credentials;
import com.alicloud.openservices.tablestore.model.*;

public class CreateTable {
    
    public static void main(String[] args) {

        // Obtain access credentials from environment variables. You must configure TABLESTORE_ACCESS_KEY_ID and TABLESTORE_ACCESS_KEY_SECRET.
        final String accessKeyId = System.getenv("TABLESTORE_ACCESS_KEY_ID");
        final String accessKeySecret = System.getenv("TABLESTORE_ACCESS_KEY_SECRET");

        // TODO: Modify the following configurations based on your instance information.
        final String region = "yourRegion"; // The ID of the region where your instance is located. Example: "cn-hangzhou".
        final String instanceName = "yourInstanceName"; // The name of your instance.
        final String endpoint = "yourEndpoint"; // The endpoint of your instance.

        SyncClient client = null;
        try {
            // Create credentials.
            DefaultCredentials credentials = new DefaultCredentials(accessKeyId, accessKeySecret);
            V4Credentials credentialsV4 = V4Credentials.createByServiceCredentials(credentials, region);
            CredentialsProvider provider = new DefaultCredentialProvider(credentialsV4);

            // Create a client instance.
            client = new SyncClient(endpoint, provider, instanceName, null, new ResourceManager(null, null));

            // Define the table schema.
            TableMeta tableMeta = new TableMeta("test_table"); // TODO: Modify the table name as needed.
            // You must add at least one primary key column to create a table.
            tableMeta.addPrimaryKeyColumn(new PrimaryKeySchema("id", PrimaryKeyType.STRING)); // TODO: Modify the table primary key as needed.

            // Configure the table.
            TableOptions tableOptions = new TableOptions();
            // You must specify the max versions when you create a data table.
            tableOptions.setMaxVersions(1);
            // You must specify the time to live (TTL) when you create a data table. A value of -1 means the data never expires.
            tableOptions.setTimeToLive(-1);

            // Create and send the request.
            CreateTableRequest request = new CreateTableRequest(tableMeta, tableOptions);
            client.createTable(request);

            System.out.println("The data table is created.");
        } catch (Exception e) {
            System.err.println("Failed to create the data table. Details:");
            e.printStackTrace();
        } finally {
            // Shut down the client.
            if (client != null) {
                client.shutdown();
            }
        }
    }
}

Adicionar chaves primárias

Adicione chaves primárias usando o método addPrimaryKeyColumn ou addPrimaryKeyColumns. O exemplo a seguir usa addPrimaryKeyColumn.

tableMeta.addPrimaryKeyColumn("name", PrimaryKeyType.STRING);

Adicionar colunas predefinidas

Adicione colunas predefinidas usando o método addDefinedColumn ou addDefinedColumns. O exemplo a seguir usa addDefinedColumn.

tableMeta.addDefinedColumn("age", DefinedColumnType.INTEGER);

Definir o desvio máximo de versão

Defina o desvio máximo de versão usando o método setMaxTimeDeviation.

tableOptions.setMaxTimeDeviation(86400);

Configurar permissões de atualização

Use o método setAllowUpdate para especificar se as atualizações de dados na tabela são permitidas.

tableOptions.setAllowUpdate(false);

Adicionar um índice secundário

Adicione um índice secundário especificando o parâmetro indexMetas ao criar a solicitação.

// Create a list of secondary indexes.
ArrayList<IndexMeta> indexMetas = new ArrayList<IndexMeta>();
// Create a secondary index.
IndexMeta indexMeta = new IndexMeta("test_table_idx");
// Set the primary key of the index.
indexMeta.addPrimaryKeyColumn("id");
// To add more primary key columns, first define the corresponding primary keys or predefined columns in the data table.
// indexMeta.addPrimaryKeyColumn("additional_column");

// Set the index type.
indexMeta.setIndexType(IndexType.IT_LOCAL_INDEX);
// Set the index update mode.
indexMeta.setIndexUpdateMode(IndexUpdateMode.IUM_SYNC_INDEX);
// Add the secondary index.
indexMetas.add(indexMeta);

// Create the request.
CreateTableRequest request = new CreateTableRequest(tableMeta, tableOptions, indexMetas);

Definir informações do stream

Defina as informações do stream usando o método setStreamSpecification da solicitação.

StreamSpecification streamSpecification = new StreamSpecification(true, 168);
request.setStreamSpecification(streamSpecification);

Ativar transações locais

Ative transações locais usando o método setLocalTxnEnabled da solicitação.

request.setLocalTxnEnabled(true);

Definir o throughput reservado de leitura/gravação

Defina o throughput reservado de leitura/gravação usando o método setReservedThroughput da solicitação.

// Set the reserved read throughput to 10000 and the reserved write throughput to 5000.
ReservedThroughput reservedThroughput = new ReservedThroughput(10000, 5000);
request.setReservedThroughput(reservedThroughput);

Definir criptografia da tabela de dados

Defina o método de criptografia usando o método setSseSpecification da solicitação.

  • Criptografia KMS

    SSESpecification sseSpecification = new SSESpecification(true, SSEKeyType.SSE_KMS_SERVICE);
    request.setSseSpecification(sseSpecification);
  • Criptografia BYOK

    Nota

    Antes de executar o código, obtenha o ID da chave mestra do cliente (CMK) e o ARN da função RAM. Para mais informações, consulte Criptografia BYOK.

    String keyId = "key-hzz6*****************";
    String roleArn = "acs:ram::1705************:role/tabletorebyok";
    SSESpecification sseSpecification = new SSESpecification(true, SSEKeyType.SSE_BYOK, keyId, roleArn);
    request.setSseSpecification(sseSpecification);

Referências