CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/maven-com-google-genai--google-genai

Java idiomatic SDK for the Gemini Developer APIs and Vertex AI APIs

Overview
Eval results
Files

file-search-stores.mddocs/

File Search Stores and Documents

Create and manage file search stores for Retrieval-Augmented Generation (RAG). File search stores enable semantic search over uploaded documents, allowing AI models to ground their responses in your custom knowledge base.

Core Imports

import com.google.genai.FileSearchStores;
import com.google.genai.Documents;
import com.google.genai.AsyncFileSearchStores;
import com.google.genai.AsyncDocuments;
import com.google.genai.Pager;
import com.google.genai.types.FileSearchStore;
import com.google.genai.types.Document;
import com.google.genai.types.CreateFileSearchStoreConfig;
import com.google.genai.types.GetFileSearchStoreConfig;
import com.google.genai.types.DeleteFileSearchStoreConfig;
import com.google.genai.types.ListFileSearchStoresConfig;
import com.google.genai.types.ImportFileOperation;
import com.google.genai.types.UploadToFileSearchStoreOperation;
import com.google.genai.types.UploadToFileSearchStoreConfig;
import com.google.genai.types.ImportFileConfig;
import java.util.concurrent.CompletableFuture;

Capabilities

File Search Stores

Create semantic search stores and upload documents for RAG applications.

Documents

Manage documents within file search stores.

FileSearchStores Service

package com.google.genai;

public final class FileSearchStores {
  public final Documents documents;

  // Create and manage stores
  public FileSearchStore create(CreateFileSearchStoreConfig config);
  public FileSearchStore get(String name, GetFileSearchStoreConfig config);
  public void delete(String name, DeleteFileSearchStoreConfig config);
  public Pager<FileSearchStore> list(ListFileSearchStoresConfig config);

  // Upload and import files
  public UploadToFileSearchStoreOperation uploadToFileSearchStore(
      String storeName,
      java.io.File file,
      UploadToFileSearchStoreConfig config);

  public UploadToFileSearchStoreOperation uploadToFileSearchStore(
      String storeName,
      byte[] bytes,
      UploadToFileSearchStoreConfig config);

  public UploadToFileSearchStoreOperation uploadToFileSearchStore(
      String storeName,
      InputStream inputStream,
      long size,
      UploadToFileSearchStoreConfig config);

  public UploadToFileSearchStoreOperation uploadToFileSearchStore(
      String storeName,
      String filePath,
      UploadToFileSearchStoreConfig config);

  public ImportFileOperation importFile(
      String fileSearchStoreName,
      String fileName,
      ImportFileConfig config);
}

AsyncFileSearchStores Service

package com.google.genai;

public final class AsyncFileSearchStores {
  public final AsyncDocuments documents;

  public CompletableFuture<FileSearchStore> create(CreateFileSearchStoreConfig config);
  public CompletableFuture<FileSearchStore> get(String name, GetFileSearchStoreConfig config);
  public CompletableFuture<Void> delete(String name, DeleteFileSearchStoreConfig config);
  public CompletableFuture<AsyncPager<FileSearchStore>> list(ListFileSearchStoresConfig config);

  public CompletableFuture<UploadToFileSearchStoreOperation> uploadToFileSearchStore(
      String storeName,
      java.io.File file,
      UploadToFileSearchStoreConfig config);

  public CompletableFuture<UploadToFileSearchStoreOperation> uploadToFileSearchStore(
      String storeName,
      byte[] bytes,
      UploadToFileSearchStoreConfig config);

  public CompletableFuture<UploadToFileSearchStoreOperation> uploadToFileSearchStore(
      String storeName,
      InputStream inputStream,
      long size,
      UploadToFileSearchStoreConfig config);

  public CompletableFuture<UploadToFileSearchStoreOperation> uploadToFileSearchStore(
      String storeName,
      String filePath,
      UploadToFileSearchStoreConfig config);

  public CompletableFuture<ImportFileOperation> importFile(
      String fileSearchStoreName,
      String fileName,
      ImportFileConfig config);
}

Documents Service

package com.google.genai;

public final class Documents {
  public Document get(String name, GetDocumentConfig config);
  public void delete(String name, DeleteDocumentConfig config);
  public Pager<Document> list(String parent, ListDocumentsConfig config);
}

AsyncDocuments Service

package com.google.genai;

public final class AsyncDocuments {
  public CompletableFuture<Document> get(String name, GetDocumentConfig config);
  public CompletableFuture<Void> delete(String name, DeleteDocumentConfig config);
  public CompletableFuture<AsyncPager<Document>> list(String parent, ListDocumentsConfig config);
}

FileSearchStore Type

package com.google.genai.types;

public final class FileSearchStore {
  public static Builder builder();

  public Optional<String> name();
  public Optional<String> displayName();
  public Optional<String> createTime();
  public Optional<String> updateTime();
}

Document Type

package com.google.genai.types;

public final class Document {
  public static Builder builder();

  public Optional<String> name();
  public Optional<String> displayName();
  public Optional<String> createTime();
  public Optional<String> updateTime();
  public Optional<Map<String, String>> customMetadata();
}

Configuration Types

Create File Search Store Config

package com.google.genai.types;

public final class CreateFileSearchStoreConfig {
  public static Builder builder();

  public Optional<String> displayName();
  public Optional<HttpOptions> httpOptions();
}

Upload to File Search Store Config

package com.google.genai.types;

public final class UploadToFileSearchStoreConfig {
  public static Builder builder();

  public Optional<String> displayName();
  public Optional<String> mimeType();
  public Optional<Map<String, String>> customMetadata();
  public Optional<HttpOptions> httpOptions();
}

Import File Config

package com.google.genai.types;

public final class ImportFileConfig {
  public static Builder builder();

  public Optional<Map<String, String>> customMetadata();
  public Optional<HttpOptions> httpOptions();
}

Operation Types

Upload to File Search Store Operation

package com.google.genai.types;

public final class UploadToFileSearchStoreOperation {
  public Optional<Document> document();
  public Optional<String> name();
}

Import File Operation

package com.google.genai.types;

public final class ImportFileOperation {
  public Optional<Document> document();
  public Optional<String> name();
}

Create File Search Store

Basic Creation

import com.google.genai.Client;
import com.google.genai.types.FileSearchStore;
import com.google.genai.types.CreateFileSearchStoreConfig;

Client client = new Client();

CreateFileSearchStoreConfig config = CreateFileSearchStoreConfig.builder()
    .displayName("Product Documentation Store")
    .build();

FileSearchStore store = client.fileSearchStores.create(config);

System.out.println("Created store: " + store.name().orElse("N/A"));
System.out.println("Display name: " + store.displayName().orElse("N/A"));

Create Without Config

FileSearchStore store = client.fileSearchStores.create(null);
System.out.println("Store created: " + store.name().orElse("N/A"));

Upload Documents to Store

Upload from File Path

import com.google.genai.types.UploadToFileSearchStoreOperation;

String storeName = "fileSearchStores/store123";

UploadToFileSearchStoreConfig config = UploadToFileSearchStoreConfig.builder()
    .displayName("Product Manual")
    .mimeType("application/pdf")
    .customMetadata(Map.of(
        "category", "manual",
        "version", "2.0"
    ))
    .build();

UploadToFileSearchStoreOperation operation =
    client.fileSearchStores.uploadToFileSearchStore(
        storeName,
        "path/to/product-manual.pdf",
        config
    );

operation.document().ifPresent(doc -> {
    System.out.println("Uploaded document: " + doc.name().orElse("N/A"));
    System.out.println("Display name: " + doc.displayName().orElse("N/A"));
});

Upload from File Object

import java.io.File as JavaFile;

JavaFile file = new JavaFile("path/to/document.pdf");

UploadToFileSearchStoreOperation operation =
    client.fileSearchStores.uploadToFileSearchStore(
        storeName,
        file,
        UploadToFileSearchStoreConfig.builder()
            .displayName(file.getName())
            .mimeType("application/pdf")
            .build()
    );

Upload from Bytes

import java.nio.file.Files;
import java.nio.file.Paths;

byte[] documentBytes = Files.readAllBytes(Paths.get("document.pdf"));

UploadToFileSearchStoreOperation operation =
    client.fileSearchStores.uploadToFileSearchStore(
        storeName,
        documentBytes,
        UploadToFileSearchStoreConfig.builder()
            .displayName("Uploaded Document")
            .mimeType("application/pdf")
            .build()
    );

Upload from InputStream

import java.io.FileInputStream;

try (FileInputStream inputStream = new FileInputStream("document.pdf")) {
    long fileSize = new JavaFile("document.pdf").length();

    UploadToFileSearchStoreOperation operation =
        client.fileSearchStores.uploadToFileSearchStore(
            storeName,
            inputStream,
            fileSize,
            UploadToFileSearchStoreConfig.builder()
                .displayName("Streamed Document")
                .mimeType("application/pdf")
                .build()
        );
}

Batch Upload Multiple Documents

List<String> documentPaths = List.of(
    "doc1.pdf", "doc2.pdf", "doc3.pdf"
);

for (String path : documentPaths) {
    UploadToFileSearchStoreOperation operation =
        client.fileSearchStores.uploadToFileSearchStore(
            storeName,
            path,
            UploadToFileSearchStoreConfig.builder()
                .displayName(new JavaFile(path).getName())
                .mimeType("application/pdf")
                .build()
        );

    System.out.println("Uploaded: " + path);
}

Import Existing Files

Import from Files API

import com.google.genai.types.File;
import com.google.genai.types.ImportFileOperation;

// First upload file using Files API
File uploadedFile = client.files.upload("document.pdf", null);

// Then import it into file search store
ImportFileConfig config = ImportFileConfig.builder()
    .customMetadata(Map.of("source", "files-api"))
    .build();

ImportFileOperation importOp = client.fileSearchStores.importFile(
    storeName,
    uploadedFile.name().get(),
    config
);

importOp.document().ifPresent(doc -> {
    System.out.println("Imported: " + doc.name().orElse("N/A"));
});

Manage File Search Stores

Get Store Information

FileSearchStore store = client.fileSearchStores.get(
    "fileSearchStores/store123",
    null
);

System.out.println("Name: " + store.name().orElse("N/A"));
System.out.println("Display name: " + store.displayName().orElse("N/A"));
System.out.println("Created: " + store.createTime().orElse("N/A"));
System.out.println("Updated: " + store.updateTime().orElse("N/A"));

List All Stores

import com.google.genai.Pager;

Pager<FileSearchStore> pager = client.fileSearchStores.list(null);

for (FileSearchStore store : pager) {
    System.out.println("Store: " + store.displayName().orElse("N/A"));
    System.out.println("  Name: " + store.name().orElse("N/A"));
    System.out.println("  Created: " + store.createTime().orElse("N/A"));
}

List with Pagination

ListFileSearchStoresConfig config = ListFileSearchStoresConfig.builder()
    .pageSize(10)
    .build();

Pager<FileSearchStore> pager = client.fileSearchStores.list(config);

// Get first page
ImmutableList<FileSearchStore> firstPage = pager.page();
System.out.println("Stores in first page: " + firstPage.size());

Delete Store

client.fileSearchStores.delete("fileSearchStores/store123", null);
System.out.println("Store deleted");

Manage Documents

List Documents in Store

String storeName = "fileSearchStores/store123";

Pager<Document> pager = client.fileSearchStores.documents.list(storeName, null);

for (Document doc : pager) {
    System.out.println("Document: " + doc.displayName().orElse("N/A"));
    System.out.println("  Name: " + doc.name().orElse("N/A"));

    doc.customMetadata().ifPresent(metadata -> {
        System.out.println("  Metadata: " + metadata);
    });
}

Get Document Details

Document doc = client.fileSearchStores.documents.get(
    "fileSearchStores/store123/documents/doc456",
    null
);

System.out.println("Document: " + doc.displayName().orElse("N/A"));
System.out.println("Created: " + doc.createTime().orElse("N/A"));

doc.customMetadata().ifPresent(metadata -> {
    metadata.forEach((key, value) -> {
        System.out.println(key + ": " + value);
    });
});

Delete Document

client.fileSearchStores.documents.delete(
    "fileSearchStores/store123/documents/doc456",
    null
);

System.out.println("Document deleted");

Use with File Search

Configure File Search Tool

import com.google.genai.types.Tool;
import com.google.genai.types.FileSearch;
import com.google.genai.types.GenerateContentConfig;

// Create file search tool referencing the store
FileSearch fileSearch = FileSearch.builder()
    .fileSearchStores(List.of("fileSearchStores/store123"))
    .build();

Tool tool = Tool.builder()
    .fileSearch(fileSearch)
    .build();

GenerateContentConfig config = GenerateContentConfig.builder()
    .tools(List.of(tool))
    .build();

// Use in content generation
GenerateContentResponse response = client.models.generateContent(
    "gemini-2.0-flash",
    "What are the key features mentioned in the product documentation?",
    config
);

System.out.println(response.text());

RAG with Multiple Stores

FileSearch fileSearch = FileSearch.builder()
    .fileSearchStores(List.of(
        "fileSearchStores/store1",
        "fileSearchStores/store2",
        "fileSearchStores/store3"
    ))
    .build();

Tool tool = Tool.builder()
    .fileSearch(fileSearch)
    .build();

GenerateContentConfig config = GenerateContentConfig.builder()
    .tools(List.of(tool))
    .systemInstruction(Content.fromParts(Part.fromText(
        "Answer questions based on the provided documentation. " +
        "Always cite your sources."
    )))
    .build();

GenerateContentResponse response = client.models.generateContent(
    "gemini-2.0-flash",
    "Compare the pricing models across all products",
    config
);

Complete RAG Example

Build Knowledge Base and Query

public class RAGExample {
    public static void main(String[] args) throws Exception {
        Client client = new Client();

        // Step 1: Create file search store
        CreateFileSearchStoreConfig storeConfig =
            CreateFileSearchStoreConfig.builder()
                .displayName("Company Knowledge Base")
                .build();

        FileSearchStore store = client.fileSearchStores.create(storeConfig);
        String storeName = store.name().get();
        System.out.println("Created store: " + storeName);

        // Step 2: Upload documents
        List<String> docPaths = List.of(
            "product-manual.pdf",
            "faq.pdf",
            "technical-specs.pdf"
        );

        for (String path : docPaths) {
            UploadToFileSearchStoreConfig uploadConfig =
                UploadToFileSearchStoreConfig.builder()
                    .displayName(new JavaFile(path).getName())
                    .mimeType("application/pdf")
                    .customMetadata(Map.of("type", "documentation"))
                    .build();

            UploadToFileSearchStoreOperation operation =
                client.fileSearchStores.uploadToFileSearchStore(
                    storeName,
                    path,
                    uploadConfig
                );

            System.out.println("Uploaded: " + path);
        }

        // Step 3: Configure file search
        FileSearch fileSearch = FileSearch.builder()
            .fileSearchStores(List.of(storeName))
            .build();

        Tool tool = Tool.builder()
            .fileSearch(fileSearch)
            .build();

        GenerateContentConfig genConfig = GenerateContentConfig.builder()
            .tools(List.of(tool))
            .temperature(0.2)
            .build();

        // Step 4: Query the knowledge base
        String question = "What is the warranty period for the product?";

        GenerateContentResponse response = client.models.generateContent(
            "gemini-2.0-flash",
            question,
            genConfig
        );

        System.out.println("\nQuestion: " + question);
        System.out.println("Answer: " + response.text());

        // Step 5: Check grounding metadata
        response.candidates().ifPresent(candidates -> {
            if (!candidates.isEmpty()) {
                candidates.get(0).groundingMetadata().ifPresent(metadata -> {
                    System.out.println("\nGrounding sources:");
                    metadata.groundingChunks().ifPresent(chunks -> {
                        chunks.forEach(chunk -> {
                            System.out.println("  - " + chunk);
                        });
                    });
                });
            }
        });

        client.close();
    }
}

Async Operations

Async Store Creation

CompletableFuture<FileSearchStore> future =
    client.async.fileSearchStores.create(
        CreateFileSearchStoreConfig.builder()
            .displayName("Async Store")
            .build()
    );

future.thenAccept(store -> {
    System.out.println("Store created: " + store.name().orElse("N/A"));
});

Async Document Upload

CompletableFuture<UploadToFileSearchStoreOperation> future =
    client.async.fileSearchStores.uploadToFileSearchStore(
        storeName,
        "document.pdf",
        UploadToFileSearchStoreConfig.builder()
            .displayName("Async Upload")
            .mimeType("application/pdf")
            .build()
    );

future.thenAccept(operation -> {
    operation.document().ifPresent(doc -> {
        System.out.println("Uploaded: " + doc.name().orElse("N/A"));
    });
});

Async List Documents

CompletableFuture<AsyncPager<Document>> future =
    client.async.fileSearchStores.documents.list(storeName, null);

future.thenAccept(pager -> {
    pager.forEach(doc -> {
        System.out.println("Document: " + doc.displayName().orElse("N/A"));
    });
});

Best Practices

Organize with Custom Metadata

UploadToFileSearchStoreConfig config = UploadToFileSearchStoreConfig.builder()
    .displayName("Q3 Financial Report")
    .mimeType("application/pdf")
    .customMetadata(Map.of(
        "department", "finance",
        "quarter", "Q3",
        "year", "2024",
        "confidentiality", "internal"
    ))
    .build();

client.fileSearchStores.uploadToFileSearchStore(storeName, "q3-report.pdf", config);

Handle Large Document Sets

// Upload documents in batches
List<String> allDocs = /* large list of document paths */;
int batchSize = 10;

for (int i = 0; i < allDocs.size(); i += batchSize) {
    List<String> batch = allDocs.subList(
        i,
        Math.min(i + batchSize, allDocs.size())
    );

    // Upload batch
    for (String docPath : batch) {
        client.fileSearchStores.uploadToFileSearchStore(
            storeName,
            docPath,
            null
        );
    }

    // Optional: Add delay to avoid rate limits
    Thread.sleep(1000);
}

Clean Up Old Documents

// List all documents
Pager<Document> pager = client.fileSearchStores.documents.list(storeName, null);

LocalDate cutoffDate = LocalDate.now().minusMonths(6);

for (Document doc : pager) {
    doc.createTime().ifPresent(createTimeStr -> {
        // Parse create time and check if older than 6 months
        LocalDate createDate = LocalDate.parse(createTimeStr.substring(0, 10));

        if (createDate.isBefore(cutoffDate)) {
            System.out.println("Deleting old document: " +
                doc.displayName().orElse("N/A"));
            client.fileSearchStores.documents.delete(doc.name().get(), null);
        }
    });
}

Error Handling

try {
    UploadToFileSearchStoreOperation operation =
        client.fileSearchStores.uploadToFileSearchStore(
            storeName,
            "document.pdf",
            null
        );

    System.out.println("Upload successful");
} catch (GenAiIOException e) {
    System.err.println("I/O error: " + e.getMessage());
} catch (ApiException e) {
    System.err.println("API error: " + e.code() + " - " + e.message());
}

Use Cases

Customer Support Knowledge Base

Upload FAQ documents, product manuals, and support articles to provide AI-powered customer support with accurate, grounded responses.

Enterprise Document Search

Build semantic search over internal documentation, policies, and procedures for employee self-service.

Research Assistant

Upload research papers, articles, and reports to create an AI research assistant that can answer questions with citations.

Code Documentation

Index code documentation, API references, and tutorials for an AI coding assistant.

Legal Document Analysis

Upload contracts, regulations, and case law for AI-assisted legal research and analysis.

Install with Tessl CLI

npx tessl i tessl/maven-com-google-genai--google-genai

docs

batch-operations.md

caching.md

chat-sessions.md

client-configuration.md

content-generation.md

embeddings-tokens.md

error-handling.md

file-search-stores.md

files-management.md

image-operations.md

index.md

live-sessions.md

model-tuning.md

operations.md

tools-functions.md

types-reference.md

video-generation.md

tile.json