表格存储：本地二级索引

前提条件

• 已初始化Client。具体操作，请参见初始化。
• 已创建数据表，且数据表的最大版本数（MaxVersions）必须为1，数据生命周期（TimeToLive）必须满足如下条件中的任意一个。
  • 数据表的数据生命周期为-1（数据永不过期）。
  • 数据表的数据生命周期不为-1时，数据表为禁止更新状态。
• 数据表已设置预定义列。

创建索引表（CreateIndex）

• 参数

  参数	说明
  MainTableName	数据表名称。
  IndexMeta	索引表的结构信息，包括如下内容： IndexName：索引表名称。 PrimaryKey：索引表的索引列，索引列为数据表主键和预定义列的组合。 使用本地二级索引时，索引表的第一个主键列必须与数据表的第一个主键列相同。 DefinedColumns：索引表的属性列，索引表属性列为数据表的预定义列的组合。 IndexType：索引类型。可选值包括IT_GLOBAL_INDEX和IT_LOCAL_INDEX。 当不设置IndexType或者设置IndexType为IT_GLOBAL_INDEX时，表示使用全局二级索引。 使用全局二级索引时，表格存储以异步方式将数据表中被索引的列和主键列的数据自动同步到索引表中，正常情况下同步延迟达到毫秒级别。 当设置IndexType为IT_LOCAL_INDEX时，表示使用本地二级索引。 使用本地二级索引时，表格存储以同步方式将数据表中被索引的列和主键列的数据自动同步到索引表中，当数据写入数据表后，即可从索引表中查询到数据。
  IncludeBaseData	索引表中是否包含数据表中已存在的数据。 当设置IncludeBaseData为true时，表示包含存量数据；设置IncludeBaseData为false时，表示不包含存量数据。

• 示例

  在主键为pk1、pk2的数据表上创建主键列为pk1、definedcol1，属性列为definedcol2的索引表。

  func CreateGlobalIndexSample(client *tablestore.TableStoreClient, tableName string) {
      indexMeta := new(tablestore.IndexMeta) //新建索引表Meta。
      indexMeta.AddPrimaryKeyColumn("pk1") ///索引表的第一列主键必须与数据表的第一列主键相同。
      indexMeta.AddPrimaryKeyColumn("definedcol1") //设置数据表的definedcol1列作为索引表的主键。
      indexMeta.AddDefinedColumn("definedcol2") //设置数据表的definedcol2列作为索引表的属性列。
      indexMeta.IndexType = IT_LOCAL_INDEX //设置索引类型为本地二级索引（IT_LOCAL_INDEX）。
      indexMeta.IndexName = "indexSample"
      indexReq := &tablestore.CreateIndexRequest{
          MainTableName:tableName, //添加索引表到数据表。
          IndexMeta: indexMeta,
          IncludeBaseData: true, //包含存量数据。
      }
      /**
        通过将IncludeBaseData参数设置为true，创建索引表后会开启数据表中存量数据的同步，然后可以通过索引表查询全部数据，
        同步时间跟数据量的大小有一定的关系。
      */  
      resp, err := client.CreateIndex(indexReq)
      if err != nil {
          fmt.Println("Failed to create table with error:", err)
      } else {
          fmt.Println("Create index finished", resp)
      }
  }

读取索引表中数据

从索引表中单行或者范围读取数据，当返回的属性列在索引表中时，可以直接读取索引表获取数据，否则请自行反查数据表获取数据。

• 单行读取索引表中数据

  更多信息，请参见读取单行数据。

  使用GetRow接口读取索引表中数据时有如下注意事项：

  • TableName需要设置为索引表名称。
  • 由于系统会自动将未出现在索引列中的数据表主键补齐到索引表主键中，所以设置行的主键时，需要同时设置索引表索引列和补齐的数据表主键。
• 范围读索引表中数据

  更多信息，请参见范围读取数据。

  • 参数
    使用GetRange接口读取索引表中数据时有如下注意事项：

    • TableName需要设置为索引表名称。
    • 由于系统会自动将未出现在索引列中的数据表主键补齐到索引表主键中，所以设置起始主键和结束主键时，需要同时设置索引表索引列和补齐的数据表主键。
  • 示例

    func GetRangeFromIndex(client *tablestore.TableStoreClient, indexName string) {
        getRangeRequest := &tablestore.GetRangeRequest{}
        rangeRowQueryCriteria := &tablestore.RangeRowQueryCriteria{}
        rangeRowQueryCriteria.TableName = indexName
    
        startPK := new(tablestore.PrimaryKey)
        startPK.AddPrimaryKeyColumnWithMinValue("pk1") //索引表的第一主键列。
        startPK.AddPrimaryKeyColumnWithMinValue("definedcol1") //索引表的第二主键列。
        startPK.AddPrimaryKeyColumnWithMinValue("pk2") //索引表的第三主键列，此主键列为自动补齐的数据表主键列。
    
        endPK := new(tablestore.PrimaryKey)
        endPK.AddPrimaryKeyColumnWithMaxValue("pk1")
        endPK.AddPrimaryKeyColumnWithMaxValue("definedcol1")  
        endPK.AddPrimaryKeyColumnWithMaxValue("pk2")
        rangeRowQueryCriteria.StartPrimaryKey = startPK
        rangeRowQueryCriteria.EndPrimaryKey = endPK
        rangeRowQueryCriteria.Direction = tablestore.FORWARD
        rangeRowQueryCriteria.MaxVersion = 1
        rangeRowQueryCriteria.Limit = 10
        getRangeRequest.RangeRowQueryCriteria = rangeRowQueryCriteria
    
        getRangeResp, err := client.GetRange(getRangeRequest)
    
        fmt.Println("get range result is ", getRangeResp)
    
        for {
            if err != nil {
                fmt.Println("get range failed with error:", err)
            }
            if len(getRangeResp.Rows) > 0 {
                for _, row := range getRangeResp.Rows {
                    fmt.Println("range get row with key", row.PrimaryKey.PrimaryKeys[0].Value, row.PrimaryKey.PrimaryKeys[1].Value, row.PrimaryKey.PrimaryKeys[2].Value)
                }
                if getRangeResp.NextStartPrimaryKey == nil {
                    break
                } else {
                    fmt.Println("next pk is :", getRangeResp.NextStartPrimaryKey.PrimaryKeys[0].Value, getRangeResp.NextStartPrimaryKey.PrimaryKeys[1].Value, getRangeResp.NextStartPrimaryKey.PrimaryKeys[2].Value)
                    getRangeRequest.RangeRowQueryCriteria.StartPrimaryKey = getRangeResp.NextStartPrimaryKey
                    getRangeResp, err = client.GetRange(getRangeRequest)
                }
            } else {
                break
            }
    
            fmt.Println("continue to query rows")
        }
        fmt.Println("putrow finished")
    }

删除索引表（DeleteIndex）

使用DeleteIndex接口删除数据表上指定的索引表。

• 参数

  参数	说明
  MainTableName	数据表名称。
  IndexName	索引表名称。

• 示例

  func DeleteIndex(client *tablestore.TableStoreClient, tableName string， indexName string) { 
      deleteIndex := &tablestore.DeleteIndexRequest{ MainTableName:tableName, IndexName: indexName }
      resp, err := client.DeleteIndex(deleteIndex)
  
      if err != nil {
          fmt.Println("Failed to delete index:", err)
      } else {
          fmt.Println("drop index finished", resp)
      }