Create a secondary index by using Tablestore SDK for PHP - Tablestore

La función de índice secundario permite consultar datos con base en la clave principal de una tabla de datos y en las columnas de índice del índice secundario creado para dicha tabla. Si necesita utilizar las columnas de atributo de una tabla de datos para consultar información, cree un índice secundario para acelerar las consultas. Al crear un índice secundario para una tabla de datos, puede establecer las columnas de índice o las columnas de atributo del índice secundario como las columnas predefinidas que especificó al crear la tabla de datos. Una vez creado el índice secundario, utilícelo para consultar los datos.

Nota

Los índices secundarios se clasifican en índices secundarios globales e índices secundarios locales. Para obtener más información sobre esta función, consulte Secondary index.
Al llamar a la operación CreateTable para crear una tabla de datos, también puede crear una o más tablas de índice. Para obtener más información, consulte Create a data table.

Requisitos previos

Se inicializó una instancia de OTSClient. Para obtener más información, consulte Initialize a Tablestore client.
Se creó una tabla de datos con el parámetro max_versions establecido en 1. El parámetro time_to_live de la tabla de datos debe cumplir alguna de las siguientes condiciones:
- El parámetro time_to_live de la tabla de datos está establecido en -1, lo que significa que los datos de la tabla nunca caducan.
- El parámetro time_to_live de la tabla de datos tiene un valor distinto de -1 y las operaciones de actualización en la tabla están prohibidas.
Se especificaron las columnas predefinidas para la tabla de datos.

Descripción

Un índice secundario utiliza un esquema de clave principal diferente, compuesto por columnas de clave principal y columnas predefinidas de una tabla de datos, para proporcionar dimensiones de consulta adicionales. Los índices secundarios se clasifican en índices secundarios globales e índices secundarios locales. Ambos tipos de índice tienen distintos modos de sincronización de datos y requisitos de clave principal. Para obtener más información, consulte Overview.

Llame a createIndex para crear un índice secundario en una tabla de datos existente. Si desea crear uno o más índices secundarios junto con una tabla de datos, configure los esquemas de índice en la solicitud createTable. Para obtener más información, consulte Create a data table.

public CreateIndexResponse createIndex(CreateIndexRequest createIndexRequest)
        throws TableStoreException, ClientException

A continuación se muestra un ejemplo de código que crea el índice secundario global example_global_index para example_table. Este índice incluye los datos existentes.

IndexMeta indexMeta = new IndexMeta("example_global_index");
indexMeta.addPrimaryKeyColumn("category");
indexMeta.addDefinedColumn("status");

CreateIndexRequest request =
        new CreateIndexRequest("example_table", indexMeta, true);
client.createIndex(request);

Operación de API

/**
 * Create a secondary index. 
 * @api
 *
 * @param [] $request
 *            The request parameter, which is the name of the data table. 
 * @return [] The response.
 * @throws OTSClientException The exception that is returned when a parameter error occurs or the Tablestore server returns a verification error. 
 * @throws OTSServerException The exception that is returned when the Tablestore server returns an error. 
 * @example "src/examples/CreateIndex.php"
 */
public function createIndex(array $request)

Parámetros

Parámetro	Descripción
table_name	El nombre de la tabla de datos.
index_meta	La información del esquema de la tabla de índice. Esta información contiene los siguientes elementos: name: el nombre de la tabla de índice. primary_key: la clave principal de la tabla de índice. Es una combinación de todas las columnas de clave principal y un número arbitrario de columnas predefinidas de la tabla de datos. defined_column: las columnas de atributo de la tabla de índice. Son una combinación de columnas predefinidas de la tabla de datos. index_update_mode: el modo de actualización de la tabla de índice. Valores válidos: `IndexUpdateModeConst::ASYNC_INDEX` y `IndexUpdateModeConst::SYNC_INDEX`. Si no especifica el parámetro index_update_mode o lo establece en `IndexUpdateModeConst::ASYNC_INDEX`, se utiliza el modo asíncrono para actualizar el índice. Si utiliza la función de índice secundario global, debe establecer el parámetro index_update_mode en `IndexUpdateModeConst::ASYNC_INDEX`. Si establece el parámetro index_update_mode en `IndexUpdateModeConst::SYNC_INDEX`, se utiliza el modo síncrono para actualizar el índice. Si utiliza la función de índice secundario local, debe establecer el parámetro index_update_mode en `IndexUpdateModeConst::SYNC_INDEX`. index_type: el tipo de la tabla de índice. Valores válidos: `IndexTypeConst::GLOBAL_INDEX` y `IndexTypeConst::LOCAL_INDEX`. Si no especifica el parámetro index_type o lo establece en `IndexTypeConst::GLOBAL_INDEX`, se crea un índice secundario global. Tablestore sincroniza automáticamente los datos desde las columnas indexadas y las columnas de clave principal de la tabla de datos hacia las columnas de la tabla de índice que desea crear. Esta sincronización se realiza en modo asíncrono y su latencia es de unos pocos milisegundos. Si establece el parámetro index_type en `IndexTypeConst::LOCAL_INDEX`, se crea un índice secundario local. Tablestore sincroniza automáticamente los datos desde las columnas indexadas y las columnas de clave principal de la tabla de datos hacia las columnas de la tabla de índice que desea crear. Esta sincronización se realiza en modo síncrono. Después de escribir los datos en la tabla de datos, puede consultarlos de inmediato en la tabla de índice.
include_base_data	Especifica si se deben incluir los datos existentes de la tabla de datos en la tabla de índice. Valor predeterminado: false. Si establece el parámetro include_base_data en true, los datos existentes de la tabla de datos se incluyen en la tabla de índice. Si no especifica el parámetro include_base_data o lo establece en false, los datos existentes de la tabla de datos no se incluyen en la tabla de índice.

Ejemplos

Crear un índice secundario global

Si no especifica los parámetros index_type e index_update_mode al crear un índice secundario, se genera un índice secundario global.

$request = array(
    'table_name' => '<TABLE_NAME>', // Specify the name of the data table. 
    //'include_base_data' => true,  // Set the include_base_data parameter to true to include the existing data of the data table to the index table. 
    'index_meta' => array(
        'name' => '<INDEX_NAME>',  // Specify the name of the index table. 
        'primary_key' => array('Col1'), // Specify the primary key column of the index table. 
        'defined_column' => array('Col2')  // Specify the attribute column of the index table. 
    )
);
$otsClient->createIndex($request);

También puede especificar los parámetros index_type e index_update_mode para crear un índice secundario global.

$request = array(
    'table_name' => '<TABLE_NAME>', // Specify the name of the data table. 
    //'include_base_data' => true,  // Set the include_base_data parameter to true to include the existing data of the data table to the index table. 
    'index_meta' => array(
        'name' => '<INDEX_NAME>',  // Specify the name of the index table. 
        'primary_key' => array('Col1'), // Specify the primary key column of the index table. 
        'defined_column' => array('Col2')  // Specify the attribute column of the index table. 
        'index_type' => IndexTypeConst::GLOBAL_INDEX,
        'index_update_mode' => IndexUpdateModeConst::ASYNC_INDEX
    )
);
$otsClient->createIndex($request);

Crear un índice secundario local

El siguiente ejemplo de código muestra cómo crear un índice secundario local:

$createLocalRequest = array (
   'table_name' => '<TABLE_NAME>', // Specify the name of the data table. 
    //'include_base_data' => true,  // Set the include_base_data parameter to true to include the existing data of the data table to the index table. 
   'index_meta' => array (
       'name' => '<INDEX_NAME>',  // Specify the name of the index table. 
       'primary_key' => array('PK0', 'Col1'), // Specify the primary key column of the index table. The first primary key column of the index table must be the same as the first primary key column of the data table. 
       'defined_column' => array('Col2')  // Specify the attribute column of the index table. 
       'index_type' => IndexTypeConst::LOCAL_INDEX,
       'index_update_mode' => IndexUpdateModeConst::SYNC_INDEX
   )
);
$otsClient->createIndex($createLocalRequest);

Referencias

Después de crear un índice secundario, utilícelo para leer una sola fila de datos o aquellos cuyos valores de clave principal estén dentro de un rango específico. Para obtener más información, consulte Use a secondary index to read data.
Puede eliminar un índice secundario que ya no necesite. Para obtener más información, consulte Delete a secondary index.