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 DataHub 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)
}

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 DataProduct struct {
	URN         string `json:"urn"`
	Name        string `json:"name"`
	Description string `json:"description,omitempty"`
	// Domain is the domain the product is filed under, nil when it has none.
	Domain *Domain `json:"domain,omitempty"`
	// Owners are the product's owners.
	Owners []Owner `json:"owners,omitempty"`
	// Assets are the datasets that make up the product.
	Assets []EntityRef `json:"assets,omitempty"`
	// CustomProperties are the product's free-form key/value properties.
	CustomProperties map[string]string `json:"custom_properties,omitempty"`
}

type DataProductReader interface {
	// GetDataProduct reads one data product by URN. A URN the catalog has no
	// product for is an error, as the other by-URN reads report one.
	GetDataProduct(ctx context.Context, urn string) (*DataProduct, error)
}

type Dataset struct {
	TableContext

	// Name is the catalog's display name for the dataset.
	Name string `json:"name,omitempty"`
	// Type is the catalog entity type ("DATASET").
	Type string `json:"type,omitempty"`
	// Platform is the data platform the dataset belongs to (the URN's
	// dataPlatform segment, e.g. "trino").
	Platform string `json:"platform,omitempty"`
	// SubTypes are the catalog's sub-type classifications ("table", "view").
	SubTypes []string `json:"sub_types,omitempty"`
	// Created is when the catalog first recorded the dataset.
	Created *time.Time `json:"created,omitempty"`
	// Schema is the declared schema, nil when the catalog holds none.
	Schema *DatasetSchema `json:"schema,omitempty"`
	// Queries are the saved queries the catalog holds against the dataset, and
	// TotalQueries is the catalog's own count of them (the list may be a page).
	Queries      []SavedQuery `json:"queries,omitempty"`
	TotalQueries int          `json:"total_queries,omitempty"`
	// RelatedDocuments are the context documents linked to the dataset.
	RelatedDocuments []DocumentResult `json:"related_documents,omitempty"`
	// Unavailable names the parts of the record the catalog could not serve on
	// this read ("schema", "queries", "related_documents"), so an absent part is
	// distinguishable from an empty one. The entity itself always resolved.
	Unavailable []string `json:"unavailable,omitempty"`
}

type DatasetReader interface {
	// GetDataset reads the dataset the table identifier names. A table the
	// catalog has no entry for is an error, as GetTableContext reports one.
	GetDataset(ctx context.Context, table TableIdentifier) (*Dataset, error)
}

type DatasetSchema struct {
	// Version is the catalog's schema version.
	Version int64 `json:"version,omitempty"`
	// Fields are the declared fields in declaration order.
	Fields []SchemaField `json:"fields"`
	// PrimaryKeys lists the primary key field paths.
	PrimaryKeys []string `json:"primary_keys,omitempty"`
	// ForeignKeys lists the declared foreign key relationships.
	ForeignKeys []ForeignKey `json:"foreign_keys,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 DocumentResult struct {
	URN     string `json:"urn"`
	Title   string `json:"title"`
	SubType string `json:"sub_type,omitempty"`
	Snippet string `json:"snippet,omitempty"`
	// Body is the full, untruncated document content. It is populated only by a
	// single-document read (GetDocument), where the whole point is to return the
	// complete content a search snippet elides; the relevance-search paths
	// (SearchDocuments, GetRelatedDocuments) leave it empty and populate the
	// bounded Snippet instead, so a multi-result search does not carry N full
	// bodies.
	Body string `json:"body,omitempty"`
	// Status is the publication state (PUBLISHED/UNPUBLISHED). The upstream search
	// applies no status filter, so a consumer carries this to exclude drafts.
	Status string `json:"status,omitempty"`
	// ShowInGlobalContext reports whether the document is meant to appear in global
	// search. The upstream search returns documents regardless of this flag, so a
	// search consumer must filter on it to honor a steward's choice to hide a document.
	ShowInGlobalContext bool     `json:"show_in_global_context"`
	RelatedAssetURNs    []string `json:"related_asset_urns,omitempty"`
}

type DocumentSearcher interface {
	// SearchDocuments ranks context documents by relevance to query; a query of "*"
	// lists all (an empty query does not list). Results carry ShowInGlobalContext and
	// Status so the caller can filter to globally-visible, published documents. limit
	// caps results (0 means the provider default).
	SearchDocuments(ctx context.Context, query string, limit int) ([]DocumentResult, error)

	// GetRelatedDocuments returns the context documents linked to an entity URN (the
	// reverse of a document's related assets), for entity-keyed discovery. Results
	// carry the same fields as SearchDocuments so the caller applies the same filter.
	GetRelatedDocuments(ctx context.Context, urn string) ([]DocumentResult, error)

	// GetDocument reads one context document by its URN, returning the full
	// untruncated body (in DocumentResult.Body) so an agent can dereference a
	// urn:li:document:<id> reference search emitted to the complete content. A URN
	// that resolves to no document returns ErrDocumentNotFound, which the fetch
	// surface maps to a structured not-found rather than an error.
	GetDocument(ctx context.Context, urn string) (*DocumentResult, error)

	// BrowseDocuments enumerates context documents for the browse surface (#695):
	// the offset/limit page of the complete document set plus the total document
	// count, so an agent can page the whole corpus to audit, dedup, or migrate it.
	// Unlike SearchDocuments this applies NO relevance threshold and NO
	// visibility/status filter: every document is enumerable (drafts and hidden
	// documents included), so the returned page and total describe the same complete
	// set. Results carry the same fields as SearchDocuments (a bounded Snippet, not
	// the full Body) since a listing shows what each document is, not its contents.
	BrowseDocuments(ctx context.Context, offset, limit int) (docs []DocumentResult, total int, err error)
}

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 FieldFilter struct {
	// Field is the filter field (e.g., "fieldPaths", "fieldTags", "platform", "owners").
	Field string `json:"field"`

	// Values to match against.
	Values []string `json:"values"`

	// Condition is the match operator: CONTAIN, EQUAL (default), IN, EXISTS.
	Condition string `json:"condition,omitempty"`

	// Negated inverts the filter (exclude matching entities).
	Negated bool `json:"negated,omitempty"`
}

type ForeignKey struct {
	// Name is the constraint name, when the catalog holds one.
	Name string `json:"name,omitempty"`
	// SourceFields are the field paths on this dataset.
	SourceFields []string `json:"source_fields"`
	// ForeignDataset is the URN of the referenced dataset, and ForeignFields the
	// field paths on it.
	ForeignDataset string   `json:"foreign_dataset"`
	ForeignFields  []string `json:"foreign_fields"`
}

type GlossaryChildren struct {
	Nodes []GlossaryNode `json:"nodes"`
	Terms []GlossaryTerm `json:"terms"`
	Start int            `json:"start"`
	Count int            `json:"count"`
	Total int            `json:"total"`
}

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 GlossaryNode struct {
	URN         string `json:"urn"`
	Name        string `json:"name"`
	Description string `json:"description,omitempty"`
	// ParentNode is the URN of the containing node, empty at the root.
	ParentNode string `json:"parent_node,omitempty"`
	TermsCount int    `json:"terms_count"`
	NodesCount int    `json:"nodes_count"`
}

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 GovernanceReader interface {
	CatalogPicker

	// SearchTags name-searches tags, bounded by limit. An empty query lists them,
	// under the same substitution rule SearchGlossaryTerms carries.
	SearchTags(ctx context.Context, query string, limit int) ([]EntityRef, error)

	// GetGlossaryTerm reads one term by URN. It is the only by-URN read any
	// governance vocabulary has, which is why a tag or a domain is resolved by
	// listing its vocabulary and matching instead.
	GetGlossaryTerm(ctx context.Context, urn string) (*GlossaryTerm, error)

	// SearchTables ranks datasets; filtered by tag, domain, or glossary term it
	// lists the datasets carrying that governance entity.
	SearchTables(ctx context.Context, filter SearchFilter) ([]TableSearchResult, error)
}

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 DataHub URN 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 SavedQuery struct {
	URN         string `json:"urn,omitempty"`
	Name        string `json:"name,omitempty"`
	Statement   string `json:"statement"`
	Description string `json:"description,omitempty"`
	// Source says how the query was recorded ("MANUAL", "SYSTEM").
	Source string `json:"source,omitempty"`
	// CreatedBy is the actor that recorded it; Created is when.
	CreatedBy string     `json:"created_by,omitempty"`
	Created   *time.Time `json:"created,omitempty"`
}

type SchemaField struct {
	// FieldPath is the full path of the field ("user.address.city" for a nested one).
	FieldPath string `json:"field_path"`
	// Type is the catalog's normalized type; NativeType is the platform's own.
	Type       string `json:"type"`
	NativeType string `json:"native_type,omitempty"`
	// Description is the field's documented meaning.
	Description string `json:"description,omitempty"`
	// Nullable reports whether the field admits NULL.
	Nullable bool `json:"nullable"`
	// IsPartitionKey marks a partition column.
	IsPartitionKey bool `json:"is_partition_key,omitempty"`
	// Tags and GlossaryTerms are the field-level classifications.
	Tags          []string       `json:"tags,omitempty"`
	GlossaryTerms []GlossaryTerm `json:"glossary_terms,omitempty"`
}

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"`

	// EntityTypes restricts search to specific entity types (e.g., "DATASET", "DASHBOARD").
	// If empty, defaults to the DataHub client's DefaultEntityType.
	EntityTypes []string `json:"entity_types,omitempty"`

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

	// Filters provides advanced field-level filtering (e.g., by column name, column tag).
	// All filters are AND'd together. These map directly to DataHub's searchAcrossEntities
	// orFilters and support fields like fieldPaths, fieldTags, fieldGlossaryTerms, etc.
	Filters []FieldFilter `json:"filters,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 (DataHub 1.4.x)
	StructuredProperties []StructuredProperty `json:"structured_properties,omitempty"`

	// Incidents (DataHub 1.4.x)
	ActiveIncidents int        `json:"active_incidents,omitempty"`
	Incidents       []Incident `json:"incidents,omitempty"`

	// Data contracts (DataHub 1.4.x)
	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"`
}

type URNResolver interface {
	// ResolveURN converts a URN to a table identifier.
	ResolveURN(ctx context.Context, urn string) (*TableIdentifier, error)

	// BuildURN creates a URN from a table identifier.
	BuildURN(ctx context.Context, table TableIdentifier) (string, error)
}