{ "@context": "https://schema.org", "@id": "https://aggr.aymericbeaumet.com/items/philschmid-de/2025-11-07-gemini-api-file-search-a-web-developer-tutorial/#webpage", "@type": [ "WebPage", "ArchiveComponent" ], "articleBody": "The Gemini API File Search tool is a fully managed RAG (Retrieval-Augmented Generation) system built directly into the Gemini API. It automatically manages file storage, chunks your data, creates embeddings, and seamlessly injects the most relevant context into your prompts.\n\nThis must be expensive? No, file storage and embedding generation at query time are completely free of charge. You only pay for the initial indexing of your files at a fixed rate of $0.15 (based on the embedding) per 1 million tokens.\n\nThis tutorial will walk you through the complete lifecycle of using File Search with the JavaScript/TypeScript, you will learn how to:\n\n1. Create a File Search Store\n2. Find a Store by Display Name\n3. Upload Multiple Files Concurrently\n4. Advanced Upload: Chunking & Metadata\n5. Run a Standard Generation Query (RAG)\n6. Find a Specific Document\n7. Delete a Document\n8. Update a Document\n9. Cleanup: Delete the File Search Store\n\nBefore we start, make sure you have an [API key from Google AI Studio](https://aistudio.google.com/api-keys) and have installed the latest SDK:\n\nBash\n\n```bash\nnpm install @google/genai\n```\n\nInitialize your client in your JavaScript environment:\n\nJavaScript\n\n```js\nimport { GoogleGenAI } from '@google/genai';\nimport fs from 'fs';\nimport path from 'path';\n \nconst ai = new GoogleGenAI({});\n```\n\n### 1) Create a File Search Store\n\nA **File Search Store** is a persistent container for your document chunks and embeddings. It's distinct from raw file storage and can hold gigabytes of data.\n\nJavaScript\n\n```js\nconst fileStoreName = 'my-example-store';\n \nconst createStoreOp = await ai.fileSearchStores.create({\n config: { displayName: fileStoreName }\n});\n \nconsole.log(`Store created with Name: ${createStoreOp.name}`);\n```\n\n### 2) Find a Store by Display Name\n\nOften the creation of a store and the use are in a different application session. Since the API assigns a unique ID (`fileSearchStores/xyz...`), you need to look it up by the human-readable `displayName`.\n\nJavaScript\n\n```js\nlet fileStore = null;\n// List stores with a page size limit\nconst pager = await ai.fileSearchStores.list({ config: { pageSize: 10 } });\nlet page = pager.page;\n \n// Iterate through pages until we find a match\nsearchLoop: while (true) {\n for (const store of page) {\n if (store.displayName === fileStoreName) {\n fileStore = store;\n break searchLoop;\n }\n }\n if (!pager.hasNextPage()) break;\n page = await pager.nextPage();\n}\n \nif (!fileStore) {\n throw new Error(`Store with display name '${fileStoreName}' not found.`);\n}\nconsole.log(`Found store: ${fileStore.name}`);\n```\n\n### 3) Upload Multiple Files Concurrently\n\nSpeed matters. When ingesting a folder of documents, don't process them sequentially. The API supports concurrent operations, so we can use `Promise.all` to upload and process multiple files at once.\n\nWe'll use the helper method `uploadToFileSearchStore`, which handles uploading the raw file and initiating the indexing process in one step. We then monitor `operation.done` to ensure processing completes before moving on.\n\nJavaScript\n\n```js\nconst docsDir = \"docs\"; // Ensure you have a 'docs' folder with some text files\nconst files = fs.readdirSync(docsDir).map(file => path.join(docsDir, file));\n \nawait Promise.all(files.map(async (filePath) => {\n // 1. Initiate upload and indexing\n let operation = await ai.fileSearchStores.uploadToFileSearchStore({\n file: filePath,\n fileSearchStoreName: fileStore.name,\n config: {\n displayName: path.basename(filePath),\n }\n });\n \n // 2. Poll until the document is fully processed\n while (!operation.done) {\n await new Promise(resolve => setTimeout(resolve, 1000)); // wait 1s\n operation = await ai.operations.get({ operation });\n }\n console.log(`Processing complete for: ${path.basename(filePath)}`);\n return operation;\n}));\n```\n\n### 4) Upload with Custom Chunking Strategies\n\nBy default, Gemini handles chunking intelligently. However, for specific use cases you might want tighter control over how your data is split.\n\nYou can define a `chunkingConfig` during upload to specify parameters like `maxTokensPerChunk` and `maxOverlapTokens` and `customMetadata` to attach key-value pairs to the document.\n\nJavaScript\n\n```js\nconst specialDocPath = 'special-docs/technical-manual.txt';\n \nlet advancedUploadOp = await ai.fileSearchStores.uploadToFileSearchStore({\n file: specialDocPath,\n fileSearchStoreName: fileStore.name,\n config: {\n displayName: 'technical-manual.txt',\n customMetadata: [\n { key: \"doc_type\", stringValue: \"manual\" },\n ],\n chunkingConfig: {\n whiteSpaceConfig: {\n maxTokensPerChunk: 500, // Smaller chunks for more precise retrieval\n maxOverlapTokens: 50 // Ensure context isn't lost between chunks\n }\n }\n }\n});\n \n// Wait for the file to process\nwhile (!advancedUploadOp.done) {\n await new Promise(resolve => setTimeout(resolve, 1000));\n advancedUploadOp = await ai.operations.get({ operation: advancedUploadOp });\n}\nconsole.log(\"Advanced file processed.\");\n```\n\n### 5) Run a Generation Query using File Search (RAG)\n\nWe don't need to manually retrieve chunks. We just tell the Gemini model to use the `fileSearch` tool and point it to our store name. Gemini understands it needs more information, searches the store, and grounds its response automatically.\n\nJavaScript\n\n```js\nconst response = await ai.models.generateContent({\n model: \"gemini-2.5-flash\",\n contents: \"What is Gemini and what is the File API?\",\n config: {\n tools: [{\n fileSearch: {\n fileSearchStoreNames: [fileStore.name]\n }\n }]\n }\n});\n \nconsole.log(\"Model response:\", response.text);\n// Optionally check response.candidates[0].groundingMetadata for citations!\n```\n\nBecause we tagged our technical manual in Step 4, we can now force Gemini to *only* look at documents matching that tag by using a metadataFilter.\n\nJavaScript\n\n```js\nconst responseFiltered = await ai.models.generateContent({\n model: \"gemini-2.5-flash\",\n contents: \"How do I reset the device according to the manual?\",\n config: {\n tools: [{\n fileSearch: {\n fileSearchStoreNames: [fileStore.name],\n metadataFilter: 'doc_type=\"manual\"'\n }\n }]\n }\n});\n \nconsole.log(\"Filtered response:\", responseFiltered.text);\n```\n\n### 6) Find a Specific Document within a Store\n\nYou'll often need to manage individual documents within your store. You can find a specific document by its display name.\n\nJavaScript\n\n```js\nconst docToFind = 'doc1.txt';\nlet targetDoc = null;\n \nlet documentPager = await ai.fileSearchStores.documents.list({\n parent: fileStore.name,\n});\n \n// Iterate through the store's document list\nsearchDocsLoop: while (true) {\n for (const document of documentPager.page) {\n if (document.displayName === docToFind) {\n targetDoc = document;\n break searchDocsLoop;\n }\n }\n if (!documentPager.hasNextPage()) break;\n documentPager = await documentPager.nextPage();\n}\n \nif (!targetDoc) throw new Error(`Document '${docToFind}' not found.`);\n```\n\n### 7) Delete a Document\n\nCurrently, the standard flow to update a document in File Search is to delete the old version and upload a new one.\n\nJavaScript\n\n```js\nawait ai.fileSearchStores.documents.delete({\n name: targetDoc.name,\n config: { force: true } // Required to permanently delete from the store\n});\n```\n\n### 8) Update a Document\n\nFile Search documents are immutable once indexed. To \"update\" a document, you must find it, delete it, and upload the new version. In this step, we will automate this entire loop to update `doc1.txt` with new information.\n\nJavaScript\n\n```js\nconst docToUpdate = 'doc1.txt'; // assuming it has new content\nconst localDocPath = path.join(docsDir, docToUpdate);\n \n// 1. Find the existing document ID in the store based on its display name\nlet documentPager = await ai.fileSearchStores.documents.list({ parent: fileStore.name });\nlet foundDoc = null;\nfindLoop: while (true) {\n for (const doc of documentPager.page) {\n if (doc.displayName === docToUpdate) {\n foundDoc = doc;\n break findLoop;\n }\n }\n if (!documentPager.hasNextPage()) break;\n documentPager = await documentPager.nextPage();\n}\n \n// 2. If we found it, delete it\nif (foundDoc) {\n await ai.fileSearchStores.documents.delete({\n name: foundDoc.name,\n config: { force: true } // 'force' is required to delete indexed docs\n });\n}\n \n// 3. Upload the new version\nlet updateOp = await ai.fileSearchStores.uploadToFileSearchStore({\n file: localDocPath,\n fileSearchStoreName: fileStore.name,\n config: { displayName: docToUpdate }\n});\nwhile (!updateOp.done) {\n await new Promise(resolve => setTimeout(resolve, 1000));\n updateOp = await ai.operations.get({ operation: updateOp });\n}\n \nconsole.log(\"Revision uploaded and indexed successfully.\");\n```\n\n### 9) Cleanup: Delete the File Search Store\n\nYou are currently limited to 10 File Search Stores per project, so it's important to clean up resources when you are finished with development.\n\nJavaScript\n\n```js\nawait ai.fileSearchStores.delete({\n name: fileStore.name,\n config: { force: true }\n});\n```\n\n* * *\n\nThanks for reading! If you have any questions or feedback, please let me know on [Twitter](https://twitter.com/_philschmid) or [LinkedIn](https://www.linkedin.com/in/philipp-schmid-a6a2bb196/).\n", "authors": [], "captured_at": "2026-09-27T19:29:15.293681927+00:00", "category": "programming", "content_html": "

The Gemini API File Search tool is a fully managed RAG (Retrieval-Augmented Generation) system built directly into the Gemini API. It automatically manages file storage, chunks your data, creates embeddings, and seamlessly injects the most relevant context into your prompts.

\n

This must be expensive? No, file storage and embedding generation at query time are completely free of charge. You only pay for the initial indexing of your files at a fixed rate of $0.15 (based on the embedding) per 1 million tokens.

\n

This tutorial will walk you through the complete lifecycle of using File Search with the JavaScript/TypeScript, you will learn how to:

\n
    \n
  1. Create a File Search Store
    2. \n
  2. Find a Store by Display Name
    3. \n
  3. Upload Multiple Files Concurrently
    4. \n
  4. Advanced Upload: Chunking & Metadata
    5. \n
  5. Run a Standard Generation Query (RAG)
    6. \n
  6. Find a Specific Document
    7. \n
  7. Delete a Document
    8. \n
  8. Update a Document
    9. \n
  9. Cleanup: Delete the File Search Store
    10. \n
\n

Before we start, make sure you have an API key from Google AI Studio and have installed the latest SDK:

\n

Bash

\n
npm install @google/genai\n
\n

Initialize your client in your JavaScript environment:

\n

JavaScript

\n
import { GoogleGenAI } from '@google/genai';\nimport fs from 'fs';\nimport path from 'path';\n \nconst ai = new GoogleGenAI({});\n
\n

1) Create a File Search Store

\n

A File Search Store is a persistent container for your document chunks and embeddings. It's distinct from raw file storage and can hold gigabytes of data.

\n

JavaScript

\n
const fileStoreName = 'my-example-store';\n \nconst createStoreOp = await ai.fileSearchStores.create({\n  config: { displayName: fileStoreName }\n});\n \nconsole.log(`Store created with Name: ${createStoreOp.name}`);\n
\n

2) Find a Store by Display Name

\n

Often the creation of a store and the use are in a different application session. Since the API assigns a unique ID (fileSearchStores/xyz...), you need to look it up by the human-readable displayName.

\n

JavaScript

\n
let fileStore = null;\n// List stores with a page size limit\nconst pager = await ai.fileSearchStores.list({ config: { pageSize: 10 } });\nlet page = pager.page;\n \n// Iterate through pages until we find a match\nsearchLoop: while (true) {\n  for (const store of page) {\n    if (store.displayName === fileStoreName) {\n      fileStore = store;\n      break searchLoop;\n    }\n  }\n  if (!pager.hasNextPage()) break;\n  page = await pager.nextPage();\n}\n \nif (!fileStore) {\n  throw new Error(`Store with display name '${fileStoreName}' not found.`);\n}\nconsole.log(`Found store: ${fileStore.name}`);\n
\n

3) Upload Multiple Files Concurrently

\n

Speed matters. When ingesting a folder of documents, don't process them sequentially. The API supports concurrent operations, so we can use Promise.all to upload and process multiple files at once.

\n

We'll use the helper method uploadToFileSearchStore, which handles uploading the raw file and initiating the indexing process in one step. We then monitor operation.done to ensure processing completes before moving on.

\n

JavaScript

\n
const docsDir = "docs"; // Ensure you have a 'docs' folder with some text files\nconst files = fs.readdirSync(docsDir).map(file => path.join(docsDir, file));\n \nawait Promise.all(files.map(async (filePath) => {\n  // 1. Initiate upload and indexing\n  let operation = await ai.fileSearchStores.uploadToFileSearchStore({\n    file: filePath,\n    fileSearchStoreName: fileStore.name,\n    config: {\n      displayName: path.basename(filePath),\n    }\n  });\n \n  // 2. Poll until the document is fully processed\n  while (!operation.done) {\n    await new Promise(resolve => setTimeout(resolve, 1000)); // wait 1s\n    operation = await ai.operations.get({ operation });\n  }\n  console.log(`Processing complete for: ${path.basename(filePath)}`);\n  return operation;\n}));\n
\n

4) Upload with Custom Chunking Strategies

\n

By default, Gemini handles chunking intelligently. However, for specific use cases you might want tighter control over how your data is split.

\n

You can define a chunkingConfig during upload to specify parameters like maxTokensPerChunk and maxOverlapTokens and customMetadata to attach key-value pairs to the document.

\n

JavaScript

\n
const specialDocPath = 'special-docs/technical-manual.txt';\n \nlet advancedUploadOp = await ai.fileSearchStores.uploadToFileSearchStore({\n  file: specialDocPath,\n  fileSearchStoreName: fileStore.name,\n  config: {\n    displayName: 'technical-manual.txt',\n    customMetadata: [\n      { key: "doc_type", stringValue: "manual" },\n    ],\n    chunkingConfig: {\n      whiteSpaceConfig: {\n        maxTokensPerChunk: 500, // Smaller chunks for more precise retrieval\n        maxOverlapTokens: 50    // Ensure context isn't lost between chunks\n      }\n    }\n  }\n});\n \n// Wait for the file to process\nwhile (!advancedUploadOp.done) {\n  await new Promise(resolve => setTimeout(resolve, 1000));\n  advancedUploadOp = await ai.operations.get({ operation: advancedUploadOp });\n}\nconsole.log("Advanced file processed.");\n
\n

5) Run a Generation Query using File Search (RAG)

\n

We don't need to manually retrieve chunks. We just tell the Gemini model to use the fileSearch tool and point it to our store name. Gemini understands it needs more information, searches the store, and grounds its response automatically.

\n

JavaScript

\n
const response = await ai.models.generateContent({\n  model: "gemini-2.5-flash",\n  contents: "What is Gemini and what is the File API?",\n  config: {\n    tools: [{\n      fileSearch: {\n        fileSearchStoreNames: [fileStore.name]\n      }\n    }]\n  }\n});\n \nconsole.log("Model response:", response.text);\n// Optionally check response.candidates[0].groundingMetadata for citations!\n
\n

Because we tagged our technical manual in Step 4, we can now force Gemini to only look at documents matching that tag by using a metadataFilter.

\n

JavaScript

\n
const responseFiltered = await ai.models.generateContent({\n  model: "gemini-2.5-flash",\n  contents: "How do I reset the device according to the manual?",\n  config: {\n    tools: [{\n      fileSearch: {\n        fileSearchStoreNames: [fileStore.name],\n        metadataFilter: 'doc_type="manual"'\n      }\n    }]\n  }\n});\n \nconsole.log("Filtered response:", responseFiltered.text);\n
\n

6) Find a Specific Document within a Store

\n

You'll often need to manage individual documents within your store. You can find a specific document by its display name.

\n

JavaScript

\n
const docToFind = 'doc1.txt';\nlet targetDoc = null;\n \nlet documentPager = await ai.fileSearchStores.documents.list({\n  parent: fileStore.name,\n});\n \n// Iterate through the store's document list\nsearchDocsLoop: while (true) {\n  for (const document of documentPager.page) {\n    if (document.displayName === docToFind) {\n      targetDoc = document;\n      break searchDocsLoop;\n    }\n  }\n  if (!documentPager.hasNextPage()) break;\n  documentPager = await documentPager.nextPage();\n}\n \nif (!targetDoc) throw new Error(`Document '${docToFind}' not found.`);\n
\n

7) Delete a Document

\n

Currently, the standard flow to update a document in File Search is to delete the old version and upload a new one.

\n

JavaScript

\n
await ai.fileSearchStores.documents.delete({\n    name: targetDoc.name,\n    config: { force: true } // Required to permanently delete from the store\n});\n
\n

8) Update a Document

\n

File Search documents are immutable once indexed. To "update" a document, you must find it, delete it, and upload the new version. In this step, we will automate this entire loop to update doc1.txt with new information.

\n

JavaScript

\n
const docToUpdate = 'doc1.txt'; // assuming it has new content\nconst localDocPath = path.join(docsDir, docToUpdate);\n \n// 1. Find the existing document ID in the store based on its display name\nlet documentPager = await ai.fileSearchStores.documents.list({ parent: fileStore.name });\nlet foundDoc = null;\nfindLoop: while (true) {\n  for (const doc of documentPager.page) {\n    if (doc.displayName === docToUpdate) {\n      foundDoc = doc;\n      break findLoop;\n    }\n  }\n  if (!documentPager.hasNextPage()) break;\n  documentPager = await documentPager.nextPage();\n}\n \n// 2. If we found it, delete it\nif (foundDoc) {\n   await ai.fileSearchStores.documents.delete({\n     name: foundDoc.name,\n     config: { force: true } // 'force' is required to delete indexed docs\n   });\n}\n \n// 3. Upload the new version\nlet updateOp = await ai.fileSearchStores.uploadToFileSearchStore({\n  file: localDocPath,\n  fileSearchStoreName: fileStore.name,\n  config: { displayName: docToUpdate }\n});\nwhile (!updateOp.done) {\n   await new Promise(resolve => setTimeout(resolve, 1000));\n   updateOp = await ai.operations.get({ operation: updateOp });\n}\n \nconsole.log("Revision uploaded and indexed successfully.");\n
\n

9) Cleanup: Delete the File Search Store

\n

You are currently limited to 10 File Search Stores per project, so it's important to clean up resources when you are finished with development.

\n

JavaScript

\n
await ai.fileSearchStores.delete({\n    name: fileStore.name,\n    config: { force: true }\n});\n
\n
\n

Thanks for reading! If you have any questions or feedback, please let me know on Twitter or LinkedIn.

\n", "content_markdown": "The Gemini API File Search tool is a fully managed RAG (Retrieval-Augmented Generation) system built directly into the Gemini API. It automatically manages file storage, chunks your data, creates embeddings, and seamlessly injects the most relevant context into your prompts.\n\nThis must be expensive? No, file storage and embedding generation at query time are completely free of charge. You only pay for the initial indexing of your files at a fixed rate of $0.15 (based on the embedding) per 1 million tokens.\n\nThis tutorial will walk you through the complete lifecycle of using File Search with the JavaScript/TypeScript, you will learn how to:\n\n1. Create a File Search Store\n2. Find a Store by Display Name\n3. Upload Multiple Files Concurrently\n4. Advanced Upload: Chunking & Metadata\n5. Run a Standard Generation Query (RAG)\n6. Find a Specific Document\n7. Delete a Document\n8. Update a Document\n9. Cleanup: Delete the File Search Store\n\nBefore we start, make sure you have an [API key from Google AI Studio](https://aistudio.google.com/api-keys) and have installed the latest SDK:\n\nBash\n\n```bash\nnpm install @google/genai\n```\n\nInitialize your client in your JavaScript environment:\n\nJavaScript\n\n```js\nimport { GoogleGenAI } from '@google/genai';\nimport fs from 'fs';\nimport path from 'path';\n \nconst ai = new GoogleGenAI({});\n```\n\n### 1) Create a File Search Store\n\nA **File Search Store** is a persistent container for your document chunks and embeddings. It's distinct from raw file storage and can hold gigabytes of data.\n\nJavaScript\n\n```js\nconst fileStoreName = 'my-example-store';\n \nconst createStoreOp = await ai.fileSearchStores.create({\n config: { displayName: fileStoreName }\n});\n \nconsole.log(`Store created with Name: ${createStoreOp.name}`);\n```\n\n### 2) Find a Store by Display Name\n\nOften the creation of a store and the use are in a different application session. Since the API assigns a unique ID (`fileSearchStores/xyz...`), you need to look it up by the human-readable `displayName`.\n\nJavaScript\n\n```js\nlet fileStore = null;\n// List stores with a page size limit\nconst pager = await ai.fileSearchStores.list({ config: { pageSize: 10 } });\nlet page = pager.page;\n \n// Iterate through pages until we find a match\nsearchLoop: while (true) {\n for (const store of page) {\n if (store.displayName === fileStoreName) {\n fileStore = store;\n break searchLoop;\n }\n }\n if (!pager.hasNextPage()) break;\n page = await pager.nextPage();\n}\n \nif (!fileStore) {\n throw new Error(`Store with display name '${fileStoreName}' not found.`);\n}\nconsole.log(`Found store: ${fileStore.name}`);\n```\n\n### 3) Upload Multiple Files Concurrently\n\nSpeed matters. When ingesting a folder of documents, don't process them sequentially. The API supports concurrent operations, so we can use `Promise.all` to upload and process multiple files at once.\n\nWe'll use the helper method `uploadToFileSearchStore`, which handles uploading the raw file and initiating the indexing process in one step. We then monitor `operation.done` to ensure processing completes before moving on.\n\nJavaScript\n\n```js\nconst docsDir = \"docs\"; // Ensure you have a 'docs' folder with some text files\nconst files = fs.readdirSync(docsDir).map(file => path.join(docsDir, file));\n \nawait Promise.all(files.map(async (filePath) => {\n // 1. Initiate upload and indexing\n let operation = await ai.fileSearchStores.uploadToFileSearchStore({\n file: filePath,\n fileSearchStoreName: fileStore.name,\n config: {\n displayName: path.basename(filePath),\n }\n });\n \n // 2. Poll until the document is fully processed\n while (!operation.done) {\n await new Promise(resolve => setTimeout(resolve, 1000)); // wait 1s\n operation = await ai.operations.get({ operation });\n }\n console.log(`Processing complete for: ${path.basename(filePath)}`);\n return operation;\n}));\n```\n\n### 4) Upload with Custom Chunking Strategies\n\nBy default, Gemini handles chunking intelligently. However, for specific use cases you might want tighter control over how your data is split.\n\nYou can define a `chunkingConfig` during upload to specify parameters like `maxTokensPerChunk` and `maxOverlapTokens` and `customMetadata` to attach key-value pairs to the document.\n\nJavaScript\n\n```js\nconst specialDocPath = 'special-docs/technical-manual.txt';\n \nlet advancedUploadOp = await ai.fileSearchStores.uploadToFileSearchStore({\n file: specialDocPath,\n fileSearchStoreName: fileStore.name,\n config: {\n displayName: 'technical-manual.txt',\n customMetadata: [\n { key: \"doc_type\", stringValue: \"manual\" },\n ],\n chunkingConfig: {\n whiteSpaceConfig: {\n maxTokensPerChunk: 500, // Smaller chunks for more precise retrieval\n maxOverlapTokens: 50 // Ensure context isn't lost between chunks\n }\n }\n }\n});\n \n// Wait for the file to process\nwhile (!advancedUploadOp.done) {\n await new Promise(resolve => setTimeout(resolve, 1000));\n advancedUploadOp = await ai.operations.get({ operation: advancedUploadOp });\n}\nconsole.log(\"Advanced file processed.\");\n```\n\n### 5) Run a Generation Query using File Search (RAG)\n\nWe don't need to manually retrieve chunks. We just tell the Gemini model to use the `fileSearch` tool and point it to our store name. Gemini understands it needs more information, searches the store, and grounds its response automatically.\n\nJavaScript\n\n```js\nconst response = await ai.models.generateContent({\n model: \"gemini-2.5-flash\",\n contents: \"What is Gemini and what is the File API?\",\n config: {\n tools: [{\n fileSearch: {\n fileSearchStoreNames: [fileStore.name]\n }\n }]\n }\n});\n \nconsole.log(\"Model response:\", response.text);\n// Optionally check response.candidates[0].groundingMetadata for citations!\n```\n\nBecause we tagged our technical manual in Step 4, we can now force Gemini to *only* look at documents matching that tag by using a metadataFilter.\n\nJavaScript\n\n```js\nconst responseFiltered = await ai.models.generateContent({\n model: \"gemini-2.5-flash\",\n contents: \"How do I reset the device according to the manual?\",\n config: {\n tools: [{\n fileSearch: {\n fileSearchStoreNames: [fileStore.name],\n metadataFilter: 'doc_type=\"manual\"'\n }\n }]\n }\n});\n \nconsole.log(\"Filtered response:\", responseFiltered.text);\n```\n\n### 6) Find a Specific Document within a Store\n\nYou'll often need to manage individual documents within your store. You can find a specific document by its display name.\n\nJavaScript\n\n```js\nconst docToFind = 'doc1.txt';\nlet targetDoc = null;\n \nlet documentPager = await ai.fileSearchStores.documents.list({\n parent: fileStore.name,\n});\n \n// Iterate through the store's document list\nsearchDocsLoop: while (true) {\n for (const document of documentPager.page) {\n if (document.displayName === docToFind) {\n targetDoc = document;\n break searchDocsLoop;\n }\n }\n if (!documentPager.hasNextPage()) break;\n documentPager = await documentPager.nextPage();\n}\n \nif (!targetDoc) throw new Error(`Document '${docToFind}' not found.`);\n```\n\n### 7) Delete a Document\n\nCurrently, the standard flow to update a document in File Search is to delete the old version and upload a new one.\n\nJavaScript\n\n```js\nawait ai.fileSearchStores.documents.delete({\n name: targetDoc.name,\n config: { force: true } // Required to permanently delete from the store\n});\n```\n\n### 8) Update a Document\n\nFile Search documents are immutable once indexed. To \"update\" a document, you must find it, delete it, and upload the new version. In this step, we will automate this entire loop to update `doc1.txt` with new information.\n\nJavaScript\n\n```js\nconst docToUpdate = 'doc1.txt'; // assuming it has new content\nconst localDocPath = path.join(docsDir, docToUpdate);\n \n// 1. Find the existing document ID in the store based on its display name\nlet documentPager = await ai.fileSearchStores.documents.list({ parent: fileStore.name });\nlet foundDoc = null;\nfindLoop: while (true) {\n for (const doc of documentPager.page) {\n if (doc.displayName === docToUpdate) {\n foundDoc = doc;\n break findLoop;\n }\n }\n if (!documentPager.hasNextPage()) break;\n documentPager = await documentPager.nextPage();\n}\n \n// 2. If we found it, delete it\nif (foundDoc) {\n await ai.fileSearchStores.documents.delete({\n name: foundDoc.name,\n config: { force: true } // 'force' is required to delete indexed docs\n });\n}\n \n// 3. Upload the new version\nlet updateOp = await ai.fileSearchStores.uploadToFileSearchStore({\n file: localDocPath,\n fileSearchStoreName: fileStore.name,\n config: { displayName: docToUpdate }\n});\nwhile (!updateOp.done) {\n await new Promise(resolve => setTimeout(resolve, 1000));\n updateOp = await ai.operations.get({ operation: updateOp });\n}\n \nconsole.log(\"Revision uploaded and indexed successfully.\");\n```\n\n### 9) Cleanup: Delete the File Search Store\n\nYou are currently limited to 10 File Search Stores per project, so it's important to clean up resources when you are finished with development.\n\nJavaScript\n\n```js\nawait ai.fileSearchStores.delete({\n name: fileStore.name,\n config: { force: true }\n});\n```\n\n* * *\n\nThanks for reading! If you have any questions or feedback, please let me know on [Twitter](https://twitter.com/_philschmid) or [LinkedIn](https://www.linkedin.com/in/philipp-schmid-a6a2bb196/).\n", "dateCreated": "2026-09-27T19:29:15.293681927+00:00", "date_created": "2025-11-07T00:00:00+00:00", "date_modified": "2025-11-07T00:00:00+00:00", "date_published": "2025-11-07T00:00:00+00:00", "description": "Learn how to use the Gemini API File Search tool with JavaScript/TypeScript to build a Retrieval-Augmented Generation (RAG) system.", "external_url": "https://www.philschmid.de/gemini-file-search-javascript", "git": { "commit": "ebb0941c5c06a2ab2377342d607535262a3e969e", "path": "items/philschmid-de/2025/11/2025-11-07-gemini-api-file-search-a-web-developer-tutorial.md", "permalink": "https://github.com/aymericbeaumet/aggr-instance/blob/ebb0941c5c06a2ab2377342d607535262a3e969e/items/philschmid-de/2025/11/2025-11-07-gemini-api-file-search-a-web-developer-tutorial.md" }, "id": "urn:aggr:item:4fa1fdce3813f181bdf171cad07d35bb3bed2ce8", "isBasedOn": { "@id": "https://www.philschmid.de/gemini-file-search-javascript" }, "mainEntity": { "@id": "https://www.philschmid.de/gemini-file-search-javascript", "@type": "CreativeWork", "archivedAt": { "@id": "https://aggr.aymericbeaumet.com/items/philschmid-de/2025-11-07-gemini-api-file-search-a-web-developer-tutorial/#webpage" }, "dateModified": "2025-11-07T00:00:00+00:00", "datePublished": "2025-11-07T00:00:00+00:00", "headline": "Gemini API File Search: A Web Developer Tutorial", "timeRequired": "PT5M", "url": "https://www.philschmid.de/gemini-file-search-javascript", "wordCount": 1092 }, "name": "Archived snapshot: Gemini API File Search: A Web Developer Tutorial", "preview": null, "reading_minutes": 5, "replicated_at": null, "source": "philschmid-de", "source_name": "philschmid.de - RSS feed", "summary": "Learn how to use the Gemini API File Search tool with JavaScript/TypeScript to build a Retrieval-Augmented Generation (RAG) system.", "tags": [], "temporalCoverage": "2026-09-27T19:29:15.293681927+00:00", "title": "Gemini API File Search: A Web Developer Tutorial", "url": "https://aggr.aymericbeaumet.com/items/philschmid-de/2025-11-07-gemini-api-file-search-a-web-developer-tutorial/", "word_count": 1092 }