rladybugdb

R interface to LadybugDB — an embedded columnar graph database with Cypher queries.

rladybugdb provides a native Rcpp binding to the LadybugDB C library. No Python, no reticulate, no runtime setup — the C library ships with the package and is loaded automatically on library(rladybugdb).

LadybugDB is a fork of KuzuDB and supports the same openCypher query dialect.

---

Installation

# install.packages("remotes")
remotes::install_github("hadimaster65555/rladybugdb")

The prebuilt LadybugDB C library is downloaded automatically during R CMD INSTALL via the configure script (macOS/Linux) or configure.win (Windows). No other setup is needed.

library(rladybugdb)
ladybugdb_version()   # "0.15.2"

---

Quick start

library(rladybugdb)

# Open an in-memory graph (or pass a directory path for persistence)
db   <- lb_database(":memory:")
conn <- lb_connection(db)

# Define schema
lb_execute(conn, "CREATE NODE TABLE Person (name STRING, age INT64, PRIMARY KEY(name))")
lb_execute(conn, "CREATE NODE TABLE City   (name STRING, country STRING, PRIMARY KEY(name))")
lb_execute(conn, "CREATE REL TABLE LivesIn (FROM Person TO City, since INT64)")

# Insert data
lb_execute(conn, "CREATE (:Person {name: 'Alice', age: 30})")
lb_execute(conn, "CREATE (:City   {name: 'London', country: 'UK'})")
lb_execute(conn, "MATCH (p:Person {name: 'Alice'}), (c:City {name: 'London'})
                  CREATE (p)-[:LivesIn {since: 2018}]->(c)")

# Query → data.frame
lb_query(conn, "MATCH (p:Person)-[:LivesIn]->(c:City)
                RETURN p.name AS person, c.name AS city, p.age AS age")
#>   person   city age
#> 1  Alice London  30

lb_close(conn)
lb_close(db)

---

Core API

Database and connection

Function	Description
lb_database(path, read_only = FALSE)	Open or create a database. Use ":memory:" for an in-memory DB.
lb_connection(database, num_threads = NULL)	Open a query connection to the database.
lb_close(x)	Close an lb_connection or lb_database and free C resources.

Querying

Function	Description
lb_execute(conn, query, parameters = NULL)	Run a Cypher query; returns an lb_result.
lb_query(conn, query, parameters = NULL)	Shortcut: run a query and return a data.frame immediately.

Parameterised queries avoid string interpolation and SQL-injection-style bugs:

lb_execute(conn,
  "MATCH (p:Person {name: $name}) RETURN p.age AS age",
  parameters = list(name = "Alice"))

Bulk loading

Function	Description
lb_copy_from_df(conn, df, table)	Write an R data.frame into a LadybugDB table via CSV.
lb_copy_from_csv(conn, path, table, header = TRUE, delim = ",")	Load a CSV file directly using COPY … FROM.

Result conversion

Function / method	Description
as.data.frame(result)	Convert lb_result → data.frame.
tibble::as_tibble(result)	Convert lb_result → tibble (requires tibble).
as_arrow_table(result)	Convert lb_result → Arrow Table (requires arrow).

Graph analysis

Function	Description
as_igraph(result)	Convert a RETURN node, rel, node result to an igraph object (requires igraph).
as_tbl_graph(result)	Convert to a tidygraph::tbl_graph (requires tidygraph).

Package info

Function	Description
ladybugdb_version()	Return the bundled LadybugDB C library version string.
ladybugdb_is_installed()	Return TRUE if the C library is functional.

---

Type mapping

LadybugDB type	R type	Notes
INT8 / INT16 / INT32	integer
INT64 / SERIAL	double	Preserves values up to 2^53 exactly
FLOAT / DOUBLE	double
BOOLEAN	logical
STRING / UUID	character
DATE	Date	Days since Unix epoch
TIMESTAMP	POSIXct	Microseconds ÷ 1e6 → seconds since epoch
INTERVAL / DECIMAL / BLOB	character	Serialised via lbug_value_to_string
NULL	NA	Typed NA matching the column type
LIST / ARRAY	list column	Each cell is an R list
MAP	list with $keys / $values
STRUCT	named list
NODE	named list with _ID, _LABEL, properties	Pass full query through as_igraph()
REL	named list with _SRC, _DST, _LABEL, _ID, properties

---

Visualisation example

example_openflights.R demonstrates a full real-data workflow:

1. Downloads the OpenFlights dataset (~6,000 airports, ~66,000 routes)
2. Loads it into a LadybugDB graph with lb_copy_from_df()
3. Runs several Cypher aggregation queries
4. Produces four plots with ggplot2, ggraph, and the maps package

Rscript example_openflights.R

Sample output:

Plot	Description
01_top_hubs.png	Bar chart — top 30 airports by outbound route count
02_airports_by_country.png	Lollipop chart — top 20 countries by airport count
03_world_map.png	Dark-background world map with sampled routes and hub markers
04_fra_network.png	Directed network graph of Frankfurt's direct destinations

---

Build from source / offline install

To pre-populate src/vendor/ and inst/libs/ before R CMD build (e.g. for CRAN or air-gapped builds):

Rscript tools/vendor.R   # downloads liblbug for the current platform
R CMD build .
R CMD INSTALL rladybugdb_0.2.0.tar.gz

The pinned library version is in tools/lbug_version.

---

Contributing

Bug reports and pull requests are welcome at https://github.com/hadimaster65555/rladybugdb/issues.

---

License

MIT © rladybugdb authors. LadybugDB C library is distributed under the MIT License.