semantic

type AssertionResult struct {
	AssertionURN string `json:"assertion_urn,omitempty"` // URN identifying the assertion
	Type         string `json:"type"`                    // FRESHNESS, SCHEMA, DATA_QUALITY
}

type CacheConfig struct {
	TTL time.Duration
}

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

type CatalogPicker interface {
	// ListDomains returns every domain; the caller filters client-side.
	ListDomains(ctx context.Context) ([]EntityRef, error)
	// SearchGlossaryTerms name-searches glossary terms, bounded by limit. An
	// empty query lists: an implementation must substitute its backend's
	// match-everything query rather than forward the empty string, which a
	// relevance backend reads as "match nothing".
	SearchGlossaryTerms(ctx context.Context, query string, limit int) ([]EntityRef, error)
	// SearchDataProducts name-searches data products, bounded by limit, under
	// the same empty-query listing rule.
	SearchDataProducts(ctx context.Context, query string, limit int) ([]EntityRef, error)
}

type ColumnContext struct {
	// Basic info
	Name        string `json:"name"`
	Description string `json:"description,omitempty"`

	// Classification
	Tags          []string       `json:"tags,omitempty"`
	GlossaryTerms []GlossaryTerm `json:"glossary_terms,omitempty"`

	// Sensitivity
	IsPII       bool `json:"is_pii,omitempty"`
	IsSensitive bool `json:"is_sensitive,omitempty"`

	// Business metadata
	BusinessName string `json:"business_name,omitempty"`

	// InheritedFrom is set when metadata was inherited from upstream lineage.
	InheritedFrom *InheritedMetadata `json:"inherited_from,omitempty"`
}

type ColumnIdentifier struct {
	TableIdentifier
	Column string `json:"column"`
}

type DataContractStatus struct {
	Status           string            `json:"status"` // PASSING or FAILING
	AssertionResults []AssertionResult `json:"assertion_results,omitempty"`
}

type Deprecation struct {
	Deprecated bool       `json:"deprecated"`
	Note       string     `json:"note,omitempty"`
	Actor      string     `json:"actor,omitempty"`
	DecommDate *time.Time `json:"decommission_date,omitempty"`
}

type Domain struct {
	URN         string `json:"urn"`
	Name        string `json:"name"`
	Description string `json:"description,omitempty"`
}

type EntityRef struct {
	URN         string `json:"urn"`
	Name        string `json:"name"`
	Description string `json:"description,omitempty"`
}

type GlossaryMatchCounter interface {
	// SearchGlossaryTermsCounted runs the same search as
	// CatalogPicker.SearchGlossaryTerms, under the same empty-query listing rule,
	// and also reports the backend's total match count.
	SearchGlossaryTermsCounted(ctx context.Context, query string, limit int) (refs []EntityRef, total int, err error)
}

type GlossaryTerm struct {
	URN         string `json:"urn"`
	Name        string `json:"name"`
	Description string `json:"description,omitempty"`
	// ParentNode is the URN of the glossary node the term is filed under, empty
	// for a term at the glossary root.
	ParentNode string `json:"parent_node,omitempty"`
	// Owners are the term's stewards.
	Owners []Owner `json:"owners,omitempty"`
	// CustomProperties are the term's free-form key/value properties.
	CustomProperties map[string]string `json:"custom_properties,omitempty"`
}

type Incident struct {
	URN         string `json:"urn"`
	Type        string `json:"type"`
	Title       string `json:"title"`
	Description string `json:"description,omitempty"`
	State       string `json:"state"`
	Created     int64  `json:"created,omitempty"`
}

type InheritedMetadata struct {
	// SourceURN is the catalog reference of the upstream dataset.
	SourceURN string `json:"source_urn"`

	// SourceColumn is the column name in the upstream dataset.
	SourceColumn string `json:"source_column"`

	// Hops is the distance from the target dataset (1 = direct upstream).
	Hops int `json:"hops"`

	// MatchMethod indicates how the column was matched.
	// Values: "column_lineage", "name_exact", "name_transformed", "alias"
	MatchMethod string `json:"match_method"`
}

type LineageDirection string

type LineageEdge struct {
	URN            string `json:"urn"`
	Type           string `json:"type,omitempty"`
	TransformLogic string `json:"transform_logic,omitempty"`
}

type LineageEntity struct {
	URN      string        `json:"urn"`
	Type     string        `json:"type"`
	Name     string        `json:"name"`
	Platform string        `json:"platform,omitempty"`
	Depth    int           `json:"depth"`
	Parents  []LineageEdge `json:"parents,omitempty"`
	Children []LineageEdge `json:"children,omitempty"`
	Context  *TableContext `json:"context,omitempty"`
}

type LineageInfo struct {
	Direction LineageDirection `json:"direction"`
	Entities  []LineageEntity  `json:"entities"`
	MaxDepth  int              `json:"max_depth"`
}

type NoopProvider struct{}

type Owner struct {
	URN   string    `json:"urn"`
	Type  OwnerType `json:"type"`
	Name  string    `json:"name,omitempty"`
	Email string    `json:"email,omitempty"`
}

type OwnerType string

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

	// GetTableContext retrieves semantic context for a table.
	GetTableContext(ctx context.Context, table TableIdentifier) (*TableContext, error)

	// GetColumnContext retrieves semantic context for a single column.
	GetColumnContext(ctx context.Context, column ColumnIdentifier) (*ColumnContext, error)

	// GetColumnsContext retrieves semantic context for all columns of a table.
	GetColumnsContext(ctx context.Context, table TableIdentifier) (map[string]*ColumnContext, error)

	// GetLineage retrieves lineage information for a table.
	GetLineage(ctx context.Context, table TableIdentifier, direction LineageDirection, maxDepth int) (*LineageInfo, error)

	// GetGlossaryTerm retrieves a glossary term by URN.
	GetGlossaryTerm(ctx context.Context, urn string) (*GlossaryTerm, error)

	// SearchTables searches for tables matching the filter.
	SearchTables(ctx context.Context, filter SearchFilter) ([]TableSearchResult, error)

	// GetCuratedQueryCount returns the number of curated/saved queries for a dataset.
	GetCuratedQueryCount(ctx context.Context, urn string) (int, error)

	// Close releases resources.
	Close() error
}

type SanitizeConfig struct {
	// MaxLength is the maximum length for strings (default: 2000).
	MaxLength int

	// StripInjectionPatterns removes detected injection patterns instead of flagging.
	StripInjectionPatterns bool

	// LogInjectionAttempts enables logging of detected injection attempts.
	LogInjectionAttempts bool
}

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

type SearchFilter struct {
	Query    string   `json:"query"`
	Platform string   `json:"platform,omitempty"`
	Tags     []string `json:"tags,omitempty"`
	Domain   string   `json:"domain,omitempty"`
	Owner    string   `json:"owner,omitempty"`
	Limit    int      `json:"limit,omitempty"`
	Offset   int      `json:"offset,omitempty"`

	// Mode selects the search strategy: "keyword" (default) or "semantic".
	Mode string `json:"mode,omitempty"`
}

type StructuredProperty struct {
	QualifiedName string `json:"qualified_name"`
	DisplayName   string `json:"display_name,omitempty"`
	Values        []any  `json:"values"`
}

type TableContext struct {
	// Basic info
	URN         string `json:"urn,omitempty"`
	Description string `json:"description,omitempty"`

	// Ownership
	Owners []Owner `json:"owners,omitempty"`

	// Classification
	Tags          []string       `json:"tags,omitempty"`
	GlossaryTerms []GlossaryTerm `json:"glossary_terms,omitempty"`
	Domain        *Domain        `json:"domain,omitempty"`

	// TagRefs carries the same tags as Tags but as URN + display-name pairs, so a
	// governance editor can remove or dedupe a tag by its URN (Tags holds only the
	// display name, which is not the identifier a write needs). Populated on the
	// entity-detail read; enrichment reads Tags, not this field (#785).
	TagRefs []EntityRef `json:"tag_refs,omitempty"`

	// Status
	Deprecation *Deprecation `json:"deprecation,omitempty"`

	// Quality
	QualityScore *float64 `json:"quality_score,omitempty"`

	// Metadata
	CustomProperties map[string]string `json:"custom_properties,omitempty"`
	LastModified     *time.Time        `json:"last_modified,omitempty"`

	// Structured properties
	StructuredProperties []StructuredProperty `json:"structured_properties,omitempty"`

	// Incidents
	ActiveIncidents int        `json:"active_incidents,omitempty"`
	Incidents       []Incident `json:"incidents,omitempty"`

	// Data contracts
	DataContract *DataContractStatus `json:"data_contract,omitempty"`
}

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

type TableMatchCounter interface {
	// SearchTablesCounted runs the same search as Provider.SearchTables and also
	// reports the backend's total match count. The total may exceed len(results)
	// both because the caller's limit bounded the page and because the backend
	// bounded it further.
	SearchTablesCounted(ctx context.Context, filter SearchFilter) (results []TableSearchResult, total int, err error)
}

type TableSearchResult struct {
	URN          string   `json:"urn"`
	Name         string   `json:"name"`
	Platform     string   `json:"platform,omitempty"`
	Description  string   `json:"description,omitempty"`
	Tags         []string `json:"tags,omitempty"`
	Domain       string   `json:"domain,omitempty"`
	MatchedField string   `json:"matched_field,omitempty"`
}