warehouse

type Column struct {
	Name string `json:"name"`
	Type string `json:"type"` // engine type name, e.g. STRING, INT64, DATE, int4, varchar
}

type Limits struct {
	// MaxRows is the maximum number of rows returned (values <= 0 mean 1).
	MaxRows int
	// MaxBytes caps the estimated size of the returned rows: their JSON
	// encoding plus a fixed per-value overhead for holding them in memory
	// (values <= 0 mean DefaultMaxResultBytes). Sources stop at the first
	// row that does not fit and never buffer a row much larger than what
	// is left, so one query cannot make the server hold an arbitrarily
	// large result.
	MaxBytes int
}

type QueryInfo struct {
	Name        string   `json:"name"`
	Description string   `json:"description,omitempty"`
	Params      []string `json:"params"`
	Source      string   `json:"source"`
}

type QueryRequest struct {
	SQL    string         `json:"sql,omitempty"`
	Query  string         `json:"query,omitempty"`  // named query
	Params any            `json:"params,omitempty"` // []any for sql, map[string]any for named
	Source string         `json:"source,omitempty"`
	Extra  map[string]any `json:"-"`
}

type Result struct {
	Columns   []Column         `json:"columns"`
	Rows      []map[string]any `json:"rows"`
	RowCount  int              `json:"row_count"`
	Truncated bool             `json:"truncated"`
}

type Service interface {
	Query(ctx context.Context, req QueryRequest) (*Result, error)
	Describe() (sources []SourceInfo, queries []QueryInfo)
	Enabled() bool
	Close() error
}

type Source interface {
	// Query runs sql with positional args and returns the rows that fit
	// within lim (Truncated=true if more were available).
	Query(ctx context.Context, sql string, args []any, lim Limits) (*Result, error)
	// Placeholder returns the engine's positional placeholder for argument i
	// (0-based): "$1" for postgres, "?" for bigquery/athena.
	Placeholder(i int) string
	// Close releases resources.
	Close() error
}

type SourceInfo struct {
	Name        string `json:"name"`
	Type        string `json:"type"`
	Description string `json:"description,omitempty"`
}