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

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `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()` Delete the schema from the index.
    `java.util.concurrent.Future<java.lang.Void>` | `deleteSchemaAsync()`
    `Document` | `get(java.lang.String documentId)` Gets a `Document` for the given document Id.
    `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()`
    `long` | `getStorageLimit()`
    `long` | `getStorageUsage()`
    `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)`
    `Results<ScoredDocument>` | `search(Query query)` Search the index for documents matching the query.
    `Results<ScoredDocument>` | `search(java.lang.String query)` Search the index for documents matching the query string.
    `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

    - #### 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

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

      See Also:
        `deleteSchema()`

    - #### 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)`

    - #### 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)`

    - #### 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

          void deleteSchema()

      Delete the schema from the index. To fully delete an index, you must delete both the index's documents and schema. This method deletes the index's schema, which contains field names and field types of previously indexed documents.
      Throws:
        `DeleteException` - if there is a failure in the search service deleting the schema

    - #### 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 `PutResponse` 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)

      Search the index for documents matching the query string.
      Parameters:
        `query` - the query string
      Returns:
        a `Results` containing `ScoredDocuments`
      Throws:
        `SearchQueryException` - if the query string is invalid
        `SearchException` - if there is a failure in the search service performing the search
      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

    - #### 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 a `SearchService.getIndexes(com.google.appengine.api.search.GetIndexesRequest)` request

    - #### getStorageUsage

          long getStorageUsage()

      Returns:
        a rough approximation of the amount of storage space currently used by this index, expressed in bytes
      Throws:
        `java.lang.UnsupportedOperationException` - if called on an Index object that is not the result of a `SearchService.getIndexes(com.google.appengine.api.search.GetIndexesRequest)` request

    - #### getStorageLimit

          long getStorageLimit()

      Returns:
        the maximum amount of storage space that the application may use in this index, expressed in bytes
      Throws:
        `java.lang.UnsupportedOperationException` - if called on an Index object that is not the result of a `SearchService.getIndexes(com.google.appengine.api.search.GetIndexesRequest)`