cz.cuni.versatile.api
Interface Query

All Known Subinterfaces:
QueryTemplate, TemplateBasedQuery

public interface Query

Multi-variant resource query (a data structure abstraction). Query is a data structure encapsulating all the information necessary to retrieve a resource possibly existing in many different variants and flavors:

Remarks:

Author:
Jaroslav Gergic
See Also:
ResourceProvider, QueryTemplate, TemplateBasedQuery

Field Summary
static double BIASED_SCORING_FACTOR
          Biased scoring factor.
static double DEFAULT_MATCH_SCORE
          Default match score is 0.0, which means all values.
static int DEFAULT_N_BEST
          Default N-best is 1-best.
static double DEFAULT_SCORING_FACTOR
          Default scoring factor.
static double EXACT_MATCH_SCORE
          Exact match score is 1.0, which means no constraint relaxing (fall-back) activity took place.
static double NEUTRAL_SCORING_FACTOR
          NEUTRAL_SCORING_FACTOR = 1.0 makes all property predicates equally significant.
 
Method Summary
 int getNBest()
          Returns the N-best (the expected size of the result set) setting for this query.
 java.util.List getPredicates()
          An ordered list of meta-data constraints.
 java.lang.String getResourceName()
          Resource name which uniquely identifies a resource within a scope of a particular ResourceProvider instance.
 double getScoreThreshold()
          Returns the resource score threshold setting for this query.
 double getScoringFactor()
          Returns the scoring factor used by the scoring function for this query.
 

Field Detail

DEFAULT_N_BEST

public static final int DEFAULT_N_BEST
Default N-best is 1-best.

See Also:
Constant Field Values

DEFAULT_MATCH_SCORE

public static final double DEFAULT_MATCH_SCORE
Default match score is 0.0, which means all values.

See Also:
Constant Field Values

EXACT_MATCH_SCORE

public static final double EXACT_MATCH_SCORE
Exact match score is 1.0, which means no constraint relaxing (fall-back) activity took place.

See Also:
PropertyOperators.BEST_MATCH, Constant Field Values

DEFAULT_SCORING_FACTOR

public static final double DEFAULT_SCORING_FACTOR
Default scoring factor. DEFAULT_SCORING_FACTOR = 0.99, which is semantically very close NEUTRAL_SCORING_FACTOR, but the small penalty of this scoring factor effectively prevents ambiguity of the result scores.

See Also:
Constant Field Values

NEUTRAL_SCORING_FACTOR

public static final double NEUTRAL_SCORING_FACTOR
NEUTRAL_SCORING_FACTOR = 1.0 makes all property predicates equally significant. the score calculated for an individual result entry by the scoring function will be 1/(1 + m), where m is the magnitude of the vector defined as the distance of the result entry from the original query in an N-dimensional Euclidean space, each property corresponding to one dimension.

Remarks: This setting can easily generate ambiguous results - multiple result entries with the same score.

See Also:
Constant Field Values

BIASED_SCORING_FACTOR

public static final double BIASED_SCORING_FACTOR
Biased scoring factor. BIASED_SCORING_FACTOR = 0.1 strongly inclines towards the properties at the beginning of the predicate list, i.e. these are the most significant. This is analogous to the order of significance of the individual digits in a decimal number.

See Also:
Constant Field Values
Method Detail

getNBest

public int getNBest()
Returns the N-best (the expected size of the result set) setting for this query. N-best mostly applies in combination with bestMatch or another constraint relaxing operator which affects the score of the ResultSet entries. Assertive operators have no effect on the score rating. N-best represents the maximum number of result entries which can be returned.

Returns:
the N-best setting for this query (a positive integer)

getScoreThreshold

public double getScoreThreshold()
Returns the resource score threshold setting for this query. Result items with a lower score will be skipped from the result set. The score threshold is a number in the interval <Query#DEFAULT_MATCH_SCORE, Query#EXACT_MATCH_SCORE> (<0.0, 1.0>).

Returns:
the resource score threshold setting for this query.

getScoringFactor

public double getScoringFactor()
Returns the scoring factor used by the scoring function for this query. The scoring factor determines relative significance of property predicates. It has a significant impact on results in cases when there are multiple property predicates using constraint-relaxing operator like bestMatch. The scoring factor is a number in the interval (0, Query#NEUTRAL_SCORING_FACTOR>.

Returns:
a scoring factor used when evaluating this query
See Also:
QueryTemplate.setScoringFactor(double)

getResourceName

public java.lang.String getResourceName()
Resource name which uniquely identifies a resource within a scope of a particular ResourceProvider instance. Unlike property names, resource names are not necessarily globally unique in Versatile).

Returns:
resource name (a unique resource key)

getPredicates

public java.util.List getPredicates()
An ordered list of meta-data constraints. The PropertyPredicates are ordered in descending order of their significance, the significance of the predicates affects the resource score in case there are one or more predicates using bestMatch or another constraint relaxing operator.

Returns:
an ordered list of PropertyPredicate objects, the list can be empty
See Also:
PropertyPredicate