1 // Copyright 2010 Google Inc. All Rights Reserved.
3 package com
.google
.appengine
.api
.search
;
5 import com
.google
.appengine
.api
.search
.checkers
.IndexChecker
;
7 import java
.util
.concurrent
.Future
;
10 * An Index allows synchronous and asynchronous adding and deleting of
11 * {@link Document Documents} as well as synchronous and asynchronous
12 * searching for Documents for a given {@link Query}. The following
13 * code fragment shows how to add documents, then search the index for
14 * documents matching a query.
17 * // Get the SearchService for the default namespace
18 * SearchService searchService = SearchServiceFactory.getSearchService();
19 * // Get the index. If not yet created, create it.
20 * Index index = searchService.getIndex(
21 * IndexSpec.newBuilder().setIndexName("indexName"));
23 * // Create a document.
24 * Document document = Document.newBuilder()
25 * .setId("documentId")
26 * .addField(Field.newBuilder().setName("subject").setText("my first email"))
27 * .addField(Field.newBuilder().setName("body")
28 * .setHTML("<html>some content here</html>")
31 * // Put the document.
33 * index.put(document);
34 * } catch (PutException e) {
35 * if (StatusCode.TRANSIENT_ERROR.equals(e.getOperationResult().getCode())) {
36 * // retry putting document
42 * Results<ScoredDocument> results =
43 * index.search(Query.newBuilder().build("subject:first body:here"));
45 * // Iterate through the search results.
46 * for (ScoredDocument document : results) {
49 * } catch (SearchException e) {
50 * if (StatusCode.TRANSIENT_ERROR.equals(e.getOperationResult().getCode())) {
57 public interface Index
{
60 * @return the name of the index
65 * @return the namespace of the index name
67 String
getNamespace();
70 * @return the consistency mode of this index
71 * @deprecated As of 1.7.3 Consistency is deprecated since only PER_DOCUMENT
75 Consistency
getConsistency();
78 * @see #delete(String...)
80 Future
<Void
> deleteAsync(String
... documentId
);
83 * @see #delete(String...)
85 Future
<Void
> deleteAsync(Iterable
<String
> documentIds
);
88 * @see #deleteSchema()
89 * @deprecated as of 1.7.4
92 Future
<Void
> deleteSchemaAsync();
95 * @see #put(Document...)
97 Future
<PutResponse
> putAsync(Document
... document
);
100 * @see #put(Document...)
102 Future
<PutResponse
> putAsync(Document
.Builder
... document
);
105 * @see #put(Document...)
107 Future
<PutResponse
> putAsync(Iterable
<Document
> documents
);
110 * @see #search(String)
112 Future
<Results
<ScoredDocument
>> searchAsync(String query
);
115 * @see #search(Query)
117 Future
<Results
<ScoredDocument
>> searchAsync(Query query
);
120 * @see #getRange(GetRequest)
122 Future
<GetResponse
<Document
>> getRangeAsync(GetRequest request
);
125 * @see #getRange(GetRequest)
127 Future
<GetResponse
<Document
>> getRangeAsync(GetRequest
.Builder builder
);
130 * Delete documents for the given document ids from the index if
131 * they are in the index.
133 * @param documentIds the ids of documents to delete
134 * @throws DeleteException if there is a failure in the search
135 * service deleting documents
136 * @throws IllegalArgumentException if some document id is invalid
138 void delete(String
... documentIds
);
141 * @see #delete(String...)
143 void delete(Iterable
<String
> documentIds
);
146 * Delete the schema from the index. A possible use may be that there are
147 * typed fields which are no longer required. Make sure that you re-index
148 * some or all of your documents to enable search again. A sample of
149 * documents is required that uses named fields to rebuild the schema.
151 * @throws DeleteException if there is a failure in the search service
152 * deleting the schema
153 * @deprecated as of 1.7.4
159 * Put the documents into the index, updating any document that is already
162 * @param documents the documents to put into the index
163 * @return an {@link PutResponse} containing the result of
164 * the put operations indicating success or failure as well as the document
165 * ids. The search service will allocate document ids for documents which
167 * @throws PutException if there is a failure in the search
168 * service putting documents
169 * @throws IllegalArgumentException if some document is invalid or
170 * more than {@link IndexChecker#MAXIMUM_DOCS_PER_REQUEST} documents
171 * requested to be put into the index
173 PutResponse
put(Document
... documents
);
176 * @see #put(Document...)
178 PutResponse
put(Document
.Builder
... builders
);
181 * @see #put(Document...)
183 PutResponse
put(Iterable
<Document
> documents
);
186 * Gets a {@link Document} for the given document Id.
188 * @param documentId the identifier for the document to retrieve
189 * @return the associated {@link Document}. can be null
191 Document
get(String documentId
);
194 * @see #search(Query)
196 Results
<ScoredDocument
> search(String query
);
199 * Search the index for documents matching the query. The query
200 * must specify a query string, and optionally, how many documents
201 * are requested, how the results are to be sorted, scored and
202 * which fields are to be returned.
204 * @param query the fully specified {@link Query} object
205 * @return a {@link Results} containing
206 * {@link ScoredDocument ScoredDocuments}
207 * @throws IllegalArgumentException if the query is invalid
208 * @throws SearchQueryException if the query string is invalid
209 * @throws SearchException if there is a failure in the search service
210 * performing the search
212 Results
<ScoredDocument
> search(Query query
);
215 * Get an index's documents, in document Id order.
217 * @param request contains various options restricting which documents are
219 * @return a {@link GetResponse} containing a list of
220 * documents from the index
221 * @throws IllegalArgumentException if the get request is invalid
223 GetResponse
<Document
> getRange(GetRequest request
);
226 * @see #getRange(GetRequest)
228 GetResponse
<Document
> getRange(GetRequest
.Builder builder
);
231 * @return the {@link Schema} describing supported document field names and
232 * {@link Field.FieldType}s supported for those field names. This schema
233 * will only be populated if the {@link GetIndexesRequest#isSchemaFetched}
234 * is set to true on an {@link SearchService#getIndexes} request