0
# File Search Stores and Documents
1
2
Create and manage file search stores for Retrieval-Augmented Generation (RAG). File search stores enable semantic search over uploaded documents, allowing AI models to ground their responses in your custom knowledge base.
3
4
## Core Imports
5
6
```java
7
import com.google.genai.FileSearchStores;
8
import com.google.genai.Documents;
9
import com.google.genai.AsyncFileSearchStores;
10
import com.google.genai.AsyncDocuments;
11
import com.google.genai.Pager;
12
import com.google.genai.types.FileSearchStore;
13
import com.google.genai.types.Document;
14
import com.google.genai.types.CreateFileSearchStoreConfig;
15
import com.google.genai.types.GetFileSearchStoreConfig;
16
import com.google.genai.types.DeleteFileSearchStoreConfig;
17
import com.google.genai.types.ListFileSearchStoresConfig;
18
import com.google.genai.types.ImportFileOperation;
19
import com.google.genai.types.UploadToFileSearchStoreOperation;
20
import com.google.genai.types.UploadToFileSearchStoreConfig;
21
import com.google.genai.types.ImportFileConfig;
22
import java.util.concurrent.CompletableFuture;
23
```
24
25
## Capabilities
26
27
### File Search Stores
28
29
Create semantic search stores and upload documents for RAG applications.
30
31
### Documents
32
33
Manage documents within file search stores.
34
35
## FileSearchStores Service
36
37
```java { .api }
38
package com.google.genai;
39
40
public final class FileSearchStores {
41
public final Documents documents;
42
43
// Create and manage stores
44
public FileSearchStore create(CreateFileSearchStoreConfig config);
45
public FileSearchStore get(String name, GetFileSearchStoreConfig config);
46
public void delete(String name, DeleteFileSearchStoreConfig config);
47
public Pager<FileSearchStore> list(ListFileSearchStoresConfig config);
48
49
// Upload and import files
50
public UploadToFileSearchStoreOperation uploadToFileSearchStore(
51
String storeName,
52
java.io.File file,
53
UploadToFileSearchStoreConfig config);
54
55
public UploadToFileSearchStoreOperation uploadToFileSearchStore(
56
String storeName,
57
byte[] bytes,
58
UploadToFileSearchStoreConfig config);
59
60
public UploadToFileSearchStoreOperation uploadToFileSearchStore(
61
String storeName,
62
InputStream inputStream,
63
long size,
64
UploadToFileSearchStoreConfig config);
65
66
public UploadToFileSearchStoreOperation uploadToFileSearchStore(
67
String storeName,
68
String filePath,
69
UploadToFileSearchStoreConfig config);
70
71
public ImportFileOperation importFile(
72
String fileSearchStoreName,
73
String fileName,
74
ImportFileConfig config);
75
}
76
```
77
78
## AsyncFileSearchStores Service
79
80
```java { .api }
81
package com.google.genai;
82
83
public final class AsyncFileSearchStores {
84
public final AsyncDocuments documents;
85
86
public CompletableFuture<FileSearchStore> create(CreateFileSearchStoreConfig config);
87
public CompletableFuture<FileSearchStore> get(String name, GetFileSearchStoreConfig config);
88
public CompletableFuture<Void> delete(String name, DeleteFileSearchStoreConfig config);
89
public CompletableFuture<AsyncPager<FileSearchStore>> list(ListFileSearchStoresConfig config);
90
91
public CompletableFuture<UploadToFileSearchStoreOperation> uploadToFileSearchStore(
92
String storeName,
93
java.io.File file,
94
UploadToFileSearchStoreConfig config);
95
96
public CompletableFuture<UploadToFileSearchStoreOperation> uploadToFileSearchStore(
97
String storeName,
98
byte[] bytes,
99
UploadToFileSearchStoreConfig config);
100
101
public CompletableFuture<UploadToFileSearchStoreOperation> uploadToFileSearchStore(
102
String storeName,
103
InputStream inputStream,
104
long size,
105
UploadToFileSearchStoreConfig config);
106
107
public CompletableFuture<UploadToFileSearchStoreOperation> uploadToFileSearchStore(
108
String storeName,
109
String filePath,
110
UploadToFileSearchStoreConfig config);
111
112
public CompletableFuture<ImportFileOperation> importFile(
113
String fileSearchStoreName,
114
String fileName,
115
ImportFileConfig config);
116
}
117
```
118
119
## Documents Service
120
121
```java { .api }
122
package com.google.genai;
123
124
public final class Documents {
125
public Document get(String name, GetDocumentConfig config);
126
public void delete(String name, DeleteDocumentConfig config);
127
public Pager<Document> list(String parent, ListDocumentsConfig config);
128
}
129
```
130
131
## AsyncDocuments Service
132
133
```java { .api }
134
package com.google.genai;
135
136
public final class AsyncDocuments {
137
public CompletableFuture<Document> get(String name, GetDocumentConfig config);
138
public CompletableFuture<Void> delete(String name, DeleteDocumentConfig config);
139
public CompletableFuture<AsyncPager<Document>> list(String parent, ListDocumentsConfig config);
140
}
141
```
142
143
## FileSearchStore Type
144
145
```java { .api }
146
package com.google.genai.types;
147
148
public final class FileSearchStore {
149
public static Builder builder();
150
151
public Optional<String> name();
152
public Optional<String> displayName();
153
public Optional<String> createTime();
154
public Optional<String> updateTime();
155
}
156
```
157
158
## Document Type
159
160
```java { .api }
161
package com.google.genai.types;
162
163
public final class Document {
164
public static Builder builder();
165
166
public Optional<String> name();
167
public Optional<String> displayName();
168
public Optional<String> createTime();
169
public Optional<String> updateTime();
170
public Optional<Map<String, String>> customMetadata();
171
}
172
```
173
174
## Configuration Types
175
176
### Create File Search Store Config
177
178
```java { .api }
179
package com.google.genai.types;
180
181
public final class CreateFileSearchStoreConfig {
182
public static Builder builder();
183
184
public Optional<String> displayName();
185
public Optional<HttpOptions> httpOptions();
186
}
187
```
188
189
### Upload to File Search Store Config
190
191
```java { .api }
192
package com.google.genai.types;
193
194
public final class UploadToFileSearchStoreConfig {
195
public static Builder builder();
196
197
public Optional<String> displayName();
198
public Optional<String> mimeType();
199
public Optional<Map<String, String>> customMetadata();
200
public Optional<HttpOptions> httpOptions();
201
}
202
```
203
204
### Import File Config
205
206
```java { .api }
207
package com.google.genai.types;
208
209
public final class ImportFileConfig {
210
public static Builder builder();
211
212
public Optional<Map<String, String>> customMetadata();
213
public Optional<HttpOptions> httpOptions();
214
}
215
```
216
217
## Operation Types
218
219
### Upload to File Search Store Operation
220
221
```java { .api }
222
package com.google.genai.types;
223
224
public final class UploadToFileSearchStoreOperation {
225
public Optional<Document> document();
226
public Optional<String> name();
227
}
228
```
229
230
### Import File Operation
231
232
```java { .api }
233
package com.google.genai.types;
234
235
public final class ImportFileOperation {
236
public Optional<Document> document();
237
public Optional<String> name();
238
}
239
```
240
241
## Create File Search Store
242
243
### Basic Creation
244
245
```java
246
import com.google.genai.Client;
247
import com.google.genai.types.FileSearchStore;
248
import com.google.genai.types.CreateFileSearchStoreConfig;
249
250
Client client = new Client();
251
252
CreateFileSearchStoreConfig config = CreateFileSearchStoreConfig.builder()
253
.displayName("Product Documentation Store")
254
.build();
255
256
FileSearchStore store = client.fileSearchStores.create(config);
257
258
System.out.println("Created store: " + store.name().orElse("N/A"));
259
System.out.println("Display name: " + store.displayName().orElse("N/A"));
260
```
261
262
### Create Without Config
263
264
```java
265
FileSearchStore store = client.fileSearchStores.create(null);
266
System.out.println("Store created: " + store.name().orElse("N/A"));
267
```
268
269
## Upload Documents to Store
270
271
### Upload from File Path
272
273
```java
274
import com.google.genai.types.UploadToFileSearchStoreOperation;
275
276
String storeName = "fileSearchStores/store123";
277
278
UploadToFileSearchStoreConfig config = UploadToFileSearchStoreConfig.builder()
279
.displayName("Product Manual")
280
.mimeType("application/pdf")
281
.customMetadata(Map.of(
282
"category", "manual",
283
"version", "2.0"
284
))
285
.build();
286
287
UploadToFileSearchStoreOperation operation =
288
client.fileSearchStores.uploadToFileSearchStore(
289
storeName,
290
"path/to/product-manual.pdf",
291
config
292
);
293
294
operation.document().ifPresent(doc -> {
295
System.out.println("Uploaded document: " + doc.name().orElse("N/A"));
296
System.out.println("Display name: " + doc.displayName().orElse("N/A"));
297
});
298
```
299
300
### Upload from File Object
301
302
```java
303
import java.io.File as JavaFile;
304
305
JavaFile file = new JavaFile("path/to/document.pdf");
306
307
UploadToFileSearchStoreOperation operation =
308
client.fileSearchStores.uploadToFileSearchStore(
309
storeName,
310
file,
311
UploadToFileSearchStoreConfig.builder()
312
.displayName(file.getName())
313
.mimeType("application/pdf")
314
.build()
315
);
316
```
317
318
### Upload from Bytes
319
320
```java
321
import java.nio.file.Files;
322
import java.nio.file.Paths;
323
324
byte[] documentBytes = Files.readAllBytes(Paths.get("document.pdf"));
325
326
UploadToFileSearchStoreOperation operation =
327
client.fileSearchStores.uploadToFileSearchStore(
328
storeName,
329
documentBytes,
330
UploadToFileSearchStoreConfig.builder()
331
.displayName("Uploaded Document")
332
.mimeType("application/pdf")
333
.build()
334
);
335
```
336
337
### Upload from InputStream
338
339
```java
340
import java.io.FileInputStream;
341
342
try (FileInputStream inputStream = new FileInputStream("document.pdf")) {
343
long fileSize = new JavaFile("document.pdf").length();
344
345
UploadToFileSearchStoreOperation operation =
346
client.fileSearchStores.uploadToFileSearchStore(
347
storeName,
348
inputStream,
349
fileSize,
350
UploadToFileSearchStoreConfig.builder()
351
.displayName("Streamed Document")
352
.mimeType("application/pdf")
353
.build()
354
);
355
}
356
```
357
358
### Batch Upload Multiple Documents
359
360
```java
361
List<String> documentPaths = List.of(
362
"doc1.pdf", "doc2.pdf", "doc3.pdf"
363
);
364
365
for (String path : documentPaths) {
366
UploadToFileSearchStoreOperation operation =
367
client.fileSearchStores.uploadToFileSearchStore(
368
storeName,
369
path,
370
UploadToFileSearchStoreConfig.builder()
371
.displayName(new JavaFile(path).getName())
372
.mimeType("application/pdf")
373
.build()
374
);
375
376
System.out.println("Uploaded: " + path);
377
}
378
```
379
380
## Import Existing Files
381
382
### Import from Files API
383
384
```java
385
import com.google.genai.types.File;
386
import com.google.genai.types.ImportFileOperation;
387
388
// First upload file using Files API
389
File uploadedFile = client.files.upload("document.pdf", null);
390
391
// Then import it into file search store
392
ImportFileConfig config = ImportFileConfig.builder()
393
.customMetadata(Map.of("source", "files-api"))
394
.build();
395
396
ImportFileOperation importOp = client.fileSearchStores.importFile(
397
storeName,
398
uploadedFile.name().get(),
399
config
400
);
401
402
importOp.document().ifPresent(doc -> {
403
System.out.println("Imported: " + doc.name().orElse("N/A"));
404
});
405
```
406
407
## Manage File Search Stores
408
409
### Get Store Information
410
411
```java
412
FileSearchStore store = client.fileSearchStores.get(
413
"fileSearchStores/store123",
414
null
415
);
416
417
System.out.println("Name: " + store.name().orElse("N/A"));
418
System.out.println("Display name: " + store.displayName().orElse("N/A"));
419
System.out.println("Created: " + store.createTime().orElse("N/A"));
420
System.out.println("Updated: " + store.updateTime().orElse("N/A"));
421
```
422
423
### List All Stores
424
425
```java
426
import com.google.genai.Pager;
427
428
Pager<FileSearchStore> pager = client.fileSearchStores.list(null);
429
430
for (FileSearchStore store : pager) {
431
System.out.println("Store: " + store.displayName().orElse("N/A"));
432
System.out.println(" Name: " + store.name().orElse("N/A"));
433
System.out.println(" Created: " + store.createTime().orElse("N/A"));
434
}
435
```
436
437
### List with Pagination
438
439
```java
440
ListFileSearchStoresConfig config = ListFileSearchStoresConfig.builder()
441
.pageSize(10)
442
.build();
443
444
Pager<FileSearchStore> pager = client.fileSearchStores.list(config);
445
446
// Get first page
447
ImmutableList<FileSearchStore> firstPage = pager.page();
448
System.out.println("Stores in first page: " + firstPage.size());
449
```
450
451
### Delete Store
452
453
```java
454
client.fileSearchStores.delete("fileSearchStores/store123", null);
455
System.out.println("Store deleted");
456
```
457
458
## Manage Documents
459
460
### List Documents in Store
461
462
```java
463
String storeName = "fileSearchStores/store123";
464
465
Pager<Document> pager = client.fileSearchStores.documents.list(storeName, null);
466
467
for (Document doc : pager) {
468
System.out.println("Document: " + doc.displayName().orElse("N/A"));
469
System.out.println(" Name: " + doc.name().orElse("N/A"));
470
471
doc.customMetadata().ifPresent(metadata -> {
472
System.out.println(" Metadata: " + metadata);
473
});
474
}
475
```
476
477
### Get Document Details
478
479
```java
480
Document doc = client.fileSearchStores.documents.get(
481
"fileSearchStores/store123/documents/doc456",
482
null
483
);
484
485
System.out.println("Document: " + doc.displayName().orElse("N/A"));
486
System.out.println("Created: " + doc.createTime().orElse("N/A"));
487
488
doc.customMetadata().ifPresent(metadata -> {
489
metadata.forEach((key, value) -> {
490
System.out.println(key + ": " + value);
491
});
492
});
493
```
494
495
### Delete Document
496
497
```java
498
client.fileSearchStores.documents.delete(
499
"fileSearchStores/store123/documents/doc456",
500
null
501
);
502
503
System.out.println("Document deleted");
504
```
505
506
## Use with File Search
507
508
### Configure File Search Tool
509
510
```java
511
import com.google.genai.types.Tool;
512
import com.google.genai.types.FileSearch;
513
import com.google.genai.types.GenerateContentConfig;
514
515
// Create file search tool referencing the store
516
FileSearch fileSearch = FileSearch.builder()
517
.fileSearchStores(List.of("fileSearchStores/store123"))
518
.build();
519
520
Tool tool = Tool.builder()
521
.fileSearch(fileSearch)
522
.build();
523
524
GenerateContentConfig config = GenerateContentConfig.builder()
525
.tools(List.of(tool))
526
.build();
527
528
// Use in content generation
529
GenerateContentResponse response = client.models.generateContent(
530
"gemini-2.0-flash",
531
"What are the key features mentioned in the product documentation?",
532
config
533
);
534
535
System.out.println(response.text());
536
```
537
538
### RAG with Multiple Stores
539
540
```java
541
FileSearch fileSearch = FileSearch.builder()
542
.fileSearchStores(List.of(
543
"fileSearchStores/store1",
544
"fileSearchStores/store2",
545
"fileSearchStores/store3"
546
))
547
.build();
548
549
Tool tool = Tool.builder()
550
.fileSearch(fileSearch)
551
.build();
552
553
GenerateContentConfig config = GenerateContentConfig.builder()
554
.tools(List.of(tool))
555
.systemInstruction(Content.fromParts(Part.fromText(
556
"Answer questions based on the provided documentation. " +
557
"Always cite your sources."
558
)))
559
.build();
560
561
GenerateContentResponse response = client.models.generateContent(
562
"gemini-2.0-flash",
563
"Compare the pricing models across all products",
564
config
565
);
566
```
567
568
## Complete RAG Example
569
570
### Build Knowledge Base and Query
571
572
```java
573
public class RAGExample {
574
public static void main(String[] args) throws Exception {
575
Client client = new Client();
576
577
// Step 1: Create file search store
578
CreateFileSearchStoreConfig storeConfig =
579
CreateFileSearchStoreConfig.builder()
580
.displayName("Company Knowledge Base")
581
.build();
582
583
FileSearchStore store = client.fileSearchStores.create(storeConfig);
584
String storeName = store.name().get();
585
System.out.println("Created store: " + storeName);
586
587
// Step 2: Upload documents
588
List<String> docPaths = List.of(
589
"product-manual.pdf",
590
"faq.pdf",
591
"technical-specs.pdf"
592
);
593
594
for (String path : docPaths) {
595
UploadToFileSearchStoreConfig uploadConfig =
596
UploadToFileSearchStoreConfig.builder()
597
.displayName(new JavaFile(path).getName())
598
.mimeType("application/pdf")
599
.customMetadata(Map.of("type", "documentation"))
600
.build();
601
602
UploadToFileSearchStoreOperation operation =
603
client.fileSearchStores.uploadToFileSearchStore(
604
storeName,
605
path,
606
uploadConfig
607
);
608
609
System.out.println("Uploaded: " + path);
610
}
611
612
// Step 3: Configure file search
613
FileSearch fileSearch = FileSearch.builder()
614
.fileSearchStores(List.of(storeName))
615
.build();
616
617
Tool tool = Tool.builder()
618
.fileSearch(fileSearch)
619
.build();
620
621
GenerateContentConfig genConfig = GenerateContentConfig.builder()
622
.tools(List.of(tool))
623
.temperature(0.2)
624
.build();
625
626
// Step 4: Query the knowledge base
627
String question = "What is the warranty period for the product?";
628
629
GenerateContentResponse response = client.models.generateContent(
630
"gemini-2.0-flash",
631
question,
632
genConfig
633
);
634
635
System.out.println("\nQuestion: " + question);
636
System.out.println("Answer: " + response.text());
637
638
// Step 5: Check grounding metadata
639
response.candidates().ifPresent(candidates -> {
640
if (!candidates.isEmpty()) {
641
candidates.get(0).groundingMetadata().ifPresent(metadata -> {
642
System.out.println("\nGrounding sources:");
643
metadata.groundingChunks().ifPresent(chunks -> {
644
chunks.forEach(chunk -> {
645
System.out.println(" - " + chunk);
646
});
647
});
648
});
649
}
650
});
651
652
client.close();
653
}
654
}
655
```
656
657
## Async Operations
658
659
### Async Store Creation
660
661
```java
662
CompletableFuture<FileSearchStore> future =
663
client.async.fileSearchStores.create(
664
CreateFileSearchStoreConfig.builder()
665
.displayName("Async Store")
666
.build()
667
);
668
669
future.thenAccept(store -> {
670
System.out.println("Store created: " + store.name().orElse("N/A"));
671
});
672
```
673
674
### Async Document Upload
675
676
```java
677
CompletableFuture<UploadToFileSearchStoreOperation> future =
678
client.async.fileSearchStores.uploadToFileSearchStore(
679
storeName,
680
"document.pdf",
681
UploadToFileSearchStoreConfig.builder()
682
.displayName("Async Upload")
683
.mimeType("application/pdf")
684
.build()
685
);
686
687
future.thenAccept(operation -> {
688
operation.document().ifPresent(doc -> {
689
System.out.println("Uploaded: " + doc.name().orElse("N/A"));
690
});
691
});
692
```
693
694
### Async List Documents
695
696
```java
697
CompletableFuture<AsyncPager<Document>> future =
698
client.async.fileSearchStores.documents.list(storeName, null);
699
700
future.thenAccept(pager -> {
701
pager.forEach(doc -> {
702
System.out.println("Document: " + doc.displayName().orElse("N/A"));
703
});
704
});
705
```
706
707
## Best Practices
708
709
### Organize with Custom Metadata
710
711
```java
712
UploadToFileSearchStoreConfig config = UploadToFileSearchStoreConfig.builder()
713
.displayName("Q3 Financial Report")
714
.mimeType("application/pdf")
715
.customMetadata(Map.of(
716
"department", "finance",
717
"quarter", "Q3",
718
"year", "2024",
719
"confidentiality", "internal"
720
))
721
.build();
722
723
client.fileSearchStores.uploadToFileSearchStore(storeName, "q3-report.pdf", config);
724
```
725
726
### Handle Large Document Sets
727
728
```java
729
// Upload documents in batches
730
List<String> allDocs = /* large list of document paths */;
731
int batchSize = 10;
732
733
for (int i = 0; i < allDocs.size(); i += batchSize) {
734
List<String> batch = allDocs.subList(
735
i,
736
Math.min(i + batchSize, allDocs.size())
737
);
738
739
// Upload batch
740
for (String docPath : batch) {
741
client.fileSearchStores.uploadToFileSearchStore(
742
storeName,
743
docPath,
744
null
745
);
746
}
747
748
// Optional: Add delay to avoid rate limits
749
Thread.sleep(1000);
750
}
751
```
752
753
### Clean Up Old Documents
754
755
```java
756
// List all documents
757
Pager<Document> pager = client.fileSearchStores.documents.list(storeName, null);
758
759
LocalDate cutoffDate = LocalDate.now().minusMonths(6);
760
761
for (Document doc : pager) {
762
doc.createTime().ifPresent(createTimeStr -> {
763
// Parse create time and check if older than 6 months
764
LocalDate createDate = LocalDate.parse(createTimeStr.substring(0, 10));
765
766
if (createDate.isBefore(cutoffDate)) {
767
System.out.println("Deleting old document: " +
768
doc.displayName().orElse("N/A"));
769
client.fileSearchStores.documents.delete(doc.name().get(), null);
770
}
771
});
772
}
773
```
774
775
### Error Handling
776
777
```java
778
try {
779
UploadToFileSearchStoreOperation operation =
780
client.fileSearchStores.uploadToFileSearchStore(
781
storeName,
782
"document.pdf",
783
null
784
);
785
786
System.out.println("Upload successful");
787
} catch (GenAiIOException e) {
788
System.err.println("I/O error: " + e.getMessage());
789
} catch (ApiException e) {
790
System.err.println("API error: " + e.code() + " - " + e.message());
791
}
792
```
793
794
## Use Cases
795
796
### Customer Support Knowledge Base
797
798
Upload FAQ documents, product manuals, and support articles to provide AI-powered customer support with accurate, grounded responses.
799
800
### Enterprise Document Search
801
802
Build semantic search over internal documentation, policies, and procedures for employee self-service.
803
804
### Research Assistant
805
806
Upload research papers, articles, and reports to create an AI research assistant that can answer questions with citations.
807
808
### Code Documentation
809
810
Index code documentation, API references, and tutorials for an AI coding assistant.
811
812
### Legal Document Analysis
813
814
Upload contracts, regulations, and case law for AI-assisted legal research and analysis.
815