NornicDB Plugin System¶

NornicDB features a powerful plugin system that extends Cypher with APOC (Awesome Procedures On Cypher) functions. The APOC plugin provides 964 functions covering collections, text processing, math, graph algorithms, data import/export, and more.

Overview¶

The plugin system provides:

Dynamic Plugin Loading: Plugins are .so files loaded automatically at startup
APOC Plugin: Pre-built plugin with 964 functions included in all Docker images
Custom Plugins: Create your own plugins following the same interface
Configuration Control: Enable/disable via environment variables

Quick Start¶

Using APOC Functions¶

All Docker images include the APOC plugin pre-loaded:

// Collection functions
RETURN apoc.coll.sum([1, 2, 3, 4, 5])           // 15
RETURN apoc.coll.avg([1, 2, 3, 4, 5])           // 3.0
RETURN apoc.coll.flatten([[1,2], [3,4]])        // [1,2,3,4]

// Text functions
RETURN apoc.text.capitalize('hello world')      // "Hello world"
RETURN apoc.text.camelCase('hello_world')       // "helloWorld"
RETURN apoc.text.levenshteinDistance('cat', 'bat')  // 1

// Math functions
RETURN apoc.math.sqrt(16)                       // 4.0
RETURN apoc.math.sigmoid(0)                     // 0.5

// Scoring functions
RETURN apoc.scoring.cosine([1,0], [0,1])        // 0.0
RETURN apoc.scoring.jaccard([1,2,3], [2,3,4])   // 0.5

// Spatial functions
RETURN apoc.spatial.haversineDistance(40.7128, -74.0060, 34.0522, -118.2437)

// Create functions
RETURN apoc.create.uuid()                       // "550e8400-e29b-41d4-..."

Configuration¶

Environment Variables¶

# Directory containing .so plugin files (default: /app/plugins in Docker)
NORNICDB_PLUGINS_DIR=/app/plugins

# Enable/disable plugin system
NORNICDB_PLUGINS_ENABLED=true

Docker Compose¶

services:
  nornicdb:
    image: timothyswt/nornicdb-arm64-metal:latest
    environment:
      - NORNICDB_PLUGINS_DIR=/app/plugins
    volumes:
      - ./custom-plugins:/app/plugins/custom  # Add custom plugins

Available Function Categories¶

The APOC plugin includes 964 functions across these categories:

Category	Count	Description
`apoc.coll`	46	Collection operations (sum, avg, sort, flatten, union, etc.)
`apoc.text`	41	Text manipulation (capitalize, replace, distance, regex, etc.)
`apoc.math`	45	Mathematical operations (sqrt, trig, statistics, etc.)
`apoc.convert`	24	Type conversion (toFloat, toJson, toList, etc.)
`apoc.date`	15	Date/time handling (format, parse, add, etc.)
`apoc.json`	18	JSON operations (parse, stringify, path, merge, etc.)
`apoc.util`	38	Utilities (md5, sha256, uuid, compress, etc.)
`apoc.agg`	15	Aggregation (median, percentile, stdev, histogram, etc.)
`apoc.algo`	9	Graph algorithms (pageRank, dijkstra, etc.)
`apoc.map`	25	Map operations (merge, flatten, groupBy, etc.)
`apoc.create`	19	Node/relationship creation (node, relationship, uuid, etc.)
`apoc.export`	14	Data export (json, csv, cypher, graphML, etc.)
`apoc.import`	19	Data import (json, csv, xml, etc.)
`apoc.load`	29	Data loading (json, csv, jdbc, s3, kafka, etc.)
`apoc.log`	25	Logging (info, debug, warn, metrics, etc.)
`apoc.node`	34	Node operations (degree, labels, properties, etc.)
`apoc.nodes`	22	Multi-node operations (group, partition, connected, etc.)
`apoc.rel`	29	Relationship operations (type, properties, weight, etc.)
`apoc.refactor`	20	Graph refactoring (mergeNodes, renameLabel, etc.)
`apoc.schema`	30	Schema operations (indexes, constraints, etc.)
`apoc.meta`	38	Metadata (schema, stats, types, etc.)
`apoc.neighbors`	6	Neighbor traversal (atHop, bfs, dfs, etc.)
`apoc.path`	9	Path operations (expand, slice, etc.)
`apoc.paths`	21	Path finding (shortest, all, kShortest, etc.)
`apoc.periodic`	10	Periodic operations (iterate, commit, etc.)
`apoc.search`	29	Search operations (fulltext, fuzzy, regex, etc.)
`apoc.scoring`	22	Similarity scoring (cosine, jaccard, bm25, etc.)
`apoc.spatial`	19	Spatial operations (distance, bearing, geohash, etc.)
`apoc.stats`	23	Statistics (mean, median, correlation, etc.)
`apoc.temporal`	26	Temporal operations (format, parse, duration, etc.)
`apoc.trigger`	24	Trigger management (add, remove, enable, etc.)
`apoc.warmup`	15	Cache warmup (run, nodes, relationships, etc.)
`apoc.xml`	23	XML operations (parse, query, transform, etc.)
`apoc.label`	27	Label operations (add, remove, exists, etc.)
`apoc.lock`	19	Locking (nodes, relationships, etc.)
`apoc.merge`	17	Merge operations (node, relationship, etc.)
`apoc.hashing`	18	Hashing (md5, sha256, murmur, etc.)
`apoc.graph`	15	Graph operations (fromData, validate, etc.)
`apoc.diff`	9	Diff operations (nodes, maps, etc.)
`apoc.cypher`	16	Cypher utilities (run, parallel, etc.)
`apoc.bitwise`	15	Bitwise operations (and, or, xor, etc.)
`apoc.atomic`	9	Atomic operations (add, update, etc.)
`apoc.number`	38	Number formatting (format, parse, toHex, etc.)

Creating Custom Plugins¶

Plugin Interface¶

Create a Go file that exports a Plugin variable implementing the interface:

// my_plugin.go
package main

import "github.com/orneryd/nornicdb/apoc"

// Plugin is the exported symbol NornicDB loads
var Plugin = MyPlugin{}

type MyPlugin struct{}

func (p MyPlugin) Name() string    { return "myplugin" }
func (p MyPlugin) Version() string { return "1.0.0" }

func (p MyPlugin) Functions() map[string]apoc.FunctionInfo {
    return map[string]apoc.FunctionInfo{
        "apoc.myplugin.hello": {
            Handler:     Hello,
            Category:    "myplugin",
            Description: "Returns a greeting",
            Examples:    []string{"apoc.myplugin.hello('World') => 'Hello, World!'"},
        },
        "apoc.myplugin.double": {
            Handler:     Double,
            Category:    "myplugin",
            Description: "Doubles a number",
            Examples:    []string{"apoc.myplugin.double(21) => 42"},
        },
    }
}

func Hello(name string) string {
    return "Hello, " + name + "!"
}

func Double(n float64) float64 {
    return n * 2
}

Building Your Plugin¶

# Build the plugin (must use same Go version as NornicDB)
go build -buildmode=plugin -o my-plugin.so my_plugin.go

# Copy to plugins directory
cp my-plugin.so /path/to/nornicdb/plugins/

Using Your Plugin¶

After restarting NornicDB, your functions are available:

RETURN apoc.myplugin.hello('World')   // "Hello, World!"
RETURN apoc.myplugin.double(21)       // 42

Startup Logs¶

On startup, NornicDB logs loaded plugins:

🔌 Loading Plugins from /app/plugins...
  ✓ apoc.so: 964 functions loaded (v1.0.0)
  ✓ my-plugin.so: 2 functions loaded (v1.0.0)
📦 Total: 966 plugin functions available

Building the APOC Plugin¶

From the NornicDB source:

# Build using Makefile
make plugins

# Or manually
cd apoc/plugin-src/apoc
go build -buildmode=plugin -o ../../../apoc/built-plugins/apoc.so apoc_plugin.go

Docker Image Plugin Locations¶

All official Docker images include the pre-built APOC plugin:

Image	Plugins Location	Functions
`nornicdb-arm64-metal`	`/app/plugins/apoc.so`	964
`nornicdb-amd64-cuda`	`/app/plugins/apoc.so`	964
`nornicdb-amd64-cpu`	`/app/plugins/apoc.so`	964

Troubleshooting¶

Plugin Not Loading¶

Check plugin file exists and is readable:
```
ls -la /app/plugins/
```
Verify Go version compatibility (plugins must be built with same Go version):
```
go version
```

Check logs for errors:

docker logs nornicdb 2>&1 | grep -i plugin

Function Not Found¶

Check if function exists:
```
CALL apoc.help('coll.sum')
```
Verify plugin loaded at startup (check logs)

Invalid ELF Header¶

This error means the plugin was built for a different architecture: - Rebuild the plugin for the target architecture (arm64 vs amd64) - Ensure you're using go build -buildmode=plugin with matching platform

Platform Support¶

Platform	Plugin Support	Notes
Linux (amd64)	✅ Full	Native Go plugin support
Linux (arm64)	✅ Full	Native Go plugin support
macOS (arm64)	✅ Full	Native Go plugin support
macOS (amd64)	✅ Full	Native Go plugin support
Windows	❌ None	Go plugins not supported

For Windows, build NornicDB with APOC functions compiled in (not as plugin).

Performance¶

Plugins load once at startup (~100ms for APOC)
Function calls have minimal overhead (direct function pointer)
No difference in performance between built-in and plugin functions

Security Considerations¶

Plugins run with the same permissions as NornicDB
Only load plugins from trusted sources
Plugin code has full system access
Use Docker volume mounts for isolation
Review plugin source code before deployment