1 // Copyright 2010 Google Inc. All Rights Reserved.
3 package com
.google
.appengine
.api
.search
;
5 import java
.util
.concurrent
.Future
;
8 * An Index allows synchronous and asynchronous adding and deleting of
9 * {@link Document Documents} as well as synchronous and asynchronous
10 * searching for Documents for a given {@link Query}. The following
11 * code fragment shows how to add documents, then search the index for
12 * documents matching a query.
15 * // Get the SearchService for the default namespace
16 * SearchService searchService = SearchServiceFactory.getSearchService();
17 * // Get the index. If not yet created, create it.
18 * Index index = searchService.getIndex(
19 * IndexSpec.newBuilder().setIndexName("indexName"));
21 * // Create a document.
22 * Document document = Document.newBuilder()
23 * .setId("documentId")
24 * .addField(Field.newBuilder().setName("subject").setText("my first email"))
25 * .addField(Field.newBuilder().setName("body")
26 * .setHTML("<html>some content here</html>")
29 * // Put the document.
31 * index.put(document);
32 * } catch (PutException e) {
33 * if (StatusCode.TRANSIENT_ERROR.equals(e.getOperationResult().getCode())) {
34 * // retry putting document
40 * Results<ScoredDocument> results =
41 * index.search(Query.newBuilder().build("subject:first body:here"));
43 * // Iterate through the search results.
44 * for (ScoredDocument document : results) {
47 * } catch (SearchException e) {
48 * if (StatusCode.TRANSIENT_ERROR.equals(e.getOperationResult().getCode())) {
55 public interface Index
{
58 * @return the name of the index
63 * @return the namespace of the index name
65 String
getNamespace();
68 * @see #delete(String...)
70 Future
<Void
> deleteAsync(String
... documentId
);
73 * @see #delete(String...)
75 Future
<Void
> deleteAsync(Iterable
<String
> documentIds
);
78 * @see #deleteSchema()
79 * @deprecated as of 1.7.4
82 Future
<Void
> deleteSchemaAsync();
85 * @see #put(Document...)
87 Future
<PutResponse
> putAsync(Document
... document
);
90 * @see #put(Document...)
92 Future
<PutResponse
> putAsync(Document
.Builder
... document
);
95 * @see #put(Document...)
97 Future
<PutResponse
> putAsync(Iterable
<Document
> documents
);
100 * @see #search(String)
102 Future
<Results
<ScoredDocument
>> searchAsync(String query
);
105 * @see #search(Query)
107 Future
<Results
<ScoredDocument
>> searchAsync(Query query
);
110 * @see #getRange(GetRequest)
112 Future
<GetResponse
<Document
>> getRangeAsync(GetRequest request
);
115 * @see #getRange(GetRequest)
117 Future
<GetResponse
<Document
>> getRangeAsync(GetRequest
.Builder builder
);
120 * Delete documents for the given document ids from the index if
121 * they are in the index.
123 * @param documentIds the ids of documents to delete
124 * @throws DeleteException if there is a failure in the search
125 * service deleting documents
126 * @throws IllegalArgumentException if some document id is invalid
128 void delete(String
... documentIds
);
131 * @see #delete(String...)
133 void delete(Iterable
<String
> documentIds
);
136 * Delete the schema from the index. A possible use may be that there are
137 * typed fields which are no longer required. Make sure that you re-index
138 * some or all of your documents to enable search again. A sample of
139 * documents is required that uses named fields to rebuild the schema.
141 * @throws DeleteException if there is a failure in the search service
142 * deleting the schema
143 * @deprecated as of 1.7.4
149 * Put the documents into the index, updating any document that is already
152 * @param documents the documents to put into the index
153 * @return an {@link PutResponse} containing the result of
154 * the put operations indicating success or failure as well as the document
155 * ids. The search service will allocate document ids for documents which
157 * @throws PutException if there is a failure in the search
158 * service putting documents
159 * @throws IllegalArgumentException if some document is invalid or
160 * more than {@link IndexChecker#MAXIMUM_DOCS_PER_REQUEST} documents
161 * requested to be put into the index
163 PutResponse
put(Document
... documents
);
166 * @see #put(Document...)
168 PutResponse
put(Document
.Builder
... builders
);
171 * @see #put(Document...)
173 PutResponse
put(Iterable
<Document
> documents
);
176 * Gets a {@link Document} for the given document Id.
178 * @param documentId the identifier for the document to retrieve
179 * @return the associated {@link Document}. can be null
181 Document
get(String documentId
);
184 * Search the index for documents matching the query string.
186 * @param query the query string
187 * @return a {@link Results} containing
188 * {@link ScoredDocument ScoredDocuments}
189 * @throws SearchQueryException if the query string is invalid
190 * @throws SearchException if there is a failure in the search service
191 * performing the search
192 * @see #search(Query)
194 Results
<ScoredDocument
> search(String query
);
197 * Search the index for documents matching the query. The query
198 * must specify a query string, and optionally, how many documents
199 * are requested, how the results are to be sorted, scored and
200 * which fields are to be returned.
202 * @param query the fully specified {@link Query} object
203 * @return a {@link Results} containing
204 * {@link ScoredDocument ScoredDocuments}
205 * @throws IllegalArgumentException if the query is invalid
206 * @throws SearchQueryException if the query string is invalid
207 * @throws SearchException if there is a failure in the search service
208 * performing the search
210 Results
<ScoredDocument
> search(Query query
);
213 * Get an index's documents, in document Id order.
215 * @param request contains various options restricting which documents are
217 * @return a {@link GetResponse} containing a list of
218 * documents from the index
219 * @throws IllegalArgumentException if the get request is invalid
221 GetResponse
<Document
> getRange(GetRequest request
);
224 * @see #getRange(GetRequest)
226 GetResponse
<Document
> getRange(GetRequest
.Builder builder
);
229 * @return the {@link Schema} describing supported document field names and
230 * {@link Field.FieldType}s supported for those field names. This schema
231 * will only be populated if the {@link GetIndexesRequest#isSchemaFetched}
232 * is set to {@code true} on a {@link SearchService#getIndexes} request
237 * @return a rough approximation of the amount of storage space
238 * currently used by this index, expressed in bytes
239 * @throws UnsupportedOperationException if called on an Index
240 * object that is not the result of a
241 * {@link SearchService#getIndexes} request
243 long getStorageUsage();
246 * @return the maximum amount of storage space that the application
247 * may use in this index, expressed in bytes
248 * @throws UnsupportedOperationException if called on an Index
249 * object that is not the result of a
250 * {@link SearchService#getIndexes}
252 long getStorageLimit();