Ladybug openCypher
Ladybug follows openCypher where possible. Schema, DDL, some clauses, and MATCH semantics differ from Neo4j. Overview: Differences between Ladybug and Neo4j. DDL: Create table.
Ladybug is embedded (in-process) — no server URI; open a file path or :memory: via real_ladybug.
Core principles
- 1. Schema first — node and relationship tables must exist before insert. One label per node/rel table; every node table needs a primary key.
- Walk vs trail — patterns use walk semantics (edges may repeat). Use
is_trail() / is_acyclic() when you need Neo4j-like trail checks. - Variable-length paths — require an upper bound for termination; if omitted, default upper bound is 30.
- Catalog — prefer
CALL procedure(...) instead of Neo4j SHOW … for many introspection tasks.
Execute from Python (quick start)
Import real_ladybug (Ladybug Python bindings). Full docs: Python API, generated reference.
CODEBLOCK0
- -
conn.execute / await conn.execute per statement unless the API documents batching. - Multiple statements (semicolon-separated) return a list of results; a single statement returns one result.
COPY / LOAD FROM paths resolve relative to the process CWD unless absolute.
For async, result helpers, UDFs, and Parquet/DataFrame import — see references/api-reference.md.
Schema snippet (DDL)
CODEBLOCK1
Optional IF NOT EXISTS. Multiplicity: MANY_ONE, ONE_MANY, MANY_MANY, ONE_ONE. CREATE NODE TABLE AS / CREATE REL TABLE AS — infer schema from LOAD FROM or MATCH … RETURN.
Import
- -
COPY NodeTable FROM "file.csv" (Parquet and other formats per Import data). - Neo4j’s
LOAD CSV FROM → LOAD FROM in Ladybug. - In Python:
LOAD FROM df / COPY Table FROM df for Pandas/Polars/Arrow without an intermediate file.
Full-text search (FTS)
Load the FTS extension first. Index STRING columns on node tables only; query with CALL QUERY_FTS_INDEX; list with CALL SHOW_INDEXES() RETURN *. Full procedure signatures: references/api-reference.md.
When results differ from Neo4j
Use the checklist and clause table in references/workflow-patterns.md: walk vs trail, variable-length defaults, unsupported clauses (FOREACH, REMOVE, FINISH, SET +=, …), and CALL vs SHOW.
Utility scripts
Bundled helpers (optional — require real_ladybug on PYTHONPATH):
- -
scripts/run_cypher.py — run a Cypher string or .cypher file against a .lbug path. scripts/check_env.py — verify import real_ladybug and print basic info.
Additional resources
Doc links
Ladybug openCypher
Ladybug 尽可能遵循 openCypher 标准。模式、DDL、部分子句以及 MATCH 语义 与 Neo4j 有所不同。概述：Ladybug 与 Neo4j 的差异。DDL：创建表。
Ladybug 是嵌入式（进程内） 的——没有服务器 URI；通过 real_ladybug 打开文件路径或 :memory:。
核心原则
- 1. 模式优先 —— 节点表和关系表必须在插入数据之前存在。每个节点/关系表只有一个标签；每个节点表都需要一个主键。
- Walk 与 trail —— 模式使用 walk 语义（边可以重复）。当需要类似 Neo4j 的 trail 检查时，请使用 istrail() / isacyclic()。
- 可变长度路径 —— 需要指定上界以确保终止；如果省略，默认上界为 30。
- 目录 —— 对于许多内省任务，建议使用 CALL procedure(...) 而不是 Neo4j 的 SHOW …。
从 Python 执行（快速入门）
导入 realladybug（Ladybug Python 绑定）。完整文档：Python API，生成的参考。
python
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 文档说明支持批处理。
- 多条语句（以分号分隔）返回一个结果列表；单条语句返回一个结果。
- COPY / LOAD FROM 的路径相对于进程当前工作目录解析，除非使用绝对路径。
关于异步、结果辅助函数、UDF 以及 Parquet/DataFrame 导入——请参见 references/api-reference.md。
模式片段（DDL）
cypher
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。多重性：MANYONE、ONEMANY、MANYMANY、ONEONE。CREATE NODE TABLE AS / CREATE REL TABLE AS —— 从 LOAD FROM 或 MATCH … RETURN 推断模式。
导入
- - COPY NodeTable FROM file.csv（Parquet 和其他格式请参见导入数据）。
- Neo4j 的 LOAD CSV FROM → Ladybug 中的 LOAD FROM。
- 在 Python 中：LOAD FROM df / COPY Table FROM df 用于 Pandas/Polars/Arrow，无需中间文件。
全文搜索（FTS）
首先加载 FTS 扩展。仅对节点表的 STRING 列建立索引；使用 CALL QUERYFTSINDEX 查询；使用 CALL SHOWINDEXES() RETURN * 列出索引。完整的过程签名：references/api-reference.md。
当结果与 Neo4j 不同时
请使用 references/workflow-patterns.md 中的检查表和子句对照表：walk 与 trail、可变长度默认值、不支持的子句（FOREACH、REMOVE、FINISH、SET += 等），以及 CALL 与 SHOW 的区别。
实用脚本
捆绑的辅助工具（可选——需要 real_ladybug 在 PYTHONPATH 上）：
- - scripts/runcypher.py —— 针对 .lbug 路径运行 Cypher 字符串或 .cypher 文件。
- scripts/checkenv.py —— 验证 import real_ladybug 并打印基本信息。
其他资源
文档链接
