Ladybug openCypher

Ladybug 尽可能遵循 openCypher 规范。模式（Schema）、DDL、部分子句以及 MATCH 语义与 Neo4j 存在差异。概览：Ladybug 与 Neo4j 的主要区别。DDL：创建表。

Ladybug 是 嵌入式（in-process） 数据库 —— 不使用服务端 URI；通过 real_ladybug 打开文件路径或 :memory:。

核心原则

1. 先建模后写入（Schema first） —— 节点表与关系表必须预先存在，方可执行插入操作；每个节点/关系表仅支持一个标签；每个节点表必须定义 主键。
2. 遍历（Walk） vs 轨迹（Trail） —— 模式匹配采用 walk 语义（允许边重复出现）。如需 Neo4j 风格的轨迹检查，请显式使用 is_trail() / is_acyclic() 函数。
3. 变长路径（Variable-length paths） —— 必须指定上界以确保终止；若未显式指定，默认上界为 30。
4. 目录（Catalog） —— 多数内省（introspection）任务推荐使用 CALL procedure(...)，而非 Neo4j 的 SHOW … 语法。

从 Python 执行（快速入门）

导入 real_ladybug（Ladybug 的 Python 绑定）。完整文档参见：Python API 及自动生成的参考手册。

import real_ladybug as lb

db = lb.Database("path/to/db.lbug")
conn = lb.Connection(db)
rows = conn.execute("""
    MATCH (a:User)-[f:Follows]->(b:User)
    RETURN a.name, b.name, f.since;
""")
for row in rows:
    print(row)

• conn.execute / await conn.execute 每次仅执行一条语句，除非 API 明确支持批处理（batching）。
• 多条语句（以分号分隔）将返回一个 结果列表；单条语句则返回单个结果对象。
• COPY / LOAD FROM 中的路径默认相对于进程当前工作目录（CWD）解析；若为绝对路径，则按绝对路径处理。

如需异步支持、结果辅助工具、UDF（用户自定义函数）及 Parquet/DataFrame 导入功能，请参阅 references/api-reference.md。

模式片段（DDL）

CREATE NODE TABLE User(name STRING PRIMARY KEY, age INT64);
CREATE NODE TABLE City(name STRING PRIMARY KEY, population INT64);
CREATE REL TABLE Follows(FROM User TO User, since INT64);
CREATE REL TABLE LivesIn(FROM User TO City, MANY_ONE);

可选 IF NOT EXISTS。基数（Multiplicity）取值包括：MANY_ONE、ONE_MANY、MANY_MANY、ONE_ONE。CREATE NODE TABLE AS / CREATE REL TABLE AS 支持从 LOAD FROM 或 MATCH … RETURN 查询结果中自动推断模式。

数据导入

• COPY NodeTable FROM "file.csv"（支持 Parquet 等多种格式，详见 Import data 文档）。
• Neo4j 的 LOAD CSV FROM 在 Ladybug 中对应 LOAD FROM。
• 在 Python 中：可直接使用 LOAD FROM df / COPY Table FROM df 将 Pandas / Polars / Arrow DataFrame 导入，无需中间文件。

全文搜索（FTS）

需先加载 FTS 扩展。仅支持对节点表中的 STRING 列建立全文索引；查询时使用 CALL QUERY_FTS_INDEX；列出所有索引使用 CALL SHOW_INDEXES() RETURN *。完整过程签名请参阅 references/api-reference.md。

当查询结果与 Neo4j 不一致时

请参考 references/workflow-patterns.md 中的检查清单与子句对照表：walk vs trail、变长路径默认上界、不支持的子句（如 FOREACH、REMOVE、FINISH、SET += 等），以及 CALL 与 SHOW 的语义差异。

实用脚本

附带的辅助脚本（可选，需确保 real_ladybug 已加入 PYTHONPATH）：

• scripts/run_cypher.py —— 对指定 .lbug 文件执行 Cypher 字符串或 .cypher 文件。
• scripts/check_env.py —— 验证 import real_ladybug 是否成功，并输出基础环境信息。

其他资源

• 详细的 Python API、FTS CALL 语法、DDL / 导入表格说明：见 references/api-reference.md
• 调试工作流、Neo4j 对比表格、常见查询习惯：见 references/workflow-patterns.md

文档链接

• Ladybug vs Neo4j
• DDL / 创建表
• 导入数据
• 全文搜索
• MATCH
• CALL / 函数