Todos os produtos
Search
Central de documentação

Tablestore:Crie uma tabela de dados

Última atualização: Jul 03, 2026

Este tópico descreve como criar uma tabela de dados do Tablestore com o SDK para PHP.

Observações de uso

Após criar uma tabela de dados, aguarde o carregamento completo antes de executar operações nos dados. Caso contrário, as operações falharão. Esse processo geralmente leva alguns segundos.

Pré-requisitos

Inicializar um cliente do Tablestore

Descrição do método

public function createTable(array $request)

Descrição do parâmetro $request

  • table_meta (obrigatório) object: Informações da estrutura da tabela. Inclui os seguintes parâmetros:

    Nome

    Tipo

    Descrição

    table_name (obrigatório)

    string

    Nome da tabela de dados.

    primary_key_schema (obrigatório)

    array

    Informações da chave primária.

    • Configure de 1 a 4 colunas de chave primária, ordenadas em ordem crescente por padrão. A primeira coluna funciona como chave de partição.

    • Os tipos de dados da chave primária incluem STRING, INTEGER e BINARY. Colunas de chave primária do tipo inteiro que não são chaves de partição podem ser definidas como colunas de chave primária com incremento automático.

    defined_column (opcional)

    array

    Informações das colunas predefinidas.

    • Colunas predefinidas são colunas de atributo definidas antecipadamente. Use-as para criar índices secundários e índices de pesquisa.

    • Os tipos de dados das colunas predefinidas incluem STRING, INTEGER, BLOB, DOUBLE ou BOOLEAN.

  • table_options (opcional) object: Informações de configuração da tabela. Inclui os seguintes parâmetros:

    Nome

    Tipo

    Descrição

    time_to_live (opcional)

    int

    Ciclo de vida dos dados em segundos. Valor padrão: -1.

    • Se definido como -1, os dados nunca expiram. Caso contrário, o valor mínimo é 86400 (1 dia). O sistema limpa automaticamente os dados que excederem o ciclo de vida.

    • Para usar índices de pesquisa ou secundários, defina o ciclo de vida dos dados como -1 ou configure allow_update como false.

    max_versions (opcional)

    int

    Número máximo de versões. Valor padrão: 1.

    • Para usar índices de pesquisa ou secundários, defina o número máximo de versões como 1.

    deviation_cell_version_in_sec (opcional)

    int

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

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

    • O intervalo de versão válido para dados de colunas de atributo é [max(Data write time - Max version offset, Data write time - TTL value), Data write time + Max version offset).

    allow_update (opcional)

    bool

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

    • Se definido como false, não é possível atualizar dados com o método updateRow().

  • index_metas (opcional) object: Lista de índices secundários. Cada índice inclui os seguintes parâmetros:

    Nome

    Tipo

    Descrição

    name (obrigatório)

    string

    Nome do índice.

    primary_key (obrigatório)

    array

    Colunas de chave primária do índice.

    • As colunas de chave primária de um índice combinam colunas de chave primária e colunas predefinidas da tabela de dados.

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

    defined_column (obrigatório)

    array

    Colunas predefinidas do índice.

    • Devem corresponder às colunas predefinidas da tabela de dados.

    index_type (opcional)

    string

    Tipo do índice. Valores válidos:

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

    • LOCAL_INDEX: índice secundário local.

    index_update_mode (opcional)

    string

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

    • ASYNC_INDEX (valor padrão): atualização assíncrona. Obrigatório para índices secundários globais.

    • SYNC_INDEX: atualização síncrona. Obrigatório para índices secundários locais.

  • stream_spec (opcional) object: Informações de configuração do Stream. Inclui os seguintes parâmetros:

    Nome

    Tipo

    Descrição

    enable_stream (opcional)

    bool

    Indica se o Stream está ativado. Valor padrão: false.

    expiration_time (opcional)

    int

    Tempo de expiração do Stream. Indica o período de retenção dos logs incrementais. Unidade: horas. Valor máximo: 168 (7 dias).

    • Se enable_stream for true, defina expiration_time.

  • reserved_throughput (obrigatório) object: O throughput reservado de leitura e gravação, em CU. Apenas instâncias de alto desempenho no modo CU aceitam valores diferentes de zero.

Código de exemplo

Criar uma tabela de dados

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

$request = array (
    // Table structure information
    'table_meta' => array (
        'table_name' => 'test_table',
        // At least one primary key is required to create a data table
        'primary_key_schema' => array (
            array('id', PrimaryKeyTypeConst::CONST_STRING)
        ),
        // (Optional) Add predefined columns
        'defined_column' => array (
            array('name', DefinedColumnTypeConst::DCT_STRING)
        )
    ), 
    // (Optional) Table configuration information
    'table_options' => array (
        // (Optional) Data lifecycle, -1 indicates that data never expires
        'time_to_live' => -1,
        // (Optional) Maximum number of versions
        'max_versions' => 1,
        // (Optional) Maximum version offset
        'deviation_cell_version_in_sec' => 86400,
        // (Optional) Whether to allow updates
        'allow_update' => true
    ), 
    // (Optional) Set Stream information
    'stream_spec' => array (
        'enable_stream' => true,
        'expiration_time' => 168
    ),
    // Reserved read and write throughput must be set when creating a data table (only high-performance instances in CU mode support setting non-zero values for reserved read and write throughput)
    'reserved_throughput' => array (
        'capacity_unit' => array (
            'read' => 0,
            'write' => 0
        )
    )
);

try{
    $client->createTable( $request );
    echo "Create table succeeded.";
} catch (Exception $e) {
    echo "Create table failed.";
}

Criar uma tabela de dados com índices secundários

O exemplo a seguir cria uma tabela de dados com índices secundários.

$request = array (
    // Table structure information
    'table_meta' => array (
        'table_name' => 'test_table',
        // Primary key
        'primary_key_schema' => array (
            array('id', PrimaryKeyTypeConst::CONST_STRING)
        ),
        // Predefined columns
        'defined_column' => array (
            array('name', DefinedColumnTypeConst::DCT_STRING)
        )
    ), 
    // Reserved read and write throughput (only high-performance instances in CU mode support setting non-zero values for reserved read and write throughput)
    'reserved_throughput' => array (
        'capacity_unit' => array (
            'read' => 0,
            'write' => 0
        )
    ),
    // Secondary index information
    'index_metas' => array(
        array(
            'name' => 'test_table_index',
            'primary_key' => array('id'),
            'defined_column' => array('name'),
            'index_type' => IndexTypeConst::LOCAL_INDEX,
            'index_update_mode' => IndexUpdateModeConst::SYNC_INDEX
        )
    )
);

try{
    $client->createTable( $request );
    echo "Create table succeeded.";
} catch (Exception $e) {
    echo "Create table failed.";
}

Referências