Extensions

Ladybug has an extension API that is designed to dynamically extend its capabilities. Extensions allow you to dynamically load the functionality you need at runtime, while helping limit the size of the core Ladybug library.

Note

Ladybug no longer provides an official extensions server, from where you can directly install the official extensions.

If you’ve upgraded to the latest version v0.11.3, Ladybug has pre-installed and pre-loaded four commonly used extensions (algo, fts, json, vector) for you. You do not need to manually INSTALL or LOAD these extensions.

For Ladybug versions before v0.11.3, or to install extensions that haven’t been pre-installed into v0.11.3, you have to set up a local extension server. The instructions of setting up a local extension server can be found here.

Available extensions

The following extensions are currently implemented:

Extension	Description
algo	Graph algorithms
azure	Scan from Azure Blob Storage and Azure Data Lake Storage (ADLS)
delta	Scan data from Delta Lake tables
duckdb	Scan data from an attached DuckDB database
fts	Perform full-text search using BM25
httpfs	Read and write files over HTTP(S) protocol. Also used for attaching a remote Ladybug database.
iceberg	Scan data from Iceberg tables
json	Scan and manipulate JSON data
llm	Generate text embeddings using external provider APIs
neo4j	Migrate data from Neo4j into Ladybug
postgres	Scan data from an attached PostgreSQL database
sqlite	Scan data from an attached SQLite database
unity	Scan data from Unity Catalog tables
vector	Perform vector similarity search

Using extensions in Ladybug

This section describes how to use officially supported extensions in Ladybug.

List available extensions

You can list all available official extensions by running:

CALL SHOW_OFFICIAL_EXTENSIONS() RETURN *;

Install an extension

Ladybug requires you to install the extension before loading and using it.

Note

In the latest version v0.11.3 Ladybug has pre-installed four commonly used extensions (algo, fts, json, vector) for you. You do not need to manually INSTALL these extensions.

Official extensions can be installed from a local extension server by running the INSTALL command.

INSTALL <EXTENSION_NAME> FROM 'http://localhost:8080/';

You only need to install an extension once.

Update an extension

If you run the INSTALL command for an extension that is already installed, the second install command will not perform any action.

If you want to re-download an extension for any reason, for example if the extension is not working properly, you can use the UPDATE command:

UPDATE <EXTENSION_NAME>;

Load an extension

Note

In the latest version v0.11.3, Ladybug has pre-loaded four commonly used extensions (algo, fts, json, vector) for you. You do not need to manually LOAD these extensions anymore.

You must load extensions before you can use them:

LOAD <EXTENSION_NAME>;

Official extensions can be loaded by simply specifying the extension name. For example, to load the json extension:

load json;

If you want to load an extension you have compiled yourself, you can specify the path to the compiled library. For example, to load a self-compiled json extension:

LOAD EXTENSION 'extension/custom_json/build/libjson.lbug_extension';

List loaded extensions

You can view all your loaded extensions by running:

CALL SHOW_LOADED_EXTENSIONS() RETURN *;

Note

Extensions are scoped to the session within which they are loaded. Thus, the LOAD command must be executed for every new CLI session or client script invocation.

Uninstall an extension

You can uninstall extensions if you don’t need them anymore by using the UNINSTALL command:

UNINSTALL <EXTENSION_NAME>;

Note

Uninstalling a currently loaded extension won’t affect the running database instance, but you won’t be able to load it again in a new Ladybug instance until it’s reinstalled.

Host your own extension server

You can host your own extension server for Ladybug using Docker.

The extension server is based on NGINX and is hosted on GitHub. You can pull the Docker image and run it in your environment:

docker pull ghcr.io/lbugdb/extension-repo:latest
docker run -d -p 8080:80 ghcr.io/lbugdb/extension-repo:latest

In this example, the extension server will be available at http://localhost:8080. You can then install extensions from your server by appending the FROM clause to the INSTALL command:

INSTALL <EXTENSION_NAME> FROM 'http://localhost:8080/';