query

Documentation

Overview

Package query provides graph query utilities and result formatting.

Index

• func FormatExplanation(e *NodeExplanation) string
• type CentralityInfo
• type CommunityInfo
• type DepthLayer
• type EdgeFilter
• type EdgeInfo
• type EdgeListOutput
  • func FilterEdges(edges []*graph.Edge, filter EdgeFilter) *EdgeListOutput
• type EdgeOutput
• type EdgeOutputWithMeta
• type ExplainOptions
  • func DefaultExplainOptions() ExplainOptions
• type FormatTraversalOptions
• type GodNode
• type NeighborInfo
• type NodeExplanation
  • func ExplainNode(nodes []*graph.Node, edges []*graph.Edge, nodeID string, opts ExplainOptions) (*NodeExplanation, error)
  • func ExplainNodeInGraph(g *graph.Graph, nodeID string, opts ExplainOptions) (*NodeExplanation, error)
• type NodeInfo
• type NodeMatch
  • func FindPartialMatches(g *graph.Graph, query string, limit int) *NodeMatch
• type PathOutput
  • func FormatPath(result *gquery.TraversalResult, from, to string) *PathOutput
• type Summary
  • func ComputeSummary(g *graph.Graph) *Summary
  • func ComputeSummaryFromLists(nodes []*graph.Node, edges []*graph.Edge) *Summary
  • func ComputeSummaryWithOptions(g *graph.Graph, opts SummaryOptions) *Summary
• type SummaryOptions
  • func DefaultSummaryOptions() SummaryOptions
• type TraversalOutput
  • func FormatTraversal(result *gquery.TraversalResult, startNode string, maxDepth int, ...) *TraversalOutput

Functions

func FormatExplanation

func FormatExplanation(e *NodeExplanation) string

FormatExplanation formats the explanation as human-readable text.

Types

type CentralityInfo

type CentralityInfo struct {
	// Betweenness is the betweenness centrality score.
	Betweenness float64 `json:"betweenness"`

	// BetweennessRank is the rank among all nodes (1 = highest).
	BetweennessRank int `json:"betweenness_rank"`

	// IsHub indicates if this is a highly connected node.
	IsHub bool `json:"is_hub"`

	// IsBridge indicates if this is a betweenness bridge.
	IsBridge bool `json:"is_bridge"`
}

CentralityInfo describes centrality metrics.

type CommunityInfo

type CommunityInfo struct {
	// CommunityID is the cluster ID this node belongs to.
	CommunityID int `json:"community_id"`

	// CommunityLabel is a human-readable label for the community.
	CommunityLabel string `json:"community_label"`

	// CommunitySize is the number of nodes in the community.
	CommunitySize int `json:"community_size"`

	// IsBridge indicates if this node connects multiple communities.
	IsBridge bool `json:"is_bridge"`

	// BridgesCommunities lists communities this node connects (if bridge).
	BridgesCommunities []int `json:"bridges_communities,omitempty"`
}

CommunityInfo describes community membership.

type DepthLayer

type DepthLayer struct {
	Depth int      `json:"depth"`
	Count int      `json:"count"`
	Nodes []string `json:"nodes"`
}

DepthLayer represents nodes at a specific depth in traversal.

type EdgeFilter

type EdgeFilter struct {
	// NodeID filters edges that touch this node (from or to).
	NodeID string

	// From filters edges by source node.
	From string

	// To filters edges by target node.
	To string

	// Type filters edges by edge type.
	Type string

	// Types filters edges by multiple edge types (OR).
	Types []string

	// Limit is the maximum number of edges to return.
	Limit int
}

EdgeFilter defines criteria for filtering edges.

type EdgeInfo

type EdgeInfo struct {
	From       string `json:"from"`
	To         string `json:"to"`
	Type       string `json:"type"`
	Confidence string `json:"confidence,omitempty"`
}

EdgeInfo describes an edge for explanation.

type EdgeListOutput

type EdgeListOutput struct {
	Query     string               `json:"query,omitempty"`
	Matches   int                  `json:"matches"`
	Edges     []EdgeOutputWithMeta `json:"edges"`
	Truncated bool                 `json:"truncated,omitempty"`
	Message   string               `json:"message,omitempty"`
}

EdgeListOutput represents filtered edge results.

func FilterEdges

func FilterEdges(edges []*graph.Edge, filter EdgeFilter) *EdgeListOutput

FilterEdges filters a list of edges according to the filter criteria.

type EdgeOutput

type EdgeOutput struct {
	From string `json:"from"`
	To   string `json:"to"`
	Type string `json:"type"`
}

EdgeOutput represents a simplified edge for output.

type EdgeOutputWithMeta

type EdgeOutputWithMeta struct {
	From       string `json:"from"`
	To         string `json:"to"`
	Type       string `json:"type"`
	Confidence string `json:"confidence,omitempty"`
}

EdgeOutputWithMeta includes confidence metadata.

type ExplainOptions

type ExplainOptions struct {
	// Depth controls how many levels of neighbors to include.
	Depth int

	// MaxNeighbors limits the number of neighbors shown.
	MaxNeighbors int

	// IncludeEdges includes edge details in output.
	IncludeEdges bool
}

ExplainOptions configures the explain operation.

func DefaultExplainOptions

func DefaultExplainOptions() ExplainOptions

DefaultExplainOptions returns sensible defaults.

type FormatTraversalOptions

type FormatTraversalOptions struct {
	// Limit is the maximum nodes/edges to include per layer.
	Limit int

	// Algorithm is "BFS" or "DFS".
	Algorithm string

	// Direction is the traversal direction.
	Direction string
}

FormatTraversalOptions controls traversal output formatting.

type GodNode

type GodNode struct {
	ID        string `json:"id"`
	EdgeCount int    `json:"edges"`
}

GodNode represents a highly-connected node in the graph.

type NeighborInfo

type NeighborInfo struct {
	// InDegree is the number of incoming edges.
	InDegree int `json:"in_degree"`

	// OutDegree is the number of outgoing edges.
	OutDegree int `json:"out_degree"`

	// TotalDegree is in + out degree.
	TotalDegree int `json:"total_degree"`

	// IncomingEdges lists edges pointing to this node.
	IncomingEdges []EdgeInfo `json:"incoming_edges,omitempty"`

	// OutgoingEdges lists edges from this node.
	OutgoingEdges []EdgeInfo `json:"outgoing_edges,omitempty"`

	// EdgeTypeBreakdown shows count by edge type.
	EdgeTypeBreakdown map[string]int `json:"edge_type_breakdown"`
}

NeighborInfo describes a node's connections.

type NodeExplanation

type NodeExplanation struct {
	// Node is the basic node information.
	Node NodeInfo `json:"node"`

	// Neighbors describes the node's immediate connections.
	Neighbors NeighborInfo `json:"neighbors"`

	// Community describes which community the node belongs to.
	Community CommunityInfo `json:"community"`

	// Centrality describes the node's centrality metrics.
	Centrality CentralityInfo `json:"centrality"`

	// SourceFile is the file containing this node (if applicable).
	SourceFile string `json:"source_file,omitempty"`

	// Package is the package this node belongs to (if applicable).
	Package string `json:"package,omitempty"`
}

NodeExplanation provides comprehensive context about a node.

func ExplainNode

func ExplainNode(nodes []*graph.Node, edges []*graph.Edge, nodeID string, opts ExplainOptions) (*NodeExplanation, error)

ExplainNode provides comprehensive context about a specific node.

func ExplainNodeInGraph

func ExplainNodeInGraph(g *graph.Graph, nodeID string, opts ExplainOptions) (*NodeExplanation, error)

ExplainNodeInGraph provides explanation using a Graph object.

type NodeInfo

type NodeInfo struct {
	ID    string            `json:"id"`
	Type  string            `json:"type"`
	Label string            `json:"label"`
	Attrs map[string]string `json:"attrs,omitempty"`
}

NodeInfo contains basic node metadata.

type NodeMatch

type NodeMatch struct {
	Query   string   `json:"query"`
	Matches []string `json:"matches"`
	Message string   `json:"message"`
}

NodeMatch represents a partial node match suggestion.

func FindPartialMatches

func FindPartialMatches(g *graph.Graph, query string, limit int) *NodeMatch

FindPartialMatches finds nodes that partially match the query.

type PathOutput

type PathOutput struct {
	From    string       `json:"from"`
	To      string       `json:"to"`
	Found   bool         `json:"found"`
	Length  int          `json:"length,omitempty"`
	Path    []string     `json:"path,omitempty"`
	Edges   []EdgeOutput `json:"edges,omitempty"`
	Message string       `json:"message,omitempty"`
}

PathOutput represents formatted path-finding results.

func FormatPath

func FormatPath(result *gquery.TraversalResult, from, to string) *PathOutput

FormatPath converts a path-finding result to formatted output.

type Summary

type Summary struct {
	TotalNodes int            `json:"total_nodes"`
	TotalEdges int            `json:"total_edges"`
	NodeTypes  map[string]int `json:"node_types"`
	EdgeTypes  map[string]int `json:"edge_types"`
	GodNodes   []GodNode      `json:"god_nodes"`
}

Summary contains aggregate statistics about a graph.

func ComputeSummary

func ComputeSummary(g *graph.Graph) *Summary

ComputeSummary calculates summary statistics for a graph.

func ComputeSummaryFromLists

func ComputeSummaryFromLists(nodes []*graph.Node, edges []*graph.Edge) *Summary

ComputeSummaryFromLists calculates summary from node and edge lists. This is useful when you have lists but not a full graph.

func ComputeSummaryWithOptions

func ComputeSummaryWithOptions(g *graph.Graph, opts SummaryOptions) *Summary

ComputeSummaryWithOptions calculates summary with custom options.

type SummaryOptions

type SummaryOptions struct {
	// MaxGodNodes is the maximum number of god nodes to return.
	MaxGodNodes int

	// ExcludePrefixes are node ID prefixes to exclude from god nodes.
	ExcludePrefixes []string

	// ExcludeContains are substrings that exclude nodes from god nodes.
	ExcludeContains []string
}

SummaryOptions controls summary computation behavior.

func DefaultSummaryOptions

func DefaultSummaryOptions() SummaryOptions

DefaultSummaryOptions returns sensible defaults for summary computation.

type TraversalOutput

type TraversalOutput struct {
	Query      string       `json:"query"`
	Algorithm  string       `json:"algorithm"`
	Direction  string       `json:"direction"`
	MaxDepth   int          `json:"max_depth"`
	NodesFound int          `json:"nodes_found"`
	EdgesFound int          `json:"edges_found"`
	Layers     []DepthLayer `json:"layers"`
	Edges      []EdgeOutput `json:"edges"`
}

TraversalOutput represents formatted traversal results.

func FormatTraversal

func FormatTraversal(result *gquery.TraversalResult, startNode string, maxDepth int, opts FormatTraversalOptions) *TraversalOutput

FormatTraversal converts a TraversalResult to formatted output.