文档

创建二级索引

更新时间:

在数据表上创建索引表后,可根据需要读取索引表中的数据或者删除数据表上指定的索引表。

说明
  • 二级索引包括全局二级索引和本地二级索引。关于二级索引的更多信息,请参见二级索引

  • 您也可以使用CreateTable接口在创建数据表的同时创建一个或者多个索引表。具体操作,请参见创建数据表

前提条件

  • 已初始化Client。具体操作,请参见初始化

  • 已创建数据表,且数据表的最大版本数(max_versions)必须为1,数据生命周期(time_to_live)必须满足如下条件中的任意一个。

    • 数据表的数据生命周期为-1(数据永不过期)。

    • 数据表的数据生命周期不为-1时,数据表为禁止更新状态。

  • 数据表已设置预定义列。

注意事项

  • 索引表名称不能与已存在的时序表名称和数据表名称相同。

  • 创建二级索引时,系统会自动将未出现在索引列中的数据表主键补齐到索引表主键中。

  • 创建本地二级索引时,索引表的第一列主键必须与数据表的第一列主键相同。

接口

/**
 * 创建二级索引。
 * @api
 *
 * @param [] $request
 *            请求参数,数据表名称。
 * @return [] 请求返回
 * @throws OTSClientException 当参数检查出错或服务端返回校验出错时抛出异常。
 * @throws OTSServerException 当OTS服务端返回错误时抛出异常。
 * @example "src/examples/CreateIndex.php"
 */
public function createIndex(array $request)

参数

参数

说明

table_name

数据表名称。

index_meta

索引表的结构信息,包括如下内容:

  • name:索引表名称。

  • primary_key:索引表的索引列,索引列为数据表主键和预定义列的任意组合。

  • defined_column:索引表的属性列,索引表属性列为数据表的预定义列的组合。

  • index_update_mode:索引表更新模式,可选值包括IndexUpdateModeConst::ASYNC_INDEXIndexUpdateModeConst::SYNC_INDEX

    • 当不设置index_update_mode或者设置index_update_mode为IndexUpdateModeConst::ASYNC_INDEX时,表示异步更新。

      使用全局二级索引时,索引更新模式必须设置为异步更新(IndexUpdateModeConst::ASYNC_INDEX)。

    • 当设置index_update_mode为IndexUpdateModeConst::SYNC_INDEX时,表示同步更新。

      使用本地二级索引时,索引更新模式必须设置为同步更新(IndexUpdateModeConst::SYNC_INDEX)。

  • index_type:索引表类型,索引类型。可选值包括IndexTypeConst::GLOBAL_INDEXIndexTypeConst::LOCAL_INDEX

    • 当不设置index_type或者设置index_type为IndexTypeConst::GLOBAL_INDEX时,表示使用全局二级索引。

      使用全局二级索引时,表格存储以异步方式将数据表中被索引的列和主键列的数据自动同步到索引表中,正常情况下同步延迟达到毫秒级别。

    • 当设置index_type为IndexTypeConst::LOCAL_INDEX时,表示使用本地二级索引。

      使用本地二级索引时,表格存储以同步方式将数据表中被索引的列和主键列的数据自动同步到索引表中,当数据写入数据表后,即可从索引表中查询到数据。

include_base_data

索引表中是否包含数据表中已存在的数据,默认值为false。

  • 当设置include_base_data为true时,表示包含存量数据。

  • 当不设置include_base_data或者设置include_base_data为false时,表示不包含存量数据。

示例

创建全局二级索引

创建二级索引时,如果不指定index_type和index_update_mode,则默认创建的为全局二级索引。

$request = array(
    'table_name' => '<TABLE_NAME>', //设置数据表名称。
    //'include_base_data' => true,  //设置此参数为true,表示创建二级索引时包含存量数据。
    'index_meta' => array(
        'name' => '<INDEX_NAME>',  //设置索引表名称。
        'primary_key' => array('Col1'), //设置索引表主键列。
        'defined_column' => array('Col2')  //设置索引表属性列。
    )
);
$otsClient->createIndex($request);

您也可以通过指定index_type和index_update_mode来创建全局二级索引。

$request = array(
    'table_name' => '<TABLE_NAME>', //设置数据表名称。
    //'include_base_data' => true,  //设置此参数为true,表示创建二级索引时包含存量数据。
    'index_meta' => array(
        'name' => '<INDEX_NAME>',  //设置索引表名称。
        'primary_key' => array('Col1'),  //设置索引表主键列。
        'defined_column' => array('Col2'), //设置索引表属性列。
        'index_type' => IndexTypeConst::GLOBAL_INDEX,
        'index_update_mode' => IndexUpdateModeConst::ASYNC_INDEX
    )
);
$otsClient->createIndex($request);

创建本地二级索引

以下示例用于创建一个本地二级索引。

$createLocalRequest = array (
   'table_name' => '<TABLE_NAME>', //设置数据表名称。
    //'include_base_data' => true,  //设置此参数为true,表示创建二级索引时包含存量数据。
   'index_meta' => array (
       'name' => '<INDEX_NAME>', //设置索引表名称。
       'primary_key' => array('PK0', 'Col1'), //设置索引表主键。索引表的第一列主键必须与数据表的第一列主键相同。
       'defined_column' => array('Col2'), //设置索引表属性列。
       'index_type' => IndexTypeConst::LOCAL_INDEX,
       'index_update_mode' => IndexUpdateModeConst::SYNC_INDEX
   )
);
$otsClient->createIndex($createLocalRequest);

相关文档

  • 创建二级索引后,您可以单行读取或者范围读取数据。具体操作,请参见使用二级索引读取数据

  • 如果不再需要使用二级索引,您可以删除二级索引。具体操作,请参见删除二级索引