datasources

type Datasource interface {

	// GetFeatures returns all Features matching the given criteria and Cursors for pagination
	GetFeatures(ctx context.Context, collection string, criteria FeaturesCriteria, axisOrder domain.AxisOrder, profile domain.Profile) (*domain.FeatureCollection, domain.Cursors, error)

	// GetFeature returns a specific Feature, based on its feature id
	GetFeature(ctx context.Context, collection string, featureID any, outputSRID domain.SRID, axisOrder domain.AxisOrder, profile domain.Profile) (*domain.Feature, error)

	// GetFeatureIDs returns all IDs of Features matching the given criteria, as well as Cursors for pagination.
	// To be used in concert with GetFeaturesByID
	GetFeatureIDs(ctx context.Context, collection string, criteria FeaturesCriteria) ([]int64, domain.Cursors, error)

	// GetFeaturesByID returns a collection of Features with the given IDs. To be used in concert with GetFeatureIDs
	GetFeaturesByID(ctx context.Context, collection string, featureIDs []int64, axisOrder domain.AxisOrder, profile domain.Profile) (*domain.FeatureCollection, error)

	// SearchFeaturesAcrossCollections search features in one or more collections. Collections can be located
	// in this dataset or in other datasets.
	SearchFeaturesAcrossCollections(ctx context.Context, criteria FeaturesSearchCriteria, axisOrder domain.AxisOrder, collections searchdomain.CollectionsWithParams) (*domain.FeatureCollection, error)

	// GetSchema returns the schema (fields, data types, descriptions, etc.) of the table associated with the given collection.
	// Along with configured queryables (= fields that can be used in filters), optionally enriched with allowed values.
	GetSchema(collection string) (*domain.Schema, Queryables, error)

	// GetCollectionType returns the type of data in the given collection, e.g. 'features' or 'attributes'.
	GetCollectionType(collection string) (geospatial.CollectionType, string, error)

	// SupportsOnTheFlyTransformation returns whether the datasource supports coordinate transformation/reprojection on-the-fly
	SupportsOnTheFlyTransformation() bool

	// Close closes (connections to) the datasource gracefully
	Close()
}

type FeaturesCriteria struct {
	// pagination (OAF part 1)
	Cursor domain.DecodedCursor
	Limit  int

	// multiple projections support (OAF part 2)
	InputSRID  domain.SRID // derived from bbox or filter param when available, or WGS84 as default
	OutputSRID domain.SRID // derived from crs param when available, or WGS84 as default

	// filtering by bounding box (OAF part 1)
	Bbox *geom.Bounds

	// filtering by reference date/time (OAF part 1)
	TemporalCriteria TemporalCriteria

	// filtering by properties (OAF part 1)
	PropertyFilters map[string]string

	// filtering by CQL (OAF part 3)
	Filter Part3Filter
}

type FeaturesSearchCriteria struct {
	// the search query after query expansion
	SearchQuery searchdomain.SearchQuery

	// global search settings
	Settings config.SearchSettings

	// search doesn't use pagination, we just return the top N results as indicated by the specified limit
	Limit int

	// multiple projections support (OAF part 2)
	InputSRID  domain.SRID // derived from bbox param when available, or WGS84 as default
	OutputSRID domain.SRID // derived from crs param when available, or WGS84 as default

	// filtering by bounding box (OAF part 1)
	Bbox *geom.Bounds
}

type Part3Filter struct {
	// SQL after parsing the provided CQL.
	SQL string

	// Named parameters used in SQL
	Params map[string]any

	// Optional SQL to include/check the RTree index for optimal performance (only for gpkg).
	RtreeSQL string
}

type QueryableWithAllowedValues struct {
	domain.Field

	// static or dynamic values that are allowed to be used in this queryable
	AllowedValues []string
}

type Queryables map[string]QueryableWithAllowedValues

type TemporalCriteria struct {
	// reference date
	ReferenceDate time.Time

	// startDate and endDate properties
	StartDateProperty string
	EndDateProperty   string
}