KuzuDB JSON加载性能问题分析与解决方案

问题背景

在使用KuzuDB数据库系统时，开发者遇到了一个关于JSON数据加载的性能问题。当尝试加载一个324KB大小的JSON文件时，系统出现了明显的性能下降，甚至疑似挂起的情况。这个问题在Ubuntu 24.04.1系统上使用Python 3.12.3和KuzuDB v0.8.2版本时复现。

问题分析

经过深入分析，我们发现这个问题实际上由两个独立但相关的问题组成：

1. JSON格式验证问题：原始JSON文件格式不规范，存在多余逗号和缺少方括号的问题。KuzuDB在处理这种不规范JSON时没有及时抛出明确的错误信息，而是进入了某种无限循环状态。

2. 多语句查询处理问题：当开发者将INSTALL、LOAD EXTENSION和LOAD FROM语句合并在一个execute调用中时，系统返回的是查询结果列表而非单个结果集，这导致了后续处理时的类型错误。

技术细节

JSON格式要求

KuzuDB对JSON文件格式有严格要求，支持两种标准格式：

1. 标准JSON数组格式：文件内容必须用方括号包裹，各对象间用逗号分隔
2. JSON Lines格式：每行一个完整的JSON对象，无需逗号分隔或方括号包裹

多语句查询处理机制

KuzuDB的Python接口在执行包含多个语句的查询时，会返回一个结果列表。每个语句对应一个结果对象，开发者需要明确指定要处理哪个结果。这种设计虽然灵活，但容易导致混淆。

解决方案

针对JSON加载问题

1. 确保JSON格式正确：

   • 对于数组格式，确保文件以方括号开始和结束
   • 对象间使用逗号分隔，但最后一个对象后不应有逗号
   • 或者转换为JSON Lines格式，每行一个完整对象

2. 分离扩展加载与数据查询：

   # 先加载扩展
   conn.execute("INSTALL json;")
   conn.execute("LOAD EXTENSION json;")
   
   # 再执行数据查询
   res = conn.execute("LOAD FROM 'data.json' RETURN *")
   

针对多语句查询问题

1. 分离不同功能的语句：

   # 不推荐
   res = conn.execute("""
       INSTALL json;
       LOAD EXTENSION json;
       LOAD FROM 'data.json' RETURN *
   """)
   
   # 推荐
   conn.execute("INSTALL json;")
   conn.execute("LOAD EXTENSION json;")
   res = conn.execute("LOAD FROM 'data.json' RETURN *")
   

2. 正确处理多结果集：

   results = conn.execute("""
       RETURN 1;
       RETURN 2;
   """)
   print(results[0].get_as_pl())  # 第一个结果
   print(results[1].get_as_pl())  # 第二个结果
   

最佳实践建议

1. 始终验证JSON文件格式，可以使用在线工具或Python的json模块预先检查
2. 将不同功能的数据库操作分离到单独的execute调用中
3. 对于复杂的数据加载场景，考虑先创建表结构再导入数据
4. 使用try-except块捕获可能的格式错误
5. 对于大型JSON文件，考虑分批处理或使用专门的ETL工具预处理

总结

KuzuDB作为新兴的图数据库系统，在JSON数据处理方面提供了强大的功能，但也需要开发者遵循特定的使用规范。通过理解系统的工作原理和遵循最佳实践，可以避免类似性能问题的发生，充分发挥数据库的性能优势。

该问题已在KuzuDB的最新版本中得到修复，系统现在能够更及时地检测并报告JSON格式错误，避免了无限循环的情况。同时，文档也得到了更新，更清晰地说明了多语句查询的处理方式。