OBKV-Table 支持的数据类型

OBKV-Table 提供表模型接口，在概念定义上和 SQL 接近，因此也有数据类型的概念。本文档介绍了 OBKV-Table 支持的数据类型。

OBKV 支持的类型（Schema 定义）

String 类型

OBKV-Table 支持的 String 类型如下：

• Varchar, Char
• Tiny Text, Text, Medium Text, Long Text

需要注意的是，OBKV 客户端没有提供设置字符集的接口，客户端的数据默认会转为 utf8mb4_general_ci 字符集的数据，如果 Schema 上定义的字符集不同，在存储的时候，会有额外的字符集转换开销。

Binary 类型

Binary 类型和 String 类型类似，不同之处在于它们存储二进制数据而不是字符串。

OBKV-Table 支持的 Binary 类型如下：

• VarBinary, Binary
• Tiny Blob, Blob, Medium Blob, Long Blob

数值类型

OBKV-Table 支持的数值类型如下：

• 整数类型：Bool / Boolean / TinyInt / SmallInt / MediumInt / Int / Integer / BigInt
• 定点类型：Decimal / Numeric
• 浮点类型：Float / Double

需要注意的是：

• OBKV-Table 主要支持的客户端是 Java 客户端。Java 不支持 unsigned 类型，因此在定义 Schema 中不允许存在 unsigned 属性。
• 定点数以及浮点数的精度（Precision）以及小数位数（Scale）都基于 Schema 定义，如果数据和 Schema 不匹配，则会报错。

日期时间类型

OBKV-Table 支持的数值类型如下：Date / Time / DataTime / Timestamp / Year。

需要注意的是，在使用 DataTime / Timestamp 的时候，默认的精度是 0，代表精度只能到秒。比如 Java 的一些函数, 返回的是毫秒级别的时间值，可能会导致精度校验的时候失败。因此在时间列的时候，可以将精度调整至 6(最大精度)。

JSON 类型

JSON 数据类型是一种在数据库中存储和处理 JSON（JavaScript Object Notation）数据的特殊数据类型。JSON 值必须是由对象（JSON 对象）、数组、字符串、数字、布尔值（false/true）或 null 组成。其中 false、true 和 null 只允许小写形式。

用户可以在表中创建 JSON 列，并使用 OBKV-Table Java 客户端接口对 JSON 数据进行读写。在客户端写入时，JSON 数据需要以特定的 Java 类型传递。目前支持的 Java 类型如下：

• String
• byte[]

用户可以在每个表上创建多个 JSON 类型的列，但是需要注意以下事项：

• JSON 类型的列不能作为 PRIMARY KEY、FOREIGN KEY 和 UNIQUE KEY，但是可以添加 NOT NULL 或 CHECK 约束。
• JSON 类型的列上不可以包含默认值。
• JSON 类型的列不能作为分区键。
• JSON 数据长度不能超过 LONGTEXT 的长度，每个 JSON 对象或数组的最大深度默认为 100，可以通过配置项 json_document_max_depth 进行设置。
• 当你从客户端写入 JSON 数据时，内部的键可能会被重新排序。例如，如果你写入 {"b": 1, "a": 2}，那么读取到的数据可能会是 {"a":2, "b":1}。虽然 "a" 和 "b" 的位置互换了，但它们仍然是同一个 JSON 对象。

OBKV-Table 使用 JSON 类型的限制如下：

• 只支持 JSON 数据的存取，不支持 JSON 相关函数（如 JSON_EXTRACT 等）。
• 客户端不能使用 put 接口写入 JSON 数据，建议使用 insertOrUpdate 接口写入。
• 如果尝试使用其他不支持的 Java 类型（如 Integer、Boolean 等）写入 JSON 列，就会报 OB_KV_COLUMN_TYPE_NOT_MATCH 错误。

创建 JSON 列的示例如下：

CREATE TABLE t1_json(
  k BIGINT, 
  v JSON, 
  PRIMARY KEY(k)) 
  kv_attributes = '{"Table": {}}'
  PARTITION BY KEY(k) PARTITIONS 97;

客户端写入 JSON 数据示例如下：

Row rowKey = row(colVal("k", 1));
String jsonText = "{ \"greeting\" : \"Hello!\", \"farewell\" : \"bye-bye!\", \
\"json_text\" : \"test!\" }";
client.insertOrUpdate("test")
      .setRowKey(rowKey)
      .addMutateColVal(colVal("v", jsonText)).execute();

客户端读取 JSON 数据示例如下：

Map<String, Object> res = client.get(tableName)
                                .setRowKey(row(colVal("k", 1)))
                                .select("k", "v")
                                .execute();
System.out.println(res.get("v"));

Java 类型和 OBKV-Table 类型的映射

Java 数据类型和 OBKV-Table 数据类型对应关系如下：