使用 GroupDocs.Search 的属性搜索 Java 指南
在现代以文档为中心的应用程序中，您常常需要不仅通过文本内容，还通过自定义元数据（如部门、机密级别或创建日期）来定位文件。Search by attribute java 为您提供了在单个高性能查询中实现此功能的能力。在本教程中，您将了解如何对已索引的文件批量更新属性、在索引时注入属性，以及使用 GroupDocs.Search for Java 库高效地通过元数据查询文档。
快速答案
- What is “search by attribute java”? 它允许您使用附加到每个已索引文档的键值元数据来过滤搜索结果。
- Can I modify attributes after indexing? 是的 – 使用
AttributeChangeBatch在不重建整个索引的情况下应用批量更改。 - How do I add attributes while indexing? 为
FileIndexing事件注册处理程序，并为每个文件以编程方式设置属性。 - Do I need a license? 免费试用可用于评估；生产部署需要永久许可证。
- Which Java version is required? 推荐使用 Java 8 或更高版本。
什么是 “search by attribute java”？
Search by attribute java 使您能够基于自定义元数据（属性）而非仅文本内容来查询文档。这种方法显著缩小结果集，减少网络流量，并加快响应时间，因为引擎在执行全文扫描之前先评估属性过滤器。
为什么使用动态元数据标记？
动态元数据标记使您能够在无需重新索引的情况下为文档分配、更新和管理自定义属性，提供能够适应业务规则变化的灵活分类，提高搜索效率，并在保持合规性和可审计性的同时，减少在大型仓库中进行昂贵的数据迁移的需求。
- Dynamic categorization – 将元数据与不断演变的业务规则保持同步。
- Faster filtering – 属性过滤器在全文搜索之前评估，提升响应时间。
- Compliance tracking – 为文档打标签以满足保留政策或审计要求。
- Batch update attributes – 在一次操作中更改大量文档，而无需重新索引全部内容。
前置条件
- Java 8+ (JDK 8 或更高版本)
- GroupDocs.Search for Java 库（请参见下面的 Maven 设置）
- 对 Java 集合和异常处理有基本了解
设置 GroupDocs.Search for Java
Maven 设置
在您的 pom.xml 中添加 GroupDocs 仓库和依赖项：
<repositories>
<repository>
<id>groupdocs-releases</id>
<url>https://repo.groupdocs.com/maven</url>
</repository>
</repositories>
<dependencies>
<dependency>
<groupId>com.groupdocs</groupId>
<artifactId>groupdocs-search</artifactId>
<version>25.4</version>
</dependency>
</dependencies>
直接下载
或者，从 GroupDocs.Search for Java releases 下载最新版本。如果您不想使用 Maven，可从 GroupDocs website 获取 JAR 包。
获取许可证
- 先使用免费试用来探索功能。
- 如需长期使用，可通过 license page 获取临时或完整许可证。
基本初始化
// Initialize the search index folder
String indexFolder = "C:/search_index";
Index index = new Index(indexFolder);
// Apply license if you have one
License license = new License();
license.setLicense("C:/licenses/groupdocs.lic");
如何修改文档属性（批量更新）
要在文档已索引后修改其属性，您可以使用 AttributeChangeBatch API 进行批量更新。此方法在单个事务中更新所选文件的元数据，避免重新索引整个集合的开销，并保持全文索引完整。
Direct answer: 使用 AttributeChangeBatch 将元数据的添加、删除或替换分组为单个原子操作，然后将批次提交到索引。这将在一次处理过程中更新许多文档的属性，同时保留现有的全文索引。
步骤 1：将文档添加到索引
index.add("C:/docs/contract1.pdf");
index.add("C:/docs/report2.docx");
步骤 2：检索已索引文档信息
DocumentInfo info = index.getDocumentInfo("contract1.pdf");
System.out.println("Current attributes: " + info.getAttributes());
步骤 3：批量更新文档属性
AttributeChangeBatch 类将多个属性修改分组为单个原子操作，降低 I/O 开销并确保索引一致性。
AttributeChangeBatch batch = new AttributeChangeBatch();
batch.addAttribute("contract1.pdf", "department", "Legal");
batch.removeAttribute("report2.docx", "confidential");
batch.replaceAttribute("report2.docx", "status", "archived", "active");
index.applyAttributeChanges(batch);
步骤 4：使用属性过滤器进行搜索
SearchOptions options = new SearchOptions();
options.addAttributeFilter("department", "Legal");
SearchResult result = index.search("agreement", options);
System.out.println("Found " + result.getCount() + " legal documents.");
如何在索引期间添加属性
在索引过程中添加属性可确保每个文档从一开始就具备必要的元数据。通过处理 FileIndexing 事件，您可以在引擎处理文件之前，以编程方式将键值对附加到每个 DocumentInfo 对象上，从而保证后续搜索时属性的一致可用性。
Direct answer: 在添加文件之前订阅 FileIndexing 事件；在事件处理程序中，对 DocumentInfo 对象调用 addAttribute 以附加键值对，然后让索引继续处理该文件。
步骤 1：订阅 FileIndexing 事件
FileIndexing 事件在每个文件被添加到索引时触发，允许您注入自定义元数据。
index.getEvents().FileIndexing.add(event -> {
// Example: set department based on folder name
String folder = new File(event.getFilePath()).getParentFile().getName();
event.getDocumentInfo().addAttribute("department", folder);
});
步骤 2：索引文档
index.add("C:/incoming/hr/policy.pdf");
index.add("C:/incoming/finance/budget.xlsx");
实际应用
- Document management systems – 在摄取时自动为文件打标签，实现即时的分面导航。
- Large content archives – 将属性过滤器与全文搜索相结合，将多千兆字节集合的查询时间从分钟缩短到秒级。
- Compliance & reporting – 动态分配保留期限、机密级别或审计标记，以便在合规检查时进行查询。
性能考虑因素
- Memory management – 监控 JVM 堆并调优
-Xmx（例如，对大于 2 GB 的索引使用-Xmx4g）。 - Batch processing – 使用
AttributeChangeBatch对属性更改进行分组，以最小化磁盘写入；将超过 10 000 条修改的批次拆分，以避免事务超时。 - Library updates – 保持使用最新的 GroupDocs.Search 版本；相较于 24.x，版本 25.4 在属性过滤评估上提升了 30 % 的速度。
常见问题及解决方案
| 问题 | 原因 | 解决方法 |
|---|---|---|
| 属性未应用 | 事件处理程序未在索引前注册 | 确保 index.getEvents().FileIndexing.add(...) 在任何 index.add(...) 调用之前 运行。 |
| 搜索未返回结果 | 属性名称不匹配（区分大小写） | 在创建过滤器时使用精确的属性名称（createAttribute("main")）。 |
| 大批量时的内存不足错误 | 单个批次中的更改过多 | 将大型更新拆分为更小的 AttributeChangeBatch 实例（例如，每批 5 000 篇文档）。 |
| 许可证未被识别 | 使用试用 JAR 且未应用许可证文件 | 在任何索引操作之前调用 License license = new License(); license.setLicense("path/to/license.file");。 |
常见问题
Q: 使用 GroupDocs.Search 在 Java 中的前置条件是什么？
A: Java 8+、GroupDocs.Search 库，以及对索引概念的基本了解。
Q: 如何通过 Maven 安装 GroupDocs.Search？
A: 将 Maven 设置部分中显示的仓库和依赖项添加到您的 pom.xml 中。
Q: 文档索引后我可以修改属性吗？
A: 可以，使用 AttributeChangeBatch 批量更新文档属性，无需重新索引。
Q: 如果我的索引过程很慢怎么办？
A: 优化 JVM 内存（-Xmx），使用批量更新，并升级到最新的库版本以获取性能补丁。
Q: 在哪里可以找到更多关于 GroupDocs.Search for Java 的资源？
A: 访问 official documentation 或浏览社区论坛。
资源
- 文档: GroupDocs.Search for Java Docs
- API 参考: API Reference
- 下载: Latest Releases
- GitHub: GitHub GroupDocs.Search
- 免费支持论坛: GroupDocs Forums
- 临时许可证: License Page
最后更新: 2026-09-21
测试环境: GroupDocs.Search 25.4 for Java
作者: GroupDocs
<repositories>
<repository>
<id>repository.groupdocs.com</id>
<name>GroupDocs Repository</name>
<url>https://releases.groupdocs.com/search/java/</url>
</repository>
</repositories>
<dependencies>
<dependency>
<groupId>com.groupdocs</groupId>
<artifactId>groupdocs-search</artifactId>
<version>25.4</version>
</dependency>
</dependencies>
import com.groupdocs.search.Index;
// Initialize an index in a specified directory
Index index = new Index("YOUR_OUTPUT_DIRECTORY/ChangeAttributes");
index.add("YOUR_DOCUMENT_DIRECTORY");
import com.groupdocs.search.results.DocumentInfo;
DocumentInfo[] documents = index.getIndexedDocuments();
import com.groupdocs.search.common.AttributeChangeBatch;
import com.groupdocs.search.SearchOptions;
AttributeChangeBatch batch = new AttributeChangeBatch();
batch.addToAll("public"); // Add 'public' to all documents
batch.remove(documents[0].getFilePath(), "public"); // Remove 'public' from a specific document
batch.add(documents[0].getFilePath(), "main", "key"); // Add 'main' and 'key' attributes
// Apply changes
index.changeAttributes(batch);
import com.groupdocs.search.results.SearchResult;
SearchOptions options = new SearchOptions();
options.setSearchDocumentFilter(SearchDocumentFilter.createAttribute("main"));
String query = "length";
SearchResult result = index.search(query, options); // Perform the search
import com.groupdocs.search.events.EventHandler;
import com.groupdocs.search.events.FileIndexingEventArgs;
index.getEvents().FileIndexing.add(new EventHandler<FileIndexingEventArgs>() {
@Override
public void invoke(Object sender, FileIndexingEventArgs args) {
if (args.getDocumentFullPath().endsWith("SampleDocument.pdf")) {
args.setAttributes(new String[] { "main", "key" });
}
}
});
index.add("YOUR_DOCUMENT_DIRECTORY");
