com.google.appengine.api.search

## Interface Index

-     public interface Index

  An Index allows synchronous and asynchronous adding and deleting of `Documents` as well as synchronous and asynchronous searching for Documents for a given `Query`. 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"));

        // Create a document.
        Document document = 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();

        // Put the document.
        try {
          index.put(document);
        } catch (PutException e) {
          if (StatusCode.TRANSIENT_ERROR.equals(e.getOperationResult().getCode())) {
            // retry putting document
          }
        }

        // Query the index.
        try {
          Results<ScoredDocument> results =
              index.search(Query.newBuilder().build("subject:first body:here"));

          // Iterate through the search results.
          for (ScoredDocument document : results) {
            // display results
          }
        } catch (SearchException e) {
          if (StatusCode.TRANSIENT_ERROR.equals(e.getOperationResult().getCode())) {
            // retry
          }
        }

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `AddResponse` | `add(Document... documents)` Deprecated. as of 1.7.3. Use `put(Document...)` instead
    `AddResponse` | `add(Document.Builder... builders)` Deprecated. as of 1.7.3. Use `put(Document.Builder...)` instead
    `AddResponse` | `add(java.lang.Iterable<Document> documents)` Deprecated. as of 1.7.3. Use `#put(Iterable)` instead
    `java.util.concurrent.Future<AddResponse>` | `addAsync(Document... document)` Deprecated. as of 1.7.3. Use `putAsync(Document...)` instead
    `java.util.concurrent.Future<AddResponse>` | `addAsync(Document.Builder... document)` Deprecated. as of 1.7.3. Use `putAsync(Document.Builder...)` instead
    `java.util.concurrent.Future<AddResponse>` | `addAsync(java.lang.Iterable<Document> documents)` Deprecated. as of 1.7.3. Use `#putAsync(Iterable)` instead
    `void` | `delete(java.lang.Iterable<java.lang.String> documentIds)`
    `void` | `delete(java.lang.String... documentIds)` Delete documents for the given document ids from the index if they are in the index.
    `java.util.concurrent.Future<java.lang.Void>` | `deleteAsync(java.lang.Iterable<java.lang.String> documentIds)`
    `java.util.concurrent.Future<java.lang.Void>` | `deleteAsync(java.lang.String... documentId)`
    `void` | `deleteSchema()` Deprecated. as of 1.7.4
    `java.util.concurrent.Future<java.lang.Void>` | `deleteSchemaAsync()` Deprecated. as of 1.7.4
    `Document` | `get(java.lang.String documentId)` Gets a `Document` for the given document Id.
    `Consistency` | `getConsistency()` Deprecated. As of 1.7.3 Consistency is deprecated since only PER_DOCUMENT mode is supported
    `java.lang.String` | `getName()`
    `java.lang.String` | `getNamespace()`
    `GetResponse<Document>` | `getRange(GetRequest.Builder builder)`
    `GetResponse<Document>` | `getRange(GetRequest request)` Get an index's documents, in document Id order.
    `java.util.concurrent.Future<GetResponse<Document>>` | `getRangeAsync(GetRequest.Builder builder)`
    `java.util.concurrent.Future<GetResponse<Document>>` | `getRangeAsync(GetRequest request)`
    `Schema` | `getSchema()`
    `ListResponse<Document>` | `listDocuments(ListRequest request)` Deprecated. as of 1.7.3. Use `getRange(GetRequest)` instead.
    `java.util.concurrent.Future<ListResponse<Document>>` | `listDocumentsAsync(ListRequest request)` Deprecated. as of 1.7.3. Use `getRangeAsync(GetRequest)`
    `PutResponse` | `put(Document... documents)` Put the documents into the index, updating any document that is already present.
    `PutResponse` | `put(Document.Builder... builders)`
    `PutResponse` | `put(java.lang.Iterable<Document> documents)`
    `java.util.concurrent.Future<PutResponse>` | `putAsync(Document... document)`
    `java.util.concurrent.Future<PutResponse>` | `putAsync(Document.Builder... document)`
    `java.util.concurrent.Future<PutResponse>` | `putAsync(java.lang.Iterable<Document> documents)`
    `void` | `remove(java.lang.Iterable<java.lang.String> documentIds)` Deprecated. as of 1.7.3. Use `#delete(Iterable)` instead
    `void` | `remove(java.lang.String... documentIds)` Deprecated. as of 1.7.3. Use `delete(String...)` instead
    `java.util.concurrent.Future<java.lang.Void>` | `removeAsync(java.lang.Iterable<java.lang.String> documentIds)` Deprecated. as of 1.7.3. Use `#deleteAsync(Iterable)` instead
    `java.util.concurrent.Future<java.lang.Void>` | `removeAsync(java.lang.String... documentId)` Deprecated. as of 1.7.3. Use `deleteAsync(String...)` instead
    `Results<ScoredDocument>` | `search(Query query)` Search the index for documents matching the query.
    `Results<ScoredDocument>` | `search(java.lang.String query)`
    `java.util.concurrent.Future<Results<ScoredDocument>>` | `searchAsync(Query query)`
    `java.util.concurrent.Future<Results<ScoredDocument>>` | `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

          @Deprecated
          Consistency getConsistency()

      Deprecated. As of 1.7.3 Consistency is deprecated since only PER_DOCUMENT mode is supported
      Returns:
        the consistency mode of this index

    - #### removeAsync

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

      Deprecated. as of 1.7.3. Use `deleteAsync(String...)` instead
      See Also:
        `delete(String...)`

    - #### removeAsync

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

      Deprecated. as of 1.7.3. Use `#deleteAsync(Iterable)` instead
      See Also:
        `delete(String...)`

    - #### deleteAsync

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

      See Also:
        `delete(String...)`

    - #### deleteAsync

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

      See Also:
        `delete(String...)`

    - #### deleteSchemaAsync

          @Deprecated
          java.util.concurrent.Future<java.lang.Void> deleteSchemaAsync()

      Deprecated. as of 1.7.4
      See Also:
        `deleteSchema()`

    - #### addAsync

          @Deprecated
          java.util.concurrent.Future<AddResponse> addAsync(Document... document)

      Deprecated. as of 1.7.3. Use `putAsync(Document...)` instead
      See Also:
        `put(Document...)`

    - #### addAsync

          @Deprecated
          java.util.concurrent.Future<AddResponse> addAsync(Document.Builder... document)

      Deprecated. as of 1.7.3. Use `putAsync(Document.Builder...)` instead
      See Also:
        `put(Document...)`

    - #### addAsync

          @Deprecated
          java.util.concurrent.Future<AddResponse> addAsync(java.lang.Iterable<Document> documents)

      Deprecated. as of 1.7.3. Use `#putAsync(Iterable)` instead
      See Also:
        `put(Document...)`

    - #### putAsync

          java.util.concurrent.Future<PutResponse> putAsync(Document... document)

      See Also:
        `put(Document...)`

    - #### putAsync

          java.util.concurrent.Future<PutResponse> putAsync(Document.Builder... document)

      See Also:
        `put(Document...)`

    - #### putAsync

          java.util.concurrent.Future<PutResponse> putAsync(java.lang.Iterable<Document> documents)

      See Also:
        `put(Document...)`

    - #### searchAsync

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

      See Also:
        `search(String)`

    - #### searchAsync

          java.util.concurrent.Future<Results<ScoredDocument>> searchAsync(Query query)

      See Also:
        `search(Query)`

    - #### listDocumentsAsync

          @Deprecated
          java.util.concurrent.Future<ListResponse<Document>> listDocumentsAsync(ListRequest request)

      Deprecated. as of 1.7.3. Use `getRangeAsync(GetRequest)`
      See Also:
        `listDocuments(ListRequest)`

    - #### getRangeAsync

          java.util.concurrent.Future<GetResponse<Document>> getRangeAsync(GetRequest request)

      See Also:
        `getRange(GetRequest)`

    - #### getRangeAsync

          java.util.concurrent.Future<GetResponse<Document>> getRangeAsync(GetRequest.Builder builder)

      See Also:
        `getRange(GetRequest)`

    - #### remove

          @Deprecated
          void remove(java.lang.String... documentIds)

      Deprecated. as of 1.7.3. Use `delete(String...)` instead
      Delete documents for the given document ids from the index if they are in the index.
      Parameters:
        `documentIds` - the ids of documents to remove
      Throws:
        `RemoveException` - if there is a failure in the search service deleting documents
        `java.lang.IllegalArgumentException` - if some document id is invalid

    - #### remove

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

      Deprecated. as of 1.7.3. Use `#delete(Iterable)` instead
      See Also:
        `delete(String...)`

    - #### delete

          void delete(java.lang.String... documentIds)

      Delete documents for the given document ids from the index if they are in the index.
      Parameters:
        `documentIds` - the ids of documents to delete
      Throws:
        `DeleteException` - if there is a failure in the search service deleting documents
        `java.lang.IllegalArgumentException` - if some document id is invalid

    - #### delete

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

      See Also:
        `delete(String...)`

    - #### deleteSchema

          @Deprecated
          void deleteSchema()

      Deprecated. as of 1.7.4
      Delete the schema from the index. A possible use may be that there are typed fields which are no longer required. Make sure that you re-index some or all of your documents to enable search again. A sample of documents is required that uses named fields to rebuild the schema.
      Throws:
        `DeleteException` - if there is a failure in the search service deleting the schema

    - #### add

          @Deprecated
          AddResponse add(Document... documents)

      Deprecated. as of 1.7.3. Use `put(Document...)` instead
      Add the documents to the index, updating any document that is already present.
      Parameters:
        `documents` - the documents to add to the index
      Returns:
        an `AddResponse` containing the result 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:
        `AddException` - if there is a failure in the search service adding documents
        `java.lang.IllegalArgumentException` - if some document is invalid or more than `IndexChecker#MAXIMUM_DOCS_PER_REQUEST` documents requested to be added

    - #### add

          @Deprecated
          AddResponse add(Document.Builder... builders)

      Deprecated. as of 1.7.3. Use `put(Document.Builder...)` instead
      See Also:
        `put(Document...)`

    - #### add

          @Deprecated
          AddResponse add(java.lang.Iterable<Document> documents)

      Deprecated. as of 1.7.3. Use `#put(Iterable)` instead
      See Also:
        `put(Document...)`

    - #### put

          PutResponse put(Document... documents)

      Put the documents into the index, updating any document that is already present.
      Parameters:
        `documents` - the documents to put into the index
      Returns:
        an `AddResponse` containing the result of the put 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:
        `PutException` - if there is a failure in the search service putting documents
        `java.lang.IllegalArgumentException` - if some document is invalid or more than `IndexChecker#MAXIMUM_DOCS_PER_REQUEST` documents requested to be put into the index

    - #### put

          PutResponse put(Document.Builder... builders)

      See Also:
        `put(Document...)`

    - #### put

          PutResponse put(java.lang.Iterable<Document> documents)

      See Also:
        `put(Document...)`

    - #### get

          Document get(java.lang.String documentId)

      Gets a `Document` for the given document Id.
      Parameters:
        `documentId` - the identifier for the document to retrieve
      Returns:
        the associated `Document`. can be null

    - #### search

          Results<ScoredDocument> search(java.lang.String query)

      See Also:
        `search(Query)`

    - #### search

          Results<ScoredDocument> search(Query query)

      Search the index for documents matching the query. The query must specify a query string, and optionally, how many documents are requested, how the results are to be sorted, scored and which fields are to be returned.
      Parameters:
        `query` - the fully specified `Query` object
      Returns:
        a `Results` containing `ScoredDocuments`
      Throws:
        `java.lang.IllegalArgumentException` - if the query is invalid
        `SearchQueryException` - if the query string is invalid
        `SearchException` - if there is a failure in the search service performing the search

    - #### listDocuments

          @Deprecated
          ListResponse<Document> listDocuments(ListRequest request)

      Deprecated. as of 1.7.3. Use `getRange(GetRequest)` instead.
      Lists the index's documents, in document Id order.
      Parameters:
        `request` - contains various options restricting which documents are returned.
      Returns:
        a `ListResponse` containing a list of documents from the index
      Throws:
        `java.lang.IllegalArgumentException` - if the list request is invalid

    - #### getRange

          GetResponse<Document> getRange(GetRequest request)

      Get an index's documents, in document Id order.
      Parameters:
        `request` - contains various options restricting which documents are returned.
      Returns:
        a `GetResponse` containing a list of documents from the index
      Throws:
        `java.lang.IllegalArgumentException` - if the get request is invalid

    - #### getRange

          GetResponse<Document> getRange(GetRequest.Builder builder)

      See Also:
        `getRange(GetRequest)`

    - #### 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 `GetIndexesRequest.isSchemaFetched()` is set to true on an `SearchService.getIndexes(com.google.appengine.api.search.GetIndexesRequest)` request