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:

Downloads the OpenFlights dataset (~6,000 airports, ~66,000 routes)
Loads it into a LadybugDB graph with lb_copy_from_df()
Runs several Cypher aggregation queries
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.