Update Icing protos from piper upstream.

Change-Id: If0117363362baedc564e4c128b6d0a1009ace9b4

7 files changed, 199 insertions, 22 deletions

diff --git a/icing/proto/document.proto b/icing/proto/document.proto
index 64c2e2b..50c0f7e 100644
--- a/icing/proto/document.proto
+++ b/icing/proto/document.proto
@@ -14,10 +14,13 @@
 
 syntax = "proto2";
 
-package icing;
+package icing.lib;
+
+option java_package = "com.google.android.icing.proto";
+option java_multiple_files = true;
 
 // Defines a unit of data understood by the IcingSearchEngine.
-// Next tag: 6
+// Next tag: 8
 message DocumentProto {
   // REQUIRED: Namespace that this Document resides in.
   // Namespaces can affect read/write permissions.
@@ -30,26 +33,40 @@ message DocumentProto {
 
   // REQUIRED: Type of the Document. This should match the 'schema_type' of
   // one of the types given to Icing as part of the overall schema.
-  // See icing.SchemaTypeConfigProto.schema_type for details.
+  // See icing.lib.SchemaTypeConfigProto.schema_type for details.
   optional string schema = 3;
 
-  // Milliseconds since epoch at which the Document was created. If not
-  // specified, it will default to when the Icing receives the Document.
-  optional uint64 creation_timestamp_ms = 4;
+  // OPTIONAL: Seconds since epoch at which the Document was created.
+  // Negative values are invalid for this field and may cause unexpected
+  // behaviors. If not specified, it will default to when the Icing receives the
+  // Document.
+  optional fixed64 creation_timestamp_secs = 4;
 
+  // REQUIRED: Properties that will be validated against the provided schema.
+  // The names of these properties should map to one of the properties
+  // already defined in the schema for this Document's schema_type.
   repeated PropertyProto properties = 5;
+
+  // OPTIONAL: Properties that will not be validated against the schema,
+  // indexed, or be searchable. The properties will be stored in the Documents,
+  // but never looked at by Icing.
+  repeated PropertyProto custom_properties = 6;
+
+  // OPTIONAL: Score of the document which could be used during search result
+  // ranking. Negative values will lead to validation errors. The default is the
+  // lowest score 0.
+  optional int32 score = 7 [default = 0];
 }
 
 // Holds a property field of the Document.
 // Next tag: 8
 message PropertyProto {
-  // Name of the property. This should be the same as one of the properties
-  // already defined in the schema for this Document's schema_type.
-  // See icing.PropertyConfigProto.property_name for details.
+  // Name of the property.
+  // See icing.lib.PropertyConfigProto.property_name for details.
   optional string name = 1;
 
   // Only the field corresponding to the DataType specified in
-  // icing.PropertyConfigProto.data_type should be set.
+  // icing.lib.PropertyConfigProto.data_type should be set.
   repeated string string_values = 2;
   repeated int64 int64_values = 3;
   repeated double double_values = 4;
diff --git a/icing/proto/document_wrapper.proto b/icing/proto/document_wrapper.proto
index d17faf9..0666e72 100644
--- a/icing/proto/document_wrapper.proto
+++ b/icing/proto/document_wrapper.proto
@@ -14,10 +14,13 @@
 
 syntax = "proto2";
 
-package icing;
+package icing.lib;
 
 import "icing/proto/document.proto";
 
+option java_package = "com.google.android.icing.proto";
+option java_multiple_files = true;
+
 // DocumentWrapper as a wrapper of the user-facing DocumentProto is meant to
 // be used by icing team internally. It stores the original document provided
 // by library users and metadata of the document which shouldn't be exposed to
diff --git a/icing/proto/icing-search-engine-options.proto b/icing/proto/icing-search-engine-options.proto
index f3b98dc..b1bf755 100644
--- a/icing/proto/icing-search-engine-options.proto
+++ b/icing/proto/icing-search-engine-options.proto
@@ -14,7 +14,10 @@
 
 syntax = "proto2";
 
-package icing;
+package icing.lib;
+
+option java_package = "com.google.android.icing.proto";
+option java_multiple_files = true;
 
 // Next tag: 6
 message IcingSearchEngineOptions {
diff --git a/icing/proto/schema.proto b/icing/proto/schema.proto
index b0a6788..dbfbfc4 100644
--- a/icing/proto/schema.proto
+++ b/icing/proto/schema.proto
@@ -14,10 +14,13 @@
 
 syntax = "proto2";
 
-package icing;
+package icing.lib;
 
 import "icing/proto/term.proto";
 
+option java_package = "com.google.android.icing.proto";
+option java_multiple_files = true;
+
 // Defines the schema that every Document of a specific "type" should adhere
 // to. These can be considered as definitions of rich structured types for
 // Documents accepted by IcingSearchEngine.
diff --git a/icing/proto/scoring.proto b/icing/proto/scoring.proto
new file mode 100644
index 0000000..ad536b4
--- /dev/null
+++ b/icing/proto/scoring.proto
@@ -0,0 +1,56 @@
+// 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;
+
+option java_package = "com.google.android.icing.proto";
+option java_multiple_files = true;
+
+// Encapsulates the configurations on how Icing should score and rank the search
+// results.
+// Next tag: 3
+message ScoringSpecProto {
+  // OPTIONAL: Indicates how the search results will be ranked.
+  message RankingStrategy {
+    enum Code {
+      // No ranking strategy specified, documents will be returned in the
+      // default order that the most recent document inserted into Icing comes
+      // first.
+      NONE = 0;
+
+      // Ranked by user-provided document scores.
+      DOCUMENT_SCORE = 1;
+
+      // Ranked by document creation timestamps.
+      CREATION_TIMESTAMP = 2;
+    }
+  }
+  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;
+}
diff --git a/icing/proto/search.proto b/icing/proto/search.proto
index b153de8..03e3a04 100644
--- a/icing/proto/search.proto
+++ b/icing/proto/search.proto
@@ -14,13 +14,16 @@
 
 syntax = "proto2";
 
-package icing;
+package icing.lib;
 
 import "icing/proto/document.proto";
 import "icing/proto/term.proto";
 
+option java_package = "com.google.android.icing.proto";
+option java_multiple_files = true;
+
 // Client-supplied specifications on what documents to retrieve.
-// Next tag: 3
+// Next tag: 5
 message SearchSpecProto {
   // REQUIRED: The "raw" query string that users may type. For example, "cat"
   // will search for documents with the term cat in it.
@@ -44,28 +47,117 @@ message SearchSpecProto {
   // "football".
   optional TermMatchType.Code term_match_type = 2;
 
-  // TODO(cassiewang): add namespace restricts
-  // TODO(cassiewang): add schema type restricts
+  // OPTIONAL: Only search for documents that have the specified namespaces. If
+  // unset, the query will search over all namespaces. Note that this applies to
+  // the entire 'query'. To issue different queries for different namespaces,
+  // separate Search()'s will need to be made.
+  repeated string namespace_filters = 3;
+
+  // OPTIONAL: Only search for documents that have the specified schema types.
+  // If unset, the query will search over all schema types. Note that this
+  // applies to the entire 'query'. To issue different queries for different
+  // schema types, separate Search()'s will need to be made.
+  repeated string schema_type_filters = 4;
 }
 
 // Client-supplied specifications on what to include/how to format the search
 // results.
-// Next tag: 3
+// Next tag: 4
 message ResultSpecProto {
   // The maximum number of documents to return in SearchResultProto. Even if
   // more documents have matched the SearchSpecProto, this may be used to limit
   // the number to actually return to the client.
-  optional int32 limit = 1 [default = 10];
+  optional int32 num_to_retrieve = 1 [default = 10];
 
   // Whether to collect and return debug_info in the SearchResultProto.
   optional bool debug_info = 2;
+
+  // How to provide snippeting information in the SearchResultProto.
+  // Next tag: 5
+  message SnippetSpecProto {
+    // Only the first num_to_snippet documents will have snippet information
+    // provided. If set to 0, snippeting is disabled.
+    optional int32 num_to_snippet = 1;
+
+    // Only the first num_matches_per_property matches for a single section will
+    // have snippet information provided. If set to 0, snippeting is disabled.
+    optional int32 num_matches_per_property = 2;
+
+    // How large of a window to provide. Windows start at max_window_bytes / 2
+    // bytes before the middle of the matching token and end at max_window_bytes
+    // / 2 bytes after the middle of the matching token. Windowing respects
+    // token boundaries.
+    // Therefore, the returned window may be smaller than requested. Setting
+    // max_requested_window_length_bytes to 0 will disable windowing
+    // information. If matches enabled is also set to false, then snippeting is
+    // disabled.
+    // Ex. window_size = 16. "foo bar baz bat rat" with a query of "baz" will
+    // return a window of "bar baz bat" which is only 11 bytes long.
+    optional int32 max_window_bytes = 3;
+  }
+  optional SnippetSpecProto snippet_spec = 3;
+}
+
+// The representation of a single match within a DocumentProto property.
+// Next tag: 6
+message SnippetMatchProto {
+  // Properties may have multiple values. values_index indicates which of these
+  // multiple string values the match occurred in. For properties with only one
+  // value, the values_index will always be 0.
+  // Ex. "Recipients" [
+  //      { { "Name"         : "Daffy Duck" }
+  //        { "EmailAddress" : "daffduck@gmail.com" } },
+  //      { { "Name"         : "Donald Duck" }
+  //        { "EmailAddress" : "donduck@gmail.com" }  }
+  // "Daffy Duck" is the string value with a value_index of 0 for property
+  // "Recipients.Name". "Donald Duck" is the string value with a value_index of
+  // 1 for property "Recipients.Name".
+  optional int32 values_index = 1;
+
+  // The position and length within the matched string at which the exact
+  // match begins.
+  optional int32 exact_match_position = 2;
+
+  optional int32 exact_match_bytes = 3;
+
+  // The position and length of the suggested snippet window.
+  optional int32 window_position = 4;
+
+  optional int32 window_bytes = 5;
+}
+
+// A Proto representing all snippets for a single DocumentProto.
+// Next tag: 2
+message SnippetProto {
+  // A pair of property name and all snippet matches that correspond to the
+  // property values in the corresponding DocumentProto.
+  // Next tag: 3
+  message EntryProto {
+    // A '.'-delimited sequence of property names indicating which property in
+    // the DocumentProto these snippets correspond to.
+    // Example properties: 'body', 'sender.name', 'sender.emailaddress', etc.
+    optional string property_name = 1;
+
+    repeated SnippetMatchProto snippet_matches = 2;
+  }
+  // Properties that do not appear in entries do not contain any matches.
+  repeated EntryProto entries = 1;
 }
 
 // Icing lib-supplied results from a search results.
 // Next tag: 4
 message SearchResultProto {
-  // Documents that match the SearchSpecProto. Empty if there was an error.
-  repeated DocumentProto documents = 1;
+  // The Results that matched the query. Empty if there was an error.
+  // Next tag: 3
+  message ResultProto {
+    // Document that matches the SearchSpecProto.
+    optional DocumentProto document = 1;
+
+    // Snippeting information for the document if requested in the
+    // ResultSpecProto. A default instance, if not requested.
+    optional SnippetProto snippet = 2;
+  }
+  repeated ResultProto results = 1;
 
   // Details on what errors were encountered. Not populated if there were no
   // errors.
diff --git a/icing/proto/term.proto b/icing/proto/term.proto
index b2cffdf..30cd1bc 100644
--- a/icing/proto/term.proto
+++ b/icing/proto/term.proto
@@ -14,7 +14,10 @@
 
 syntax = "proto2";
 
-package icing;
+package icing.lib;
+
+option java_package = "com.google.android.icing.proto";
+option java_multiple_files = true;
 
 // Encapsulates the configurations on how Icing should query/index these terms.
 // Next tag: 0