Gemini File Search: A RAG Lifecycle You Can Operate

A File Search demo can look finished before its retrieval system is ready. A document enters a store, Gemini returns a fluent answer, and the happy path appears complete. The missing work sits between those events: proving that indexing finished, constraining which documents are eligible, preserving citations, removing superseded material, and knowing which data terms apply to the project.

Gemini File Search takes responsibility for a useful part of retrieval-augmented generation. According to the current File Search guide, it imports, chunks, embeds, and indexes content, then retrieves relevant chunks as context for a model request. That is a managed retrieval path, not a guarantee that a corpus is correct or that every generated claim is supported.

This guide maps the complete operating cycle as documented on July 17, 2026. It covers store creation, both ingestion routes, chunking, queries, citations, metadata filters, deletion, limits, billing, and data handling. It does not report a HUMAI benchmark or claim that File Search is better than a separate retrieval stack.

The unit you operate is a store, not an upload

A FileSearchStore is a collection of processed documents. The store reference exposes create, list, get, and delete operations. A store can also specify an embedding model when it is created. That choice matters because the current guide distinguishes text embeddings through gemini-embedding-001 from image and multimodal embeddings through gemini-embedding-2.

Raw files and indexed store data have different lifetimes. Files uploaded through the Files API are deleted after 48 hours. Imported chunks and embeddings have no ordinary time-to-live and remain until they are manually deleted or the relevant model is deprecated. A cleanup job that watches only Files API objects therefore misses the durable copy used for retrieval.

Give each store one explicit governance boundary. A product release, customer workspace, policy family, or documentation version can be a boundary. Mixing unrelated owners into one store makes metadata rules, deletion requests, and incident response harder to prove. The API permits multiple stores, so store design does not need to mirror one giant company folder.

Direct upload and File import are separate ingestion routes

The current guide documents two ways to feed a store. uploadToFileSearchStore accepts local content and starts a resumable upload directly against the target store. The alternative first creates a temporary resource with the Files API, then calls importFile with that file name and the destination store.

Both routes return a long-running operation for indexing. Do not treat the first HTTP success as searchable content. Poll the operation until it reports completion, record any error, and then use the Documents API to confirm that the expected document exists in the store. A batch importer should preserve the relationship among the source checksum, operation name, and final document resource so retries do not quietly create an ambiguous corpus.

The import request can carry custom metadata and a chunking configuration. This is the right moment to attach stable fields such as tenant, document_type, policy_version, or effective_year. Avoid metadata derived from a mutable filename if authorization or retention depends on it.

import time

operation = client.file_search_stores.upload_to_file_search_store(
    file="handbook.txt",
    file_search_store_name=store.name,
    config={
        "display_name": "Handbook 2026-07",
        "chunking_config": {
            "white_space_config": {
                "max_tokens_per_chunk": 300,
                "max_overlap_tokens": 30,
            }
        },
    },
)

while not operation.done:
    time.sleep(5)
    operation = client.operations.get(operation)

This snippet follows the documented SDK shape. The numbers are an example configuration, not a recommended default. Retrieval quality depends on the document structure and the questions the application must answer.

Chunking is a product decision with an API control

File Search automatically divides imported content, embeds each chunk, and adds it to the store. The documented whitespace configuration exposes max_tokens_per_chunk and max_overlap_tokens. Google does not publish one universal setting that fits contracts, code, manuals, and short support notes.

Choose settings with a small labeled question set. Each question should identify the source passage that ought to be retrieved. Test at least one direct fact, one clause that crosses a paragraph boundary, one question that should return no answer, and one ambiguous term that exists in several documents. Record retrieved citations, not just whether the prose sounds right.

When content is revised, treat the new version as a controlled replacement. The current Documents reference provides list, get, and delete methods, but no in-place document update method. The practical implication is to import the replacement, verify it, then remove the superseded document. Keep a version field in metadata during the overlap so queries can select the approved revision.

A query contract needs a filter and a citation policy

The latest documentation presents the generally available Interactions API as the recommended route for current features and models, while the File Search page can be toggled to its generateContent version. In an Interaction, the tool entry names one or more stores. The current model table lists Gemini 3.5 Flash, Gemini 3.1 Pro Preview, Gemini 3.1 Flash-Lite, and Gemini 3 Flash Preview. Check that table at deployment time because preview status and model availability can change.

interaction = client.interactions.create(
    model="gemini-3.5-flash",
    input="Which travel policy applies to contractors?",
    tools=[{
        "type": "file_search",
        "file_search_store_names": [store.name],
        "metadata_filter": 'audience="contractor"',
    }],
)

Custom metadata supports string and numeric values. The query tool accepts metadata_filter, and the guide points to AIP-160 list-filter syntax. Filters should enforce the same tenant, access, status, and version boundaries used by the source application. A natural-language instruction such as "only use current policies" is not a substitute for excluding obsolete documents from retrieval.

File Search responses may include file_citation annotations. In the Interactions API, annotations sit on content blocks within model-output steps. They can identify the file name and source; paged documents may also include a page number. Citation annotations can carry custom metadata. With multimodal stores, an image citation can expose a persistent media_id for downloading the referenced image chunk.

The word "may" matters. Define what the application does when a consequential sentence lacks a citation, cites the wrong version, or points to a document the viewer cannot open. Safe options include withholding the sentence, returning the retrieved source list without an answer, or routing the request to a reviewer. A citation is evidence to inspect, not an automatic truth label.

Deletion has document and store levels

The Documents API can list, get, and delete individual documents. Deleting with force=true also removes associated chunks and objects. Without force, the service returns FAILED_PRECONDITION when dependent chunks remain. Store deletion follows the same pattern: forced deletion also removes its documents and related objects.

Build deletion around resource names, not display names. After a delete response, list the parent store and confirm the document has disappeared. Then run a question whose only valid evidence came from the deleted material. Passing the lifecycle gate requires both absence from the inventory and absence from retrieval.

A full-store deletion is appropriate for a tenant exit or an abandoned experiment. A single-document deletion is better for version retirement or a scoped erasure request. In either case, keep the deletion request, actor, reason, resource name, time, and verification result in the system that owns retention policy.

Limits shape the store plan before quality does

As of July 17, 2026, the File Search guide sets a 100 MB maximum per document. Total File Search storage per project is 1 GB on Free, 10 GB on Tier 1, 100 GB on Tier 2, and 1 TB on Tier 3. Google recommends keeping each store below 20 GB for retrieval latency. Backend accounting includes input plus generated embeddings and is typically about three times the input size.

Those figures turn capacity planning into a pre-ingestion check. Estimate expanded storage, not just raw folder size. Reserve space for replacements during a controlled version swap. Split stores by governance or latency needs before a project reaches its ceiling.

File Search is unavailable in the Live API. The guide also says built-in grounding tools cannot be combined with one another in the same request, so File Search cannot share a request with Grounding with Google Search or URL Context. Audio and video formats are not currently supported. Multimodal stores accept PNG and JPEG images up to 4K by 4K when created with gemini-embedding-2.

The bill has three moving parts

The Gemini Developer API pricing page showed $0.15 per one million tokens in its generic paid-tier File Search row when this article was checked. That figure is not a universal indexing rate. The File Search guide says indexing follows the selected embedding model's pricing, and the same pricing page lists different text and image rates for gemini-embedding-2. Storage and query-time embedding generation are free. Retrieved document tokens are billed as regular model context, and the selected Gemini model adds its normal input and output charges.

Free storage does not make an unbounded corpus free to query. A loose filter can retrieve extra context on every request. Measure indexed tokens per release, retrieved context tokens per acceptance prompt, model input, model output, and retry volume. Recheck the live pricing page before approving a budget because model and tool rates can move independently.

Data handling depends on billing and logging choices

The Gemini API Additional Terms draw a material line between unpaid and paid services. For unpaid services, Google says submitted content and generated responses may be used to provide, improve, and develop products, and human reviewers may process API input and output. The terms tell users not to submit sensitive, confidential, or personal information to unpaid services. For users in the EEA, Switzerland, and the United Kingdom, the paid-services data-use terms apply to all services.

For paid services, Google says prompts, system instructions, cached content, uploaded files, and responses are not used to improve its products and are processed under the referenced Data Processing Addendum. Separate safety logging still applies. The current abuse-monitoring policy says prompts, supplied context, and outputs are retained for 55 days for policy enforcement, safety, and required legal or regulatory disclosures.

Developer-visible project logs are another control, and Google makes that log storage available only to paid-tier projects. For those projects, the logs guide says Interactions store requests by default with store=true, while generateContent defaults to store=false. Logging can be changed by project or request. Project logs have a default 55-day retention window that can be set to 7, 14, 28, or 55 days; copies saved into datasets do not have that set expiry. These developer controls are separate from the abuse-monitoring record described above.

Sharing a dataset with Google is optional and changes the data-use boundary. The data logging and sharing policy says shared requests and responses can be used for product improvement and model training under unpaid-service terms. Do not turn on sharing for proprietary retrieval traces without the necessary rights and a separate review.

Use an acceptance gate that can fail

A release checklist should test the retrieval product, not the attractiveness of one answer. Run it first on a synthetic or approved corpus with no restricted material. Preserve the exact source files and expected passages so a model or chunking change can be retested later.

The ship decision should name the store owner, approved corpus version, embedding model, supported Gemini model, chunk settings, mandatory filters, citation failure rule, deletion procedure, data-service class, logging configuration, and cost envelope. If one of those fields is unknown, File Search may still answer a demo question, but the retrieval system is not yet ready to carry production evidence.