cypher

type Attribute ¶

type Attribute struct {
	Key   string
	Value any
}

Attribute represents a key-value attribute for tracing and metrics.

type Executor ¶

type Executor struct {
	// Store is the underlying storage database.
	Store *storage.DB

	// Index provides efficient lookups for nodes and relationships.
	Index *graph.Index
	// contains filtered or unexported fields
}

Executor executes Cypher queries against the graph database. It coordinates parsing, planning, and execution of queries.

The executor manages:

• Query parsing and AST generation
• Index management for efficient lookups
• Transaction coordination
• Match, create, and modify operations

Example:

executor := cypher.NewExecutor(store)
result, err := executor.Execute(ctx, "MATCH (n:Person) RETURN n.name", nil)
if err != nil {
    log.Fatal(err)
}
for _, row := range result.Rows {
    fmt.Println(row["n.name"])
}

func NewExecutor(store *storage.DB) *Executor

store, _ := storage.Open("/path/to/db")
executor := cypher.NewExecutor(store)

func (e *Executor) Execute(ctx context.Context, query string, params map[string]interface{}) (Result, error)

// Execute a CREATE query
result, err := executor.Execute(ctx, "CREATE (n:Person {name: 'Alice'})", nil)

// Execute with parameters
result, err := executor.Execute(ctx,
    "CREATE (n:Person {name: $name})",
    map[string]interface{}{"name": "Alice"},
)

func (e *Executor) ExecuteAST(ctx context.Context, query *ast.Query, params map[string]interface{}) (Result, error)

p := parser.New("MATCH (n:Person) RETURN n.name")
ast, _ := p.Parse()
result, err := executor.ExecuteAST(ctx, ast, nil)

func (e *Executor) ExecuteWithTx(t *tx.Transaction, query *ast.Query, params map[string]interface{}) (Result, error)

tx, _ := manager.Begin(false)
result, err := executor.ExecuteWithTx(tx, ast, params)
if err != nil {
    tx.Rollback()
} else {
    tx.Commit()
}

type Logger ¶

type Logger interface {
	// Debug logs a debug message with optional key-value pairs.
	Debug(msg string, args ...any)

	// Info logs an informational message with optional key-value pairs.
	Info(msg string, args ...any)

	// Warn logs a warning message with optional key-value pairs.
	Warn(msg string, args ...any)

	// Error logs an error message with optional key-value pairs.
	Error(msg string, args ...any)
}

Logger defines the interface for logging operations. Implementations can use different logging backends (slog, zap, logrus, etc.).

type Meter ¶

type Meter interface {
	// RecordHistogram records a histogram observation.
	RecordHistogram(ctx context.Context, name string, value float64, attrs ...Attribute)

	// RecordCounter increments a counter.
	RecordCounter(ctx context.Context, name string, value float64, attrs ...Attribute)
}

Meter defines the interface for recording metrics. Implementations can use different metrics backends (Prometheus, StatsD, etc.).

type Observability ¶

type Observability struct {
	// Logger is used for logging operations.
	Logger Logger

	// Tracer is used for distributed tracing.
	Tracer Tracer

	// Meter is used for recording metrics.
	Meter Meter
}

Observability contains the logging, tracing, and metering interfaces used throughout the Cypher execution pipeline.

It provides a unified interface for observability concerns, allowing users to plug in their own implementations or use the defaults.

Example:

// Use default observability (uses slog for logging)
obs := cypher.NewObservability()

// Use custom logger
obs := cypher.NewObservability(cypher.WithLogger(myLogger))

// Use custom tracer and meter
obs := cypher.NewObservability(
    cypher.WithTracer(myTracer),
    cypher.WithMeter(myMeter),
)

func NewObservability(opts ...ObservabilityOption) *Observability

// Default observability
obs := cypher.NewObservability()

// With custom options
obs := cypher.NewObservability(
    cypher.WithLogger(myLogger),
    cypher.WithTracer(myTracer),
)

type ObservabilityOption ¶

type ObservabilityOption func(*Observability)

ObservabilityOption configures optional parameters for observability.

func WithLogger(l Logger) ObservabilityOption

obs := cypher.NewObservability(cypher.WithLogger(myLogger))

func WithMeter(m Meter) ObservabilityOption

obs := cypher.NewObservability(cypher.WithMeter(myMeter))

func WithTracer(t Tracer) ObservabilityOption

obs := cypher.NewObservability(cypher.WithTracer(myTracer))

type Parser ¶

type Parser struct {
	// contains filtered or unexported fields
}

func NewParser(input string) *Parser

p := cypher.NewParser("MATCH (n:Person) RETURN n.name")
query, err := p.Parse()

func (p *Parser) Parse() (*ast.Query, error)

p := cypher.NewParser("MATCH (n:Person) RETURN n.name")
query, err := p.Parse()
if err != nil {
    log.Fatal(err)
}

type Result ¶

type Result struct {
	// AffectedNodes is the number of nodes created, modified, or deleted.
	AffectedNodes int

	// AffectedRels is the number of relationships created or deleted.
	AffectedRels int

	// NodesCreated is the number of nodes created during the query.
	NodesCreated int

	// RelsCreated is the number of relationships created during the query.
	RelsCreated int

	// Rows contains matched data rows for MATCH queries.
	// Each row is a map of column names to values.
	Rows []map[string]interface{}

	// Columns contains the names of columns returned in Rows.
	Columns []string
}

Result contains the count of affected graph elements after executing a data-modifying Cypher query (CREATE, SET, DELETE, REMOVE).

It also contains the result data for MATCH queries, including the matched rows and column names.

Example:

result, err := executor.Execute(ctx, "CREATE (n:Person)", nil)
if err != nil {
    log.Fatal(err)
}
fmt.Printf("Nodes created: %d\n", result.AffectedNodes)
fmt.Printf("Relationships created: %d\n", result.AffectedRels)

// For MATCH queries
result, err := executor.Execute(ctx, "MATCH (n:Person) RETURN n.name", nil)
for _, row := range result.Rows {
    fmt.Println(row["n.name"])
}

func (r *Result) AddAffected(nodes, rels int)

result := &cypher.Result{}
result.AddAffected(2, 1) // 2 nodes and 1 relationship affected
fmt.Printf("Total affected: %d nodes, %d relationships\n",
    result.AffectedNodes, result.AffectedRels)

type Span ¶

type Span interface {
	// End completes the span.
	End()

	// AddEvent adds an event to the span.
	AddEvent(name string, attrs ...Attribute)

	// SetAttributes sets attributes on the span.
	SetAttributes(attrs ...Attribute)
}

Span represents a tracing span for observing execution.

type SpanOption ¶

type SpanOption func(*spanConfig)

SpanOption configures span creation.

type Tracer ¶

type Tracer interface {
	// StartSpan starts a new span with the given name and options.
	StartSpan(ctx context.Context, name string, opts ...SpanOption) (context.Context, Span)

	// RecordError records an error on the current span.
	RecordError(ctx context.Context, err error, attrs ...Attribute)
}

Tracer defines the interface for distributed tracing. Implementations can use different tracing backends (OpenTelemetry, Jaeger, etc.).