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 delegates statement execution to specialized handlers via the StatementRouter, maintaining clean separation of concerns.

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 StatementRouter ¶ added in v0.2.3

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

StatementRouter routes AST statements to their respective execution handlers. It encapsulates the statement dispatch logic, keeping the Executor focused on high-level coordination.

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.).