Skip to content

API Reference

This document categorizes the core structures and exported methods by code modules and packages.

1. pkg/api

This package contains high-level, general-purpose graph library interface abstractions exposed to external users.

  • func Open(path string, opts ...DBOption) (*DB, error) Opens the database file at the specified path. If it does not exist, initializes it as a Pebble KV store structure.

  • type DBOption func(*DB) Configuration definition using the functional options pattern.

  • func WithObservability(o *cypher.Observability) DBOption Creates a DBOption that allows injection of configured logging, tracing, and monitoring metrics.

  • type DB struct The core thread-safe graph database instance that controls interaction with the underlying engine:

  • func (db *DB) Exec(ctx context.Context, cypherQuery string, args ...interface{}) (Result, error)
  • func (db *DB) Query(ctx context.Context, cypherQuery string, args ...interface{}) (*Rows, error)
  • func (db *DB) BeginTx(ctx context.Context, opts *TxOptions) (*Tx, error)
  • func (db *DB) Close() error

  • func (db *DB) IsClosed() bool

  • type Result = cypher.Result Contains the status and count after graph modification operations (alias):

  • AffectedNodes int: Number of affected nodes.
  • AffectedRels int: Number of affected relationships.
  • Rows []map[string]interface{}: Internal matched data rows (used for chained execution).

  • Columns []string: Internal column names.

  • type Rows struct The graph engine's iteration cursor:

  • func (r *Rows) Next() bool
  • func (r *Rows) Scan(dest ...interface{}) error
  • func (r *Rows) Columns() []string

  • func (r *Rows) Close() error

  • type Tx struct Safe concurrent multi-version control transaction wrapper:

  • func (tx *Tx) Exec(cypherQuery string, args ...interface{}) (Result, error)
  • func (tx *Tx) Query(cypherQuery string, args ...interface{}) (*Rows, error)
  • func (tx *Tx) Commit() error
  • func (tx *Tx) Rollback() error

2. pkg/cypher

Package for handling Cypher query statements and their execution environment.

  • type Executor struct Context object for executing abstract syntax trees. Composed of Creator, Matcher, and Modifier.

  • func NewExecutor(store *storage.DB, opts ...ExecutorOption) *Executor Creates an executor instance.

  • type Observability struct Composed of three capability interfaces: Logger, Tracer, and Meter.

  • func NewObservability(opts ...ObservabilityOption) *Observability Generates an observer with default empty implementations, which can be replaced via WithLogger, WithTracer, WithMeter.

3. pkg/graph

Describes the core graph database model and serialization metadata.

  • type Mutator interface Defines abstract mutation capabilities for transactions/storage, enabling entities to participate in underlying transactions:
  • Put(key, value []byte) error

  • Delete(key []byte) error

  • type Index struct Manages efficient index construction and querying for node labels and properties.

  • type AdjacencyList struct The adjacency list structure for graphs, supporting O(1) bidirectional relationship queries and maintenance.

  • type Node struct

  • ID string
  • Labels []string
  • Properties map[string]PropertyValue

Provides convenience methods like GetProperty, SetProperty, HasLabel, RemoveLabel.

  • type Relationship struct
  • ID string
  • StartNodeID string
  • EndNodeID string
  • Type string

  • Properties map[string]PropertyValue

  • type PropertyValue struct Wraps primitive data types:

  • Type() PropertyType
  • StringValue() string
  • IntValue() int64
  • FloatValue() float64
  • BoolValue() bool

4. pkg/storage

Contains efficient interaction with the underlying Pebble and defines binary key-value pairs for custom graph databases.

  • func Open(path string) (*DB, error) Opens the KV persistence layer.

  • func (db *DB) Put(key, value []byte) error

  • func (db *DB) Get(key []byte) ([]byte, error)
  • func (db *DB) Delete(key []byte) error
  • func Marshal(v interface{}) ([]byte, error)
  • func Unmarshal(data []byte, v interface{}) error