使用 GroupDocs.Search 的 Java 屬性搜尋指南

在現代以文件為中心的應用程式中，您常常需要不僅依靠文字內容來定位檔案，還需要依據部門、機密等級或建立日期等自訂中繼資料。Search by attribute java 為您提供單一高效能查詢的能力。在本教學中，您將看到如何對已索引的檔案批次更新屬性、在索引時注入屬性，以及使用 GroupDocs.Search for Java 函式庫以中繼資料高效查詢文件。

快速解答

  • 什麼是「search by attribute java」？ 它允許您使用附加於每個已索引文件的鍵值中繼資料來篩選搜尋結果。
  • 索引後可以修改屬性嗎？ 可以 – 使用 AttributeChangeBatch 於不重新建構整個索引的情況下套用大量變更。
  • 如何在索引時加入屬性？ 為 FileIndexing 事件註冊處理程式，並以程式方式為每個檔案設定屬性。
  • 需要授權嗎？ 免費試用可供評估；正式上線需購買永久授權。
  • 需要哪個 Java 版本？ 建議使用 Java 8 或更新版本。

什麼是「search by attribute java」？

Search by attribute java 讓您能夠根據自訂中繼資料（屬性）而非僅文字內容來查詢文件。此方式可大幅縮小結果集、減少網路流量，並加快回應時間，因為引擎會在執行全文掃描前先評估屬性過濾條件。

為什麼使用動態中繼資料標記？

動態中繼資料標記讓您在不重新索引的情況下指派、更新與管理文件的自訂屬性，提供彈性的分類方式以因應變化的業務規則、提升搜尋效率，並減少在大型資料庫中執行昂貴資料遷移的需求，同時維持合規與稽核能力。

  • 動態分類 – 讓中繼資料與不斷演變的業務規則保持同步。
  • 更快的篩選 – 屬性過濾在全文搜尋之前評估，提升回應速度。
  • 合規追蹤 – 為文件標記保存期限或稽核需求。
  • 批次更新屬性 – 在一次操作中變更多個文件，無需重新索引全部內容。

前置條件

  • Java 8+（JDK 8 或更新版本）
  • GroupDocs.Search for Java 函式庫（請參考下方 Maven 設定）
  • 基本的 Java 集合與例外處理概念

設定 GroupDocs.Search for Java

Maven 設定

將 GroupDocs 儲存庫與相依性加入您的 pom.xml：

<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 官方網站 取得 JAR 檔。

取得授權

  • 先使用免費試用版探索功能。
  • 若需長期使用，請透過 授權頁面 取得臨時或正式授權。

基本初始化

// 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 進行批次更新。此方法會在單一交易中更新所選文件的中繼資料，避免重新索引整個集合，同時保留全文索引。

直接答案： 使用 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 物件上，確保後續搜尋時屬性始終可用。

直接答案： 在加入檔案前訂閱 FileIndexing 事件；於事件處理程式中呼叫 addAttribute 於 DocumentInfo 物件上以附加鍵值對，然後讓索引繼續處理該檔案。

步驟 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");

實務應用

  1. 文件管理系統 – 在檔案匯入時自動標記，實現即時分面導覽。
  2. 大型內容檔案庫 – 結合屬性過濾與全文搜尋，將多 GB 集合的查詢時間從分鐘縮短至秒級。
  3. 合規與報表 – 動態指派保存期限、機密等級或稽核旗標，供法規檢查時查詢。

效能考量

  • 記憶體管理 – 監控 JVM 堆積並調整 -Xmx（例如 -Xmx4g 以處理大於 2 GB 的索引）。
  • 批次處理 – 使用 AttributeChangeBatch 合併屬性變更以減少磁碟寫入；將超過 10 000 筆的批次拆分，以避免交易逾時。
  • 函式庫更新 – 保持使用最新的 GroupDocs.Search 版本；版本 25.4 相較 24.x 在屬性過濾評估上提升約 30 % 的速度。

常見問題與解決方案

問題發生原因解決方法
屬性未套用索引前未註冊事件處理程式確保 index.getEvents().FileIndexing.add(...) 在 任何 index.add(...) 呼叫之前執行。
搜尋未返回結果屬性名稱不匹配（區分大小寫）建立過濾條件時使用完全相同的屬性名稱（例如 createAttribute("main")）。
大批次時記憶體不足錯誤單次批次變更過多將大型更新拆分為較小的 AttributeChangeBatch（例如每批 5 000 份文件）。
授權未被識別使用試用 JAR 卻未套用授權檔在任何索引操作之前呼叫 License license = new License(); license.setLicense("path/to/license.file");。

常見問答

問：在 Java 中使用 GroupDocs.Search 的前置條件是什麼？
答： Java 8+、GroupDocs.Search 函式庫，以及基本的索引概念知識。

問：如何透過 Maven 安裝 GroupDocs.Search？
答： 將 Maven 設定段落中示範的儲存庫與相依性加入 pom.xml 即可。

問：索引後可以修改屬性嗎？
答： 可以，使用 AttributeChangeBatch 批次更新文件屬性，無需重新索引。

問：如果我的索引過程很慢，該怎麼辦？
答： 調整 JVM 記憶體 (-Xmx)、使用批次更新，並升級至最新函式庫以取得效能修補。

問：在哪裡可以找到更多 GroupDocs.Search for Java 的資源？
答： 前往 官方文件 或參與社群論壇。

資源

最後更新： 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");

相關教學