xref: /external/icing/proto/icing/proto/scoring.proto

// Copyright 2019 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//      http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

syntax = "proto2";

package icing.lib;

import "icing/proto/term.proto";

option java_package = "com.google.android.icing.proto";
option java_multiple_files = true;
option objc_class_prefix = "ICNG";

// Encapsulates the configurations on how Icing should score and rank the search
// results.
// TODO(b/170347684): Change all timestamps to seconds.
// Next tag: 8
message ScoringSpecProto {
  // OPTIONAL: Indicates how the search results will be ranked.
  message RankingStrategy {
    enum Code {
      // No ranking strategy specified, documents may be returned in an
      // arbitrary order.
      NONE = 0;

      // Ranked by user-provided document scores.
      DOCUMENT_SCORE = 1;

      // Ranked by document creation timestamps.
      CREATION_TIMESTAMP = 2;

      // The following ranking strategies are based on usage reporting. Please
      // see usage.proto for more information. If one of the usage ranking
      // strategy is used but none of result documents have reported usage, the
      // documents will be returned in the default reverse insertion order.

      // Ranked by count of reports with usage type 1.
      USAGE_TYPE1_COUNT = 3;

      // Ranked by count of reports with usage type 2.
      USAGE_TYPE2_COUNT = 4;

      // Ranked by count of reports with usage type 3.
      USAGE_TYPE3_COUNT = 5;

      // Ranked by last used timestamp with usage type 1. The timestamps are
      // compared in seconds.
      USAGE_TYPE1_LAST_USED_TIMESTAMP = 6;

      // Ranked by last used timestamp with usage type 2. The timestamps are
      // compared in seconds.
      USAGE_TYPE2_LAST_USED_TIMESTAMP = 7;

      // Ranked by last used timestamp with usage type 3. The timestamps are
      // compared in seconds.
      USAGE_TYPE3_LAST_USED_TIMESTAMP = 8;

      // Ranked by relevance score, currently computed as BM25F score.
      RELEVANCE_SCORE = 9;

      // Ranked by the aggregated score of the joined documents.
      JOIN_AGGREGATE_SCORE = 10;

      // Ranked by the advanced scoring expression provided.
      ADVANCED_SCORING_EXPRESSION = 11;
    }
  }
  optional RankingStrategy.Code rank_by = 1;

  // OPTIONAL: Indicates the order of returned search results, the default is
  // DESC, meaning that results with higher scores come first. This order field
  // will be ignored if 'rank_by' is NONE.
  message Order {
    enum Code {
      // Search results will be returned in a descending order.
      DESC = 0;

      // Search results will be returned in a ascending order.
      ASC = 1;
    }
  }
  optional Order.Code order_by = 2;

  // OPTIONAL: Specifies property weights for RELEVANCE_SCORE scoring strategy.
  // Property weights are used for promoting or demoting query term matches in a
  // document property. When property weights are provided, the term frequency
  // is multiplied by the normalized property weight when computing the
  // normalized term frequency component of BM25F. To prefer query term matches
  // in the "subject" property over the "body" property of "Email" documents,
  // set a higher property weight value for "subject" than "body". By default,
  // all properties that are not specified are given a raw, pre-normalized
  // weight of 1.0 when scoring.
  repeated TypePropertyWeights type_property_weights = 3;

  // OPTIONAL: Specifies the scoring expression for ADVANCED_SCORING_EXPRESSION
  // RankingStrategy.
  optional string advanced_scoring_expression = 4;

  // OPTIONAL: Specifies additional scoring expressions to return extra helpful
  // scores for clients. The scores will not be used for ranking.
  //
  // To set this field, the ranking strategy must be set to
  // ADVANCED_SCORING_EXPRESSION.
  repeated string additional_advanced_scoring_expressions = 5;

  // OPTIONAL: Specifies the schema type alias map for advanced scoring
  // expression.
  //
  // The alias map must be provided for all alias schema types used in the
  // getScorableProperty function of the advanced scoring expression. Otherwise,
  // an error will be returned.
  //
  // For example, Icing clients can pass a SchemaTypeAliasMapProto to icing:
  //   schema_type_alias_for_advanced_scoring {
  //     alias_schema_type: "person"
  //     schema_types: "package1$database1/person"
  //     schema_types: "package2$database1/person"
  //   }
  //   schema_type_alias_for_advanced_scoring {
  //     alias_schema_type: "email"
  //     schema_types: "package3$database2/email"
  //     schema_types: "package4$database2/email"
  //   }
  //
  // When Icing processes the advanced scoring expression such as:
  // "getScorableProperty('person', 'rfsScore')",
  // Icing will
  //   1. first look up documents with schema type "person".
  //   2. if the SchemaTypeAliasMapProto is provided, Icing will also look up
  //      documents with schema types from:
  //         - "package1$database1/person"
  //         - "package2$database1/person"
  //
  // TODO(b/357105837): Consider moving this to a higher level proto.
  // Currently, ScoringSpec from both parent and child queries need to provide
  // this proto, thus introducing duplicates. We can consider moving this to a
  // higher level proto and send it to downstreams.
  repeated SchemaTypeAliasMapProto schema_type_alias_map_protos = 6;

  // Features enabled for scoring.
  repeated ScoringFeatureType scoring_feature_types_enabled = 7 [packed = true];
}

// Next tag: 3
message SuggestionScoringSpecProto {
  message SuggestionRankingStrategy {
    enum Code {
      // No ranking strategy specified, terms may be returned in an arbitrary
      // order.
      NONE = 0;

      // Ranked by the term's hit count.
      DOCUMENT_COUNT = 1;

      // Ranked by the term's frequency.
      TERM_FREQUENCY = 2;
    }
  }

  // TermMatchType.Code=UNKNOWN
  // Should never purposely be set and may lead to undefined behavior. This is
  // used for backwards compatibility reasons.
  //
  // TermMatchType.Code=EXACT_ONLY
  // Only exact hits will be counted to score a suggestion term.
  //
  // TermMatchType.Code=PREFIX
  // Both exact hits and prefix hits will be counted to score a suggestion
  // term.
  optional TermMatchType.Code scoring_match_type = 1;

  // Rank the output suggested result by given SuggestionRankingStrategy.
  optional SuggestionRankingStrategy.Code rank_by = 2;
}

// Next tag: 3
message TypePropertyWeights {
  // Schema type to apply property weights to.
  optional string schema_type = 1;

  // Property weights to apply to the schema type.
  repeated PropertyWeight property_weights = 2;
}

// Next tag: 3
message PropertyWeight {
  // Property path to assign property weight to. Property paths must be composed
  // only of property names and property separators (the '.' character).
  // For example, if an "Email" schema type has string property "subject" and
  // document property "sender", which has string property "name", the property
  // path for the email's subject would just be "subject" and the property path
  // for the sender's name would be "sender.name". If an invalid path is
  // specified, the property weight is discarded.
  optional string path = 1;

  // Property weight, valid values are positive and zero. Setting a zero
  // property weight will remove scoring contribution for a query term match in
  // the property. Negative weights are invalid and will result in an error.
  // By default, a property is given a raw, pre-normalized weight of 1.0.
  optional double weight = 2;
}

// Proto that maps an alias schema type to a list of Icing schema types.
//
// Next tag: 3
message SchemaTypeAliasMapProto {
  // Alias schema type provided by Icing clients.
  optional string alias_schema_type = 1;
  // Schema types in Icing.
  repeated string schema_types = 2;
}

// Next tag: 2
enum ScoringFeatureType {
  SCORING_FEATURE_TYPE_UNKNOWN = 0;

  // Ranking with getScorableProperty(), in advanced scoring expression.
  SCORABLE_PROPERTY_RANKING = 1;
}