• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1// Copyright 2019 Google LLC
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7//      http://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14
15syntax = "proto2";
16
17package icing.lib;
18
19import "icing/proto/logging.proto";
20import "icing/proto/persist.proto";
21import "icing/proto/status.proto";
22
23option java_package = "com.google.android.icing.proto";
24option java_multiple_files = true;
25option objc_class_prefix = "ICNG";
26
27// Holds a list of DocumentProto.
28// Next tag: 3
29message PutDocumentRequest {
30  repeated DocumentProto documents = 1;
31
32  // The persist type used to call PersistToDisk at the end of the Put request.
33  // If not specified, PersistToDisk will not be called.
34  optional PersistType.Code persist_type = 2;
35}
36
37// Defines a unit of data understood by the IcingSearchEngine.
38// Next tag: 10
39message DocumentProto {
40  // REQUIRED: Namespace that this Document resides in.
41  // Namespaces can affect read/write permissions.
42  optional string namespace = 1;
43
44  // REQUIRED: Identifier of the Document; must be unique within the
45  // Document's `namespace`. Otherwise, the new Document will override any
46  // other Documents with the same `namespace`+`uri` that Icing knows about.
47  optional string uri = 2;
48
49  // REQUIRED: Type of the Document. This should match the 'schema_type' of
50  // one of the types given to Icing as part of the overall schema.
51  // See icing.lib.SchemaTypeConfigProto.schema_type for details.
52  optional string schema = 3;
53
54  // OPTIONAL: Seconds since epoch at which the Document was created.
55  // Negative values will lead to validation errors. If not specified, it will
56  // default to when the Icing receives the Document.
57  optional int64 creation_timestamp_ms = 4;
58
59  // REQUIRED: Properties that will be validated against the provided schema.
60  // The names of these properties should map to one of the properties
61  // already defined in the schema for this Document's schema_type.
62  repeated PropertyProto properties = 5;
63
64  // OPTIONAL: Score of the document which could be used during search result
65  // ranking. Negative values will lead to validation errors. The default is the
66  // lowest score 0.
67  optional int32 score = 7 [default = 0];
68
69  // The time-to-live that should be enforced on this Document. Documents get
70  // garbage-collected once the current time exceeds the ttl_ms after the
71  // creation_timestamp_ms. Negative values will lead to validation errors.
72  //
73  // Default value of 0 keeps the Documents till they're explicitly deleted.
74  //
75  // TODO(cassiewang): Benchmark if fixed64 or some other proto type is better
76  // in terms of space/time efficiency. Both for ttl_ms and timestamp fields
77  optional int64 ttl_ms = 8 [default = 0];
78
79  // Defines document level data that's generated internally by Icing.
80  message InternalFields {
81    // The length of the document as a count of tokens (or terms) in all indexed
82    // text properties. This field is used in the computation of BM25F relevance
83    // score.
84    optional int32 length_in_tokens = 1;
85  }
86  optional InternalFields internal_fields = 9;
87
88  reserved 6;
89}
90
91// Holds a property field of the Document.
92// Next tag: 10
93message PropertyProto {
94  // Name of the property.
95  // See icing.lib.PropertyConfigProto.property_name for details.
96  optional string name = 1;
97
98  // Only the field corresponding to the DataType specified in
99  // icing.lib.PropertyConfigProto.data_type should be set.
100  repeated string string_values = 2;
101  repeated int64 int64_values = 3;
102  repeated double double_values = 4;
103  repeated bool boolean_values = 5;
104  repeated bytes bytes_values = 6;
105  repeated DocumentProto document_values = 7;
106
107  message VectorProto {
108    // The values of the vector.
109    repeated float values = 1 [packed = true];
110    // The model signature of the vector, which can be any string used to
111    // identify the model, so that embedding searches can be restricted only to
112    // the vectors with the matching target signature.
113    // Eg: "universal-sentence-encoder_v0"
114    optional string model_signature = 2;
115  }
116  repeated VectorProto vector_values = 8;
117
118  // Holds a blob handle field of the property.
119  // Next tag: 4
120  message BlobHandleProto {
121    // The sha-256 hashed digest for a blob.
122    optional bytes digest = 1;
123
124    // The namespace of the blob.
125    optional string namespace = 3;
126
127    reserved 2;
128  }
129  repeated BlobHandleProto blob_handle_values = 9;
130}
131
132// Holds a list of PutResultProto.
133// Next tag: 4
134message BatchPutResultProto {
135  // The overall status of doing the batch put. It is independent of the status
136  // of the individual PutResultProtos. E.g. we may still return OK here even if
137  // all the PutResultProto have errors. Or return INTERNAL_ERROR if there is
138  // some issue parsing this proto, even if all documents are indexed
139  // successfully.
140  optional StatusProto status = 3;
141  repeated PutResultProto put_result_protos = 1;
142
143  // The result of calling PersistToDisk at the end of the BatchPut request if
144  // PutDocumentRequest.persist_type is set.
145  optional PersistToDiskResultProto persist_to_disk_result_proto = 2;
146}
147
148// Result of a call to IcingSearchEngine.Put
149// Next tag: 5
150message PutResultProto {
151  // Status code can be one of:
152  //   OK
153  //   FAILED_PRECONDITION
154  //   NOT_FOUND
155  //   INTERNAL
156  //   OUT_OF_SPACE
157  //
158  // See status.proto for more details.
159  //
160  // TODO(b/147699081): Fix error codes: +ABORTED
161  // go/icing-library-apis.
162  optional StatusProto status = 1;
163
164  // The uri of the document that was put.
165  optional string uri = 4;
166
167  // Stats of the function call. Inside PutDocumentStatsProto, the function
168  // call latency 'latency_ms' will always be populated. The other fields will
169  // be accurate only when the status above is OK. See logging.proto for
170  // details.
171  optional PutDocumentStatsProto put_document_stats = 2;
172
173  // Whether or not the document was a replacement of an existing document.
174  optional bool was_replacement = 3;
175}
176
177// Result of a call to IcingSearchEngine.Get
178// Next tag: 4
179message GetResultProto {
180  // Status code can be one of:
181  //   OK
182  //   FAILED_PRECONDITION
183  //   NOT_FOUND
184  //   INTERNAL
185  //
186  // See status.proto for more details.
187  //
188  // TODO(b/147699081): Fix error codes: +ABORTED, -INTERNAL.
189  // go/icing-library-apis.
190  optional StatusProto status = 1;
191
192  // The uri of the document that was retrieved, or failed to be retrieved.
193  // It won't be set now for a single Get call, as the caller knows the uri if
194  // the Get fails.
195  // TODO(b/404275015) We should always set this field in Get once we refactor
196  // the tests.
197  optional string uri = 3;
198
199  // Copy of the Document proto with the specified name_space, uri. Modifying
200  // this does not affect the Document in IcingSearchEngine.
201  optional DocumentProto document = 2;
202}
203
204// Result of a call to IcingSearchEngine.BatchGet
205// Next tag: 3
206message BatchGetResultProto {
207  optional StatusProto status = 1;
208  repeated GetResultProto get_result_protos = 2;
209}
210
211// Result of a call to IcingSearchEngine.GetAllNamespaces
212// Next tag: 3
213message GetAllNamespacesResultProto {
214  // Status code can be one of:
215  //   OK
216  //
217  // See status.proto for more details.
218  optional StatusProto status = 1;
219
220  // List of namespaces which have at least one existing document in it (not
221  // deleted and not expired). Order of namespaces is undefined.
222  repeated string namespaces = 2;
223}
224
225// Result of a call to IcingSearchEngine.Delete
226// Next tag: 3
227message DeleteResultProto {
228  // Status code can be one of:
229  //   OK
230  //   FAILED_PRECONDITION
231  //   NOT_FOUND
232  //   INTERNAL
233  //
234  // See status.proto for more details.
235  //
236  // TODO(b/147699081): Fix error codes: +ABORTED.
237  // go/icing-library-apis.
238  optional StatusProto status = 1;
239
240  // Stats for delete execution performance.
241  optional DeleteStatsProto delete_stats = 2;
242}
243
244// Result of a call to IcingSearchEngine.DeleteByNamespace
245// Next tag: 3
246message DeleteByNamespaceResultProto {
247  // Status code can be one of:
248  //   OK
249  //   FAILED_PRECONDITION
250  //   NOT_FOUND
251  //   INTERNAL
252  //
253  // See status.proto for more details.
254  //
255  // TODO(b/147699081): Fix error codes: +ABORTED.
256  // go/icing-library-apis.
257  optional StatusProto status = 1;
258
259  // Stats for delete execution performance.
260  optional DeleteStatsProto delete_stats = 2;
261}
262
263// Result of a call to IcingSearchEngine.DeleteBySchemaType
264// Next tag: 3
265message DeleteBySchemaTypeResultProto {
266  // Status code can be one of:
267  //   OK
268  //   FAILED_PRECONDITION
269  //   NOT_FOUND
270  //   INTERNAL
271  //
272  // See status.proto for more details.
273  //
274  // TODO(b/147699081): Fix error codes: +ABORTED.
275  // go/icing-library-apis.
276  optional StatusProto status = 1;
277
278  // Stats for delete execution performance.
279  optional DeleteStatsProto delete_stats = 2;
280}
281
282// Result of a call to IcingSearchEngine.DeleteByQuery
283// Next tag: 5
284message DeleteByQueryResultProto {
285  // Status code can be one of:
286  //   OK
287  //   FAILED_PRECONDITION
288  //   NOT_FOUND
289  //   INTERNAL
290  //
291  // See status.proto for more details.
292  //
293  // TODO(b/147699081): Fix error codes: +ABORTED.
294  // go/icing-library-apis.
295  optional StatusProto status = 1;
296
297  // Stats for delete execution performance.
298  optional DeleteByQueryStatsProto delete_by_query_stats = 3;
299
300  // Used by DeleteByQueryResultProto to return information about deleted
301  // documents.
302  message DocumentGroupInfo {
303    optional string namespace = 1;
304    optional string schema = 2;
305    repeated string uris = 3;
306  }
307
308  // Additional return message that shows the uris of the deleted documents, if
309  // users set return_deleted_document_info to true.
310  // The result is grouped by the corresponding namespace and type.
311  repeated DocumentGroupInfo deleted_documents = 4;
312
313  reserved 2;
314}
315