主键列自增功能是表格存储新推出的一个功能,JAVA SDK 4.2.0 版本开始支持。

主键列自增功能是指若用户指定某一列主键为自增列,在其写入数据时,表格存储会自动为用户在这一列产生一个新的值,且这个值为同一个分区键下该列的最大值。主要用于系统设计中需要使用主键列自增功能的场景,例如电商网站的商品 ID、大型网站的用户 ID、论坛帖子的 ID、聊天工具的消息 ID 等。

特点

  • 表格存储目前支持多个主键,第一个主键为分区键,分区键上不允许使用主键列自增功能。

  • 除了分区键外,其余主键中的任意一个都可以被设置为递增列。

  • 由于是在分区键基础上递增,所以主键列自增是分区键级别的自增。

  • 对于每张表,目前只允许设置一个主键列为自增列。

  • 自动生成地自增列为 64 位的有符号长整型。

接口

主键自增列功能主要涉及两类接口,创建表和写数据。

  • 创建表

    创建表时,只需将需要自增的主键属性设置为 PrimaryKeyOption.AUTO_INCREMENT。

    相关接口:CreateTable。

    private static void createTable(SyncClient client) {
    		TableMeta tableMeta = new TableMeta(“table_name”);
    
    		// 第一列为分区建
            tableMeta.addPrimaryKeyColumn(new PrimaryKeySchema("PK_1", PrimaryKeyType.STRING));
    
    		// 第二列为自增列,类型为INTEGER,属性为AUTO_INCREMENT
            tableMeta.addPrimaryKeyColumn(new PrimaryKeySchema("PK_2", PrimaryKeyType.INTEGER, PrimaryKeyOption.AUTO_INCREMENT));
    
            int timeToLive = -1;  // 永不过期
            int maxVersions = 1;  // 只保存一个版本
    
            TableOptions tableOptions = new TableOptions(timeToLive, maxVersions);
    
            CreateTableRequest request = new CreateTableRequest(tableMeta, tableOptions);
    
            client.createTable(request);
        }
    
    • 第一个主键是分区键,不能设置为自增列。

    • 只有整数类型的列才可以设置为自增列。

    • 每张表只能设置一个主键自增列。

  • 写数据

    写入数据时,只需将自增列的值为设置为占位符 PrimaryKeyValue.AUTO_INCREMENT。

    相关接口:PutRow/UpdateRow/BatchWriteRow。

        private static void putRow(SyncClient client, String receive_id) {
            // 构造主键
            PrimaryKeyBuilder primaryKeyBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
    		
    		// 第一列的值为 md5(receive_id)前4位
            primaryKeyBuilder.addPrimaryKeyColumn(“PK_1”, PrimaryKeyValue.fromString("Hangzhou");
    		
    
    		// 第三列是主键递增列,这个值是TableStore产生的,用户在这里不需要填入真实值,只需要一个占位符:AUTO_INCREMENT 即可。
            primaryKeyBuilder.addPrimaryKeyColumn("PK_2", PrimaryKeyValue.AUTO_INCREMENT);
            PrimaryKey primaryKey = primaryKeyBuilder.build();
    
            RowPutChange rowPutChange = new RowPutChange("table_name", primaryKey);
    		
    		// 这里设置返回类型为RT_PK,意思是在返回结果中包含PK列的值。如果不设置ReturnType,默认不返回。
            rowPutChange.setReturnType(ReturnType.RT_PK);
    
            //加入属性列,消息内容
    		rowPutChange.addColumn(new Column("content", ColumnValue.fromString(content)));
    
    		//写数据到TableStore
            PutRowResponse response = client.putRow(new PutRowRequest(rowPutChange));
    		
    		// 打印出返回的PK列
            Row returnRow = response.getRow();
    		if (returnRow != null) {
    			System.out.println("PrimaryKey:" + returnRow.getPrimaryKey().toString());
    		}
    
    		// 打印出消耗的CU
    		CapacityUnit  cu = response.getConsumedCapacity().getCapacityUnit();
    		System.out.println("Read CapacityUnit:" + cu.getReadCapacityUnit());
    		System.out.println("Write CapacityUnit:" + cu.getWriteCapacityUnit());
        }
    
    • 写入数据时,主键自增列不需要填值,只需填充占位符即可。

    • 如果用户想获取向表格存储写入数据后自动生成的主键值,可以将 ReturnType 设置为 RT_PK,这样就能在写入成功后返回主键值。