One File Search Store for Many Apps: Splitting Retrieval With customMetadata and Chunk Config

The metadataFilter trap — empty results, no exception

This is the heart of it. Import succeeded, yet a query with metadataFilter returned an empty answer without throwing anything.

First, the form that works:

from google.genai import types
 
resp = client.models.generate_content(
    model="gemini-3.5-flash",
    contents="What should I do if a wallpaper won't save?",
    config=types.GenerateContentConfig(
        tools=[types.Tool(
            file_search=types.FileSearch(
                file_search_store_names=[store.name],
                # AIP-160 list-filter syntax: string values must be quoted
                metadata_filter='app_id="wallpaper"',
            )
        )],
    ),
)
print(resp.text)

What I had written first left the value unquoted: metadata_filter='app_id=wallpaper'. That is the source of the silent empty answer. metadata_filter follows the AIP-160 filter syntax, and string values must be wrapped in double quotes. Leave them off and, in many cases, the filter is treated as matching nothing — you get empty grounding, not an exception.

The nasty part is precisely that it is not an exception. try/except never catches it. resp.text just returns a thin, generic answer, so it took me a while to suspect the filter at all.

There are at least three mistakes that produce the same silence.

Always begin isolation by comparing against the same query with no filter. The helper below fires the same question with and without a filter and prints the grounding-chunk count side by side.

def diagnose_filter(question: str, metadata_filter: str):
    def run(mf):
        resp = client.models.generate_content(
            model="gemini-3.5-flash",
            contents=question,
            config=types.GenerateContentConfig(
                tools=[types.Tool(file_search=types.FileSearch(
                    file_search_store_names=[store.name],
                    metadata_filter=mf,
                ))],
            ),
        )
        gm = resp.candidates[0].grounding_metadata
        chunks = getattr(gm, "grounding_chunks", None) or []
        return len(chunks)
 
    no_filter = run(None)
    with_filter = run(metadata_filter)
    print(f"filter=None       -> chunks={no_filter}")
    print(f"filter={metadata_filter!r} -> chunks={with_filter}")
    # Verdict: chunks>0 without the filter but 0 with it => filter syntax
    if no_filter > 0 and with_filter == 0:
        print("=> Import is fine. Suspect filter syntax or key name.")
    elif no_filter == 0:
        print("=> Problem is before the filter (import or the question).")
 
diagnose_filter("What should I do if a wallpaper won't save?", 'app_id="wallpaper"')

Once you can say "chunks come back without the filter but zero with it," you can immediately conclude the cause is the filter syntax or the key name. That single habit changed the time I spend on silent empty results by an order of magnitude.

Fixing "the answer split into two chunks" with chunkingConfig

After fixing metadataFilter, I noticed a second kind of drop. For certain FAQs, even with a correct filter, the answer was never cited.

The cause was chunking at import time. File Search auto-chunks by default, but chunking_config lets you set the maximum tokens per chunk and the overlap.

op = client.file_search_stores.upload_to_file_search_store(
    file="faq_wallpaper_en.md",
    file_search_store_name=store.name,
    config={
        "custom_metadata": [{"key": "app_id", "string_value": "wallpaper"}],
        "chunking_config": {
            "white_space_config": {
                "max_tokens_per_chunk": 200,
                "max_overlap_tokens": 20,
            }
        },
    },
)

Each chunk is embedded independently. So when one procedure's explanation spans two chunks, neither embedding carries more than half of it, its similarity to the query drops, and it is less likely to be retrieved. A small overlap is the insurance that absorbs this boundary splitting.

How much overlap is enough? Before pinning it against live data, I reproduced only the chunk-boundary behavior locally to get a first read. Using a tiny simulator of whitespace chunking, I checked whether a "90-token procedure span (tokens 170-260)" inside a 520-token FAQ body fits inside a single chunk, per setting.

The reading is simple. At max_tokens_per_chunk=200 / overlap=20, a procedure that starts just before a boundary gets split. Raising overlap from 20 to 40 alone let the procedure fit in a single chunk without adding chunks. Push overlap up to 80 and it fits, but the chunk count rises, inflating embedding cost and storage.

On that basis, my policy became: add only the minimum overlap needed so that important procedures or code snippets don't split. As a rule of thumb, documents full of short procedures (like FAQs) get thicker overlap (around 40), while prose where each sentence stands alone can stay near the default. Shrinking chunks blindly adds boundaries and makes splitting more likely — which the table above also shows.

If what you really want is to shrink the stored embeddings themselves, dimension truncation is a different lever. I put measured cost and latency in truncating Gemini Embedding from 3072 to 768 dimensions with a Matryoshka design.

Recovering customMetadata from grounding back into the app

The finishing touch on isolation is letting the app receive "which app, which document" an answer came from. The customMetadata you attached comes straight back from the grounding chunks.

resp = client.models.generate_content(
    model="gemini-3.5-flash",
    contents="What should I do if a wallpaper won't save?",
    config=types.GenerateContentConfig(
        tools=[types.Tool(file_search=types.FileSearch(
            file_search_store_names=[store.name],
            metadata_filter='app_id="wallpaper"',
        ))],
    ),
)
 
for chunk in resp.candidates[0].grounding_metadata.grounding_chunks:
    rc = getattr(chunk, "retrieved_context", None)
    if not rc:
        continue
    meta = {m.key: (m.string_value or m.numeric_value)
            for m in (rc.custom_metadata or [])}
    # Expect: {'app_id': 'wallpaper', 'kind': 'faq', 'lang': 'en'}
    print(meta.get("app_id"), "->", rc.title)

Now I can return an answer with "which FAQ file in which app grounds this." I use that app_id to drive the in-app help path — a deep link to the relevant FAQ. Filter to narrow, grounding to recover, hand it back to the app screen. Only when that round trip is complete does a single shared store hold up in real use.

For pruning documents that are never cited at all, I wrote that up separately in pruning a File Search store from citation logs.

Constraints worth knowing before you merge

Before choosing a single shared store, checking today's File Search constraints saves regret.

The first one shapes design the most. Since File Search can't be mixed with other tools, keep "answer from the store's FAQ" and "fetch fresh info from the web" separated at the call level.

Wrapping up

Start by importing a single FAQ from your smallest app into your existing store with an app_id, then run the diagnose_filter helper to compare grounding-chunk counts with and without the filter. Make that comparison a habit and the metadataFilter silence usually resolves in minutes.

A single shared store is not a cure-all. But for running frequently edited FAQs solo, I've come to feel that logical separation by metadata lasts far longer than endlessly adding stores. I'm still refining this in production, but if it spares someone the same detour, I'll be glad. Thank you for reading.