CSS索引使用指南

操作场景

在CSS数据同步场景中，若需将GeminiDB Cassandra实例中的用户表数据同步至CSS集群，关键流程之一是通过同步功能连接GeminiDB Cassandra实例，并对目标用户表执行创建CSS索引的CQL操作。所以本章将详细介绍CSS索引的使用方法及注意事项。

使用须知

• 支持的数据同步操作：创建CSS索引、删除CSS索引、修改索引mappings配置，以及INSERT、UPDATE、DELETE类型CQL的数据同步。
• 一个GeminiDB Cassandra实例只能选择一个目标CSS集群执行数据同步。
• 一个GeminiDB Cassandra用户表只能创建一个CSS索引，且同一个用户表中不得同时存在CSS索引与Lucene索引。
• 不同用户表创建的CSS索引建议避免重名，除非这些表中的用户数据需要在CSS端同步到同一个索引中。
• CSS索引一旦创建，其settings和cassandra_mapping_templates配置无法通过ALTER命令修改。
• 通过TTL机制或Truncate命令删除的数据不支持CSS数据同步。
• CSS索引不能包含存量文档。
• GeminiDB Cassandra用户表仅部分支持CSS数据同步，详细信息请参见用户表数据类型限制。

• 用户表每行记录中，主键个数与主键编码字符数之和不得超过512。主键类型与主键编码字符数的关系请参见主键类型与主键编码字符数的关系。
• CSS索引mappings限制。
  • 在strict模式下，properties必须包含用户表中的所有主键列。
  • 当主键类型为text或varchar时，properties中对应的数据类型必须指定为keyword。
  • properties中的列必须存在于GeminiDB Cassandra用户表中。
  • properties中的列名不得与保留字段 _TIMESTAMP_INTERNAL 冲突。
  • properties中的列数据类型须与GeminiDB Cassandra表中同名列兼容。详细信息请参见Cassandra数据类型兼容的CSS数据类型。

创建CSS索引

基础表结构示例

CREATE TABLE test_ks.test_cf(
     country text,
     city text,
     longitude int, 
     latitude int, 
     primary key(country,city) 
); 

创建CSS索引语法

使用特定的settings和mappings，为用户表创建名为test_index的CSS索引，数据会同步到目标CSS集群的test_index索引下。

CREATE CUSTOM INDEX test_index ON test_ks.test_cf () USING 'OpenSearchIndex'
WITH OPTIONS = {
     'settings': '{
       "number_of_shards": 1,
       "number_of_replicas": 1
     }',
     'mappings': '{
         "properties": {
             "country": {"type": "keyword"},
             "city": {"type": "keyword"},
             "longitude": {"type": "long"},
             "latitude": {"type": "long"}
        }
    }'
}; 

数据同步示例

执行CQL插入：

INSERT INTO test_ks.test_cf(country, city, longitude, latitude) VALUES('XXX', 'XXX', 39, 116); 

CSS中查询结果：

{ 
    "country": "XXX",
    "city": "XXX",
    "longitude": 39,
    "latitude": 116
} 

OPTIONS配置参数说明

• settings

  与CSS ElasticSearch中的创建索引配置settings含义一致，在CSS创建索引时直接引用。

• mappings

  与CSS ElasticSearch中的创建索引配置mappings含义一致，在CSS创建索引时直接引用。

• cassandra_mapping_templates

  支持使用ElasticSearch复杂数据类型（如object、point等），提供GeminiDB Cassandra普通列值填充复杂数据类型的模板。

  • point类型示例

    在CSS ElasticSearch中，point数据类型表示经纬度地理信息数据。如下示例使用point类型，并用longitude、latitude列的值对经度和纬度数据进行填充。

    CREATE CUSTOM INDEX test_index ON test_ks.test_cf () USING 'OpenSearchIndex'
    WITH OPTIONS = {
         'cassandra_mapping_templates': '{
             "location": {
                 "type": "point",
                 "coordinates": ["${longitude}", "${latitude}"]
             }
         }'
    }; 

    执行CQL插入：

    INSERT INTO test_ks.test_cf(country, city, longitude, latitude) VALUES('XXX', 'XXX', 39, 116); 

    插入数据后CSS查询结果：

    {     
        "country": "XXX",
        "city": "XXX", 
        "longitude": 39, 
        "latitude": 116, 
        "location": {
            "type": "point",
            "coordinates": [39, 116]
        }
    }

  • 默认值处理

    当普通列值为Null时，可使用默认值避免Null填充：

    CREATE CUSTOM INDEX test_index ON test_ks.test_cf () USING 'OpenSearchIndex'
    WITH OPTIONS = {
        'cassandra_mapping_templates': '{
            "location": {
                "type": "point",
                "coordinates": ["${longitude:90}", "${latitude:180}"]
            }
        }'
    }; 

    未指定经纬度值的插入：

    INSERT INTO test_ks.test_cf(country, city) VALUES('XXX', 'unknown'); 

    CSS查询结果：

    {
        "country": "XXX",
        "city": "unknown",
        "location": {
            "type": "point",
            "coordinates": [90, 180]
        }
    }

更改CSS索引的mappings配置

更改索引test_index的mappings配置，将动态映射模式设置为strict。

ALTER INDEX test_index WITH options =
{
    'mappings': '{
        "dynamic": "strict",
        "properties": {
            "country": {"type": "keyword"},
            "city": {"type": "keyword"},
            "longitude": {"type": "long"},
            "latitude": {"type": "long"}
        }
    }'
};

删除CSS索引

与普通索引的删除CQL相同。

DROP INDEX test_index;

用户表数据类型限制

GeminiDB Cassandra用户表仅部分支持CSS数据同步。

主键类型与主键编码字符数的关系

用户表每行记录中，主键个数与主键编码字符数之和不得超过512。

Cassandra数据类型兼容的CSS数据类型