catalog

type AspectEdit struct {
	Ref    Ref
	Aspect AspectName
	Value  json.RawMessage
	// Expect, when Checked, is the value the writer read the aspect as, nil
	// for absent. WriteAspects refuses the whole write with ErrStale when the
	// aspect holds anything else, so a value computed from what was read never
	// replaces a write made since.
	Expect  json.RawMessage
	Checked bool
}

type AspectName string

type Aspects struct {
	Description          string            `json:"description,omitempty"`
	Tags                 []string          `json:"tags,omitempty"`
	GlossaryTerms        []string          `json:"glossary_terms,omitempty"`
	Owners               []Owner           `json:"owners,omitempty"`
	Domain               string            `json:"domain,omitempty"`
	CustomProperties     map[string]string `json:"custom_properties,omitempty"`
	StructuredProperties map[string][]any  `json:"structured_properties,omitempty"`
	DocumentationLinks   []Link            `json:"documentation_links,omitempty"`
	CuratedQueries       []CuratedQuery    `json:"curated_queries,omitempty"`
	Incidents            []Incident        `json:"incidents,omitempty"`
	ContextDocuments     []ContextDocument `json:"context_documents,omitempty"`
}

type BrowseEntry struct {
	Name string `json:"name"`
	// Reference is the dataset's reference, or for a group a dataset reference
	// whose path is the group's, which fetching browses in turn.
	Reference string `json:"reference"`
	// Datasets is how many datasets a group holds; zero for a dataset.
	Datasets int         `json:"datasets"`
	Type     DatasetType `json:"type,omitempty"`
}

type BrowseQuery struct {
	ConnectionKind string
	Connection     string
	// Prefix is the path above the level listed; empty lists the top level.
	Prefix []string
}

type Change struct {
	ID        string          `json:"id"`
	Reference string          `json:"reference"`
	Aspect    AspectName      `json:"aspect"`
	Version   int             `json:"version"`
	Previous  json.RawMessage `json:"previous,omitempty"`
	Value     json.RawMessage `json:"value,omitempty"`
	WrittenBy string          `json:"written_by"`
	WrittenAt time.Time       `json:"written_at"`
	// Reverts names the change this one rolled back.
	Reverts string `json:"reverts,omitempty"`
}

type Column struct {
	Name     string  `json:"name"`
	DataType string  `json:"data_type,omitempty"`
	Ordinal  int     `json:"ordinal"`
	Nullable bool    `json:"nullable"`
	Aspects  Aspects `json:"aspects"`
}

type ColumnInput struct {
	Name     string
	DataType string
	Nullable bool
}

type ConflictError struct {
	// Change is the change asked to be reverted.
	Change string
	// Reference and Aspect name what both changes wrote.
	Reference string
	Aspect    AspectName
	// Newer is the latest change to that aspect.
	Newer Change
}

type ContextDocument struct {
	ID          string `json:"id"`
	Title       string `json:"title"`
	Content     string `json:"content"`
	ContentType string `json:"content_type,omitempty"`
	Category    string `json:"category,omitempty"`
}

type CuratedQuery struct {
	Name        string `json:"name"`
	SQL         string `json:"sql"`
	Description string `json:"description,omitempty"`
}

type Dataset struct {
	ID        string      `json:"id"`
	Reference string      `json:"reference"`
	Ref       Ref         `json:"-"`
	Name      string      `json:"name"`
	Type      DatasetType `json:"type"`
	// SchemaResourceID is the managed resource a registered table was created
	// from, when it was created from one.
	SchemaResourceID string `json:"schema_resource_id,omitempty"`
	// SchemaDocument is the reference of the connection's schema document the
	// scan read the dataset from, when it was read from one (#1918).
	SchemaDocument string   `json:"schema_document,omitempty"`
	Columns        []Column `json:"columns"`
	Aspects        Aspects  `json:"aspects"`
	// RemovedAt is when a scan stopped seeing the dataset. Its curation stays
	// readable, and a scan that sees it again clears this.
	RemovedAt *time.Time `json:"removed_at,omitempty"`
	CreatedAt time.Time  `json:"created_at"`
	UpdatedAt time.Time  `json:"updated_at"`
}

type DatasetInput struct {
	Ref              Ref
	Name             string
	Type             DatasetType
	SchemaResourceID string
	// SchemaDocument is the filename of the connection's schema document the
	// dataset was read from. Empty keeps the one already recorded.
	SchemaDocument string
	Columns        []ColumnInput
}

type DatasetQuery struct {
	Text           string
	ConnectionKind string
	// Connection narrows the search to one connection of ConnectionKind.
	Connection string
	// Scoped limits the search to the connections in Within, each written
	// "<connection kind>/<connection>"; a scoped search with none finds
	// nothing. It is how a caller holds a search to the connections its
	// persona reaches.
	Scoped bool
	Within []string
	Tags   []string
	Limit  int
	Offset int
}

type DatasetSummary struct {
	Reference      string      `json:"reference"`
	ConnectionKind string      `json:"connection_kind"`
	Connection     string      `json:"connection"`
	Path           string      `json:"path"`
	Name           string      `json:"name"`
	Type           DatasetType `json:"type"`
	Description    string      `json:"description,omitempty"`
	Tags           []string    `json:"tags,omitempty"`
	Domain         string      `json:"domain,omitempty"`
}

type DatasetType string

type Definition struct {
	ID        string `json:"id"`
	Reference string `json:"reference"`
	Kind      Kind   `json:"kind"`
	// Slug is the stable readable key a reference may use in place of the id.
	// For a tag it is the tag's name.
	Slug string `json:"slug"`
	Name string `json:"name"`
	// Parent is the glossary node a term or node sits under, as a reference.
	Parent    string    `json:"parent,omitempty"`
	Aspects   Aspects   `json:"aspects"`
	CreatedAt time.Time `json:"created_at"`
	UpdatedAt time.Time `json:"updated_at"`
}

type DefinitionInput struct {
	Kind   Kind
	Slug   string
	Name   string
	Parent string
}

type DefinitionQuery struct {
	// Kinds are the definition kinds listed; empty lists every kind.
	Kinds []Kind
	// Parent lists the glossary terms and nodes directly under this glossary
	// node reference.
	Parent string
	// Roots lists only the definitions under no glossary node. It is ignored
	// when Parent is set.
	Roots bool
	// Text matches the name, the slug or the description, ignoring case.
	Text   string
	Limit  int
	Offset int
}

type DefinitionSummary struct {
	Reference   string `json:"reference"`
	Kind        Kind   `json:"kind"`
	Slug        string `json:"slug"`
	Name        string `json:"name"`
	Description string `json:"description,omitempty"`
	// Parent is the glossary node the definition sits under, as a reference.
	Parent string `json:"parent,omitempty"`
	// Children is how many glossary terms and nodes sit directly under a
	// glossary node.
	Children int `json:"children"`
}

type Direction string

type DocumentInput struct {
	ConnectionKind string
	Connection     string
	Filename       string
	MIMEType       string
	Content        []byte
}

type DocumentStore interface {
	// PutDocument stores a document, recording a new version only when its
	// content or media type changed, and reports whether it did.
	PutDocument(ctx context.Context, in DocumentInput) (*SchemaDocument, bool, error)
	// GetDocument reads one document with its content.
	GetDocument(ctx context.Context, ref Ref) (*SchemaDocument, error)
	// ListDocuments lists every document without its content, by connection
	// and filename.
	ListDocuments(ctx context.Context) ([]SchemaDocument, error)
}

type Edge struct {
	Source     string     `json:"source"`
	Target     string     `json:"target"`
	WriterKind WriterKind `json:"writer_kind"`
	// WriterRef names the writer: a script, an audited call, a registration.
	WriterRef string    `json:"writer_ref,omitempty"`
	WrittenBy string    `json:"written_by,omitempty"`
	WrittenAt time.Time `json:"written_at"`
}

type Hop struct {
	Edge
	Depth int `json:"depth"`
}

type InUseError struct {
	Reference string
	// Children is how many glossary terms and nodes sit under a glossary node.
	Children int
	// Entities is how many datasets and columns carry the definition.
	Entities int
}

type Incident struct {
	ID          string `json:"id"`
	Type        string `json:"type,omitempty"`
	Title       string `json:"title"`
	Description string `json:"description,omitempty"`
	State       string `json:"state"`
	// Resolution is what was said when the incident was resolved.
	Resolution string `json:"resolution,omitempty"`
}

type Kind string

type Link struct {
	URL         string `json:"url"`
	Description string `json:"description,omitempty"`
}

type Lister interface {
	// ListDefinitions returns a page of definitions, ordered by name.
	ListDefinitions(ctx context.Context, q DefinitionQuery) ([]DefinitionSummary, error)
	// DeleteDefinition deletes a definition. It refuses with an *InUseError
	// while anything uses it, and with ErrNotFound for an unknown one.
	DeleteDefinition(ctx context.Context, ref Ref) error
	// Uses returns the datasets and columns carrying a glossary term, a tag or
	// a domain, at most limit of them, ordered by reference.
	Uses(ctx context.Context, ref Ref, limit int) ([]Use, error)
	// Browse lists one level of a connection's datasets that are not removed.
	Browse(ctx context.Context, q BrowseQuery) ([]BrowseEntry, error)
}

type Owner struct {
	Owner string `json:"owner"`
	Type  string `json:"type,omitempty"`
}

type Ref struct {
	Kind Kind
	// ConnectionKind and Connection name the connection a dataset or column is
	// seen through. Connection is the instance name, the same name an
	// mcp:connection:(kind,name) reference carries.
	ConnectionKind string
	Connection     string
	// Path is the dataset's name under its connection, one element per dotted
	// segment.
	Path []string
	// Column is the column name, set only on a KindColumn reference.
	Column string
	// Key is the id or slug of a glossary term, glossary node, domain or data
	// product, the name of a tag, or a schema document's filename.
	Key string
}

type Removal struct {
	ConnectionKind string
	Connection     string
	// Types are the dataset types the scan produces; no other type is marked.
	Types []DatasetType
	// Keep are the references of the datasets the scan saw.
	Keep []string
	// Unread are dataset path prefixes, in reference form, the scan could not
	// read; nothing under one is marked.
	Unread []string
}

type SchemaDocument struct {
	ID             string `json:"id"`
	Reference      string `json:"reference"`
	ConnectionKind string `json:"connection_kind"`
	Connection     string `json:"connection"`
	Filename       string `json:"filename"`
	MIMEType       string `json:"mime_type"`
	SizeBytes      int    `json:"size_bytes"`
	// Version counts the times the document's content changed; a scan that
	// reads the same content again does not move it.
	Version   int       `json:"version"`
	UpdatedAt time.Time `json:"updated_at"`
	// Content is the document itself. A listing leaves it empty.
	Content []byte `json:"-"`
}

type Store interface {
	Lister
	// PutDataset creates or updates a dataset and replaces its column set with
	// the one given. Curation on a column that is still declared is kept; a
	// column no longer declared is removed with its curation.
	PutDataset(ctx context.Context, in DatasetInput) (*Dataset, error)
	// GetDataset reads a dataset with its columns and all curation.
	GetDataset(ctx context.Context, ref Ref) (*Dataset, error)
	// PutDefinition creates or updates a glossary term, glossary node, domain,
	// data product or tag, keyed by kind and slug.
	PutDefinition(ctx context.Context, in DefinitionInput) (*Definition, error)
	// GetDefinition reads a definition by its reference, whose key may be the
	// id or the slug.
	GetDefinition(ctx context.Context, ref Ref) (*Definition, error)
	// WriteAspect writes one aspect of a dataset, column or definition and
	// records the change. A nil or JSON-null value clears the aspect.
	WriteAspect(ctx context.Context, ref Ref, name AspectName, value json.RawMessage, by string) (*Change, error)
	// History lists the changes to one aspect, newest first.
	History(ctx context.Context, ref Ref, name AspectName) ([]Change, error)
	// Rollback restores the value a change replaced and records that as a new
	// change.
	Rollback(ctx context.Context, changeID, by string) (*Change, error)
	// WriteAspects writes several aspects in one transaction: every edit is
	// recorded as a change, or none is. Each value is checked as WriteAspect
	// checks it.
	WriteAspects(ctx context.Context, edits []AspectEdit, by string) ([]Change, error)
	// RevertChanges rolls back several changes in one transaction. It refuses
	// with a *ConflictError, reverting none, when an aspect one of them wrote
	// has been written again since, and with ErrNotFound for an unknown change.
	RevertChanges(ctx context.Context, changeIDs []string, by string) ([]Change, error)
	// TaggedEntities returns the references of the datasets and columns whose
	// tags aspect holds the tag, ordered by reference, at most limit of them.
	TaggedEntities(ctx context.Context, tag string, limit int) ([]string, error)
	// MarkRemoved marks the datasets a scan of one connection did not see as
	// removed, and returns how many it marked. A dataset already marked is
	// left as it is.
	MarkRemoved(ctx context.Context, r Removal) (int, error)
	// MarkDatasetRemoved marks one dataset removed, keeping its curation. A
	// dataset the store does not hold is not an error.
	MarkDatasetRemoved(ctx context.Context, ref Ref) error
	// AddEdges records lineage edges; recording an edge again refreshes when
	// it was written.
	AddEdges(ctx context.Context, edges []Edge) error
	// Lineage walks the edges from a dataset reference in one direction, at
	// most maxDepth hops, each edge once at its shortest distance.
	Lineage(ctx context.Context, ref string, direction Direction, maxDepth int) ([]Hop, error)
	// DatasetsByPath returns the references of the datasets of one connection
	// kind with the given path, one per connection that sees it, ordered by
	// connection.
	DatasetsByPath(ctx context.Context, connectionKind, path string) ([]string, error)
	// SearchDatasets returns a page of datasets that are not removed and match
	// the query, with their curation.
	SearchDatasets(ctx context.Context, q DatasetQuery) ([]DatasetSummary, error)
}

type Use struct {
	// Reference is the dataset's or the column's.
	Reference string `json:"reference"`
	// Dataset is the dataset's reference, the same as Reference for a dataset.
	Dataset string `json:"dataset"`
	Name    string `json:"name"`
	// Column is set when a column, rather than the dataset, carries it.
	Column     string `json:"column,omitempty"`
	Connection string `json:"connection"`
}

type WriterKind string