clickhouse

package
v0.32.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 11, 2026 License: MIT Imports: 17 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	// DefaultSchemaRefreshInterval is the refresh interval for schema discovery.
	DefaultSchemaRefreshInterval = 15 * time.Minute

	// DefaultSchemaQueryTimeout is the timeout for individual schema queries.
	DefaultSchemaQueryTimeout = 60 * time.Second
)

Variables

View Source 
var ErrSchemaClusterNotConfigured = errors.New("clickhouse schema cluster is not configured")

ErrSchemaClusterNotConfigured is returned when a caller asks for a cluster that is neither cached nor known through datasource discovery.

Functions

func RegisterSchemaResources 

func RegisterSchemaResources(
	log logrus.FieldLogger,
	reg module.ResourceRegistry,
	client SchemaClient,
)

RegisterSchemaResources registers ClickHouse schema resources with the registry.

Types

type ClusterTables 

type ClusterTables struct {
	ClusterName string                  `json:"cluster_name"`
	Tables      map[string]*TableSchema `json:"tables"`
	LastUpdated time.Time               `json:"last_updated"`
}

ClusterTables holds tables for a ClickHouse cluster, keyed by "<database>.<name>".

type ClusterTablesSummary 

type ClusterTablesSummary struct {
	Databases     []*DatabaseSummary `json:"databases,omitempty"`
	Tables        []*TableSummary    `json:"tables,omitempty"`
	TableCount    int                `json:"table_count"`
	DatabaseCount int                `json:"database_count,omitempty"`
	LastUpdated   string             `json:"last_updated"`
}

ClusterTablesSummary is a compact summary of tables in a cluster.

type Config 

type Config struct {
	SchemaDiscovery SchemaDiscoveryConfig `yaml:"schema_discovery"`
}

Config holds the ClickHouse module configuration.

type DatabaseSummary added in v0.32.0 

type DatabaseSummary struct {
	Name       string `json:"name"`
	TableCount int    `json:"table_count"`
}

DatabaseSummary is a compact overview of a database/table namespace.

type Module 

type Module struct {
	// contains filtered or unexported fields
}

Module implements the module.Module interface for ClickHouse.

func New 

func New() *Module

New creates a new ClickHouse module.

func (*Module) ApplyDefaults 

func (m *Module) ApplyDefaults()

ApplyDefaults sets default values before validation.

func (*Module) DatasourceInfo 

func (m *Module) DatasourceInfo() []types.DatasourceInfo

DatasourceInfo returns datasource metadata for datasources:// resources.

func (*Module) Init 

func (m *Module) Init(rawConfig []byte) error

Init parses the raw YAML config for this module.

func (*Module) InitFromDiscovery 

func (m *Module) InitFromDiscovery(datasources []types.DatasourceInfo) error

InitFromDiscovery initializes the module from discovered datasources. Safe to call repeatedly: subsequent calls replace the datasource list in place so the proxy client's periodic refresh propagates without a restart.

Always writes the filtered list, including when empty. ErrNoValidConfig is purely a hint to the registry ("don't activate me at initial init") — an already-running module whose datasources have all disappeared still gets its list cleared, so panda datasources, sandbox env, and schema discovery stop reporting stale entries.

func (*Module) Name 

func (m *Module) Name() string

func (*Module) OnDiscoveryReloaded added in v0.24.0 

func (m *Module) OnDiscoveryReloaded(_ context.Context) error

OnDiscoveryReloaded pushes the refreshed datasource list into the running schema discovery client so newly added ClickHouse clusters get their schemas fetched without a server restart. Skipped when YAML schema_discovery.datasources is configured (those are authoritative) or when schema discovery is disabled.

func (*Module) PythonAPIDocs 

func (m *Module) PythonAPIDocs() map[string]types.ModuleDoc

PythonAPIDocs returns the ClickHouse module documentation. It describes the generic transport only; dataset-specific guidance (table syntax, conventions) lives in the dataset knowledge packs surfaced via search and datasets://{name}.

func (*Module) RegisterResources 

func (m *Module) RegisterResources(log logrus.FieldLogger, reg module.ResourceRegistry) error

RegisterResources registers ClickHouse schema resources.

func (*Module) SandboxEnv 

func (m *Module) SandboxEnv() (map[string]string, error)

SandboxEnv returns environment variables for the sandbox.

func (*Module) SetProxyClient 

func (m *Module) SetProxyClient(client proxy.Service)

SetProxyClient injects the proxy service for schema discovery.

func (*Module) Start 

func (m *Module) Start(ctx context.Context) error

Start performs async initialization (schema discovery).

func (*Module) Stop 

func (m *Module) Stop(_ context.Context) error

Stop cleans up resources.

func (*Module) Validate 

func (m *Module) Validate() error

Validate checks that the parsed config is valid.

type QueryErrorClass added in v0.32.0 

type QueryErrorClass int

QueryErrorClass identifies a recognizable class of ClickHouse query failure. Classification is integration knowledge and lives here; consumers (CLI, MCP surfaces) own the wording of any guidance they attach to a class. The sandbox Python library keeps a mirrored matcher in python/clickhouse.py (it cannot call into Go) — keep the two in sync when classes change. 

const (
	// QueryErrorUnknown is any error this module does not recognize.
	QueryErrorUnknown QueryErrorClass = iota
	// QueryErrorPrimaryKeyFilterRequired: the cluster enforces
	// force_primary_key / index-usage and the query had no selective filter.
	QueryErrorPrimaryKeyFilterRequired
	// QueryErrorUnknownIdentifier: the SQL references a column or expression
	// the selected table does not have.
	QueryErrorUnknownIdentifier
	// QueryErrorNotAggregate: a selected expression is neither aggregated nor
	// in GROUP BY.
	QueryErrorNotAggregate
	// QueryErrorSyntax: ClickHouse rejected the SQL syntax.
	QueryErrorSyntax
	// QueryErrorDatasourceNotFound: the referenced ClickHouse datasource does
	// not exist.
	QueryErrorDatasourceNotFound
	// QueryErrorDistributedJoinDenied: ClickHouse rejected a distributed
	// subquery or join under the datasource's distributed_product_mode.
	QueryErrorDistributedJoinDenied
	// QueryErrorUnknownTable: the SQL references a table or database that is
	// not available in the selected datasource.
	QueryErrorUnknownTable
	// QueryErrorUnknownFunction: the SQL uses a function unavailable in the
	// selected ClickHouse deployment/version.
	QueryErrorUnknownFunction
	// QueryErrorBadFunctionArguments: the SQL calls a function with an
	// incompatible column type or argument shape.
	QueryErrorBadFunctionArguments
	// QueryErrorIllegalAggregation: the SQL nests aggregate functions or uses
	// aggregate outputs in a way ClickHouse rejects.
	QueryErrorIllegalAggregation
	// QueryErrorAliasRequired: the SQL uses a subquery/table expression in a
	// join context where ClickHouse requires an explicit alias.
	QueryErrorAliasRequired
)

func ClassifyQueryError added in v0.32.0 

func ClassifyQueryError(message string) QueryErrorClass

ClassifyQueryError maps an upstream error message to a QueryErrorClass.

type SchemaClient added in v0.30.0 

type SchemaClient interface {
	Start(ctx context.Context) error
	Stop() error
	GetAllTables() map[string]*ClusterTables
	GetClusterTables(clusterName string) (*ClusterTables, bool)
	GetTableInCluster(clusterName, database, tableName string) (*TableSchema, bool)
	FetchTablesInCluster(ctx context.Context, clusterName, database string) (*ClusterTables, error)
	FetchTableInCluster(ctx context.Context, clusterName, database, tableName string) (*TableSchema, error)
	UpdateDatasources(datasources []SchemaDiscoveryDatasource)
}

SchemaClient fetches and caches ClickHouse schema information.

func NewSchemaClient added in v0.30.0 

func NewSchemaClient(
	log logrus.FieldLogger,
	cfg SchemaConfig,
	proxySvc proxy.Service,
) SchemaClient

NewSchemaClient creates a new schema discovery client.

type SchemaConfig added in v0.30.0 

type SchemaConfig struct {
	RefreshInterval time.Duration
	QueryTimeout    time.Duration
	Datasources     []SchemaDiscoveryDatasource
}

SchemaConfig holds configuration for schema discovery.

type SchemaDiscoveryConfig 

type SchemaDiscoveryConfig struct {
	// Enabled controls whether schema discovery is active. Defaults to true if datasources are configured.
	Enabled *bool `yaml:"enabled,omitempty"`

	// RefreshInterval is the duration between schema refresh cycles. Defaults to 15 minutes.
	RefreshInterval time.Duration `yaml:"refresh_interval,omitempty"`

	// Datasources lists the ClickHouse datasources to discover schemas from.
	// Each entry references a proxy-exposed datasource by name.
	// If empty, all proxy datasources are used.
	Datasources []SchemaDiscoveryDatasource `yaml:"datasources"`
}

SchemaDiscoveryConfig holds configuration for ClickHouse schema discovery.

func (*SchemaDiscoveryConfig) IsEnabled 

func (c *SchemaDiscoveryConfig) IsEnabled() bool

IsEnabled returns whether schema discovery is enabled. Defaults to true; set enabled=false to disable explicitly.

type SchemaDiscoveryDatasource 

type SchemaDiscoveryDatasource struct {
	// Name references a ClickHouse datasource by its proxy name.
	Name string `yaml:"name"`

	// Cluster is the logical cluster name used in schema resources.
	// Defaults to Name when empty.
	Cluster string `yaml:"cluster"`
}

SchemaDiscoveryDatasource maps a proxy datasource name to a logical cluster name for schema discovery.

type TableColumn 

type TableColumn struct {
	Name         string `json:"name"`
	Type         string `json:"type"`
	Comment      string `json:"comment,omitempty"`
	DefaultType  string `json:"default_type,omitempty"`
	DefaultValue string `json:"default_value,omitempty"`
}

TableColumn represents a column in a ClickHouse table.

type TableDetailResponse 

type TableDetailResponse struct {
	Cluster string       `json:"cluster"`
	Table   *TableSchema `json:"table"`
}

TableDetailResponse is the response for clickhouse://tables/{cluster}/{database}/{table_name}.

type TableSchema 

type TableSchema struct {
	Database        string        `json:"database"`
	Name            string        `json:"name"`
	Engine          string        `json:"engine,omitempty"`
	PartitionBy     string        `json:"partition_by,omitempty"`
	OrderBy         string        `json:"order_by,omitempty"`
	PrimaryKey      string        `json:"primary_key,omitempty"`
	Columns         []TableColumn `json:"columns"`
	CreateStatement string        `json:"create_statement,omitempty"`
	Comment         string        `json:"comment,omitempty"`
}

TableSchema is the full schema of a ClickHouse table identified by (Database, Name).

type TableSummary 

type TableSummary struct {
	Database    string `json:"database"`
	Name        string `json:"name"`
	ColumnCount int    `json:"column_count"`
}

TableSummary is a compact overview of a table for the list view.

type TablesListResponse 

type TablesListResponse struct {
	Description string                           `json:"description"`
	Clusters    map[string]*ClusterTablesSummary `json:"clusters"`
	Usage       string                           `json:"usage"`
}

TablesListResponse is the response for the table listing resources (clickhouse://tables/{cluster} and .../{cluster}/{database}).

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.