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 ¶
- Variables
- type ClickHouseStore
- func (s *ClickHouseStore) ActivityHeatmap(ctx context.Context, orgID string, projectName string, dateFrom, dateTo string) ([]HeatmapCell, error)
- func (s *ClickHouseStore) Close() error
- func (s *ClickHouseStore) DailyActivity(ctx context.Context, orgID string, projectName string, dateFrom, dateTo string) ([]DailyActivity, error)
- func (s *ClickHouseStore) EnsureSchema(ctx context.Context) error
- func (s *ClickHouseStore) GetSession(ctx context.Context, orgID string, id string) (*Session, error)
- func (s *ClickHouseStore) GetSessionGitLinks(ctx context.Context, orgID string, sessionID string) ([]GitLink, error)
- func (s *ClickHouseStore) GetSessionMessages(ctx context.Context, orgID string, sessionID string) ([]Message, error)
- func (s *ClickHouseStore) GetSessionToolCalls(ctx context.Context, orgID string, sessionID string) ([]ToolCall, error)
- func (s *ClickHouseStore) ListAgents(ctx context.Context, orgID string) ([]string, error)
- func (s *ClickHouseStore) ListProjects(ctx context.Context, orgID string) ([]ProjectInfo, error)
- func (s *ClickHouseStore) ListSessions(ctx context.Context, orgID string, filter SessionFilter) (*SessionPage, error)
- func (s *ClickHouseStore) ListUsers(ctx context.Context, orgID string) ([]UserInfo, error)
- func (s *ClickHouseStore) LookupGitLinks(ctx context.Context, orgID string, sha string, prURL string) ([]GitLinkResult, error)
- func (s *ClickHouseStore) ResetDatabase(ctx context.Context) error
- func (s *ClickHouseStore) Search(ctx context.Context, orgID string, query SearchQuery) (*SearchPage, error)
- func (s *ClickHouseStore) ToolUsageDistribution(ctx context.Context, orgID string, projectName string, dateFrom, dateTo string) ([]ToolUsageStat, error)
- func (s *ClickHouseStore) UsageByUser(ctx context.Context, orgID string, projectName string, dateFrom, dateTo string) ([]UserUsage, error)
- func (s *ClickHouseStore) WriteBatch(ctx context.Context, orgID string, sessions []Session, messages []Message, ...) error
- func (s *ClickHouseStore) WriteGitLinks(ctx context.Context, orgID string, links []GitLink) error
- func (s *ClickHouseStore) WriteSession(ctx context.Context, orgID string, session Session, messages []Message, ...) error
- type ConnectOptions
- type DailyActivity
- type GitLink
- type GitLinkResult
- type HeatmapCell
- type Highlight
- type Message
- type ProjectInfo
- type ReadStore
- type SearchPage
- type SearchQuery
- type SearchResult
- type Session
- type SessionFilter
- type SessionPage
- type Store
- type ToolCall
- type ToolUsageStat
- type UserInfo
- type UserUsage
Constants ¶
This section is empty.
Variables ¶
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 (*ClickHouseStore) GetSessionGitLinks ¶ added in v0.2.2
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 ¶
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 ¶
ListUsers returns distinct user_id/user_name pairs from browsable sessions.
func (*ClickHouseStore) LookupGitLinks ¶
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 (*ClickHouseStore) WriteGitLinks ¶
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 ¶
ConnectOptions holds parameters for connecting to ClickHouse.
type DailyActivity ¶
type GitLink ¶
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 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 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 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 SessionPage ¶
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"`
}