store

package
v0.2.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Mar 6, 2026 License: MIT Imports: 10 Imported by: 0

Documentation

Overview

ABOUTME: ClickHouse connection management, schema bootstrap, and lifecycle. ABOUTME: Defines the ClickHouseStore struct and constructors; write/read/search in separate files.

ABOUTME: Cursor encoding and decoding for paginated ClickHouse queries. ABOUTME: Cursors are base64-encoded composite keys of timestamp and session ID.

ABOUTME: Read operations for the ClickHouse store. ABOUTME: Implements all ReadStore query methods: sessions, messages, tool calls, users, projects, agents, and git links.

ABOUTME: Full-text search for the ClickHouse store. ABOUTME: Implements Search across messages and tool calls with snippet extraction and highlighting.

ABOUTME: Write operations for the ClickHouse store. ABOUTME: Implements WriteSession, WriteBatch, and WriteGitLinks with batch inserts.

Index

Constants

This section is empty.

Variables

View Source
var (
	ErrNotFound      = errors.New("not found")
	ErrInvalidCursor = errors.New("invalid cursor")
)

Functions

This section is empty.

Types

type ClickHouseStore

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

ClickHouseStore implements Store and ReadStore using ClickHouse native protocol.

func NewClickHouseStore

func NewClickHouseStore(addr, database string) (*ClickHouseStore, error)

NewClickHouseStore opens a native-protocol connection to ClickHouse with default credentials.

func NewClickHouseStoreFromOptions

func NewClickHouseStoreFromOptions(opts ConnectOptions) (*ClickHouseStore, error)

NewClickHouseStoreFromOptions opens a native-protocol connection using the given options. Bootstraps by connecting to "default" first to CREATE DATABASE IF NOT EXISTS, since hosted ClickHouse validates the database during connection handshake.

func NewClickHouseStoreWithAuth

func NewClickHouseStoreWithAuth(addr, database, user, password string) (*ClickHouseStore, error)

NewClickHouseStoreWithAuth opens a native-protocol connection to ClickHouse with explicit credentials.

func (*ClickHouseStore) ActivityHeatmap

func (s *ClickHouseStore) ActivityHeatmap(ctx context.Context, orgID string, projectName string, dateFrom, dateTo string) ([]HeatmapCell, error)

ActivityHeatmap returns session counts grouped by day-of-week and hour.

func (*ClickHouseStore) Close

func (s *ClickHouseStore) Close() error

Close releases the ClickHouse connection.

func (*ClickHouseStore) DailyActivity

func (s *ClickHouseStore) DailyActivity(ctx context.Context, orgID string, projectName string, dateFrom, dateTo string) ([]DailyActivity, error)

DailyActivity returns per-day session and message counts.

func (*ClickHouseStore) EnsureSchema

func (s *ClickHouseStore) EnsureSchema(ctx context.Context) error

EnsureSchema creates the tables defined in the embedded DDL file. Statements are split on ";\n" and executed one by one. Lines starting with -- are stripped before execution.

func (*ClickHouseStore) GetSession

func (s *ClickHouseStore) GetSession(ctx context.Context, orgID string, id string) (*Session, error)

GetSession returns a single session by ID or an error containing "not found".

func (s *ClickHouseStore) GetSessionGitLinks(ctx context.Context, orgID string, sessionID string) ([]GitLink, error)

GetSessionGitLinks returns all git links for a session ordered by message_ordinal ASC.

func (*ClickHouseStore) GetSessionMessages

func (s *ClickHouseStore) GetSessionMessages(ctx context.Context, orgID string, sessionID string) ([]Message, error)

GetSessionMessages returns all messages for a session ordered by ordinal ASC.

func (*ClickHouseStore) GetSessionToolCalls

func (s *ClickHouseStore) GetSessionToolCalls(ctx context.Context, orgID string, sessionID string) ([]ToolCall, error)

GetSessionToolCalls returns all tool calls for a session ordered by message_ordinal ASC, tool_use_id ASC.

func (*ClickHouseStore) ListAgents

func (s *ClickHouseStore) ListAgents(ctx context.Context, orgID string) ([]string, error)

ListAgents returns distinct non-empty agent types from browsable sessions.

func (*ClickHouseStore) ListProjects

func (s *ClickHouseStore) ListProjects(ctx context.Context, orgID string) ([]ProjectInfo, error)

ListProjects returns distinct project info from browsable sessions with non-empty project_name. Groups by project_id+project_name to deduplicate across users who share a project but have different local paths.

func (*ClickHouseStore) ListSessions

func (s *ClickHouseStore) ListSessions(ctx context.Context, orgID string, filter SessionFilter) (*SessionPage, error)

ListSessions returns a cursor-paginated page of browsable sessions. The cursor encodes base64(started_at_rfc3339 + "|" + id).

func (*ClickHouseStore) ListUsers

func (s *ClickHouseStore) ListUsers(ctx context.Context, orgID string) ([]UserInfo, error)

ListUsers returns distinct user_id/user_name pairs from browsable sessions.

func (s *ClickHouseStore) LookupGitLinks(ctx context.Context, orgID string, sha string, prURL string) ([]GitLinkResult, error)

LookupGitLinks finds sessions by commit SHA prefix or PR URL.

func (*ClickHouseStore) ResetDatabase

func (s *ClickHouseStore) ResetDatabase(ctx context.Context) error

ResetDatabase drops and recreates the database, then re-creates the schema. ClickHouse allows cross-database DDL from any connection.

func (*ClickHouseStore) Search

func (s *ClickHouseStore) Search(ctx context.Context, orgID string, query SearchQuery) (*SearchPage, error)

Search performs case-insensitive substring search across messages and tool calls.

func (*ClickHouseStore) ToolUsageDistribution

func (s *ClickHouseStore) ToolUsageDistribution(ctx context.Context, orgID string, projectName string, dateFrom, dateTo string) ([]ToolUsageStat, error)

ToolUsageDistribution returns the top 20 tool name/category pairs by usage count.

func (*ClickHouseStore) UsageByUser

func (s *ClickHouseStore) UsageByUser(ctx context.Context, orgID string, projectName string, dateFrom, dateTo string) ([]UserUsage, error)

UsageByUser returns per-user/agent/project session, message, and commit counts.

func (*ClickHouseStore) WriteBatch

func (s *ClickHouseStore) WriteBatch(ctx context.Context, orgID string, sessions []Session, messages []Message, toolCalls []ToolCall) error

WriteBatch inserts multiple sessions with their messages and tool calls in combined batches — one PrepareBatch+Send per table.

func (s *ClickHouseStore) WriteGitLinks(ctx context.Context, orgID string, links []GitLink) error

WriteGitLinks inserts git link records into the git_links table.

func (*ClickHouseStore) WriteSession

func (s *ClickHouseStore) WriteSession(ctx context.Context, orgID string, session Session, messages []Message, toolCalls []ToolCall) error

WriteSession inserts or replaces a session row and appends new messages and tool calls. ReplacingMergeTree deduplicates by keeping the highest _version.

type ConnectOptions

type ConnectOptions struct {
	Addr     string
	Database string
	User     string
	Password string
	Secure   bool
}

ConnectOptions holds parameters for connecting to ClickHouse.

type DailyActivity

type DailyActivity struct {
	Date         string `json:"date"`
	SessionCount int    `json:"session_count"`
	MessageCount int    `json:"message_count"`
}
type GitLink struct {
	OrgID          string `json:"org_id"`
	SessionID      string `json:"session_id"`
	UserID         string `json:"user_id"`
	MessageOrdinal int    `json:"message_ordinal"`
	CommitSHA      string `json:"commit_sha"`
	PRURL          string `json:"pr_url"`
	LinkType       string `json:"link_type"`
	Confidence     string `json:"confidence"`
}

type GitLinkResult

type GitLinkResult struct {
	SessionID      string     `json:"session_id"`
	UserID         string     `json:"user_id"`
	UserName       string     `json:"user_name"`
	ProjectID      string     `json:"project_id"`
	ProjectName    string     `json:"project_name"`
	AgentType      string     `json:"agent_type"`
	StartedAt      *time.Time `json:"started_at"`
	FirstMessage   string     `json:"first_message"`
	CommitSHA      string     `json:"commit_sha"`
	PRURL          string     `json:"pr_url"`
	LinkType       string     `json:"link_type"`
	Confidence     string     `json:"confidence"`
	MessageOrdinal int        `json:"message_ordinal"`
}

type HeatmapCell

type HeatmapCell struct {
	DayOfWeek    int `json:"day_of_week"`
	Hour         int `json:"hour"`
	SessionCount int `json:"session_count"`
}

type Highlight

type Highlight struct {
	Start int `json:"start"`
	End   int `json:"end"`
}

type Message

type Message struct {
	OrgID         string     `json:"org_id"`
	SessionID     string     `json:"session_id"`
	Ordinal       int        `json:"ordinal"`
	Role          string     `json:"role"`
	Content       string     `json:"content"`
	Timestamp     *time.Time `json:"timestamp"`
	HasThinking   bool       `json:"has_thinking"`
	HasToolUse    bool       `json:"has_tool_use"`
	ContentLength int        `json:"content_length"`
}

type ProjectInfo

type ProjectInfo struct {
	ID   string `json:"id"`
	Name string `json:"name"`
	Path string `json:"path"`
}

type ReadStore

type ReadStore interface {
	ListSessions(ctx context.Context, orgID string, filter SessionFilter) (*SessionPage, error)
	GetSession(ctx context.Context, orgID string, id string) (*Session, error)
	GetSessionMessages(ctx context.Context, orgID string, sessionID string) ([]Message, error)
	GetSessionToolCalls(ctx context.Context, orgID string, sessionID string) ([]ToolCall, error)
	ListUsers(ctx context.Context, orgID string) ([]UserInfo, error)
	ListProjects(ctx context.Context, orgID string) ([]ProjectInfo, error)
	ListAgents(ctx context.Context, orgID string) ([]string, error)
	Search(ctx context.Context, orgID string, query SearchQuery) (*SearchPage, error)
	GetSessionGitLinks(ctx context.Context, orgID string, sessionID string) ([]GitLink, error)
	LookupGitLinks(ctx context.Context, orgID string, sha string, prURL string) ([]GitLinkResult, error)
	UsageByUser(ctx context.Context, orgID string, projectName string, dateFrom, dateTo string) ([]UserUsage, error)
	ActivityHeatmap(ctx context.Context, orgID string, projectName string, dateFrom, dateTo string) ([]HeatmapCell, error)
	ToolUsageDistribution(ctx context.Context, orgID string, projectName string, dateFrom, dateTo string) ([]ToolUsageStat, error)
	DailyActivity(ctx context.Context, orgID string, projectName string, dateFrom, dateTo string) ([]DailyActivity, error)
	Close() error
}

ReadStore handles read operations for agent session data.

type SearchPage

type SearchPage struct {
	Results []SearchResult `json:"results"`
	Total   int            `json:"total"`
}

type SearchQuery

type SearchQuery struct {
	Query       string
	UserID      string
	ProjectID   string
	ProjectName string
	AgentType   string
	DateFrom    string
	DateTo      string
	Limit       int
}

type SearchResult

type SearchResult struct {
	SessionID    string      `json:"session_id"`
	Ordinal      int         `json:"ordinal"`
	Role         string      `json:"role"`
	UserID       string      `json:"user_id"`
	UserName     string      `json:"user_name"`
	ProjectName  string      `json:"project_name"`
	AgentType    string      `json:"agent_type"`
	StartedAt    *time.Time  `json:"started_at"`
	FirstMessage string      `json:"first_message"`
	Snippet      string      `json:"snippet"`
	Highlights   []Highlight `json:"highlights"`
}

type Session

type Session struct {
	OrgID            string     `json:"org_id"`
	ID               string     `json:"id"`
	UserID           string     `json:"user_id"`
	UserName         string     `json:"user_name"`
	ProjectID        string     `json:"project_id"`
	ProjectName      string     `json:"project_name"`
	ProjectPath      string     `json:"project_path"`
	Machine          string     `json:"machine"`
	AgentType        string     `json:"agent_type"`
	FirstMessage     string     `json:"first_message"`
	StartedAt        *time.Time `json:"started_at"`
	EndedAt          *time.Time `json:"ended_at"`
	MessageCount     int        `json:"message_count"`
	UserMessageCount int        `json:"user_message_count"`
	ParentSessionID  string     `json:"parent_session_id"`
	RelationshipType string     `json:"relationship_type"`
	SourceCreatedAt  string     `json:"source_created_at"`
	CommitCount      int        `json:"commit_count"`
}

type SessionFilter

type SessionFilter struct {
	UserID           string
	ProjectID        string
	ProjectName      string
	AgentType        string
	DateFrom         string
	DateTo           string
	Cursor           string
	Limit            int
	IncludeSubagents bool
}

type SessionPage

type SessionPage struct {
	Sessions   []Session `json:"sessions"`
	NextCursor string    `json:"next_cursor"`
	Total      int64     `json:"total"`
}

type Store

type Store interface {
	EnsureSchema(ctx context.Context) error
	WriteSession(ctx context.Context, orgID string, session Session, messages []Message, toolCalls []ToolCall) error
	WriteBatch(ctx context.Context, orgID string, sessions []Session, messages []Message, toolCalls []ToolCall) error
	WriteGitLinks(ctx context.Context, orgID string, links []GitLink) error
	Close() error
}

Store handles write operations for agent session data.

type ToolCall

type ToolCall struct {
	OrgID               string `json:"org_id"`
	MessageOrdinal      int    `json:"message_ordinal"`
	SessionID           string `json:"session_id"`
	ToolName            string `json:"tool_name"`
	Category            string `json:"tool_category"`
	ToolUseID           string `json:"tool_use_id"`
	InputJSON           string `json:"input_json"`
	SkillName           string `json:"skill_name"`
	ResultContentLength *int   `json:"result_content_length"`
	ResultContent       string `json:"result_content"`
	SubagentSessionID   string `json:"subagent_session_id"`
}

type ToolUsageStat

type ToolUsageStat struct {
	ToolName   string `json:"tool_name"`
	Category   string `json:"category"`
	UsageCount int    `json:"usage_count"`
}

type UserInfo

type UserInfo struct {
	ID   string `json:"id"`
	Name string `json:"name"`
}

type UserUsage

type UserUsage struct {
	UserID       string `json:"user_id"`
	UserName     string `json:"user_name"`
	AgentType    string `json:"agent_type"`
	ProjectName  string `json:"project_name"`
	SessionCount int    `json:"session_count"`
	MessageCount int    `json:"message_count"`
	CommitCount  int    `json:"commit_count"`
}

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL