vitaledge

README

vitaledge-go

vitaledge-go is a Go client library for VitalEdge's gRPC QueryService.

It provides typed request/response handling for Execute, Explain, Prepared Query execution, and capability discovery over gRPC.

By default, the client dials 127.0.0.1:7443 with plaintext transport credentials. If your deployment requires TLS or other gRPC dial behavior, configure it with WithDialOptions(...).

Install

go get github.com/spaceqraft/vitaledge-go

Quick Example

package main

import (
	"context"
	"fmt"
	"log"

	vitaledge "github.com/spaceqraft/vitaledge-go"
)

func main() {
	ctx := context.Background()

	client, err := vitaledge.New(
		vitaledge.DefaultTarget,
		vitaledge.WithTenant("acme"),
	)
	if err != nil {
		log.Fatal(err)
	}
	defer func() {
		_ = client.Close()
	}()

	result, err := client.Execute(
		ctx,
		`MATCH (n:Seed) RETURN n.id AS id LIMIT 5`,
		nil,
		vitaledge.WithReadOnly(),
		vitaledge.WithStats(),
	)
	if err != nil {
		log.Fatal(err)
	}

	for _, row := range result.Rows {
		fmt.Println(row["id"])
	}

	fmt.Printf("rows=%d durationMs=%d\n", result.Stats.RowsReturned, result.Stats.DurationMS)
}

API Overview

• New(target, opts...) opens a gRPC client connection.
• Execute(ctx, cypher, parameters, opts...) runs a Cypher query with server-side parameter binding from a map[string]any.
• ExecutePrepared(ctx, prepared, opts...) sends a prepared-query payload.
• Explain(ctx, cypher, opts...) returns the raw explain JSON payload plus stats and warnings.
• Capabilities(ctx) fetches server protocol and prepared-query support metadata.
• CreatePropertyIndex(ctx, schema, property, ifNotExists) creates an index via gRPC when index DDL is supported by the server.
• Close() closes the underlying gRPC connection.

Parameter example:

result, err := client.Execute(
	ctx,
	`MATCH (:Movie {title: $movieTitle})<-[r:ACTED_IN]-(p:Person)
	WHERE r.role CONTAINS $actorRole
	RETURN p.name AS actor, r.role AS role`,
	map[string]any{
		"movieTitle": "Wall Street",
		"actorRole":  "Fox",
	},
	vitaledge.WithReadOnly(),
)

Decoded row values map to Go values as follows:

• bool_value -> bool
• int_value -> int64
• double_value -> float64
• string_value -> string
• bytes_value -> []byte
• list_value -> []any
• map_value -> map[string]any
• null_value -> nil

Examples

Run the converted Go examples from the repository root:

# Basic usage
go run ./examples/basic_usage

# Movie recommendation (requires MovieLens-style CSV files)
go run ./examples/intermediate_movie_recommendation \
	--movies /path/to/movies.csv \
	--ratings /path/to/ratings.csv

# Cyber threat detection (requires the Kaggle CSV file)
go run ./examples/advanced_cyber_threat_detection \
	--csv /path/to/cyberfeddefender_dataset.csv

Notes

• The repository vendors the VitalEdge protobuf definition and generated Go stubs under api/proto/vitaledge/v1, so builds do not depend on external proto generation at install time.
• Default dial behavior is plaintext gRPC via insecure.NewCredentials() to match the current local server setup.
• For TLS or custom transport settings, pass explicit gRPC dial options with WithDialOptions(...).

Regenerate Protobuf Stubs

To resync the vendored proto file from the VitalEdge server repo and regenerate Go stubs:

./scripts/gen_proto.sh

Optional environment variables:

• VITALEDGE_PROTO_ROOT (default: $HOME/go/src/vitaledge/api/proto)
• PROTO_FILE_REL (default: vitaledge/v1/query.proto)

The script writes:

• api/proto/vitaledge/v1/query.proto
• api/proto/vitaledge/v1/query.pb.go
• api/proto/vitaledge/v1/query_grpc.pb.go

Documentation

Index

• Constants
• func DecodeValue(value *v1.Value) any
• func EncodeValue(value any) (*v1.Value, error)
• type Client
  • func New(target string, opts ...Option) (*Client, error)
  • func (c *Client) Capabilities(ctx context.Context) (*v1.CapabilitiesResponse, error)
  • func (c *Client) Close() error
  • func (c *Client) CreateEdgeIdentityConfig(ctx context.Context, edgeType string, identityProperties []string, ...) (*CreateIdentityConfigResult, error)
  • func (c *Client) CreateEdgePropertyIndex(ctx context.Context, schema string, property string, ifNotExists bool) (*CreatePropertyIndexResult, error)
  • func (c *Client) CreateVertexIdentityConfig(ctx context.Context, schema string, identityProperties []string, ...) (*CreateIdentityConfigResult, error)
  • func (c *Client) CreateVertexPropertyIndex(ctx context.Context, schema string, property string, ifNotExists bool) (*CreatePropertyIndexResult, error)
  • func (c *Client) Execute(ctx context.Context, query string, parameters map[string]any, ...) (*Result, error)
  • func (c *Client) ExecutePrepared(ctx context.Context, prepared PreparedQuery, opts ...QueryOption) (*Result, error)
  • func (c *Client) Explain(ctx context.Context, query string, opts ...QueryOption) (*ExplainResult, error)
• type CreateIdentityConfigResult
• type CreatePropertyIndexResult
• type Diagnostic
• type ExplainResult
• type Option
  • func WithClientContext(clientContext *v1.ClientContext) Option
  • func WithDialOptions(options ...grpc.DialOption) Option
  • func WithTenant(tenant string) Option
• type PreparedQuery
• type QueryOption
  • func WithFallbackToCypher() QueryOption
  • func WithReadOnly() QueryOption
  • func WithStats() QueryOption
  • func WithWarnings() QueryOption
• type Result
• type Row
• type Stats

Constants

const (
	DefaultTarget = "127.0.0.1:7443"
	DefaultTenant = "default"
	SDKVersion    = "0.1.0"
)

Functions

func DecodeValue

func DecodeValue(value *v1.Value) any

func EncodeValue

func EncodeValue(value any) (*v1.Value, error)

Types

type Client

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

func New

func New(target string, opts ...Option) (*Client, error)

func (*Client) Capabilities

func (c *Client) Capabilities(ctx context.Context) (*v1.CapabilitiesResponse, error)

func (*Client) Close

func (c *Client) Close() error

func (*Client) CreateEdgeIdentityConfig

func (c *Client) CreateEdgeIdentityConfig(ctx context.Context, edgeType string, identityProperties []string, ifNotExists bool) (*CreateIdentityConfigResult, error)

func (*Client) CreateEdgePropertyIndex

func (c *Client) CreateEdgePropertyIndex(ctx context.Context, schema string, property string, ifNotExists bool) (*CreatePropertyIndexResult, error)

func (*Client) CreateVertexIdentityConfig

func (c *Client) CreateVertexIdentityConfig(ctx context.Context, schema string, identityProperties []string, ifNotExists bool) (*CreateIdentityConfigResult, error)

func (*Client) CreateVertexPropertyIndex

func (c *Client) CreateVertexPropertyIndex(ctx context.Context, schema string, property string, ifNotExists bool) (*CreatePropertyIndexResult, error)

func (*Client) Execute

func (c *Client) Execute(ctx context.Context, query string, parameters map[string]any, opts ...QueryOption) (*Result, error)

func (*Client) ExecutePrepared

func (c *Client) ExecutePrepared(ctx context.Context, prepared PreparedQuery, opts ...QueryOption) (*Result, error)

func (*Client) Explain

func (c *Client) Explain(ctx context.Context, query string, opts ...QueryOption) (*ExplainResult, error)

type CreateIdentityConfigResult

type CreateIdentityConfigResult struct {
	Created   bool
	RawVertex *v1.CreateVertexIdentityConfigResponse
	RawEdge   *v1.CreateEdgeIdentityConfigResponse
}

type CreatePropertyIndexResult

type CreatePropertyIndexResult struct {
	Created         bool
	IndexedEntities int64
	RawVertex       *v1.CreateVertexPropertyIndexResponse
	RawEdge         *v1.CreateEdgePropertyIndexResponse
}

type Diagnostic

type Diagnostic struct {
	Code    string
	Message string
}

type ExplainResult

type ExplainResult struct {
	JSON     []byte
	Stats    Stats
	Warnings []Diagnostic
	Raw      *v1.ExplainResponse
}

type Option

type Option func(*config)

func WithClientContext

func WithClientContext(clientContext *v1.ClientContext) Option

func WithDialOptions

func WithDialOptions(options ...grpc.DialOption) Option

func WithTenant

func WithTenant(tenant string) Option

type PreparedQuery

type PreparedQuery struct {
	ParserVersion  string
	IRVersion      string
	Fingerprint    string
	Payload        []byte
	FallbackCypher string
}

type QueryOption

type QueryOption func(*v1.RequestOptions)

func WithFallbackToCypher

func WithFallbackToCypher() QueryOption

func WithReadOnly

func WithReadOnly() QueryOption

func WithStats

func WithStats() QueryOption

func WithWarnings

func WithWarnings() QueryOption

type Result

type Result struct {
	Columns  []string
	Rows     []Row
	Stats    Stats
	Warnings []Diagnostic
	Raw      *v1.QueryResponse
}

type Row

type Row map[string]any

type Stats

type Stats struct {
	RowsReturned int64
	DurationMS   int64
}