Gemini.APIs.FileSearchStores (GeminiEx v0.8.4)

File Search Stores API for semantic search and RAG (Retrieval-Augmented Generation).

File Search Stores enable semantic search over documents using vector embeddings. They are part of the Vertex AI RAG system and provide powerful document search capabilities for grounding generation responses.

Note: This API is only available through Vertex AI authentication.

Overview

The File Search Stores API allows you to:

Create stores for organizing searchable documents
Import files into stores for indexing
Upload files directly to stores
List and manage stores
Delete stores when no longer needed

Workflow

Create a Store: Set up a semantic search store
Import Files: Add documents to the store
Wait for Processing: Documents are indexed asynchronously
Use in Generation: Reference the store for grounded responses

Example: Basic Store Creation

alias Gemini.APIs.FileSearchStores
alias Gemini.Types.CreateFileSearchStoreConfig

# Create a store
config = %CreateFileSearchStoreConfig{
  display_name: "Product Documentation",
  description: "Technical documentation for all products"
}

{:ok, store} = FileSearchStores.create(config, auth: :vertex_ai)
IO.puts("Created: #{store.name}")

# Wait for store to be active
{:ok, ready_store} = FileSearchStores.wait_for_active(store.name)

# Import a file that was already uploaded
{:ok, doc} = FileSearchStores.import_file(
  store.name,
  "files/abc123"
)

Example: Upload and Import

# Upload a file directly to the store
{:ok, doc} = FileSearchStores.upload_to_store(
  store.name,
  "/path/to/document.pdf",
  display_name: "Product Manual"
)

# Wait for document to be processed
{:ok, ready_doc} = FileSearchStores.wait_for_document(doc.name)

Example: List and Cleanup

# List all stores
{:ok, response} = FileSearchStores.list()

Enum.each(response.file_search_stores, fn store ->
  IO.puts("#{store.display_name}: #{store.document_count} docs")
end)

# Delete a store (requires force: true if it has documents)
:ok = FileSearchStores.delete("fileSearchStores/abc123", force: true)

Grounding with File Search

Once documents are indexed, use the store for grounding in generation:

{:ok, response} = Gemini.generate_content(
  "What are the safety features?",
  tools: [
    %{file_search_stores: ["fileSearchStores/abc123"]}
  ]
)

Best Practices

Descriptive Names: Use clear display names for stores
Wait for Processing: Always wait for documents to reach :active state
Batch Imports: Import multiple files before using the store
Monitor Size: Check document_count and total_size_bytes
Clean Up: Delete stores when no longer needed to avoid costs

Summary

Types

create_opts()

delete_opts()

import_opts()

list_opts()

store_opts()

upload_opts()

wait_doc_opts()

wait_opts()

Functions

create(config, opts \\ [])

Create a new file search store.

delete(name, opts \\ [])

Delete a file search store.

get(name, opts \\ [])

Get a file search store by name.

get_document(document_name, opts \\ [])

Get a document from a file search store.

import_file(store_name, file_name, opts \\ [])

Import an already uploaded file into the store.

list(opts \\ [])

List file search stores.

list_all(opts \\ [])

List all file search stores across all pages.

upload_to_store(store_name, file_path, opts \\ [])

Upload a file directly to the store.

wait_for_active(name, opts \\ [])

Wait for a store to become active.

wait_for_document(document_name, opts \\ [])

Wait for a document to finish processing.

Types

create_opts()

@type create_opts() :: [{:auth, :gemini | :vertex_ai}]

delete_opts()

@type delete_opts() :: [force: boolean(), auth: :gemini | :vertex_ai]

import_opts()

@type import_opts() :: [{:auth, :gemini | :vertex_ai}]

list_opts()

@type list_opts() :: [
  page_size: pos_integer(),
  page_token: String.t(),
  auth: :gemini | :vertex_ai
]

store_opts()

@type store_opts() :: [{:auth, :gemini | :vertex_ai}]

upload_opts()

@type upload_opts() :: [
  display_name: String.t(),
  mime_type: String.t(),
  auth: :gemini | :vertex_ai
]

wait_doc_opts()

@type wait_doc_opts() :: [
  poll_interval: pos_integer(),
  timeout: pos_integer(),
  on_status: (Gemini.Types.FileSearchDocument.t() -> any()),
  auth: :gemini | :vertex_ai
]

wait_opts()

@type wait_opts() :: [
  poll_interval: pos_integer(),
  timeout: pos_integer(),
  on_status: (Gemini.Types.FileSearchStore.t() -> any()),
  auth: :gemini | :vertex_ai
]

Functions

create(config, opts \\ [])

@spec create(Gemini.Types.CreateFileSearchStoreConfig.t(), create_opts()) ::
  {:ok, Gemini.Types.FileSearchStore.t()} | {:error, term()}

Create a new file search store.

Creates a semantic search store for organizing and searching documents. The store will be in :creating state initially and will transition to :active once ready.

Parameters

config - CreateFileSearchStoreConfig struct with store configuration
opts - Options (must include auth: :vertex_ai)

Examples

config = %CreateFileSearchStoreConfig{
  display_name: "Product Docs",
  description: "All product documentation"
}

{:ok, store} = FileSearchStores.create(config, auth: :vertex_ai)

# Wait for it to be active
{:ok, active_store} = FileSearchStores.wait_for_active(store.name)

delete(name, opts \\ [])

@spec delete(String.t(), delete_opts()) :: :ok | {:error, term()}

Delete a file search store.

By default, stores with documents cannot be deleted. Use force: true to delete a store and all its documents.

Parameters

name - Store resource name
opts - Delete options

Options

:force - Delete even if store contains documents (default: false)
:auth - Authentication strategy

Examples

# Delete empty store
:ok = FileSearchStores.delete("fileSearchStores/abc123")

# Force delete store with documents
:ok = FileSearchStores.delete(
  "fileSearchStores/abc123",
  force: true
)

get(name, opts \\ [])

@spec get(String.t(), store_opts()) ::
  {:ok, Gemini.Types.FileSearchStore.t()} | {:error, term()}

Get a file search store by name.

Parameters

name - Store resource name (e.g., "fileSearchStores/abc123")
opts - Options

Examples

{:ok, store} = FileSearchStores.get("fileSearchStores/abc123")
IO.puts("State: #{store.state}")
IO.puts("Documents: #{store.document_count}")
IO.puts("Size: #{store.total_size_bytes} bytes")

get_document(document_name, opts \\ [])

@spec get_document(String.t(), store_opts()) ::
  {:ok, Gemini.Types.FileSearchDocument.t()} | {:error, term()}

Get a document from a file search store.

Parameters

document_name - Document resource name
opts - Options

Examples

{:ok, doc} = FileSearchStores.get_document(
  "fileSearchStores/abc/documents/xyz"
)
IO.puts("State: #{doc.state}")

import_file(store_name, file_name, opts \\ [])

@spec import_file(String.t(), String.t(), import_opts()) ::
  {:ok, Gemini.Types.FileSearchDocument.t()} | {:error, term()}

Import an already uploaded file into the store.

The file must have been previously uploaded using the Files API. This creates a document in the store that will be indexed for search.

Parameters

store_name - Store resource name
file_name - File resource name (e.g., "files/abc123")
opts - Options

Examples

# Upload a file first
{:ok, file} = Gemini.upload_file("/path/to/doc.pdf")

# Import it into the store
{:ok, doc} = FileSearchStores.import_file(
  "fileSearchStores/abc123",
  file.name
)

# Wait for processing
{:ok, ready_doc} = FileSearchStores.wait_for_document(doc.name)

list(opts \\ [])

@spec list(list_opts()) ::
  {:ok, Gemini.Types.ListFileSearchStoresResponse.t()} | {:error, term()}

List file search stores.

Parameters

opts - List options

Options

:page_size - Number of stores per page (default: 100)
:page_token - Token from previous response for pagination
:auth - Authentication strategy

Examples

# List all stores
{:ok, response} = FileSearchStores.list()

Enum.each(response.file_search_stores, fn store ->
  IO.puts("#{store.display_name}: #{store.state}")
end)

# With pagination
{:ok, page1} = FileSearchStores.list(page_size: 10)
if ListFileSearchStoresResponse.has_more_pages?(page1) do
  {:ok, page2} = FileSearchStores.list(
    page_token: page1.next_page_token
  )
end

list_all(opts \\ [])

@spec list_all(list_opts()) ::
  {:ok, [Gemini.Types.FileSearchStore.t()]} | {:error, term()}

List all file search stores across all pages.

Automatically handles pagination to retrieve all stores.

Parameters

opts - Options

Examples

{:ok, all_stores} = FileSearchStores.list_all()
active = Enum.filter(all_stores, &FileSearchStore.active?/1)
IO.puts("Active stores: #{length(active)}")

upload_to_store(store_name, file_path, opts \\ [])

@spec upload_to_store(String.t(), String.t(), upload_opts()) ::
  {:ok, Gemini.Types.FileSearchDocument.t()} | {:error, term()}

Upload a file directly to the store.

This is a convenience method that uploads a file and imports it into the store in a single operation.

Parameters

store_name - Store resource name
file_path - Path to local file
opts - Upload options

Options

:display_name - Human-readable name for the document
:mime_type - MIME type (auto-detected if not provided)
:auth - Authentication strategy

Examples

{:ok, doc} = FileSearchStores.upload_to_store(
  "fileSearchStores/abc123",
  "/path/to/document.pdf",
  display_name: "Product Manual v2.0"
)

IO.puts("Uploaded: #{doc.name}")

wait_for_active(name, opts \\ [])

@spec wait_for_active(String.t(), wait_opts()) ::
  {:ok, Gemini.Types.FileSearchStore.t()} | {:error, term()}

Wait for a store to become active.

Polls the store status until it reaches :active or :failed state.

Parameters

name - Store resource name
opts - Wait options

Options

:poll_interval - Milliseconds between status checks (default: 2000)
:timeout - Maximum wait time in milliseconds (default: 300000 = 5 min)
:on_status - Callback for status updates fn(FileSearchStore.t()) -> any()
:auth - Authentication strategy

Examples

{:ok, store} = FileSearchStores.wait_for_active(
  "fileSearchStores/abc123",
  poll_interval: 5000,
  on_status: fn s -> IO.puts("State: #{s.state}") end
)

if FileSearchStore.active?(store) do
  IO.puts("Store ready!")
end

wait_for_document(document_name, opts \\ [])

@spec wait_for_document(String.t(), wait_doc_opts()) ::
  {:ok, Gemini.Types.FileSearchDocument.t()} | {:error, term()}

Wait for a document to finish processing.

Polls the document status until it reaches :active or :failed state.

Parameters

document_name - Document resource name
opts - Wait options

Options

:poll_interval - Milliseconds between status checks (default: 2000)
:timeout - Maximum wait time in milliseconds (default: 300000 = 5 min)
:on_status - Callback for status updates
:auth - Authentication strategy

Examples

{:ok, doc} = FileSearchStores.wait_for_document(
  "fileSearchStores/abc/documents/xyz",
  on_status: fn d -> IO.puts("Chunks: #{d.chunk_count}") end
)