Documentation
¶
Index ¶
- func BoolPtr(v bool) *bool
- func Int64Ptr(v int64) *int64
- func IsQueryStatsFetch(ctx context.Context) bool
- func WithCallback(ctx context.Context, cb Callback) context.Context
- func WithDriverStats(ctx context.Context, ds *DriverStats) context.Context
- func WithQueryStatsFetch(ctx context.Context) context.Context
- type Callback
- type Collector
- type DriverStats
- type QueryStats
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func IsQueryStatsFetch ¶
IsQueryStatsFetch reports whether the context has the query-stats-fetch flag set.
func WithCallback ¶
WithCallback attaches a stats callback to the context. When a query is executed with this context, the callback will be invoked with whatever statistics the driver is able to collect.
func WithDriverStats ¶
func WithDriverStats(ctx context.Context, ds *DriverStats) context.Context
WithDriverStats attaches a DriverStats accumulator to the context. Database executors should call GetDriverStats to retrieve and populate it.
func WithQueryStatsFetch ¶
WithQueryStatsFetch marks the context so that drivers which require extra API calls to fetch detailed stats (e.g. Snowflake's GetQueryStatus) will do so. Without this flag, those drivers only collect cheap metrics like the query ID.
Types ¶
type Callback ¶
type Callback func(QueryStats)
Callback is the function type invoked with query execution statistics. It is called once, right before the query function returns, even on error.
type Collector ¶
type Collector struct {
Stats QueryStats
// contains filtered or unexported fields
}
Collector accumulates query statistics and invokes the callback on Finish. Use Start() to create a Collector; call Finish() (typically via defer) to invoke the callback.
func Start ¶
Start creates a Collector if a callback is present in the context. Returns nil and the original context if no callback is registered. It reuses an existing DriverStats from context (e.g., set by a driver-specific enrichment layer), or creates a new one if needed.
func (*Collector) Finish ¶
func (c *Collector) Finish()
Finish merges driver-specific stats, sets the duration, and invokes the callback. Safe to call on nil Collector.
func (*Collector) SetQueryID ¶
SetQueryID sets the database-assigned query identifier. Safe to call on nil Collector.
func (*Collector) SetRowsProduced ¶
SetRowsProduced sets the number of rows produced. Safe to call on nil Collector.
type DriverStats ¶
type DriverStats struct {
// contains filtered or unexported fields
}
DriverStats is a thread-safe accumulator for driver-specific stats. Database executors populate this via ClickHouse callbacks, BigQuery job stats, etc. The Collector merges these into the final QueryStats on Finish().
func GetDriverStats ¶
func GetDriverStats(ctx context.Context) *DriverStats
GetDriverStats retrieves the DriverStats accumulator from the context, if any. Returns nil if no DriverStats is present.
func GetOrCreateDriverStats ¶
func GetOrCreateDriverStats(ctx context.Context) (*DriverStats, context.Context)
GetOrCreateDriverStats retrieves an existing DriverStats from the context, or creates a new one if a stats callback is present but no DriverStats exists yet. Returns the DriverStats and a potentially updated context. Returns nil and the original context if no stats callback is registered.
func (*DriverStats) AddOnFinish ¶
func (d *DriverStats) AddOnFinish(fn func())
AddOnFinish registers a function to be called when the Collector finishes, right before merging DriverStats into the final QueryStats. This is useful for drivers that need to collect stats after the query completes (e.g. Snowflake query ID from a channel).
func (*DriverStats) Get ¶
func (d *DriverStats) Get() QueryStats
Get returns a copy of the accumulated driver stats.
func (*DriverStats) Set ¶
func (d *DriverStats) Set(s QueryStats)
Set replaces the accumulated driver stats with a merge.
type QueryStats ¶
type QueryStats struct {
// QueryID is the database-assigned query identifier for auditing.
// Available for BigQuery (job ID), Snowflake, ClickHouse (client-generated).
QueryID string `json:"query_id,omitempty"`
// RowsRead is the number of rows read/scanned by the query engine.
RowsRead *int64 `json:"rows_read,omitempty"`
// BytesRead is the number of bytes read/scanned by the query engine.
BytesRead *int64 `json:"bytes_read,omitempty"`
// RowsProduced is the number of result rows returned to the caller.
RowsProduced *int64 `json:"rows_produced,omitempty"`
// CacheHit indicates whether the query result was served from cache.
CacheHit *bool `json:"cache_hit,omitempty"`
// BytesBilled is the number of bytes billed (BigQuery).
BytesBilled *int64 `json:"bytes_billed,omitempty"`
// SlotMillis is the slot time consumed (BigQuery).
SlotMillis *int64 `json:"slot_millis,omitempty"`
// Blocks is the number of data blocks read (ClickHouse).
Blocks *int64 `json:"blocks,omitempty"`
// CompletedSplits is the number of completed splits (Trino).
CompletedSplits *int64 `json:"completed_splits,omitempty"`
// CPUTimeMillis is the CPU time consumed (Trino).
CPUTimeMillis *int64 `json:"cpu_time_millis,omitempty"`
// WallTimeMillis is the wall time reported by the engine (Trino).
WallTimeMillis *int64 `json:"wall_time_millis,omitempty"`
// Duration is the wall-clock time of the query as measured by the client.
// This field is always set.
Duration time.Duration `json:"duration"`
}
QueryStats holds execution statistics collected from the database driver. Fields are pointers — nil means the metric is not available for the driver.
func (*QueryStats) Merge ¶
func (s *QueryStats) Merge(other QueryStats)
Merge copies non-nil/non-zero fields from other into s, overwriting existing values.
Source Files