Package {rladybugdb}

rladybugdb: Native R access to LadybugDB

Description

Provides an R interface to 'LadybugDB', an embedded columnar graph database using the 'Cypher' query language. 'LadybugDB' was formerly known as 'Kuzu'. This package uses native 'Rcpp' bindings to the 'LadybugDB' C library, requiring no 'Python' runtime.

Author(s)

Maintainer: Raden Muhammad Hadi hadimaster65555@gmail.com

Authors:

• Raden Muhammad Hadi hadimaster65555@gmail.com

See Also

Useful links:

• https://github.com/hadimaster65555/rladybugdb

• Report bugs at https://github.com/hadimaster65555/rladybugdb/issues

Build an igraph from a data frame with node/rel list-columns

Description

Heuristic: columns whose values are named lists containing ⁠_id⁠ / ⁠_label⁠ / properties are NODE columns; those containing ⁠_src⁠ / ⁠_dst⁠ are REL columns.

Usage

.build_igraph(df, column_types = NULL)

Value

A directed igraph object representing the query's nodes and relationships, with database properties stored as attributes.

Assert that an object is an lb_connection

Description

Assert that an object is an lb_connection

Usage

.lb_check_conn(conn)

Arguments

Value

The supplied lb_connection object invisibly if it is open. Raises a typed error for an invalid or closed connection.

Handle C++ exceptions from LadybugDB

Description

Wraps a call expression, catches any condition thrown by the Rcpp layer, and re-throws as a typed R error with class rladybugdb_error_query.

Usage

.lb_handle_error(expr)

Arguments

Value

The value of expr, with its class and visibility preserved. Raises a typed error if evaluating the expression fails.

Create a LadybugDB DBI driver

Description

Create a LadybugDB DBI driver

Usage

Ladybug()

Value

A LadybugDriver S4 object, inheriting from DBIDriver, for use with DBI::dbConnect() to open a LadybugDB database.

LadybugDB DBI connection

Description

LadybugDB DBI connection

Slots

database

Native database object.

connection

Native connection object.

state

Mutable connection state.

bigint

INT64 conversion policy.

LadybugDB DBI methods

Description

LadybugDB implements the standard DBI lifecycle, query, binding, fetch, transaction, quoting, and table-metadata generics. LadybugDB's native schema distinguishes node and relationship tables, so relational helpers outside this documented subset are intentionally left to graph-specific Cypher and the ⁠lb_*⁠ API. SQL SELECT, dbWriteTable(), and dbAppendTable() are not translated. dbExecute() returns zero after successful DDL/DML because the LadybugDB 0.20.4 C result summary does not expose a stable affected-row count. Applicable driver behavior is exercised with a focused DBItest subset.

Value

The return value depends on the DBI method:

• dbConnect() returns a LadybugConnection S4 object, inheriting from DBIConnection, that owns an open database and native connection.

• dbSendQuery() and dbSendStatement() return a LadybugResult S4 object, inheriting from DBIResult, representing an executed statement or a parameterized statement awaiting dbBind().

• dbBind() returns the supplied LadybugResult invisibly after executing the statement with the supplied parameters and resetting its fetch cursor.

• dbFetch() and dbGetQuery() return a data.frame with one column per returned expression and one row per query record. dbFetch() advances the cursor; dbGetQuery() fetches all rows and clears its result.

• dbExecute() and dbGetRowsAffected() return the numeric scalar 0. The engine does not expose an affected-row count, so this value does not indicate how many rows were changed.

• dbGetRowCount() returns a numeric scalar counting rows fetched since the result was created or most recently bound.

• dbColumnInfo() returns a data.frame with character columns name and type, giving each result column's name and LadybugDB type.

• dbGetInfo() returns a named list. For a driver, driver.version and client.version are character strings identifying the package and engine versions. For a connection, dbname, bigint, and serverVersion are character strings describing its path, integer conversion policy, and engine version; read.only and valid are logical scalars. For a result, statement is the Cypher string, row.count is the numeric fetched-row count, and completed is a logical scalar. An unbound result also has pending = TRUE; an executed, valid result also includes the metadata described by lb_result_info().

• dbIsValid(), dbHasCompleted(), and dbIsReadOnly() return a logical scalar indicating whether the object is usable, fetching is complete, or the database was opened read-only, respectively. Drivers are always valid.

• dbExistsTable() returns a logical vector indicating whether each supplied table name exists.

• dbListTables() and dbListFields() return character vectors of table names and field names, respectively; an empty vector means none were found.

• dbDataType() returns a character string naming the LadybugDB type for an R vector, or a named character vector of types for data-frame columns.

• dbQuoteIdentifier() and dbQuoteString() return DBI::SQL objects containing quoted identifiers or string literals, with the same length as the input character vector.

• dbDisconnect(), dbClearResult(), dbBegin(), dbCommit(), dbRollback(), and dbUnloadDriver() return the logical scalar TRUE after successfully releasing resources or completing transaction control.

• show() returns invisible NULL, called for the side effect of displaying a summary of the driver, connection, or result.

See Also

Ladybug(), DBI::DBI-package

LadybugDB DBI driver

Description

LadybugDB DBI driver

Slots

state

Internal driver state.

LadybugDB DBI result

Description

LadybugDB DBI result

Slots

connection

Owning DBI connection.

state

Mutable result state.

statement

Original Cypher statement.

Convert a LadybugDB result to a data frame

Description

Materialization preserves the current streaming cursor, so it is repeatable and does not change subsequent calls to lb_fetch().

Usage

## S3 method for class 'lb_result'
as.data.frame(x, ...)

Arguments

Value

A data.frame containing all query rows, with one column per returned expression. Nested database values are stored in list columns.

Convert a LadybugDB result to an Arrow Table

Description

Convert a LadybugDB result to an Arrow Table

Usage

as_arrow_table(x, ...)

Arguments

Value

An arrow::Table containing all query rows and columns, backed by LadybugDB's Arrow C Data export. The streaming cursor is preserved.

Convert an lb_result to an igraph object

Description

Extracts node and relationship columns from a LadybugDB query result and constructs an igraph::graph_from_data_frame() object.

Usage

as_igraph(x, ...)

Arguments

Details

Node columns must have LadybugDB type NODE and relationship columns type REL/RELATIONSHIP. When the result contains no structural columns the function aborts with an informative error.

Value

A directed igraph object whose vertices and edges represent the nodes and relationships in the query result. Database properties become vertex and edge attributes; repeated internal identifiers are deduplicated.

Examples

if (requireNamespace("igraph", quietly = TRUE)) {
  with_lb_connection(":memory:", {
    lb_close(lb_execute(
      conn, "CREATE NODE TABLE Person (name STRING, PRIMARY KEY(name))"
    ))
    lb_close(lb_execute(conn, "CREATE REL TABLE Knows (FROM Person TO Person)"))
    lb_close(lb_execute(
      conn, "CREATE (:Person {name:'A'})-[:Knows]->(:Person {name:'B'})"
    ))
    result <- lb_execute(
      conn, "MATCH (a:Person)-[r:Knows]->(b:Person) RETURN a, r, b"
    )
    graph <- as_igraph(result)
    lb_close(result)
    graph
  }, num_threads = 2)
}

Convert an lb_result to a tbl_graph (tidygraph)

Description

Convert an lb_result to a tbl_graph (tidygraph)

Usage

as_tbl_graph(x, ...)

Arguments

Value

A tbl_graph object, inheriting from igraph, whose nodes and edges represent the query's nodes and relationships, with their properties available as attributes for tidygraph operations.

Convert a LadybugDB result to a tibble

Description

Convert a LadybugDB result to a tibble

Usage

as_tibble(x, ...)

Arguments

Value

A tibble (classes tbl_df, tbl, and data.frame) containing all query rows, with one column per returned expression.

Format a LadybugDB interval

Description

Format a LadybugDB interval

Usage

## S3 method for class 'lb_interval'
format(x, ...)

## S3 method for class 'lb_interval'
print(x, ...)

Arguments

Value

format() returns a character string describing the interval's months, days, and microseconds. print() displays that description and returns the supplied lb_interval object invisibly.

Examples

interval <- structure(
  list(months = 1L, days = 2L, microseconds = 3000000),
  class = "lb_interval"
)
format(interval)
print(interval)

Install the LadybugDB C library (deprecated)

Description

This function is deprecated. The C library is built from bundled source during package installation and no Python installation is required. This helper only issues a deprecation warning; it does not install any software.

Usage

ladybugdb_install(...)

Arguments

Value

Invisible NULL, called for the side effect of issuing a deprecation warning. No software is installed.

Check whether LadybugDB is available

Description

Returns TRUE if the native LadybugDB C library is loaded and functional.

Usage

ladybugdb_is_installed()

Value

A logical scalar: TRUE if the native LadybugDB C library responds to a version query, and FALSE if that query fails.

Examples

ladybugdb_is_installed()

Return the LadybugDB C library version string

Description

Return the LadybugDB C library version string

Usage

ladybugdb_version()

Value

A character string identifying the bundled LadybugDB engine version, e.g. "0.20.4".

Examples

ladybugdb_version()

Transaction control

Description

Transaction control

Usage

lb_begin(conn)

lb_commit(conn)

lb_rollback(conn)

Arguments

Value

The supplied lb_connection object invisibly, after starting, committing, or rolling back its transaction, respectively.

Close a LadybugDB result, connection, or database

Description

Closing an object more than once is harmless. A connection cannot be closed while it owns open results, and a database cannot be closed while it owns open connections.

Usage

lb_close(x, ...)

Arguments

Value

Invisible NULL, called for the side effect of releasing the object's native resources.

Open a connection to a LadybugDB database

Description

Open a connection to a LadybugDB database

Usage

lb_connection(database, num_threads = NULL)

Arguments

Value

An lb_connection list containing a native connection pointer and its owning database. Use it to execute queries, and release it with lb_close() after its results are closed.

Load an Arrow object into a LadybugDB table

Description

Registers a temporary Arrow-backed table through the Arrow C Data Interface, copies its rows into an existing native node table, and unregisters it. No data-frame or CSV conversion is performed.

Usage

lb_copy_from_arrow(conn, value, table)

Arguments

Value

An lb_result containing the COPY statement's metadata after loading the Arrow rows into the target table. Release it with lb_close().

Load a CSV file into a LadybugDB table

Description

Load a CSV file into a LadybugDB table

Usage

lb_copy_from_csv(conn, path, table, header = TRUE, delim = ",", ...)

Arguments

Value

An lb_result containing the COPY statement's metadata after loading the CSV rows into the target table. Release it with lb_close().

Load an R data frame into a LadybugDB table

Description

Uses native Arrow transport when the optional arrow package is available. Otherwise it uses the explicit CSV loader as a compatibility fallback.

Usage

lb_copy_from_df(conn, df, table)

Arguments

Value

An lb_result containing the COPY statement's metadata after loading the data-frame rows into the target table. Release it with lb_close().

Open a LadybugDB database

Description

Creates or opens a LadybugDB database. LadybugDB v0.20.4 can read the storage formats created by v0.15.x. For incompatible future formats, export with the original engine and import into a fresh database.

Usage

lb_database(path = ":memory:", read_only = FALSE, config = list())

Arguments

Value

An lb_database list containing a native database pointer, its path, read-only flag, and configuration. It represents an open database that should be released with lb_close() after its connections are closed.

Execute a Cypher query

Description

Sends a Cypher query string to LadybugDB and returns an lb_result object. For DDL or DML statements (CREATE TABLE, CREATE, MERGE, …) the result contains metadata; for MATCH/RETURN it contains rows.

Usage

lb_execute(conn, query, parameters = NULL)

Arguments

Value

An lb_result list containing a native result pointer, its owning connection, query text, column names and types, and row count. It represents query rows or statement metadata and must be released with lb_close().

Examples

with_lb_connection(":memory:", {
  lb_close(lb_execute(
    conn, "CREATE NODE TABLE Person (name STRING, PRIMARY KEY(name))"
  ))
  result <- lb_execute(conn, "CREATE (:Person {name: $name})",
                       parameters = list(name = "Alice"))
  print(result)
  lb_close(result)
}, num_threads = 2)

Fetch rows from a LadybugDB result

Description

Fetch rows from a LadybugDB result

Usage

lb_fetch(result, n = 10000)

lb_has_next(result)

lb_reset(result)

Arguments

Value

lb_fetch() returns a data.frame with up to n rows from the current cursor position and one column per returned expression. Repeated calls advance the cursor. lb_has_next() returns a logical scalar that is TRUE when unfetched rows remain. lb_reset() returns the supplied lb_result invisibly after moving its cursor back to the first row.

Fetch a chunk as an Arrow Table

Description

Fetch a chunk as an Arrow Table

Usage

lb_fetch_arrow(result, n = Inf)

Arguments

Value

An arrow::Table containing up to n rows from the current cursor position. The cursor advances by the number of rows returned.

Manage LadybugDB extensions

Description

These are thin wrappers around LadybugDB's extension Cypher commands. Remote installation and updating are unavailable in the CRAN build because those operations require a native networking stack. Compatible extensions installed outside R can still be loaded with lb_load_extension().

Usage

lb_list_extensions(conn)

lb_install_extension(conn, name)

lb_load_extension(conn, name)

lb_update_extension(conn, name)

Arguments

Value

lb_list_extensions() returns a data.frame describing the official extensions reported by the engine, with one row per extension. lb_load_extension() returns an lb_result containing the LOAD statement's metadata; release it with lb_close(). lb_install_extension() and lb_update_extension() always raise an error of class rladybugdb_error_unsupported and return no value, because remote installation and updates are unavailable in the CRAN build.

Retrieve the next result from a multi-statement query

Description

Retrieve the next result from a multi-statement query

Usage

lb_next_result(result)

Arguments

Value

An lb_result representing the next statement's rows or metadata, or NULL if no further result is available. Close each returned result with lb_close().

Execute a Cypher query and return a data frame

Description

Convenience wrapper around lb_execute() that immediately converts the result to an R data.frame. Equivalent to as.data.frame(lb_execute(conn, query, ...)).

Usage

lb_query(conn, query, parameters = NULL, ...)

Arguments

Value

A data.frame containing all query rows, with one column per returned expression. The underlying native result is closed automatically.

Examples

with_lb_connection(":memory:", {
  lb_close(lb_execute(
    conn,
    "CREATE NODE TABLE Person (name STRING, age INT64, PRIMARY KEY(name))"
  ))
  lb_close(lb_execute(conn, "CREATE (:Person {name: 'Alice', age: 30})"))
  lb_query(conn, "MATCH (p:Person) RETURN p.name AS name, p.age AS age")
}, num_threads = 2)

Return query timing information

Description

Return query timing information

Usage

lb_query_summary(result)

Arguments

Value

A named list with numeric scalars compiling_time_ms and execution_time_ms, measuring the query's compilation and execution times in milliseconds.

Inspect result metadata

Description

Inspect result metadata

Usage

lb_result_info(result)

Arguments

Value

A named list with character vectors column_names and column_types; numeric scalars num_columns, num_tuples (total rows), and rows_fetched (current cursor position); and logical scalars complete (no unfetched rows remain) and has_next_result (another statement's result is available).

Configure and interrupt queries

Description

Configure and interrupt queries

Usage

lb_set_timeout(conn, milliseconds)

lb_interrupt(conn)

Arguments

Value

The supplied lb_connection object invisibly. lb_set_timeout() changes its query timeout; lb_interrupt() requests interruption of its running query.

LadybugDB query result

Description

A native query result with an independent, resettable cursor. Results keep their connection and database reachable until lb_close() is called.

Usage

new_lb_result(ptr, conn = NULL, query = NULL, parent = NULL)

Arguments

Value

An lb_result list containing the native result pointer, its owning connection, original query, optional parent result, column names and types, and the total row count.

Run code with an automatically closed LadybugDB connection

Description

Run code with an automatically closed LadybugDB connection

Usage

with_lb_connection(path = ":memory:", code, ..., num_threads = NULL)

Arguments

Value

The value produced by code, with its class and visibility preserved. The connection and database are closed before returning.