CSV 图加载器生成器

将 CSV 数据集转换为适用于知识图谱构建的图就绪结构。

该能力将表格型 CSV 数据转化为适用于图数据库导入的格式，例如节点（nodes）、边（edges）或三元组（triples）。它可为 Neo4j、RDF 三元组存储、属性图（property graphs）和知识图谱（knowledge graphs） 等图系统生成映射规则与加载脚本。

快速入门

适用场景

• 将 CSV 数据集转换为图结构
• 为图数据库导入准备数据
• 生成 Neo4j 的 LOAD CSV 脚本
• 创建 RDF 三元组映射
• 从关系表构建属性图
• 基于结构化数据构建知识图谱
• 自动化 CSV → 图的 ETL 工作流

输入

• CSV 文件或数据内容
• 列定义及数据类型
• 实体类型说明
• 关系定义
• 目标图格式
• 自定义映射规则

输出

• 节点定义（标签、属性）
• 关系映射（类型、方向）
• Neo4j Cypher 导入脚本
• RDF 三元组定义
• 属性图 JSON 格式
• 图模式（schema）定义
• 映射配置文件

示例

输入 CSV：

person_id,name,company_name,company_industry,job_title
1,Alice Johnson,Acme Corp,Technology,Software Engineer
2,Bob Smith,Acme Corp,Technology,Product Manager
3,Carol Davis,TechStart Inc,Technology,CTO

生成输出（节点与边）：

{
  "nodes": [
    {"id": "p1", "type": "Person", "properties": {"name": "Alice Johnson", "job": "Software Engineer"}},
    {"id": "p2", "type": "Person", "properties": {"name": "Bob Smith", "job": "Product Manager"}},
    {"id": "c1", "type": "Company", "properties": {"name": "Acme Corp", "industry": "Technology"}},
    {"id": "c2", "type": "Company", "properties": {"name": "TechStart Inc", "industry": "Technology"}}
  ],
  "edges": [
    {"source": "p1", "target": "c1", "type": "WORKS_AT"},
    {"source": "p2", "target": "c1", "type": "WORKS_AT"},
    {"source": "p3", "target": "c2", "type": "WORKS_AT"}
  ]
}

CSV 到图的转换策略

1. 实体识别

自动识别实体列：

• ID 列 — 唯一标识符（如 person_id、company_id）
• 名称列 — 实体名称（如 name、title、company_name）
• 类别列 — 实体类型（如 type、category、industry）

2. 实体分类

根据识别出的实体创建节点类型：

person_id → Person 节点
company_name → Company 节点
department → Department 节点

3. 关系推断

将列之间的关联映射为关系：

person_id + company_name → WORKS_AT
employee_id + manager_id → REPORTS_TO
product_id + category_id → BELONGS_TO

4. 属性分配

其余列作为节点属性：

name → Person.name
salary → Person.salary
industry → Company.industry

5. 输出生成

为目标系统生成加载脚本：

Neo4j：LOAD CSV WITH HEADERS...
RDF：:Alice rdf:type :Person
JSON：{"nodes": [...], "edges": [...]}

支持的实体模式

ID 型实体

模式：列名包含 "id" 或 "identifier"
示例：person_id、user_id、company_id

名称型实体

模式：列名包含 "name" 或 "title"
示例：person_name、company_name、job_title

类别型实体

模式：列名包含 "type" 或 "category"
示例：person_type、company_category、product_category

隐式实体

模式：列值本身即代表实体
示例：department 列，其值为 "Sales"、"Engineering" 等

输出格式

Neo4j Cypher 脚本

LOAD CSV WITH HEADERS FROM 'file:///employees.csv' AS row
MERGE (p:Person {id: row.person_id})
SET p.name = row.name, p.job_title = row.job_title
MERGE (c:Company {name: row.company_name})
SET c.industry = row.company_industry
MERGE (p)-[:WORKS_AT]->(c)

RDF 三元组（Turtle 格式）

@prefix ex:  .

ex:person1 a ex:Person ;
  ex:name "Alice Johnson" ;
  ex:jobTitle "Software Engineer" ;
  ex:worksAt ex:acme_corp .

ex:acme_corp a ex:Company ;
  ex:name "Acme Corp" ;
  ex:industry "Technology" .

属性图 JSON 格式

{
  "nodes": [
    {"id": "p1", "type": "Person", "properties": {"name": "Alice", "job": "Engineer"}},
    {"id": "c1", "type": "Company", "properties": {"name": "Acme", "industry": "Tech"}}
  ],
  "edges": [
    {"source": "p1", "target": "c1", "type": "WORKS_AT"}
  ]
}

CSV 到节点/边表

# nodes.csv
id,type,name,job_title
p1,Person,Alice,Software Engineer
p2,Person,Bob,Product Manager
c1,Company,Acme Corp,

# edges.csv
source,target,type
p1,c1,WORKS_AT
p2,c1,WORKS_AT

映射策略

自动检测

优势：无需手动配置
劣势：可能推断出错误的关系
适用场景：快速原型验证、简单数据集

半自动（带提示）

优势：在自动化与可控性之间取得平衡
劣势：需提供部分输入
适用场景：最常见的生产环境用例

显式映射

优势：完全可控，确保输出符合预期
劣势：需完整配置所有细节
适用场景：复杂 schema、严格合规要求

数据类型推断

加载器自动推断以下类型：

• String — 文本列
• Integer — 整数型数值
• Float — 浮点型数值
• Boolean — 布尔值（true/false）
• DateTime — 日期时间格式
• Reference — 指向其他实体的列

重复项处理

合并策略（Merge Strategy）

跨行出现的相同实体将被合并
示例：“Acme Corp” 出现在两行中 → 仅生成一个 Company 节点

去重（Deduplication）

移除源节点与目标节点均相同的重复边
示例：多个 WORKS_AT 边 → 合并为单条边

ID 驱动的去重（ID-Based Deduplication）

使用唯一标识符防止重复
示例：以 person_id 作为 Person 节点的稳定主键

执行步骤

1. 解析 CSV — 读取文件并校验结构
2. 分析 Schema — 推断数据类型与模式
3. 识别实体 — 定位实体列
4. 推断关系 — 映射列间关联
5. 构建 Schema — 定义节点类型与关系类型
6. 生成映射 — 创建列到属性的映射规则
7. 数据校验 — 检查数据质量问题
8. 生成加载器 — 输出目标系统的加载脚本

推荐库

• CSV 处理： pandas、csv、polars
• 图生成： neo4j、rdflib、networkx
• 数据校验： pydantic、jsonschema
• RDF/OWL： rdflib、owlready2、sparql-client
• JSON 转换： jsonschema、jinja2

最佳实践

✓ 使用稳定且语义明确的标识符
✓ 对实体名称进行标准化以避免重复
✓ 显式定义实体类型，而非依赖猜测
✓ 在导入图数据库前校验数据质量
✓ 记录自定义映射规则
✓ 首先使用样本数据测试
✓ 监控节点或关系的重复情况
✓ 将映射配置纳入版本控制
✓ 显式处理缺失值
✓ 实施引用完整性检查

与下游能力的集成

生成的图数据可直接用于以下能力：

• 图查询优化 — 优化生成的 Cypher 查询语句
• Schema 校验 — 对照图 Schema 进行数据一致性校验
• 图约束生成器 — 为已加载数据定义约束条件
• 知识图谱构建 — 基于 CSV 数据源构建知识图谱
• ETL 流水线生成器 — 编排完整的 CSV → 图工作流

参考文档

详见 loader-patterns.md 获取详细的 CSV 加载器模式；参阅 example-loaders.md 查看面向具体领域的完整示例。

版本： 1.0.0