Gemini.APIs.Documents (GeminiEx v0.8.4)

View Source

Documents API for RAG (Retrieval-Augmented Generation) document management.

Documents are stored in RAG stores and used for semantic search and context augmentation in generation requests.

Overview

The Documents API allows you to:

  • List documents in a RAG store
  • Get document metadata
  • Delete documents

Example Workflow

# List documents in a store
{:ok, response} = Gemini.APIs.Documents.list("ragStores/my-store")

Enum.each(response.documents, fn doc ->
  IO.puts("#{doc.name}: #{doc.state}")
end)

# Get specific document
{:ok, doc} = Gemini.APIs.Documents.get("ragStores/my-store/documents/doc123")

if Document.active?(doc) do
  IO.puts("Document ready: #{doc.chunk_count} chunks")
end

# Delete document
:ok = Gemini.APIs.Documents.delete("ragStores/my-store/documents/doc123")

RAG Store Integration

Documents are typically created by uploading files to a RAG store via the FileSearchStores API. This API focuses on document management after creation.

Summary

Types

document_opts()
list_opts()
wait_opts()

Functions

delete(name, opts \\ [])

Delete a document from a RAG store.

get(name, opts \\ [])

Get a document by name.

list(store_name, opts \\ [])

List documents in a RAG store.

list_all(store_name, opts \\ [])

List all documents across all pages.

wait_for_processing(name, opts \\ [])

Wait for a document to finish processing.

Types

document_opts()

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

list_opts()

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

wait_opts()

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

Functions

delete(name, opts \\ [])

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

Delete a document from a RAG store.

Parameters

  • name - Document resource name
  • opts - Options

Examples

:ok = Gemini.APIs.Documents.delete("ragStores/my-store/documents/doc123")

get(name, opts \\ [])

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

Get a document by name.

Parameters

  • name - Document resource name (e.g., "ragStores/abc/documents/xyz")
  • opts - Options

Examples

{:ok, doc} = Gemini.APIs.Documents.get("ragStores/my-store/documents/doc123")
IO.puts("State: #{doc.state}")
IO.puts("Size: #{doc.size_bytes} bytes")
IO.puts("Chunks: #{doc.chunk_count}")

list(store_name, opts \\ [])

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

List documents in a RAG store.

Parameters

  • store_name - RAG store resource name (e.g., "ragStores/abc")
  • opts - List options

Options

  • :page_size - Number of documents per page (default: 100)
  • :page_token - Token from previous response for pagination
  • :filter - Filter expression
  • :auth - Authentication strategy

Examples

# List all documents
{:ok, response} = Gemini.APIs.Documents.list("ragStores/my-store")

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

# With pagination
{:ok, page1} = Gemini.APIs.Documents.list("ragStores/my-store", page_size: 10)
if ListDocumentsResponse.has_more_pages?(page1) do
  {:ok, page2} = Gemini.APIs.Documents.list("ragStores/my-store",
    page_token: page1.next_page_token
  )
end

list_all(store_name, opts \\ [])

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

List all documents across all pages.

Automatically handles pagination to retrieve all documents.

Parameters

  • store_name - RAG store resource name
  • opts - Options

Examples

{:ok, all_docs} = Gemini.APIs.Documents.list_all("ragStores/my-store")
active = Enum.filter(all_docs, &Document.active?/1)
IO.puts("Active documents: #{length(active)}")

wait_for_processing(name, opts \\ [])

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

Wait for a document to finish processing.

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

Parameters

  • 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 fn(Document.t()) -> any()

Examples

{:ok, doc} = Gemini.APIs.Documents.wait_for_processing(
  "ragStores/my-store/documents/doc123",
  poll_interval: 5000,
  on_status: fn d -> IO.puts("State: #{d.state}") end
)

if Document.active?(doc) do
  IO.puts("Document ready with #{doc.chunk_count} chunks")
end