创建多元索引

最佳使用方式

请根据实际查询需求确定在一张数据表中创建多元索引的个数。

例如有一张数据表有5个字段，分别为id、name、age、city、sex，需要按照name、age或city查询数据时，有两种创建多元索引的方式。

• 方法一：一个字段建立一个多元索引

  按照name、age或city字段分别创建多元索引，名称分别为name_index、age_index、city_index。

  • 如果按照城市查询学生，则查询city_index，如果按照年龄查询学生，则查询age_index。

  • 如果查询年龄小于12岁且城市是成都的学生，此种方式就无法查询。

  此方式的实现类似于全局二级索引，使用此方式创建多元索引会带来更高的费用，因此不建议使用此方式创建多元索引。

• 方法二：多个字段创建在一个多元索引中

  将name、age和city字段创建在一个多元索引中，名称为student_index。

  • 如果按照城市查询学生，则查询student_index中city字段；如果按照年龄查询学生，则查询student_index中age字段。

  • 如果查询年龄小于12岁且城市是成都的学生，则查询student_index中age和city字段。

  此方式才能发挥多元索引最大优势，不仅功能更丰富，而且价格会更低。极力推荐使用此方式创建多元索引。

使用限制

• 创建索引的时效性

  创建多元索引后，需要等几秒钟才能使用，但是此过程中不影响数据写入，只影响索引元信息的查询和索引查询。

• 创建多元索引时，请确保多元索引中的字段类型与表中的字段类型相匹配。更多信息，请参见数据类型映射。

• 数量限制

  更多信息，请参见多元索引限制。

参数

创建多元索引时，需要指定数据表名称（tableName）、多元索引名称（indexName）和索引的结构信息（indexSchema），其中indexSchema包含fieldSchemas（Index的所有字段的设置）、indexSetting（索引设置）和indexSort（索引预排序设置）。详细参数说明请参见下表。

注意事项

• 当要实现全文检索时，您可以在多元索引中将字段设置为可分词字符串（TEXT）类型并为TEXT类型的字段设置分词，然后使用匹配查询或短语匹配查询功能查询数据。关于分词的更多信息，请参见分词。

• 在不修改表格存储的存储结构及数据的情况下，当要实现新字段和新数据类型的查询功能时，您可以在多元索引中将字段设置为虚拟列。更多信息，请参见虚拟列。

• 当要使用日期数据类型进行数据查询时，您可以在多元索引中将数据表中的整型（Integer）或字符串（String）类型的数据在多元索引中映射为日期数据类型。更多信息，请参见日期数据类型。

• 当要使用数值向量进行近似最近邻查询时，您可以在多元索引中将字段设置为向量类型，然后使用向量检索功能查询数据。

• 当要使用数组类型存储数据时，您可以在数据表中以String类型字段存储数据，然后在多元索引中将字段设置为数组。

  在写入数据到数据表中时，数组类型字段的值必须按照JSON数组格式写入，例如["a","b","c"]。

  说明

  数组类型仅是多元索引中的概念，数据表中还不支持数组。更多信息，请参见数组和嵌套类型。

• 当要使用单字段存储存在层次关系或者一对多关系的数据时，您可以在多元索引中将字段设置为嵌套类型，然后使用嵌套类型查询功能查询数据。

  在写入数据到数据表中时，嵌套类型字段的值必须按照JSON数组格式写入，例如[{"tagName":"tag1", "score":0.8}, {"tagName":"tag2", "score":0.2}]。

• 当要存储的数据为地理位置信息时，您可以在多元索引中将字段设置为地理位置（Geo-point）类型，然后使用地理距离查询、地理长方形范围查询或地理多边形范围查询功能查询数据。

• 系统默认使用分区键作为路由键，当要使用其他主键列作为路由键来定向搜索指定数据分区，以减少长尾对延迟的影响时，您可以修改路由字段配置。更多信息，请参见多元索引路由字段的使用。

• 多元索引默认按照主键升序的排序方式返回查询结果，当要按照指定字段值或主键降序进行预排序时，您可以修改预排序方式。更多信息，请参见索引预排序。

• 当要实现自动清理多元索引中的历史数据时，您可以使用多元索引的数据生命周期（TTL）功能有效地管理数据，减少数据存储空间，降低存储成本。更多信息，请参见生命周期管理。

使用方式

您可以使用控制台、命令行工具或者SDK进行创建多元索引操作。

进行多元索引创建之前，您需要完成如下准备工作。

• 使用阿里云账号或者使用具有表格存储操作权限的RAM用户进行操作。如果需要为RAM用户授权表格存储操作权限，请参见通过RAM Policy为RAM用户授权进行配置。

  使用SDK方式和命令行工具方式进行操作时，如果当前无可用AccessKey，则需要为阿里云账号或者RAM用户创建AccessKey。具体操作，请参见创建AccessKey。

• 已创建数据表。具体操作，请参见数据表操作。

• 使用SDK方式进行操作时，还需要完成初始化Client。具体操作，请参见初始化OTSClient。

• 使用命令行工具方式进行操作前，还需要完成下载并启动命令行工具，然后配置接入实例信息。具体操作，请参见下载命令行工具和启动并配置。

private static void createSearchIndex(SyncClient client) {
    CreateSearchIndexRequest request = new CreateSearchIndexRequest();
    //设置数据表名称。
    request.setTableName("<TABLE_NAME>"); 
    //设置多元索引名称。
    request.setIndexName("<SEARCH_INDEX_NAME>"); 
    IndexSchema indexSchema = new IndexSchema();
    indexSchema.setFieldSchemas(Arrays.asList(
            //设置字段名和类型。
            new FieldSchema("Col_Keyword", FieldType.KEYWORD), 
            new FieldSchema("Col_Long", FieldType.LONG)));
            // 设置向量类型。
            new FieldSchema("Col_Vector", FieldType.VECTOR).setIndex(true)
                    // 向量维度为4，相似度算法为点积。
                    .setVectorOptions(new VectorOptions(VectorDataType.FLOAT_32, 4, VectorMetricType.DOT_PRODUCT))
    ));
    request.setIndexSchema(indexSchema);
    //调用client创建多元索引。
    client.createSearchIndex(request); 
}

private static void createSearchIndexWithIndexSort(SyncClient client) {
    CreateSearchIndexRequest request = new CreateSearchIndexRequest();
    //设置数据表名称。
    request.setTableName("<TABLE_NAME>"); 
    //设置多元索引名称。
    request.setIndexName("<SEARCH_INDEX_NAME>"); 
    IndexSchema indexSchema = new IndexSchema();
    indexSchema.setFieldSchemas(Arrays.asList(
            new FieldSchema("Col_Keyword", FieldType.KEYWORD),
            new FieldSchema("Col_Long", FieldType.LONG),
            new FieldSchema("Col_Text", FieldType.TEXT),
            new FieldSchema("Timestamp", FieldType.LONG)
                    .setEnableSortAndAgg(true)));
    //设置按照Timestamp列进行预排序。
    indexSchema.setIndexSort(new Sort(
            Arrays.<Sort.Sorter>asList(new FieldSort("Timestamp", SortOrder.ASC))));
    request.setIndexSchema(indexSchema);
    //调用client创建多元索引。
    client.createSearchIndex(request);
}

// 请使用5.12.0及以上版本的Java SDK。
public static void createIndexWithTTL(SyncClient client) {
    int days = 7;
    CreateSearchIndexRequest createRequest = new CreateSearchIndexRequest();
    //设置数据表名称。
    createRequest.setTableName("<TABLE_NAME>");
    //设置多元索引名称。
    createRequest.setIndexName("<SEARCH_INDEX_NAME>");
    IndexSchema indexSchema = new IndexSchema();
    indexSchema.setFieldSchemas(Arrays.asList(
            //设置字段名和类型。
            new FieldSchema("Col_Keyword", FieldType.KEYWORD), 
            new FieldSchema("Col_Long", FieldType.LONG)));
    createRequest.setIndexSchema(indexSchema);
    //设置多元索引TTL。
    createRequest.setTimeToLiveInDays(days);
    //调用client创建多元索引。
    client.createSearchIndex(createRequest);
}

private static void createSearchIndex(SyncClient client) {
    CreateSearchIndexRequest request = new CreateSearchIndexRequest();
    //设置数据表名称。
    request.setTableName("<TABLE_NAME>"); 
    //设置多元索引名称。
    request.setIndexName("<SEARCH_INDEX_NAME>"); 
    IndexSchema indexSchema = new IndexSchema();
    indexSchema.setFieldSchemas(Arrays.asList(
        //设置字段名和类型。
        new FieldSchema("Col_Keyword", FieldType.KEYWORD), 
        //设置字段名和类型。
        new FieldSchema("Col_Keyword_Virtual_Long", FieldType.LONG) 
             //设置字段是否为虚拟列。
            .setVirtualField(true) 
             //虚拟列对应的数据表中字段。
            .setSourceFieldName("Col_Keyword"), 
        new FieldSchema("Col_Long", FieldType.LONG),
        new FieldSchema("Col_Long_Virtual_Keyword", FieldType.KEYWORD)
            .setVirtualField(true)
            .setSourceFieldName("Col_Long")));
    request.setIndexSchema(indexSchema);
    //调用client创建多元索引。
    client.createSearchIndex(request); 
}

后续操作

创建多元索引后，您可以通过多元索引进行数据查询、数据分析与数据导出。

相关文档

创建多元索引后，请根据需要执行相应操作。

• 如果希望清理多元索引中的历史数据或者希望延长数据保存时间，您可以修改多元索引的数据生命周期。具体操作，请参见生命周期管理。

• 如果要在多元索引中新增、更新或者删除索引列，您可以使用动态修改schema功能实现。具体操作，请参见动态修改schema。

• 如果要获取某个数据表关联的所有多元索引的列表信息，您可以使用列出多元索引列表功能实现。具体操作，请参见列出多元索引列表。

• 如果要查询多元索引的描述信息，包括多元索引的字段信息和索引配置等，您可以使用查询多元索引描述信息功能实现。具体操作，请参见查询多元索引描述信息。

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

• 您还可以使用SQL查询功能或者通过MaxCompute、Spark、Hive或者HadoopMR、函数计算、Flink、PrestoDB等计算引擎计算与分析表中数据。具体操作，请参见SQL查询和计算与分析概述。

附录：距离度量算法说明

向量的距离度量算法说明请参见下表，其中评分公式的值越大表示的相似度越大。

向量归一化的示例代码如下：

  public static float[] l2normalize(float[] v, boolean throwOnZero) {
    double squareSum = 0.0f;
    int dim = v.length;
    for (float x : v) {
      squareSum += x * x;
    }
    if (squareSum == 0) {
      if (throwOnZero) {
        throw new IllegalArgumentException("can't normalize a zero-length vector");
      } else {
        return v;
      }
    }
    double length = Math.sqrt(squareSum);
    for (int i = 0; i < dim; i++) {
      v[i] /= length;
    }
    return v;
  }