Package elki.database.query

Class QueryBuilder<O>

  • Type Parameters:
    O - Object type
    public class QueryBuilder<O>
extends java.lang.Object
    Class to build a query.

    TODO: move this class to the elki-core-api module, linking the linear-scan dependencies via dynamic class loading instead?

    TODO: use a service loader to load optimization modules.

    Since:
    0.8.0
    Author:
    Erich Schubert

    • Field Detail

      • LOG

        private static final Logging LOG
        Class logger.

      • FLAG_LINEAR_ONLY

        public static final int FLAG_LINEAR_ONLY
        Linear scans only
        See Also:
        Constant Field Values

      • FLAG_OPTIMIZED_ONLY

        public static final int FLAG_OPTIMIZED_ONLY
        Optimized queries only, no linear scans
        See Also:
        Constant Field Values

      • FLAG_EXACT_ONLY

        public static final int FLAG_EXACT_ONLY
        Exact queries only
        See Also:
        Constant Field Values

      • FLAG_CHEAP_ONLY

        public static final int FLAG_CHEAP_ONLY
        Cheap query only - do not build indexes automatically
        See Also:
        Constant Field Values

      • FLAG_NO_CACHE

        public static final int FLAG_NO_CACHE
        Do not keep auto-generated indexes (c.f., MaterializeKNNPreprocessor).
        See Also:
        Constant Field Values

      • FLAG_PRECOMPUTE

        public static final int FLAG_PRECOMPUTE
        Flag indicating expected pairwise usage / need for precomputation.
        See Also:
        Constant Field Values

      • FLAGS_NO_OPTIMIZER

        public static final int FLAGS_NO_OPTIMIZER
        Flags that do not allow the optimizer to run.
        See Also:
        Constant Field Values

      • FLAGS_NO_INHERIT

        public static final int FLAGS_NO_INHERIT
        Flags that are not inherited to nested distanceQuery calls.
        See Also:
        Constant Field Values

      • OPTIMIZER

        private static final QueryOptimizer OPTIMIZER
        Global query optimizer, populated at startup.

      • relation

        private Relation<O> relation
        Relation to query.

      • distance

        private Distance<? super O> distance
        Distance to query

      • similarity

        private Similarity<? super O> similarity
        Similarity to query

      • distQuery

        private DistanceQuery<O> distQuery
        Bound distance to query

      • flags

        private int flags
        Query flags

    • Constructor Detail

      • QueryBuilder

        public QueryBuilder​(Relation<O> relation,
                    Distance<? super O> distance)
        Constructor.
        Parameters:
        relation - Relation to query

      • QueryBuilder

        public QueryBuilder​(DistanceQuery<? super O> distQuery)
        Constructor.
        Parameters:
        distQuery - Query to use

      • QueryBuilder

        public QueryBuilder​(Relation<O> relation,
                    Similarity<? super O> similarity)
        Constructor.
        Parameters:
        relation - Relation to query

      • QueryBuilder

        public QueryBuilder​(SimilarityQuery<? super O> simQuery)
        Constructor.
        Parameters:
        simQuery - Query to use

    • Method Detail

      • linearOnly

        public QueryBuilder<O> linearOnly()
        Only build linear-scan queries, useful as reference for evaluation of approximate methods. This can obviously not be combined with FLAG_OPTIMIZED_ONLY.
        Returns:
        query builder, for chaining

      • optimizedOnly

        public QueryBuilder<O> optimizedOnly()
        Only query for optimized functions, returning null otherwise. This allows the user to choose fallback strategies instead. This can obviously not be combined with FLAG_LINEAR_ONLY.
        Returns:
        query builder, for chaining

      • exactOnly

        public QueryBuilder<O> exactOnly()
        Only accept exact methods, no approximate methods.
        Returns:
        query builder, for chaining

      • cheapOnly

        public QueryBuilder<O> cheapOnly()
        Only perform the cheapest optimizations, used to indicate that the query will not be used much.
        Returns:
        query builder, for chaining

      • noCache

        public QueryBuilder<O> noCache()
        Avoid caching optimizations such as computing a distance matrix, because the results will be used to, e.g., build a similar data structure.
        Returns:
        query builder, for chaining

      • precomputed

        public QueryBuilder<O> precomputed()
        Indicate that the almost all pairwise distances / each objects knn will be used multiple times, and results should be precomputed and cached.
        Returns:
        query builder, for chaining

      • distanceQuery

        public DistanceQuery<O> distanceQuery()
        Build a distance query.
        Returns:
        distance query

      • similarityQuery

        public SimilarityQuery<O> similarityQuery()
        Build a similarity query.
        Returns:
        similarity query

      • kNNByObject

        public KNNSearcher<O> kNNByObject()
        Build a k-nearest-neighbors query; if possible also give a maximum k.
        Returns:
        knn query

      • kNNByObject

        public KNNSearcher<O> kNNByObject​(int maxk)
        Build a k-nearest-neighbors query.
        Parameters:
        maxk - Maximum k that will be used later.
        Returns:
        knn query

      • kNNByDBID

        public KNNSearcher<DBIDRef> kNNByDBID()
        Build a k-nearest-neighbors query; if possible also give a maximum k.
        Returns:
        knn query

      • kNNByDBID

        public KNNSearcher<DBIDRef> kNNByDBID​(int maxk)
        Build a k-nearest-neighbors query.
        Parameters:
        maxk - Maximum k that will be used later.
        Returns:
        knn query

      • rangeByObject

        public RangeSearcher<O> rangeByObject()
        Build a range query; if possible also give a maximum query radius.
        Returns:
        range query

      • rangeByObject

        public RangeSearcher<O> rangeByObject​(double maxrange)
        Build a range query with maximum radius.
        Parameters:
        maxrange - Maximum radius that will be used.
        Returns:
        range query

      • rangeByDBID

        public RangeSearcher<DBIDRef> rangeByDBID()
        Build a range query; if possible also give a maximum query radius.
        Returns:
        range query

      • rangeByDBID

        public RangeSearcher<DBIDRef> rangeByDBID​(double maxrange)
        Build a range query with maximum radius.
        Parameters:
        maxrange - Maximum radius that will be used.
        Returns:
        range query

      • similarityRangeByObject

        public RangeSearcher<O> similarityRangeByObject()
        Build a similarity range query; if possible also specify the least selective threshold.
        Returns:
        Similarity range query

      • similarityRangeByObject

        public RangeSearcher<O> similarityRangeByObject​(double threshold)
        Build a similarity range query.
        Parameters:
        threshold - smallest similarity that will be queried later
        Returns:
        Similarity range query

      • similarityRangeByDBID

        public RangeSearcher<DBIDRef> similarityRangeByDBID()
        Build a similarity range query; if possible also specify the least selective threshold.
        Returns:
        Similarity range query

      • similarityRangeByDBID

        public RangeSearcher<DBIDRef> similarityRangeByDBID​(double threshold)
        Build a similarity range query.
        Parameters:
        threshold - smallest similarity that will be queried later
        Returns:
        Similarity range query

      • rKNNByObject

        public RKNNSearcher<O> rKNNByObject()
        Build a reverse k-nearest neighbors query.
        Returns:
        rkNN query

      • rKNNByObject

        public RKNNSearcher<O> rKNNByObject​(int k)
        Build a reverse k-nearest neighbors query.
        Parameters:
        k - k to be used; many indexes cannot support arbitrary k.
        Returns:
        rkNN query

      • rKNNByDBID

        public RKNNSearcher<DBIDRef> rKNNByDBID()
        Build a reverse k-nearest neighbors query.
        Returns:
        rkNN query

      • rKNNByDBID

        public RKNNSearcher<DBIDRef> rKNNByDBID​(int k)
        Build a reverse k-nearest neighbors query.
        Parameters:
        k - k to be used; many indexes cannot support arbitrary k.
        Returns:
        rkNN query

      • priorityByObject

        public PrioritySearcher<O> priorityByObject()
        Build a priority searcher.
        Returns:
        priority searcher

      • priorityByObject

        public PrioritySearcher<O> priorityByObject​(double maxrange)
        Build a priority searcher.
        Parameters:
        maxrange - maximum cut-off
        Returns:
        priority searcher

      • priorityByDBID

        public PrioritySearcher<DBIDRef> priorityByDBID()
        Build a priority searcher.
        Returns:
        priority searcher

      • priorityByDBID

        public PrioritySearcher<DBIDRef> priorityByDBID​(double maxrange)
        Build a priority searcher.
        Parameters:
        maxrange - maximum cut-off
        Returns:
        priority searcher

      • logUsing

        private void logUsing​(Index index,
                      java.lang.String kind,
                      boolean used)
        Log if we use a particular index.
        Parameters:
        index - Index tested
        kind - Query kind
        used - true if the index is used.

      • logNotAccelerated

        private void logNotAccelerated​(java.lang.String kind)
        Log if we have to fall back to a linear scan.
        Parameters:
        kind - Query kind

      • initStaticOptimizer

        private static QueryOptimizer initStaticOptimizer()
        Initialization method, which sets OPTIMIZER.
        Returns:
        Optimizer