ExLLM.Gemini.Document (ex_llm v0.5.0)

View Source

Document management for Gemini's Semantic Retrieval API.

A Document is a collection of Chunks. A Corpus can have a maximum of 10,000 Documents. Documents are used to organize and query related content within a corpus.

Authentication

Document operations require authentication. Both API key and OAuth2 are supported:

  • API key: Most operations work with API keys
  • OAuth2: Required for some operations, especially those involving user-specific data

Examples

# Create a document
{:ok, document} = Document.create_document(
  "corpora/my-corpus",
  %{display_name: "Research Papers"}
)

# List documents with pagination
{:ok, result} = Document.list_documents(
  "corpora/my-corpus",
  %{page_size: 10}
)

# Query a document
{:ok, results} = Document.query_document(
  "corpora/my-corpus/documents/my-doc",
  "artificial intelligence",
  %{results_count: 5}
)

# Update document
{:ok, updated} = Document.update_document(
  "corpora/my-corpus/documents/my-doc",
  %{display_name: "Updated Name"},
  %{update_mask: "displayName"}
)

# Delete document
:ok = Document.delete_document("corpora/my-corpus/documents/my-doc")

Summary

Functions

Creates an empty Document in the specified corpus.

Deletes a Document.

Gets information about a specific Document.

Lists all Documents in a Corpus with pagination support.

Performs semantic search over a Document.

Types

t()

@type t() :: %ExLLM.Gemini.Document{
  create_time: String.t() | nil,
  custom_metadata: [CustomMetadata.t()] | nil,
  display_name: String.t() | nil,
  name: String.t() | nil,
  update_time: String.t() | nil
}

Functions

create_document(parent, params, opts \\ [])

@spec create_document(String.t(), map(), Keyword.t()) :: {:ok, t()} | {:error, map()}

Creates an empty Document in the specified corpus.

Parameters

  • parent - The corpus name in format "corpora/{corpus_id}"
  • params - Document creation parameters
  • auth - Authentication (API key or OAuth2 token)

Params

  • :name - Optional custom document name
  • :display_name - Human-readable display name (max 512 characters)
  • :custom_metadata - List of key-value metadata (max 20 items)

Examples

# Create with auto-generated name
{:ok, doc} = Document.create_document(
  "corpora/my-corpus",
  %{display_name: "Research Papers"}
)

# Create with custom name and metadata
{:ok, doc} = Document.create_document(
  "corpora/my-corpus",
  %{
    name: "corpora/my-corpus/documents/research-2024",
    display_name: "Research Papers 2024",
    custom_metadata: [
      %{key: "category", string_value: "research"},
      %{key: "year", numeric_value: 2024}
    ]
  }
)

delete_document(name, opts \\ [])

@spec delete_document(String.t(), Keyword.t()) :: :ok | {:error, map()}

Deletes a Document.

Parameters

  • name - The document name in format "corpora/{corpus_id}/documents/{document_id}"
  • opts - Delete options
  • auth - Authentication (API key or OAuth2 token)

Options

  • :force - If true, delete related chunks. If false (default), fail if chunks exist.

Examples

# Delete document (fails if chunks exist)
:ok = Document.delete_document("corpora/my-corpus/documents/my-doc")

# Force delete with chunks
:ok = Document.delete_document(
  "corpora/my-corpus/documents/my-doc",
  %{force: true}
)

get_document(name, opts \\ [])

@spec get_document(String.t(), Keyword.t()) :: {:ok, t()} | {:error, map()}

Gets information about a specific Document.

Parameters

  • name - The document name in format "corpora/{corpus_id}/documents/{document_id}"
  • auth - Authentication (API key or OAuth2 token)

Examples

{:ok, document} = Document.get_document("corpora/my-corpus/documents/my-doc")

list_documents(parent, opts \\ [])

@spec list_documents(String.t(), Keyword.t()) ::
  {:ok, ExLLM.Gemini.Document.ListResult.t()} | {:error, map()}

Lists all Documents in a Corpus with pagination support.

Parameters

  • parent - The corpus name in format "corpora/{corpus_id}"
  • opts - Optional listing parameters
  • auth - Authentication (API key or OAuth2 token)

Options

  • :page_size - Maximum documents per page (1-20, default 10)
  • :page_token - Token for pagination

Examples

# List all documents
{:ok, result} = Document.list_documents("corpora/my-corpus")

# List with pagination
{:ok, result} = Document.list_documents(
  "corpora/my-corpus",
  %{page_size: 20, page_token: "next-page-token"}
)

query_document(name, query, query_opts \\ %{}, opts \\ [])

@spec query_document(String.t(), String.t(), map(), Keyword.t()) ::
  {:ok, ExLLM.Gemini.Document.QueryResult.t()} | {:error, map()}

Performs semantic search over a Document.

Parameters

  • name - The document name in format "corpora/{corpus_id}/documents/{document_id}"
  • query - Query string to perform semantic search
  • opts - Query options
  • auth - Authentication (API key or OAuth2 token)

Options

  • :results_count - Maximum chunks to return (1-100, default 10)
  • :metadata_filters - List of metadata filters for chunk filtering

Examples

# Simple query
{:ok, result} = Document.query_document(
  "corpora/my-corpus/documents/my-doc",
  "artificial intelligence"
)

# Query with filters
{:ok, result} = Document.query_document(
  "corpora/my-corpus/documents/my-doc",
  "machine learning",
  %{
    results_count: 5,
    metadata_filters: [
      %{
        key: "chunk.custom_metadata.category",
        conditions: [%{operation: "EQUAL", string_value: "research"}]
      }
    ]
  }
)

update_document(name, updates, update_mask, opts \\ [])

@spec update_document(String.t(), map(), [String.t()], Keyword.t()) ::
  {:ok, t()} | {:error, map()}

Updates a Document.

Parameters

  • name - The document name in format "corpora/{corpus_id}/documents/{document_id}"
  • updates - Fields to update
  • opts - Update options including update_mask
  • auth - Authentication (API key or OAuth2 token)

Updates

  • :display_name - New display name
  • :custom_metadata - New custom metadata

Options

  • :update_mask - Required. Fields to update ("displayName", "customMetadata")

Examples

# Update display name
{:ok, doc} = Document.update_document(
  "corpora/my-corpus/documents/my-doc",
  %{display_name: "New Name"},
  %{update_mask: "displayName"}
)

# Update metadata
{:ok, doc} = Document.update_document(
  "corpora/my-corpus/documents/my-doc",
  %{custom_metadata: [%{key: "status", string_value: "published"}]},
  %{update_mask: "customMetadata"}
)