Mybatis操作Clickhouse數(shù)組的最佳實踐分享
更新時間：2025年09月19日 08:39:38 作者：Jaising666
ClickHouse 的 Array(T) 數(shù)據(jù)類型支持任意有效數(shù)據(jù)類型作為元素,包括基本類型、嵌套數(shù)組和可空類型,本文給大家分享了Mybatis操作Clickhouse數(shù)組的最佳實踐,需要的朋友可以參考下
ClickHouse Array 類型概述
ClickHouse 的 Array(T) 數(shù)據(jù)類型支持任意有效數(shù)據(jù)類型作為元素，包括基本類型、嵌套數(shù)組和可空類型，關鍵特性包括：
- 索引從1開始：區(qū)別于多數(shù)編程語言的 0 索引機制
- 自動類型推斷：選擇最窄兼容類型以優(yōu)化存儲
- 嚴格類型檢查：混合不兼容類型將導致異常
- NULL值處理：包含 NULL 值時自動轉(zhuǎn)換為 Nullable 類型
-- 有效用法
SELECT array(1, 2, 3); -- Array(UInt8)
SELECT array('a', 'b', 'c'); -- Array(String)
SELECT array([1, 2], [3, 4]); -- Array(Array(UInt8))
-- 無效用法：類型不兼容
SELECT array(1, 'a');
-- Error: There is no supertype for types UInt8, String
MyBatis 寫入 ClickHouse 數(shù)組的兩種方法比較
JPA 與 Mybatis 是常見的兩種 ORM 框架。JPA 主要為 OLTP 設計，ClickHouse 是 OLAP 數(shù)據(jù)庫，JPQL 難以表達 ClickHouse 的復雜分析查詢，而這正好可以發(fā)揮 Mybaits 靈活控制 SQL 的特性。對于 Clickhouse 的數(shù)組類型寫入一般有兩種方法：
方法一：使用 ClickHouse array() 函數(shù) + ${} 參數(shù)替換
Mybatis XML 代碼：
insert into xxx_base
(array1)
values (array(${array1Value}))
Java 代碼：
// 手動格式化數(shù)組
List<String> userIds = Arrays.asList("user1", "user2", "user3");
String userIdsStr = userIds.stream()
.map(s -> "'" + s.replace("'", "\\'") + "'") // 轉(zhuǎn)義單引號
.collect(Collectors.joining(","));
// userIdsStr = "'user1','user2','user3'"
// 處理空值
String deviceIdsStr = deviceIds.isEmpty() ? "" :
deviceIds.stream()
.map(s -> "'" + s.replace("'", "\\'") + "'")
.collect(Collectors.joining(","));
方法二：使用自定義 TypeHandler + #{} 參數(shù)綁定
Mybatis XML 代碼：
insert into xxx_base
(array1)
values (#{array1Value,typeHandler=com.test.clickhousemybatisdemo.typehandler.ClickHouseArrayTypeHandler})
Java 代碼：
// 直接使用List對象
List<String> userIds = Arrays.asList("user1", "user2", "user3");
List<String> deviceIds = new ArrayList<>(); // 空列表也可以直接使用
// TypeHandler會自動處理轉(zhuǎn)換和空值情況
方案對比分析
| 維度 | array() + ${} | TypeHandler + #{} |
|---|---|---|
| 安全性 | ? SQL注入風險 | ? 預編譯安全，類型安全 |
| 可讀性 | ? 需要格式化處理 | ? 直接使用List |
| 可維護性 | ? 邏輯分散 | ? 邏輯集中 |
| 性能 | ?? 字符串拼接開銷 | ? 預編譯緩存 |
得到的結論是推薦方法二：
- 安全性差異：
${}參數(shù)替換存在 SQL 注入漏洞，#{}預編譯機制提供安全保障 - 開發(fā)復雜度：字符串拼接方案需要復雜的格式化與轉(zhuǎn)義處理，TypeHandler 方案支持直接對象操作
自定義 TypeHandler 的優(yōu)勢
MyBatis 內(nèi)置的 TypeHandler 主要針對關系型數(shù)據(jù)庫的標準 SQL 類型設計，對于 ClickHouse 這樣的分析型數(shù)據(jù)庫的特殊數(shù)據(jù)類型支持有限，Java 的List<T>與 ClickHouse 的Array(T)之間缺少直接的類型轉(zhuǎn)換機制。而如果使用 Java String 來處理又會帶來數(shù)據(jù)類型頻繁轉(zhuǎn)換的工程問題，代碼可讀性與可維護性都會受到影響。
ClickHouse JDBC 驅(qū)動對數(shù)組類型的處理與傳統(tǒng)關系型數(shù)據(jù)庫存在差異：
// 傳統(tǒng)數(shù)據(jù)庫的數(shù)組處理（如PostgreSQL）
Array sqlArray = connection.createArrayOf("varchar", stringArray);
// ClickHouse需要特殊的類型名稱映射
Array sqlArray = connection.createArrayOf("String", stringArray); // 注意："String"而非"varchar"
于是，擴展 TypeHandler 實現(xiàn)處理數(shù)組問題就變得有必要：
- 雙向轉(zhuǎn)換：實現(xiàn) Java
List<T>↔ ClickHouseArray(T)的無縫轉(zhuǎn)換 - 類型安全：確保編譯期和運行期的類型一致性
- 空值處理：正確處理 null 值和空數(shù)組的邊界情況
- 性能優(yōu)化：避免不必要的字符串拼接和解析開銷
擴展 TypeHandler 支持 Clickhouse Array
TypeHandler 接口設計
Mybatis TypeHandler 的設計就是為了緩解 JDBC 與 Java 數(shù)據(jù)類型不匹配的問題，通過擴展 TypeHandler 可以對各種數(shù)據(jù)庫的各種數(shù)據(jù)類型予以支持。
TypeHandler 接口很簡潔，一個是 setParameter 方法通過 PreparedStatement 為 SQL 語句綁定參數(shù)，實現(xiàn) JDBC 到 Java 的數(shù)據(jù)類型轉(zhuǎn)換；另外三個 getResult 重載方法通過 ResultSet 獲取數(shù)據(jù)時，將 Java 轉(zhuǎn)換成 JDBC 數(shù)據(jù)類型。
public interface TypeHandler<T> {
void setParameter(PreparedStatement ps, int i, T parameter, JdbcType jdbcType) throws SQLException;
T getResult(ResultSet rs, String columnName) throws SQLException;
T getResult(ResultSet rs, int columnIndex) throws SQLException;
T getResult(CallableStatement cs, int columnIndex) throws SQLException;
}
BaseTypeHandler 抽象類設計
BaseTypeHandler 實現(xiàn) TypeHandler 接口抽象成基類，setParameter 提取出參數(shù)是否為空的條件判斷，如果為空就會調(diào)用 PreparedStatement#setNull，如果不為空就會調(diào)用 setNonNullParameter。前者會委托給具體的數(shù)據(jù)庫驅(qū)動，這里引入的 clickhouse-jdbc 就會實現(xiàn) setNull 方法；后者則會交給具體的 TypeHandler 實現(xiàn)類。
類似的，BaseTypeHandler 實現(xiàn)了 TypeHandler#getResult 后抽象出了 getNullableResult 方法，委托給具體的 TypeHandler 實現(xiàn)。
public abstract class BaseTypeHandler<T> extends TypeReference<T> implements TypeHandler<T> {
@Override
public void setParameter(PreparedStatement ps, int i, T parameter, JdbcType jdbcType) throws SQLException {
if (parameter == null) {
if (jdbcType == null) {
...
ps.setNull(i, jdbcType.TYPE_CODE);
...
} else {
...
setNonNullParameter(ps, i, parameter, jdbcType);
...
}
}
@Override
public T getResult(ResultSet rs, String columnName) throws SQLException {
...
return getNullableResult(rs, columnIndex);
...
}
@Override
public T getResult(ResultSet rs, int columnIndex) throws SQLException {
...
return getNullableResult(rs, columnIndex);
...
}
@Override
public T getResult(CallableStatement cs, int columnIndex) throws SQLException {
...
return getNullableResult(rs, columnIndex);
...
}
public abstract void setNonNullParameter(PreparedStatement ps, int i, T parameter, JdbcType jdbcType)
throws SQLException;
public abstract T getNullableResult(ResultSet rs, String columnName) throws SQLException;
public abstract T getNullableResult(ResultSet rs, int columnIndex) throws SQLException;
public abstract T getNullableResult(CallableStatement cs, int columnIndex) throws SQLException;
}
要想擴展簡單的 TypeHandler 就可以繼承 BaseTypeHandler，實現(xiàn)設置非空 Java 數(shù)據(jù)類型和獲取非空 JDBC 數(shù)據(jù)類型的 4 個抽象方法。
Mybatis 內(nèi)置了一些常用的 BaseTypeHandler 實現(xiàn)類，比如 ArrayTypeHandler（當然，這個指的是 Java 中的基礎類型 Array 而不是 List）、ClobTypeHandler、LocalDateTimeTypeHandler 等。
實現(xiàn) BaseTypeHandler<List<String>>
參考這些內(nèi)置的 BaseTypeHandler，容易實現(xiàn)支持 Java 的 List 與 ClickHouse 的 Array 的類型綁定，首先支持 List<String> 與 Array(String) 的類型綁定。
/**
* ClickHouse Array(String) 類型處理器
* 處理 Java List<String> 和 ClickHouse Array(String) 之間的轉(zhuǎn)換
*/
@MappedTypes(List.class)
@MappedJdbcTypes(JdbcType.ARRAY)
public class ClickHouseArrayTypeHandler extends BaseTypeHandler<List<String>> {
@Override
public void setNonNullParameter(PreparedStatement ps, int i, List<String> parameter, JdbcType jdbcType) throws SQLException {
if (parameter == null || parameter.isEmpty()) {
ps.setArray(i, null);
} else {
// 將 List<String> 轉(zhuǎn)換為數(shù)組
String[] array = parameter.toArray(new String[0]);
Array sqlArray = ps.getConnection().createArrayOf("String", array);
ps.setArray(i, sqlArray);
}
}
@Override
public List<String> getNullableResult(ResultSet rs, String columnName) throws SQLException {
Array array = rs.getArray(columnName);
return convertArrayToList(array);
}
@Override
public List<String> getNullableResult(ResultSet rs, int columnIndex) throws SQLException {
Array array = rs.getArray(columnIndex);
return convertArrayToList(array);
}
@Override
public List<String> getNullableResult(CallableStatement cs, int columnIndex) throws SQLException {
Array array = cs.getArray(columnIndex);
return convertArrayToList(array);
}
/**
* 將 SQL Array 轉(zhuǎn)換為 List<String>
*/
private List<String> convertArrayToList(Array sqlArray) throws SQLException {
if (sqlArray == null) {
return new ArrayList<>();
}
Object[] array = (Object[]) sqlArray.getArray();
if (array == null || array.length == 0) {
return new ArrayList<>();
}
List<String> result = new ArrayList<>();
for (Object item : array) {
if (item != null) {
result.add(item.toString());
}
}
return result;
}
}
實現(xiàn) BaseTypeHandler<List<T>>
進一步的，可以將 Array(String) 擴展為支持 Array(T)，這樣可以處理 Clickhouse 通用數(shù)組類型。
通過動態(tài)類型檢測實現(xiàn)多數(shù)據(jù)類型支持，getSqlTypeName 方法提供 Java 類型到 ClickHouse 類型的映射機制：
/**
* ClickHouse Array(T) 類型處理器
* 處理 Java List<T> 和 ClickHouse Array(T) 之間的轉(zhuǎn)換
* 支持 String, Integer, Long, Double, Float, Boolean 等基本類型
*/
@MappedTypes(List.class)
@MappedJdbcTypes(JdbcType.ARRAY)
public class ClickHouseArrayTypeHandler<T> extends BaseTypeHandler<List<T>> {
@Override
public void setNonNullParameter(PreparedStatement ps, int i, List<T> parameter, JdbcType jdbcType) throws SQLException {
if (parameter == null || parameter.isEmpty()) {
ps.setArray(i, null);
} else {
// 檢測元素類型并創(chuàng)建相應的數(shù)組
Object firstElement = parameter.get(0);
String sqlTypeName = getSqlTypeName(firstElement);
Object[] array = parameter.toArray();
Array sqlArray = ps.getConnection().createArrayOf(sqlTypeName, array);
ps.setArray(i, sqlArray);
}
}
@Override
public List<T> getNullableResult(ResultSet rs, String columnName) throws SQLException {
Array array = rs.getArray(columnName);
return convertArrayToList(array);
}
@Override
public List<T> getNullableResult(ResultSet rs, int columnIndex) throws SQLException {
Array array = rs.getArray(columnIndex);
return convertArrayToList(array);
}
@Override
public List<T> getNullableResult(CallableStatement cs, int columnIndex) throws SQLException {
Array array = cs.getArray(columnIndex);
return convertArrayToList(array);
}
/**
* 將 SQL Array 轉(zhuǎn)換為 List<T>
*/
@SuppressWarnings("unchecked")
private List<T> convertArrayToList(Array sqlArray) throws SQLException {
if (sqlArray == null) {
return new ArrayList<>();
}
Object[] array = (Object[]) sqlArray.getArray();
if (array == null || array.length == 0) {
return new ArrayList<>();
}
List<T> result = new ArrayList<>();
for (Object item : array) {
if (item != null) {
result.add((T) convertToTargetType(item));
}
}
return result;
}
/**
* 根據(jù) Java 對象類型獲取對應的 SQL 類型名稱
*/
private String getSqlTypeName(Object obj) {
if (obj instanceof String) {
return "String";
} else if (obj instanceof Integer) {
return "Int32";
} else if (obj instanceof Long) {
return "Int64";
} else if (obj instanceof Double) {
return "Float64";
} else if (obj instanceof Float) {
return "Float32";
} else if (obj instanceof Boolean) {
return "UInt8";
} else {
// 默認轉(zhuǎn)換為字符串
return "String";
}
}
/**
* 將對象轉(zhuǎn)換為目標類型
*/
private Object convertToTargetType(Object obj) {
// 對于基本類型，直接返回
if (obj instanceof String || obj instanceof Integer || obj instanceof Long ||
obj instanceof Double || obj instanceof Float || obj instanceof Boolean) {
return obj;
}
// 對于其他類型，轉(zhuǎn)換為字符串
return obj.toString();
}
}
Docker 容器化測試
這里引入 TestContainers 實現(xiàn)自動化測試，避免安裝 Clickhouse 的繁瑣、避免使用替身數(shù)據(jù)庫無法還原真實依賴，確保 MyBatis 與ClickHouse 數(shù)組操作的可靠性。
環(huán)境配置
Docker Compose 配置（docker-compose.yml）：
version: '3.8'
services:
clickhouse:
image: clickhouse/clickhouse-server:latest
ports:
- "8123:8123"
- "9000:9000"
environment:
CLICKHOUSE_DB: test_db
CLICKHOUSE_USER: test_user
CLICKHOUSE_PASSWORD: test_password
healthcheck:
test: ["CMD", "wget", "--spider", "http://localhost:8123/ping"]
interval: 30s
timeout: 10s
Maven 依賴：
<dependencies>
<dependency>
<groupId>org.testcontainers</groupId>
<artifactId>testcontainers</artifactId>
<scope>test</scope>
</dependency>
<dependency>
<groupId>org.testcontainers</groupId>
<artifactId>junit-jupiter</artifactId>
<scope>test</scope>
</dependency>
</dependencies>
集成測試實現(xiàn)
測試類核心實現(xiàn)：
@SpringBootTest
@ActiveProfiles("test")
@Testcontainers
class ClickHouseIntegrationTest {
@Container
static GenericContainer<?> clickhouseContainer = new GenericContainer<>(
DockerImageName.parse("clickhouse/clickhouse-server:latest"))
.withExposedPorts(8123, 9000)
.withEnv("CLICKHOUSE_DB", "test_db")
.withEnv("CLICKHOUSE_USER", "test_user")
.withEnv("CLICKHOUSE_PASSWORD", "test_password")
.waitingFor(Wait.forHttp("/ping").forPort(8123));
@Autowired
private xxxMapper xxxMapper;
@Autowired
private JdbcTemplate jdbcTemplate;
@DynamicPropertySource
static void configureProperties(DynamicPropertyRegistry registry) {
registry.add("spring.datasource.url", () ->
"jdbc:clickhouse://localhost:" + clickhouseContainer.getMappedPort(8123) + "/test_db");
registry.add("spring.datasource.username", () -> "test_user");
registry.add("spring.datasource.password", () -> "test_password");
}
@BeforeEach
void initializeDatabase() {
jdbcTemplate.execute("CREATE DATABASE IF NOT EXISTS test_db");
jdbcTemplate.execute("CREATE TABLE IF NOT EXISTS xxx_base (" +
"uuid String, name String, xxx_type Array(String), userIds Array(String), " +
"deviceIds Array(String)) ENGINE = MergeTree() ORDER BY uuid");
}
}
核心測試用例
容器狀態(tài)驗證：
@Test
void testContainerIsRunning() {
assertTrue(clickhouseContainer.isRunning());
}
數(shù)組 CRUD 操作測試：
@Test
void testArrayInsertAndQuery() {
int result = xxxMapper.insert(testxxx);
assertEquals(1, result);
List<xxxBase> list = xxxMapper.selectByPage(0, 10);
assertNotNull(list);
xxxBase found = list.stream()
.filter(a -> test.getUuid().equals(a.getUuid()))
.findFirst().orElse(null);
assertNotNull(found.getUserIds());
}
執(zhí)行測試
命令行執(zhí)行：
# 使用TestContainers自動化測試 mvn test -Dtest=ClickHouseIntegrationTest # 或使用Docker Compose手動環(huán)境 docker-compose up -d && mvn test
測試配置（application-test.properties）：
mybatis.type-handlers-package=com.test.clickhousemybatisdemo.typehandler logging.level.com.test.clickhousemybatisdemo=DEBUG
驗證結果
容器化讀寫測試驗證 TypeHandler 實現(xiàn)了 Java List<T> 與 Clickhouse Array(T) 的映射關系。
以上就是Mybatis操作Clickhouse數(shù)組的最佳實踐分享的詳細內(nèi)容，更多關于Mybatis操作Clickhouse數(shù)組的資料請關注腳本之家其它相關文章！
相關文章
Spring AOP實現(xiàn)功能權限校驗功能的示例代碼
本篇文章主要介紹了Spring AOP實現(xiàn)功能權限校驗功能的示例代碼，小編覺得挺不錯的，現(xiàn)在分享給大家，也給大家做個參考。一起跟隨小編過來看看吧2017-12-12
這篇文章主要介紹了解決使用mybatis取值,字段賦值錯誤的問題，具有很好的參考價值，希望對大家有所幫助。如有錯誤或未考慮完全的地方，望不吝賜教2022-01-01
這篇文章主要為大家詳細介紹了JavaWeb郵件發(fā)送接收功能的實現(xiàn)，郵件發(fā)送和接收功能是非常常用的功能，文中示例代碼介紹的非常詳細，具有一定的參考價值，感興趣的小伙伴們可以參考一下2015-12-12
這篇文章主要介紹了Java文件選擇對話框JFileChooser使用詳解的相關資料,需要的朋友可以參考下2015-07-07
重排序通常是編譯器或運行時環(huán)境為了優(yōu)化程序性能而采取的對指令進行重新排序執(zhí)行的一種手段。重排序分為兩類：編譯期重排序和運行期重排序，分別對應編譯時和運行時環(huán)境2014-05-05
Java中String和StringBuffer及StringBuilder?有什么區(qū)別
這篇文章主要介紹了Java中String和StringBuffer及StringBuilder?有什么區(qū)別，String?是?Java?語言非?；A和重要的類，更多相關內(nèi)容需要的小伙伴可以參考下面文章內(nèi)容2022-06-06
這篇文章主要給大家介紹了關于javaSE中數(shù)組的概念與使用的相關資料,數(shù)組在內(nèi)存中是一段連續(xù)的空間,空間的編號都是從0開始的,依次遞增,該編號稱為數(shù)組的下標,需要的朋友可以參考下2023-08-08
這篇文章主要介紹了淺談SpringBoot是如何實現(xiàn)日志的，文中通過示例代碼介紹的非常詳細，對大家的學習或者工作具有一定的參考學習價值，需要的朋友們下面隨著小編來一起學習學習吧2019-03-03
Springboot整合WebSocket實戰(zhàn)教程
WebSocket使得客戶端和服務器之間的數(shù)據(jù)交換變得更加簡單，允許服務端主動向客戶端推送數(shù)據(jù)，這篇文章主要介紹了Springboot整合WebSocket實戰(zhàn)教程,需要的朋友可以參考下2023-05-05
這篇文章主要介紹了Springboot通過請求頭獲取當前用戶信息的方法，文中通過示例代碼介紹的非常詳細，對大家的學習或者工作具有一定的參考學習價值，需要的朋友們下面隨著小編來一起學習吧2022-11-11