querylogs

type DwhContext struct {
	// Instance is the unique identifier for the data warehouse instance.
	// This is typically the hostname, account ID, or workspace URL that uniquely
	// identifies the data warehouse deployment.
	// - Set by: Snowflake (account), Databricks (workspace_url), Redshift/Postgres/Trino (host), DuckDB (motherduck_account)
	// - Empty for: BigQuery, ClickHouse, MySQL
	Instance string

	// Database name (may be empty for platforms without database level)
	// - Snowflake: database_name
	// - Databricks: catalog_name
	// - BigQuery: project_id
	// - Redshift/Postgres: database_name
	// - Trino: catalog
	// - MySQL: host (used as instance identifier)
	// - ClickHouse: hostname or configured database alias from config (used as instance identifier, NOT the schema-level database)
	// - DuckDB: "" (empty)
	Database string

	// Schema name (may be empty for platforms without schema concept)
	// - Snowflake/Databricks/Redshift/Postgres/MySQL: schema_name
	// - BigQuery: dataset_id
	// - Trino: schema
	// - ClickHouse: database_name (2-level hierarchy)
	// - DuckDB: schema_name
	Schema string

	// Warehouse identifier (available in Snowflake, Databricks)
	Warehouse string

	// User who executed the query
	User string

	// Role used to execute the query (available in Snowflake, Postgres, etc.)
	Role string

	// Cluster identifier or hostname (for platforms that use cluster concept)
	// Redshift: cluster hostname
	// ClickHouse: cluster name (if applicable)
	Cluster string
}

type NativeLineage struct {
	// InputTables are the tables read by the query
	InputTables []scrapper.DwhFqn

	// OutputTables are the tables written by the query
	OutputTables []scrapper.DwhFqn
}

type ObfuscationMode int

type ObfuscatorOption func(*obfuscatorConfig)

type QueryLog struct {
	// CreatedAt is the timestamp when the query log was recorded (when query finished and results committed).
	// This is the time when query results became available for other queries to use.
	// Should be set to FinishedAt/EndTime across all platforms for consistency.
	CreatedAt time.Time

	// StartedAt is when query execution started (optional, nil if unknown).
	// Platform scrappers should set this to the actual query start time.
	// Duration is computed as FinishedAt - StartedAt.
	StartedAt *time.Time

	// FinishedAt is when query execution finished and results were committed (optional, nil if unknown).
	// Platform scrappers should set this to the actual query end time.
	// Duration is computed as FinishedAt - StartedAt.
	FinishedAt *time.Time

	// QueryID is the native query identifier or computed hash
	QueryID string

	// SQL is the query text (may be obfuscated based on SqlObfuscationMode)
	SQL string

	// NormalizedQueryHash is a hash of the normalized/parameterized query (without literal values)
	// Used for lineage caching - queries that differ only in literal values share the same lineage
	// Available for: Snowflake (QUERY_PARAMETERIZED_HASH), ClickHouse (cityHash64(normalizeQuery))
	// For platforms without native support, this field is nil
	NormalizedQueryHash *string

	// SqlDialect is the SQL dialect from Scrapper.DialectType() (snowflake, bigquery, databricks, etc.)
	SqlDialect string

	// DwhContext contains structured context information (database, schema, warehouse, user, role, etc.)
	DwhContext *DwhContext

	// QueryType is the platform-specific query type (e.g., "CREATE_TABLE_AS_SELECT", "SELECT", "INSERT")
	QueryType string

	// Status represents the query execution status ("SUCCESS", "FAILED", "CANCELED", etc.)
	Status string

	// Metadata contains platform-specific fields that don't fit into the standard structure
	Metadata map[string]interface{}

	// SqlObfuscationMode indicates how the SQL was obfuscated (if at all)
	SqlObfuscationMode ObfuscationMode

	// HasCompleteNativeLineage indicates that NativeLineage contains complete lineage information
	// and SQL parsing can be skipped entirely. When true, the backend should trust the native
	// lineage and avoid expensive SQL parsing.
	HasCompleteNativeLineage bool

	// IsTruncated indicates whether the SQL text was truncated by the data warehouse.
	// When true, the SQL field contains incomplete query text and should not be parsed.
	// This is common in systems that limit query text length in their system tables.
	IsTruncated bool

	// NativeLineage contains table lineage information when provided natively by the platform
	// (e.g., BigQuery, ClickHouse). For other platforms, this will be nil and SQL parsing is required.
	NativeLineage *NativeLineage
}

type QueryLogIterator interface {
	// Next returns the next query log from the iterator.
	//
	// Returns:
	//   - The next QueryLog and nil error on success
	//   - nil and io.EOF when no more logs are available
	//   - nil and an error if fetching fails
	//
	// Implementation notes:
	//   - Should fetch from warehouse in optimal batch sizes internally
	//   - Should buffer results to minimize warehouse connection time
	//   - Must respect context cancellation
	//   - MUST auto-close all resources before returning io.EOF (defensive programming)
	//   - Safe to call multiple times after io.EOF
	Next(ctx context.Context) (*QueryLog, error)

	// Close releases any resources held by the iterator.
	// Should be called when iteration is complete or abandoned, but implementations
	// MUST also auto-close when Next() returns io.EOF to prevent resource leaks.
	// Safe to call multiple times.
	Close() error
}

type QueryLogsProvider interface {
	// FetchQueryLogs returns an iterator for query logs within the specified time range.
	//
	// Parameters:
	//   - ctx: Context for cancellation and deadlines
	//   - from: Start of the time range (inclusive)
	//   - to: End of the time range (exclusive)
	//   - obfuscator: Controls SQL obfuscation mode and provides helper function
	//
	// Returns:
	//   - An iterator for sequential access to query logs
	//   - The caller is responsible for calling Close() on the iterator
	//
	// Implementation notes:
	//   - Iterator should fetch from warehouse as fast as possible
	//   - Platform-specific optimizations (batch sizes, parallel fetching) should happen inside the iterator
	//   - Query logs should be ordered by CreatedAt timestamp when possible
	//   - Context cancellation should be respected throughout iteration
	//   - Platforms should handle obfuscation optimally:
	//       * Use native SQL functions when available (e.g., ClickHouse normalizeQuery())
	//       * Use obfuscator.Obfuscate() helper for post-processing when native isn't available
	//       * Skip obfuscation entirely if obfuscator.Mode() == ObfuscationNone
	//
	// Example usage:
	//   obfuscator := querylogs.NewLiteralsObfuscator()
	//   iter, err := provider.FetchQueryLogs(ctx, from, to, obfuscator)
	//   if err != nil {
	//       return err
	//   }
	//   defer iter.Close()
	//
	//   for {
	//       log, err := iter.Next(ctx)
	//       if err == io.EOF {
	//           break
	//       }
	//       if err != nil {
	//           return err
	//       }
	//       // Process log...
	//   }
	FetchQueryLogs(ctx context.Context, from, to time.Time, obfuscator QueryObfuscator) (QueryLogIterator, error)
}

type QueryObfuscator interface {
	// Mode returns the obfuscation mode configured for this obfuscator.
	// Platforms with native obfuscation support should check this to decide
	// whether to use native SQL functions (e.g., normalizeQuery() in ClickHouse).
	Mode() ObfuscationMode

	// Obfuscate processes SQL text and returns obfuscated version based on Mode().
	// If Mode() is ObfuscationNone, returns SQL unchanged.
	// Otherwise applies configured obfuscation (literals, bind parameters, etc.)
	Obfuscate(sql string) string
}

type SqlxRowsIterator[T any] struct {
	// contains filtered or unexported fields
}