Skip to contents

grafeoR

grafeoR provides R bindings for the embedded Grafeo graph database, implemented in Rust with extendr and rextendr.

Documentation site: https://hadimaster65555.github.io/grafeoR/

Current package scope:

  • embedded Grafeo database handles
  • in-memory and persistent databases
  • GQL execution and query results as base data.frames
  • ACID-style transaction handles
  • bundled real-world OpenFlights sample data
  • a visualization example built with ggplot2

The package is currently focused on the embedded LPG/GQL workflow. It does not yet expose Grafeo server features, RDF/SPARQL support, or higher-level graph analysis helpers.

Status

The package is tested from its vendored Rust dependency archive so builds do not need network access during compilation. The bundled Grafeo engine is 0.5.42.

Requirements

  • R >= 4.2
  • Rust stable >= 1.91.1
  • Cargo

ggplot2 is only needed for the visualization example and vignette, not for the core database API.

Install

Install remotes if needed, then install directly from GitHub:

install.packages("remotes")
remotes::install_github("hadimaster65555/grafeoR")

Or install into a custom library:

install.packages("remotes")
remotes::install_github("hadimaster65555/grafeoR", lib = "/path/to/R/library")

Quick Start 

library(grafeoR)

db <- grafeo_db()

db$execute("INSERT (:Person {name: 'Alix', age: 30})")
db$execute("INSERT (:Person {name: 'Gus', age: 41})")

people <- db$query(
  "MATCH (p:Person) WHERE p.name = $name RETURN p.name, p.age",
  params = list(name = "Alix")
)
people

tx <- db$begin()
tx$execute("INSERT (:Person {name: 'Committed'})")
tx$commit()

db$info()
grafeo_version()

db$close()

Real-World Example: OpenFlights

The package bundles a compact OpenFlights subset for offline demos and smoke tests:

  • 20 airports with the highest outbound route counts in the upstream snapshot
  • 1,129 airline route records whose endpoints are both inside that 20-airport subset

Load the bundled data directly in R:

library(grafeoR)

sample <- openflights_sample_data()

dim(sample$airports)
dim(sample$routes)
sample$metadata

Run the full real-world example:

Rscript inst/examples/openflights-example.R

That script:

  • loads the bundled OpenFlights sample into an in-memory Grafeo database
  • imports airports and routes through the transaction-backed bulk APIs
  • queries airport and route data back into R
  • saves openflights-top-hubs.png and openflights-route-map.png

Vignettes And Examples

Vignettes:

Runnable examples:

API Surface

User-facing functions:

grafeo_db() returns an R6 database handle with:

  • db$execute(query, params = list())
  • db$query(query, params = list())
  • db$begin(isolation = "snapshot")
  • db$import_nodes(data, labels, id_col = NULL)
  • db$import_edges(data, source, target, type)
  • db$nodes() and db$edges()
  • db$info()
  • db$close()

Transactions use an R6 handle with:

  • tx$execute(query, params = list())
  • tx$query(query, params = list())
  • tx$commit()
  • tx$rollback()

Parameters are named lists and use Grafeo’s $name placeholders. Scalar logical, integer, double, character, raw, Date, POSIXct, vector, list, and named-map values are supported. Query results expose column_types; large Grafeo INT64 values are returned as exact decimal strings when an R numeric would lose precision.

Example: Persistent Database 

library(grafeoR)

db <- grafeo_db(path = "example.grafeo")
db$execute("INSERT (:Person {name: 'Persistent'})")
db$close()

db <- grafeo_db(path = "example.grafeo")
db$query("MATCH (p:Person) RETURN p.name")
db$close()

Grafeo 0.5.35 changed the persistent on-disk format. Databases created by Grafeo 0.5.34 or earlier (including databases created by grafeoR releases based on Grafeo 0.5.23) must be recreated or migrated before opening them with this release; keep a backup before attempting any migration.

OpenFlights Attribution

The bundled sample data is derived from OpenFlights:

The bundled attribution note is in inst/extdata/openflights-README.md.

OpenFlights states that the Airport, Airline, Plane and Route databases are made available under the Open Database License (ODbL) v1.0, with individual contents under the Database Contents License (DbCL) v1.0.

Upstream Grafeo