feat(api): add queryable suites table populated from summary.json during indexing (#129)

Add a `suites` table with suite_hash, discovery_path, name (from
metadata labels), tests_total, and indexed_at. The table is populated
via UpsertSuite during indexRun when summary.json is available, and is
queryable through the same PostgREST-style API as runs/test_stats. The
Query Builder UI includes a new "suites" tab with column groups.

Author: skylenet

pkg/api/handlers_index.go

@@ -199,6 +199,32 @@ func (s *server) handleQueryTestStats(
 	writeJSON(w, http.StatusOK, result)
 }
 
+// handleQuerySuites handles PostgREST-style queries against the suites
+// table.
+func (s *server) handleQuerySuites(
+	w http.ResponseWriter, r *http.Request,
+) {
+	params, err := indexstore.ParseQueryParams(
+		r.URL.Query(), indexstore.AllowedSuiteColumns(),
+	)
+	if err != nil {
+		writeJSON(w, http.StatusBadRequest,
+			errorResponse{err.Error()})
+
+		return
+	}
+
+	result, err := s.indexStore.QuerySuites(r.Context(), params)
+	if err != nil {
+		writeJSON(w, http.StatusInternalServerError,
+			errorResponse{"querying suites: " + err.Error()})
+
+		return
+	}
+
+	writeJSON(w, http.StatusOK, result)
+}
+
 // handleQueryTestStatsBlockLogs handles PostgREST-style queries against
 // the test_stats_block_logs table.
 func (s *server) handleQueryTestStatsBlockLogs(

pkg/api/indexer/indexer.go

@@ -10,6 +10,7 @@ import (
 
 	"github.com/ethpandaops/benchmarkoor/pkg/api/indexstore"
 	"github.com/ethpandaops/benchmarkoor/pkg/api/storage"
+	"github.com/ethpandaops/benchmarkoor/pkg/config"
 	"github.com/ethpandaops/benchmarkoor/pkg/executor"
 	"github.com/sirupsen/logrus"
 	"golang.org/x/sync/errgroup"
@@ -375,14 +376,16 @@ func (idx *indexer) indexRun(
 		return fmt.Errorf("building index entry: %w", err)
 	}
 
-	// Override tests_total from suite summary when available.
+	// Override tests_total from suite summary when available and
+	// upsert the suite record.
 	if entry.SuiteHash != "" {
 		summaryData, sErr := idx.reader.GetSuiteFile(
 			ctx, dp, entry.SuiteHash, "summary.json",
 		)
 		if sErr == nil && summaryData != nil {
 			var summary struct {
-				Tests json.RawMessage `json:"tests"`
+				Tests    json.RawMessage        `json:"tests"`
+				Metadata *config.MetadataConfig `json:"metadata"`
 			}
 
 			if json.Unmarshal(summaryData, &summary) == nil {
@@ -392,6 +395,28 @@ func (idx *indexer) indexRun(
 					len(tests) > 0 {
 					entry.Tests.TestsTotal = len(tests)
 				}
+
+				// Extract suite name from metadata labels.
+				suiteName := ""
+				if summary.Metadata != nil {
+					if n, ok := summary.Metadata.Labels["name"]; ok {
+						suiteName = n
+					}
+				}
+
+				suite := &indexstore.Suite{
+					SuiteHash:     entry.SuiteHash,
+					DiscoveryPath: dp,
+					Name:          suiteName,
+					TestsTotal:    entry.Tests.TestsTotal,
+					IndexedAt:     time.Now().UTC(),
+				}
+
+				if uErr := idx.store.UpsertSuite(ctx, suite); uErr != nil {
+					idx.log.WithError(uErr).
+						WithField("suite_hash", entry.SuiteHash).
+						Warn("Failed to upsert suite")
+				}
 			}
 		}
 	}

pkg/api/indexstore/indexstore.go

@@ -35,6 +35,8 @@ type Store interface {
 
 	ListAllRuns(ctx context.Context) ([]Run, error)
 
+	UpsertSuite(ctx context.Context, suite *Suite) error
+
 	BulkInsertTestStatsBlockLogs(
 		ctx context.Context, logs []*TestStatsBlockLog,
 	) error
@@ -47,6 +49,9 @@ type Store interface {
 	QueryTestStatsBlockLogs(
 		ctx context.Context, params *QueryParams,
 	) (*QueryResult, error)
+	QuerySuites(
+		ctx context.Context, params *QueryParams,
+	) (*QueryResult, error)
 }
 
 // Compile-time interface check.
@@ -122,6 +127,7 @@ func (s *store) Start(ctx context.Context) error {
 		&Run{},
 		&TestStat{},
 		&TestStatsBlockLog{},
+		&Suite{},
 	); err != nil {
 		return fmt.Errorf("running index migrations: %w", err)
 	}
@@ -338,6 +344,19 @@ func (s *store) DeleteTestStatsBlockLogsForRun(
 	return nil
 }
 
+// UpsertSuite inserts or updates a suite record keyed by suite_hash.
+func (s *store) UpsertSuite(ctx context.Context, suite *Suite) error {
+	result := s.db.WithContext(ctx).
+		Where("suite_hash = ?", suite.SuiteHash).
+		Assign(suite).
+		FirstOrCreate(suite)
+	if result.Error != nil {
+		return fmt.Errorf("upserting suite: %w", result.Error)
+	}
+
+	return nil
+}
+
 // QueryRuns executes a flexible query against the runs table using the
 // validated QueryParams. It returns paginated results with a total count.
 func (s *store) QueryRuns(
@@ -462,6 +481,45 @@ func (s *store) QueryTestStatsBlockLogs(
 	}, nil
 }
 
+// QuerySuites executes a flexible query against the suites table using
+// the validated QueryParams. It returns paginated results with a total
+// count.
+func (s *store) QuerySuites(
+	ctx context.Context, params *QueryParams,
+) (*QueryResult, error) {
+	q := applyQuery(s.db.WithContext(ctx), &Suite{}, params)
+
+	// When select is specified, scan into maps so the JSON response
+	// only contains the requested columns (no zero-valued extras).
+	if len(params.Select) > 0 {
+		return scanMaps(q, params)
+	}
+
+	var total int64
+	if err := q.Count(&total).Error; err != nil {
+		return nil, fmt.Errorf("counting suites: %w", err)
+	}
+
+	var suites []Suite
+	if err := q.Offset(params.Offset).
+		Limit(params.Limit).
+		Find(&suites).Error; err != nil {
+		return nil, fmt.Errorf("querying suites: %w", err)
+	}
+
+	data := make([]SuiteResponse, 0, len(suites))
+	for i := range suites {
+		data = append(data, toSuiteResponse(&suites[i]))
+	}
+
+	return &QueryResult{
+		Data:   data,
+		Total:  total,
+		Limit:  params.Limit,
+		Offset: params.Offset,
+	}, nil
+}
+
 // scanMaps scans query results into []map[string]any so only the selected
 // columns appear in the JSON response.
 func scanMaps(

pkg/api/indexstore/query.go

@@ -93,6 +93,17 @@ var allowedTestStatColumns = map[string]bool{
 	"test_resource_disk_write_iops":    true,
 }
 
+// allowedSuiteColumns lists columns that may be filtered, sorted, or selected
+// on the suites table.
+var allowedSuiteColumns = map[string]bool{
+	"id":             true,
+	"suite_hash":     true,
+	"discovery_path": true,
+	"name":           true,
+	"tests_total":    true,
+	"indexed_at":     true,
+}
+
 // allowedTestStatsBlockLogColumns lists columns that may be filtered, sorted,
 // or selected on the test_stats_block_logs table.
 var allowedTestStatsBlockLogColumns = map[string]bool{
@@ -276,6 +287,16 @@ type TestStatsBlockLogResponse struct {
 	CacheCodeMissBytes int     `json:"cache_code_miss_bytes"`
 }
 
+// SuiteResponse is the JSON DTO for a suites row.
+type SuiteResponse struct {
+	ID            uint   `json:"id"`
+	SuiteHash     string `json:"suite_hash"`
+	DiscoveryPath string `json:"discovery_path"`
+	Name          string `json:"name"`
+	TestsTotal    int    `json:"tests_total"`
+	IndexedAt     string `json:"indexed_at"`
+}
+
 // AllowedRunColumns returns the set of queryable run columns.
 func AllowedRunColumns() map[string]bool {
 	return allowedRunColumns
@@ -292,6 +313,11 @@ func AllowedTestStatsBlockLogColumns() map[string]bool {
 	return allowedTestStatsBlockLogColumns
 }
 
+// AllowedSuiteColumns returns the set of queryable suite columns.
+func AllowedSuiteColumns() map[string]bool {
+	return allowedSuiteColumns
+}
+
 // ParseQueryParams validates and parses raw URL query values against the
 // provided column whitelist. It returns an error for any invalid column,
 // operator, or parameter value.
@@ -611,3 +637,15 @@ func toTestStatsBlockLogResponse(l *TestStatsBlockLog) TestStatsBlockLogResponse
 		CacheCodeMissBytes:        l.CacheCodeMissBytes,
 	}
 }
+
+// toSuiteResponse converts a Suite model to its JSON DTO.
+func toSuiteResponse(s *Suite) SuiteResponse {
+	return SuiteResponse{
+		ID:            s.ID,
+		SuiteHash:     s.SuiteHash,
+		DiscoveryPath: s.DiscoveryPath,
+		Name:          s.Name,
+		TestsTotal:    s.TestsTotal,
+		IndexedAt:     s.IndexedAt.UTC().Format("2006-01-02T15:04:05Z"),
+	}
+}

pkg/api/indexstore/suite.go

@@ -0,0 +1,13 @@
+package indexstore
+
+import "time"
+
+// Suite represents a unique benchmark suite discovered during indexing.
+type Suite struct {
+	ID            uint   `gorm:"primaryKey"`
+	SuiteHash     string `gorm:"uniqueIndex;not null"`
+	DiscoveryPath string `gorm:"not null"`
+	Name          string
+	TestsTotal    int
+	IndexedAt     time.Time
+}

pkg/api/routes.go

@@ -90,6 +90,7 @@ func (s *server) buildRouter() http.Handler {
 						s.handleQueryTestStats)
 					r.Get("/test_stats_block_logs",
 						s.handleQueryTestStatsBlockLogs)
+					r.Get("/suites", s.handleQuerySuites)
 				})
 			})
 		}

ui/src/pages/QueryBuilderPage.tsx

@@ -43,6 +43,12 @@ const TEST_STAT_COLUMN_GROUPS: ColumnGroup[] = [
   { label: 'Timing', columns: ['run_start', 'run_end'] },
 ]
 
+const SUITES_COLUMN_GROUPS: ColumnGroup[] = [
+  { label: 'Identity', columns: ['id', 'suite_hash', 'discovery_path'] },
+  { label: 'Info', columns: ['name', 'tests_total'] },
+  { label: 'Timing', columns: ['indexed_at'] },
+]
+
 const TEST_STATS_BLOCK_LOG_COLUMN_GROUPS: ColumnGroup[] = [
   { label: 'Identity', columns: ['id', 'suite_hash', 'run_id', 'test_name', 'client'] },
   { label: 'Block', columns: ['block_number', 'block_hash', 'block_gas_used', 'block_tx_count'] },
@@ -76,6 +82,7 @@ const TEST_STATS_BLOCK_LOG_COLUMN_GROUPS: ColumnGroup[] = [
 const RUNS_COLUMNS = RUNS_COLUMN_GROUPS.flatMap((g) => g.columns)
 const TEST_STAT_COLUMNS = TEST_STAT_COLUMN_GROUPS.flatMap((g) => g.columns)
 const TEST_STATS_BLOCK_LOG_COLUMNS = TEST_STATS_BLOCK_LOG_COLUMN_GROUPS.flatMap((g) => g.columns)
+const SUITES_COLUMNS = SUITES_COLUMN_GROUPS.flatMap((g) => g.columns)
 
 const OPERATORS = [
   { value: 'eq', label: '= equals' },
@@ -97,7 +104,7 @@ const TIMESTAMP_COLUMNS = new Set([
 
 // --- Types ---
 
-type Endpoint = 'runs' | 'test_stats' | 'test_stats_block_logs'
+type Endpoint = 'runs' | 'test_stats' | 'test_stats_block_logs' | 'suites'
 
 interface FilterRow {
   id: string
@@ -172,6 +179,7 @@ function searchParamsToState(params: QuerySearchParams): QueryBuilderState | nul
   const endpoint: Endpoint =
     params.endpoint === 'test_stats' ? 'test_stats'
     : params.endpoint === 'test_stats_block_logs' ? 'test_stats_block_logs'
+    : params.endpoint === 'suites' ? 'suites'
     : 'runs'
   const validCols = new Set(columnsForEndpoint(endpoint))
 
@@ -244,12 +252,14 @@ function uid() {
 function columnsForEndpoint(ep: Endpoint) {
   if (ep === 'runs') return RUNS_COLUMNS
   if (ep === 'test_stats_block_logs') return TEST_STATS_BLOCK_LOG_COLUMNS
+  if (ep === 'suites') return SUITES_COLUMNS
   return TEST_STAT_COLUMNS
 }
 
 function columnGroupsForEndpoint(ep: Endpoint): ColumnGroup[] {
   if (ep === 'runs') return RUNS_COLUMN_GROUPS
   if (ep === 'test_stats_block_logs') return TEST_STATS_BLOCK_LOG_COLUMN_GROUPS
+  if (ep === 'suites') return SUITES_COLUMN_GROUPS
   return TEST_STAT_COLUMN_GROUPS
 }
 
@@ -620,6 +630,16 @@ export function QueryBuilderPage() {
           >
             test_stats_block_logs
           </button>
+          <button
+            onClick={() => dispatch({ type: 'SET_ENDPOINT', endpoint: 'suites' })}
+            className={`px-3 py-1.5 text-sm font-medium ${
+              state.endpoint === 'suites'
+                ? 'bg-blue-600 text-white'
+                : 'bg-white text-gray-700 hover:bg-gray-50 dark:bg-gray-800 dark:text-gray-300 dark:hover:bg-gray-700'
+            }`}
+          >
+            suites
+          </button>
         </div>
       </div>