# Index
Date: 2012-02-24

## com.google.appengine.api.search
Interface Index

    public interface Index

An Index allows synchronous adding and deleting of `Documents` as well as synchronous searching for Documents. The following code fragment shows how to add documents, then search the index for documents matching a query.

      // Get the SearchService for the default namespace
      SearchService searchService = SearchServiceFactory.getSearchService();
      // Get the index. If not yet created, create it.
      Index index = searchService.getIndex(
          IndexSpec.newBuilder()
              .setIndexName("indexName")
              .setConsistency(Consistency.PER_DOCUMENT));

      // Create a document.
      Document d = Document.newBuilder()
          .setId("documentId")
          .addField(Field.newBuilder().setName("subject").setText("my first email"))
          .addField(Field.newBuilder().setName("body")
               .setHTML("<html>some content here</html>")
          .build();

      // Add the document.
      try {
        index.add(d);
      } catch (AddDocumentsException e) {
        if (StatusCode.TRANSIENT_ERROR.equals(e.getOperationResult().getCode())) {
          // retry adding document
        }
      }

      // Query the index.
      try {
        SearchResponse response = index.search("subject:first body:here");

        // Iterate through the search results.
        for (SearchResult result : response) {
          Document doc = result.getDocument();
        }
      } catch (SearchException e) {
        if (StatusCode.TRANSIENT_ERROR.equals(e.getOperationResult().getCode())) {
          // retry
        }
      }

Method Summary
`AddDocumentsResponse` `add(Document document)` Add the document, update the document if it is already present.
`AddDocumentsResponse` `add(java.lang.Iterable<Document> documents)` Adds the collection of documents.
`java.util.concurrent.Future<AddDocumentsResponse>` `addAsync(Document document)`
`java.util.concurrent.Future<AddDocumentsResponse>` `addAsync(java.lang.Iterable<Document> documents)`
`Consistency` `getConsistency()`
`java.lang.String` `getName()`
`java.lang.String` `getNamespace()`
`Schema` `getSchema()`
`ListDocumentsResponse` `listDocuments(ListDocumentsRequest request)` Lists the index's documents, in document Id order.
`java.util.concurrent.Future<ListDocumentsResponse>` `listDocumentsAsync(ListDocumentsRequest request)`
`void` `remove(java.lang.Iterable<java.lang.String> documentIds)` Delete documents from the index which have IDs in the `documentIds` collection.
`void` `remove(java.lang.String documentId)` Delete the document with the corresponding document id from the index if it is in the index.
`java.util.concurrent.Future<java.lang.Void>` `removeAsync(java.lang.Iterable<java.lang.String> documentIds)`
`java.util.concurrent.Future<java.lang.Void>` `removeAsync(java.lang.String documentId)`
`SearchResponse` `search(SearchRequest request)` Search the index for documents matching the query in the request.
`SearchResponse` `search(java.lang.String query)` Search the index for documents matching the query.
`java.util.concurrent.Future<SearchResponse>` `searchAsync(SearchRequest request)`
`java.util.concurrent.Future<SearchResponse>` `searchAsync(java.lang.String query)`

Method Detail

### getName

    java.lang.String getName()

  Returns:
    the name of the index

### getNamespace

    java.lang.String getNamespace()

  Returns:
    the namespace of the index name

### getConsistency

    Consistency getConsistency()

  Returns:
    the consistency mode of this index

### removeAsync

    java.util.concurrent.Future<java.lang.Void> removeAsync(java.lang.String documentId)

  See Also:
    `remove(String)`

### removeAsync

    java.util.concurrent.Future<java.lang.Void> removeAsync(java.lang.Iterable<java.lang.String> documentIds)

  See Also:
    `remove(Iterable)`

### addAsync

    java.util.concurrent.Future<AddDocumentsResponse> addAsync(Document document)

  See Also:
    `add(Document)`

### addAsync

    java.util.concurrent.Future<AddDocumentsResponse> addAsync(java.lang.Iterable<Document> documents)

  See Also:
    `add(Iterable)`

### searchAsync

    java.util.concurrent.Future<SearchResponse> searchAsync(java.lang.String query)

  See Also:
    `search(String)`

### searchAsync

    java.util.concurrent.Future<SearchResponse> searchAsync(SearchRequest request)

  See Also:
    `search(SearchRequest)`

### listDocumentsAsync

    java.util.concurrent.Future<ListDocumentsResponse> listDocumentsAsync(ListDocumentsRequest request)

  See Also:
    `listDocuments(ListDocumentsRequest)`

### remove

    void remove(java.lang.String documentId)

  Delete the document with the corresponding document id from the index if it is in the index. If no document exists for the document id, then the request is ignored.

  Parameters:
    `documentId` - the id of the document to remove
  Throws:
    `RemoveDocumentsException` - if there is a failure in the search service deleting documents
    `java.lang.IllegalArgumentException` - if the document id is invalid

### remove

    void remove(java.lang.Iterable<java.lang.String> documentIds)

  Delete documents from the index which have IDs in the `documentIds` collection. If the index does not have a document for a given document id, that is ignored. For globally consistent indexes either all or none of documents are removed. For per-document consistent indexes, if some documents are not successfully removed, their IDs are reported in the `RemoveDocumentsException`

  Parameters:
    `documentIds` - the IDs of documents which are to be removed from the index
  Throws:
    `RemoveDocumentsException` - if there is a failure in the search service deleting documents
    `java.lang.IllegalArgumentException` - if the document id collection is invalid or larger than `IndexChecker#MAXIMUM_DOCS_PER_REQUEST`.

### add

    AddDocumentsResponse add(Document document)

  Add the document, update the document if it is already present.

  Parameters:
    `document` - the document to add to the index
  Returns:
    an `AddDocumentsResponse` containing the result of the add operation indicating success or failure as well as the document id. The search service will allocate document ids for documents which have none provided
  Throws:
    `AddDocumentsException` - if there is a failure in the search service adding documents
    `java.lang.IllegalArgumentException` - if the document is invalid

### add

    AddDocumentsResponse add(java.lang.Iterable<Document> documents)

  Adds the collection of documents. If any of the documents are already in the index, then update them with their corresponding fresh document. If any of the documents fail to be added, then none of the documents will be added.

  Parameters:
    `documents` - the documents to add to the index
  Returns:
    an `AddDocumentsResponse` containing the results of the add operations indicating success or failure as well as the document Ids. The search service will allocate document ids for documents which have none provided
  Throws:
    `AddDocumentsException` - if there is a failure in the search service adding documents
    `java.lang.IllegalArgumentException` - if the document collection is invalid or larger than `IndexChecker#MAXIMUM_DOCS_PER_REQUEST`.

### search

    SearchResponse search(java.lang.String query)

  Search the index for documents matching the query.

  Parameters:
    `query` - the query to match against documents in the index
  Returns:
    a `SearchResponse` containing the search results
  Throws:
    `java.lang.IllegalArgumentException` - if the query is null
    `SearchQueryException` - if the query is invalid
    `SearchException` - if there is a failure in the search service performing the search

### search

    SearchResponse search(SearchRequest request)

  Search the index for documents matching the query in the request. The search request must specify a query, how many documents are requested, how the results are to be sorted, scored and which fields are to be returned.

  Parameters:
    `request` - the fully specified search request
  Returns:
    a `SearchResponse` containing the search results
  Throws:
    `java.lang.IllegalArgumentException` - if the search request is invalid
    `SearchQueryException` - if the query is invalid
    `SearchException` - if there is a failure in the search service performing the search

### listDocuments

    ListDocumentsResponse listDocuments(ListDocumentsRequest request)

  Lists the index's documents, in document Id order.

  Parameters:
    `request` - contains various options restricting which documents are returned.
  Returns:
    a `ListDocumentsResponse` containing a list of documents from the index
  Throws:
    `java.lang.IllegalArgumentException` - if the list documents request is invalid

### getSchema

    Schema getSchema()

  Returns:
    the `Schema` describing supported document field names and `Field.FieldType`s supported for those field names. This schema will only be populated if the `ListIndexesRequest.isSchemaFetched()` is set to true on an `SearchService.listIndexes(com.google.appengine.api.search.ListIndexesRequest)` request