0
# File Search Stores and Documents
1

2
Create and manage file search stores with document retrieval for retrieval-augmented generation (RAG). File search stores enable semantic search over your documents, allowing models to ground responses in your own data sources.
3

4
## Capabilities
5

6
### Create File Search Store
7

8
Create a file search store to organize and search documents.
9

10
```python { .api }
11
class FileSearchStores:
12
    """Synchronous file search stores API."""
13

14
    def create(
15
        self,
16
        *,
17
        config: CreateFileSearchStoreConfig
18
    ) -> FileSearchStore:
19
        """
20
        Create a file search store.
21

22
        Parameters:
23
            config (CreateFileSearchStoreConfig): Store configuration including:
24
                - display_name: Display name for the store
25
                - description: Description of the store
26

27
        Returns:
28
            FileSearchStore: Created store with name and metadata.
29

30
        Raises:
31
            ClientError: For client errors (4xx status codes)
32
            ServerError: For server errors (5xx status codes)
33
        """
34
        ...
35

36
    @property
37
    def documents(self) -> Documents:
38
        """Access documents sub-API for managing documents within stores."""
39
        ...
40

41
class AsyncFileSearchStores:
42
    """Asynchronous file search stores API."""
43

44
    async def create(
45
        self,
46
        *,
47
        config: CreateFileSearchStoreConfig
48
    ) -> FileSearchStore:
49
        """Async version of create."""
50
        ...
51

52
    @property
53
    def documents(self) -> AsyncDocuments:
54
        """Access async documents sub-API."""
55
        ...
56
```
57

58
**Usage Example:**
59

60
```python
61
from google.genai import Client
62
from google.genai.types import CreateFileSearchStoreConfig
63

64
client = Client(vertexai=True, project='PROJECT_ID', location='us-central1')
65

66
config = CreateFileSearchStoreConfig(
67
    display_name='Product Documentation',
68
    description='Store for product manuals and guides'
69
)
70

71
store = client.file_search_stores.create(config=config)
72
print(f"Created store: {store.name}")
73
```
74

75
### Get File Search Store
76

77
Retrieve information about a file search store.
78

79
```python { .api }
80
class FileSearchStores:
81
    """Synchronous file search stores API."""
82

83
    def get(self, *, name: str) -> FileSearchStore:
84
        """
85
        Get file search store information.
86

87
        Parameters:
88
            name (str): Store name in format 'fileSearchStores/*'.
89

90
        Returns:
91
            FileSearchStore: Store information.
92
        """
93
        ...
94

95
class AsyncFileSearchStores:
96
    """Asynchronous file search stores API."""
97

98
    async def get(self, *, name: str) -> FileSearchStore:
99
        """Async version of get."""
100
        ...
101
```
102

103
### Delete File Search Store
104

105
Delete a file search store and all its documents.
106

107
```python { .api }
108
class FileSearchStores:
109
    """Synchronous file search stores API."""
110

111
    def delete(self, *, name: str) -> None:
112
        """
113
        Delete a file search store.
114

115
        Parameters:
116
            name (str): Store name in format 'fileSearchStores/*'.
117
        """
118
        ...
119

120
class AsyncFileSearchStores:
121
    """Asynchronous file search stores API."""
122

123
    async def delete(self, *, name: str) -> None:
124
        """Async version of delete."""
125
        ...
126
```
127

128
### Import File
129

130
Import a file into a file search store from GCS.
131

132
```python { .api }
133
class FileSearchStores:
134
    """Synchronous file search stores API."""
135

136
    def import_file(
137
        self,
138
        *,
139
        store: str,
140
        source: ImportFileSource,
141
        config: Optional[ImportFileConfig] = None
142
    ) -> ImportFileOperation:
143
        """
144
        Import file into store (returns long-running operation).
145

146
        Parameters:
147
            store (str): Store name.
148
            source (ImportFileSource): Import source (GCS URI).
149
            config (ImportFileConfig, optional): Import configuration.
150

151
        Returns:
152
            ImportFileOperation: Long-running operation for import.
153
        """
154
        ...
155

156
class AsyncFileSearchStores:
157
    """Asynchronous file search stores API."""
158

159
    async def import_file(
160
        self,
161
        *,
162
        store: str,
163
        source: ImportFileSource,
164
        config: Optional[ImportFileConfig] = None
165
    ) -> ImportFileOperation:
166
        """Async version of import_file."""
167
        ...
168
```
169

170
**Usage Example:**
171

172
```python
173
from google.genai import Client
174
from google.genai.types import ImportFileSource
175

176
client = Client(vertexai=True, project='PROJECT_ID', location='us-central1')
177

178
source = ImportFileSource(
179
    gcs_uri='gs://my-bucket/document.pdf'
180
)
181

182
operation = client.file_search_stores.import_file(
183
    store='fileSearchStores/abc123',
184
    source=source
185
)
186

187
# Poll for completion
188
while not operation.done:
189
    import time
190
    time.sleep(5)
191
    operation = client.operations.get(operation)
192

193
print("Import complete")
194
```
195

196
### Upload to File Search Store
197

198
Upload a local file directly to a file search store.
199

200
```python { .api }
201
class FileSearchStores:
202
    """Synchronous file search stores API."""
203

204
    def upload_to_file_search_store(
205
        self,
206
        *,
207
        store: str,
208
        file: Union[str, Path, IO],
209
        config: Optional[UploadToFileSearchStoreConfig] = None
210
    ) -> UploadToFileSearchStoreOperation:
211
        """
212
        Upload file to store (returns long-running operation).
213

214
        Parameters:
215
            store (str): Store name.
216
            file (Union[str, Path, IO]): File to upload.
217
            config (UploadToFileSearchStoreConfig, optional): Upload configuration including:
218
                - mime_type: File MIME type
219
                - display_name: Display name
220

221
        Returns:
222
            UploadToFileSearchStoreOperation: Long-running operation for upload.
223
        """
224
        ...
225

226
class AsyncFileSearchStores:
227
    """Asynchronous file search stores API."""
228

229
    async def upload_to_file_search_store(
230
        self,
231
        *,
232
        store: str,
233
        file: Union[str, Path, IO],
234
        config: Optional[UploadToFileSearchStoreConfig] = None
235
    ) -> UploadToFileSearchStoreOperation:
236
        """Async version of upload_to_file_search_store."""
237
        ...
238
```
239

240
### List File Search Stores
241

242
List all file search stores.
243

244
```python { .api }
245
class FileSearchStores:
246
    """Synchronous file search stores API."""
247

248
    def list(
249
        self,
250
        *,
251
        config: Optional[ListFileSearchStoresConfig] = None
252
    ) -> Union[Pager[FileSearchStore], Iterator[FileSearchStore]]:
253
        """
254
        List file search stores.
255

256
        Parameters:
257
            config (ListFileSearchStoresConfig, optional): List configuration.
258

259
        Returns:
260
            Union[Pager[FileSearchStore], Iterator[FileSearchStore]]: Paginated store list.
261
        """
262
        ...
263

264
class AsyncFileSearchStores:
265
    """Asynchronous file search stores API."""
266

267
    async def list(
268
        self,
269
        *,
270
        config: Optional[ListFileSearchStoresConfig] = None
271
    ) -> Union[AsyncPager[FileSearchStore], AsyncIterator[FileSearchStore]]:
272
        """Async version of list."""
273
        ...
274
```
275

276
### Documents Sub-API
277

278
Manage documents within file search stores.
279

280
```python { .api }
281
class Documents:
282
    """Synchronous documents API."""
283

284
    def get(self, *, name: str) -> Document:
285
        """
286
        Get document information.
287

288
        Parameters:
289
            name (str): Document name in format 'fileSearchStores/*/documents/*'.
290

291
        Returns:
292
            Document: Document information.
293
        """
294
        ...
295

296
    def delete(self, *, name: str) -> None:
297
        """
298
        Delete a document.
299

300
        Parameters:
301
            name (str): Document name.
302
        """
303
        ...
304

305
    def list(
306
        self,
307
        *,
308
        parent: str,
309
        config: Optional[ListDocumentsConfig] = None
310
    ) -> Union[Pager[Document], Iterator[Document]]:
311
        """
312
        List documents in a store.
313

314
        Parameters:
315
            parent (str): Store name in format 'fileSearchStores/*'.
316
            config (ListDocumentsConfig, optional): List configuration.
317

318
        Returns:
319
            Union[Pager[Document], Iterator[Document]]: Paginated document list.
320
        """
321
        ...
322

323
class AsyncDocuments:
324
    """Asynchronous documents API."""
325

326
    async def get(self, *, name: str) -> Document:
327
        """Async version of get."""
328
        ...
329

330
    async def delete(self, *, name: str) -> None:
331
        """Async version of delete."""
332
        ...
333

334
    async def list(
335
        self,
336
        *,
337
        parent: str,
338
        config: Optional[ListDocumentsConfig] = None
339
    ) -> Union[AsyncPager[Document], AsyncIterator[Document]]:
340
        """Async version of list."""
341
        ...
342
```
343

344
**Usage Example - Using File Search in RAG:**
345

346
```python
347
from google.genai import Client
348
from google.genai.types import (
349
    GenerateContentConfig,
350
    Tool,
351
    FileSearch
352
)
353

354
client = Client(vertexai=True, project='PROJECT_ID', location='us-central1')
355

356
# Configure file search tool
357
config = GenerateContentConfig(
358
    tools=[Tool(file_search=FileSearch(
359
        file_search_store='fileSearchStores/abc123'
360
    ))]
361
)
362

363
# Generate with grounding in documents
364
response = client.models.generate_content(
365
    model='gemini-2.0-flash',
366
    contents='What is the return policy for damaged items?',
367
    config=config
368
)
369

370
print(response.text)
371

372
# Check grounding metadata
373
if response.candidates[0].grounding_metadata:
374
    print("Grounded in store documents")
375
```
376

377
## Types
378

379
```python { .api }
380
from typing import Optional, Union, List, Iterator, AsyncIterator, IO, TypedDict
381
from pathlib import Path
382
from datetime import datetime
383
from enum import Enum
384

385
# Configuration types
386
class CreateFileSearchStoreConfig:
387
    """
388
    Configuration for creating file search store.
389

390
    Attributes:
391
        display_name (str, optional): Display name.
392
        description (str, optional): Description.
393
    """
394
    display_name: Optional[str] = None
395
    description: Optional[str] = None
396

397
class ImportFileConfig:
398
    """Configuration for importing files."""
399
    display_name: Optional[str] = None
400

401
class UploadToFileSearchStoreConfig:
402
    """
403
    Configuration for uploading files.
404

405
    Attributes:
406
        mime_type (str, optional): MIME type.
407
        display_name (str, optional): Display name.
408
    """
409
    mime_type: Optional[str] = None
410
    display_name: Optional[str] = None
411

412
class ListFileSearchStoresConfig:
413
    """Configuration for listing stores."""
414
    page_size: Optional[int] = None
415
    page_token: Optional[str] = None
416

417
class ListDocumentsConfig:
418
    """Configuration for listing documents."""
419
    page_size: Optional[int] = None
420
    page_token: Optional[str] = None
421

422
# Response types
423
class FileSearchStore:
424
    """
425
    File search store information.
426

427
    Attributes:
428
        name (str): Store resource name.
429
        display_name (str, optional): Display name.
430
        description (str, optional): Description.
431
        create_time (datetime): Creation time.
432
        update_time (datetime): Last update time.
433
    """
434
    name: str
435
    display_name: Optional[str] = None
436
    description: Optional[str] = None
437
    create_time: datetime
438
    update_time: datetime
439

440
class Document:
441
    """
442
    Document in file search store.
443

444
    Attributes:
445
        name (str): Document resource name.
446
        display_name (str, optional): Display name.
447
        mime_type (str): MIME type.
448
        size_bytes (int): Size in bytes.
449
        state (DocumentState): Processing state.
450
        create_time (datetime): Creation time.
451
        update_time (datetime): Last update time.
452
    """
453
    name: str
454
    display_name: Optional[str] = None
455
    mime_type: str
456
    size_bytes: int
457
    state: DocumentState
458
    create_time: datetime
459
    update_time: datetime
460

461
class DocumentState(Enum):
462
    """Document processing states."""
463
    STATE_UNSPECIFIED = 'STATE_UNSPECIFIED'
464
    PROCESSING = 'PROCESSING'
465
    ACTIVE = 'ACTIVE'
466
    FAILED = 'FAILED'
467

468
class ImportFileSource:
469
    """
470
    Import source.
471

472
    Attributes:
473
        gcs_uri (str): GCS URI of file to import.
474
    """
475
    gcs_uri: str
476

477
# Operation types
478
class ImportFileOperation:
479
    """Long-running operation for file import."""
480
    name: str
481
    done: bool
482
    error: Optional[OperationError] = None
483
    response: Optional[dict] = None
484

485
class UploadToFileSearchStoreOperation:
486
    """Long-running operation for file upload."""
487
    name: str
488
    done: bool
489
    error: Optional[OperationError] = None
490
    response: Optional[dict] = None
491

492
class OperationError:
493
    """Operation error."""
494
    code: int
495
    message: str
496

497
# Tool types for RAG
498
class FileSearch:
499
    """
500
    File search tool configuration.
501

502
    Attributes:
503
        file_search_store (str, optional): Store name to search.
504
    """
505
    file_search_store: Optional[str] = None
506

507
# Pager types
508
class Pager[T]:
509
    """Synchronous pager."""
510
    page: list[T]
511
    def next_page(self) -> None: ...
512
    def __iter__(self) -> Iterator[T]: ...
513

514
class AsyncPager[T]:
515
    """Asynchronous pager."""
516
    page: list[T]
517
    async def next_page(self) -> None: ...
518
    async def __aiter__(self) -> AsyncIterator[T]: ...
519
```
520