ExLLM.Gemini.Document (ex_llm v0.5.0)
View SourceDocument 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.
Updates a Document.
Types
Functions
Creates an empty Document in the specified corpus.
Parameters
parent
- The corpus name in format "corpora/{corpus_id}"params
- Document creation parametersauth
- 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}
]
}
)
Deletes a Document.
Parameters
name
- The document name in format "corpora/{corpus_id}/documents/{document_id}"opts
- Delete optionsauth
- 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}
)
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")
@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 parametersauth
- 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"}
)
@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 searchopts
- Query optionsauth
- 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"}]
}
]
}
)
Updates a Document.
Parameters
name
- The document name in format "corpora/{corpus_id}/documents/{document_id}"updates
- Fields to updateopts
- Update options including update_maskauth
- 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"}
)