diff options
Diffstat (limited to 'icing')
-rw-r--r-- | icing/proto/document.proto | 37 | ||||
-rw-r--r-- | icing/proto/document_wrapper.proto | 5 | ||||
-rw-r--r-- | icing/proto/icing-search-engine-options.proto | 5 | ||||
-rw-r--r-- | icing/proto/schema.proto | 5 | ||||
-rw-r--r-- | icing/proto/scoring.proto | 56 | ||||
-rw-r--r-- | icing/proto/search.proto | 108 | ||||
-rw-r--r-- | icing/proto/term.proto | 5 |
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 |