query

type CatalogBrowser interface {
	// ListCatalogs returns the catalog names visible to the engine connection.
	ListCatalogs(ctx context.Context) ([]string, error)
	// ListSchemas returns the schema names in a catalog.
	ListSchemas(ctx context.Context, catalog string) ([]string, error)
	// ListTables returns the table names in a catalog schema.
	ListTables(ctx context.Context, catalog, schema string) ([]string, error)
}

type Column struct {
	Name     string `json:"name"`
	Type     string `json:"type"`
	Nullable bool   `json:"nullable"`
	Comment  string `json:"comment,omitempty"`
}

type Example struct {
	Description string `json:"description"`
	SQL         string `json:"sql"`
}

type ExecutionContext struct {
	Tables      []TableInfo `json:"tables"`
	Connections []string    `json:"connections"`
}

type Executor interface {
	// Execute runs a query and returns results.
	Execute(ctx context.Context, sql string, limit int) (*Result, error)

	// Describe returns information about a table.
	Describe(ctx context.Context, table TableIdentifier) (*TableSchema, error)
}

type LocationResolver interface {
	// ResolveLocation reports whether the entity is queryable and where, with
	// EstimatedRows always nil. Its contract is otherwise GetTableAvailability's:
	// an entity that cannot be resolved comes back Available=false with Error
	// set, not as an error.
	ResolveLocation(ctx context.Context, urn string) (*TableAvailability, error)
}

type NoopProvider struct{}

type Provider interface {
	// Name returns the provider name.
	Name() string

	// ResolveTable converts a URN to a query table identifier.
	ResolveTable(ctx context.Context, urn string) (*TableIdentifier, error)

	// GetTableAvailability checks if a table is queryable.
	GetTableAvailability(ctx context.Context, urn string) (*TableAvailability, error)

	// GetQueryExamples returns sample queries for a table.
	GetQueryExamples(ctx context.Context, urn string) ([]Example, error)

	// GetExecutionContext returns context for querying multiple tables.
	GetExecutionContext(ctx context.Context, urns []string) (*ExecutionContext, error)

	// GetTableSchema returns the schema of a table.
	GetTableSchema(ctx context.Context, table TableIdentifier) (*TableSchema, error)

	// Close releases resources.
	Close() error
}

type Result struct {
	Columns []string `json:"columns"`
	Rows    [][]any  `json:"rows"`
	Count   int      `json:"count"`
}

type TableAvailability struct {
	Available     bool   `json:"available"`
	QueryTable    string `json:"query_table,omitempty"`
	Connection    string `json:"connection,omitempty"`
	EstimatedRows *int64 `json:"estimated_rows,omitempty"`
	Error         string `json:"error,omitempty"`
}

type TableIdentifier struct {
	Catalog    string `json:"catalog,omitempty"`
	Schema     string `json:"schema"`
	Table      string `json:"table"`
	Connection string `json:"connection,omitempty"`
}

type TableInfo struct {
	URN           string `json:"urn"`
	QueryTable    string `json:"query_table"`
	Connection    string `json:"connection"`
	EstimatedRows *int64 `json:"estimated_rows,omitempty"`
}

type TableSchema struct {
	Columns    []Column `json:"columns"`
	PrimaryKey []string `json:"primary_key,omitempty"`
}

type Verifiable struct {
	URN        string `json:"urn" example:"urn:li:dataset:(urn:li:dataPlatform:trino,iceberg.retail.orders,PROD)"`
	QueryTable string `json:"query_table" example:"iceberg.retail.orders"`
	Connection string `json:"connection,omitempty" example:"primary"`
}