/*-------------------------------------------------------------------------
 *
 * statistics.h
 *	  Extended statistics and selectivity estimation functions.
 *
 * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
 * Portions Copyright (c) 1994, Regents of the University of California
 *
 * src/include/statistics/statistics.h
 *
 *-------------------------------------------------------------------------
 */
#ifndef STATISTICS_H
#define STATISTICS_H

#include "commands/vacuum.h"
#include "nodes/pathnodes.h"

#define STATS_MAX_DIMENSIONS	8	/* max number of attributes */

/* Multivariate distinct coefficients */
#define STATS_NDISTINCT_MAGIC		0xA352BFA4	/* struct identifier */
#define STATS_NDISTINCT_TYPE_BASIC	1	/* struct version */

/* MVNDistinctItem represents a single combination of columns */
typedef struct MVNDistinctItem
{
	double		ndistinct;		/* ndistinct value for this combination */
	int			nattributes;	/* number of attributes */
	AttrNumber *attributes;		/* attribute numbers */
} MVNDistinctItem;

/* A MVNDistinct object, comprising all possible combinations of columns */
typedef struct MVNDistinct
{
	uint32		magic;			/* magic constant marker */
	uint32		type;			/* type of ndistinct (BASIC) */
	uint32		nitems;			/* number of items in the statistic */
	MVNDistinctItem items[FLEXIBLE_ARRAY_MEMBER];
} MVNDistinct;

/* Multivariate functional dependencies */
#define STATS_DEPS_MAGIC		0xB4549A2C	/* marks serialized bytea */
#define STATS_DEPS_TYPE_BASIC	1	/* basic dependencies type */

/*
 * Functional dependencies, tracking column-level relationships (values
 * in one column determine values in another one).
 */
typedef struct MVDependency
{
	double		degree;			/* degree of validity (0-1) */
	AttrNumber	nattributes;	/* number of attributes */
	AttrNumber	attributes[FLEXIBLE_ARRAY_MEMBER];	/* attribute numbers */
} MVDependency;

typedef struct MVDependencies
{
	uint32		magic;			/* magic constant marker */
	uint32		type;			/* type of MV Dependencies (BASIC) */
	uint32		ndeps;			/* number of dependencies */
	MVDependency *deps[FLEXIBLE_ARRAY_MEMBER];	/* dependencies */
} MVDependencies;

/* used to flag stats serialized to bytea */
#define STATS_MCV_MAGIC			0xE1A651C2	/* marks serialized bytea */
#define STATS_MCV_TYPE_BASIC	1	/* basic MCV list type */

/* max items in MCV list */
#define STATS_MCVLIST_MAX_ITEMS        MAX_STATISTICS_TARGET

/*
 * Multivariate MCV (most-common value) lists
 *
 * A straightforward extension of MCV items - i.e. a list (array) of
 * combinations of attribute values, together with a frequency and null flags.
 */
typedef struct MCVItem
{
	double		frequency;		/* frequency of this combination */
	double		base_frequency; /* frequency if independent */
	bool	   *isnull;			/* NULL flags */
	Datum	   *values;			/* item values */
} MCVItem;

/* multivariate MCV list - essentially an array of MCV items */
typedef struct MCVList
{
	uint32		magic;			/* magic constant marker */
	uint32		type;			/* type of MCV list (BASIC) */
	uint32		nitems;			/* number of MCV items in the array */
	AttrNumber	ndimensions;	/* number of dimensions */
	Oid			types[STATS_MAX_DIMENSIONS];	/* OIDs of data types */
	MCVItem		items[FLEXIBLE_ARRAY_MEMBER];	/* array of MCV items */
} MCVList;

extern MVNDistinct *statext_ndistinct_load(Oid mvoid, bool inh);
extern MVDependencies *statext_dependencies_load(Oid mvoid, bool inh);
extern MCVList *statext_mcv_load(Oid mvoid, bool inh);

extern void BuildRelationExtStatistics(Relation onerel, bool inh, double totalrows,
									   int numrows, HeapTuple *rows,
									   int natts, VacAttrStats **vacattrstats);
extern int	ComputeExtStatisticsRows(Relation onerel,
									 int natts, VacAttrStats **vacattrstats);
extern bool statext_is_kind_built(HeapTuple htup, char type);
extern Selectivity dependencies_clauselist_selectivity(PlannerInfo *root,
													   List *clauses,
													   int varRelid,
													   JoinType jointype,
													   SpecialJoinInfo *sjinfo,
													   RelOptInfo *rel,
													   Bitmapset **estimatedclauses);
extern Selectivity statext_clauselist_selectivity(PlannerInfo *root,
												  List *clauses,
												  int varRelid,
												  JoinType jointype,
												  SpecialJoinInfo *sjinfo,
												  RelOptInfo *rel,
												  Bitmapset **estimatedclauses,
												  bool is_or);
extern bool has_stats_of_kind(List *stats, char requiredkind);
extern StatisticExtInfo *choose_best_statistics(List *stats, char requiredkind,
												bool inh,
												Bitmapset **clause_attnums,
												List **clause_exprs,
												int nclauses);
extern HeapTuple statext_expressions_load(Oid stxoid, bool inh, int idx);

#endif							/* STATISTICS_H */
