AppSearch

AppSearch 裝置端搜尋程式庫可管理本機儲存的結構化資料，並且提供 API 供資料索引與擷取 (透過全文搜尋) 作業使用。您可以使用這項功能為使用者建構自訂應用程式內搜尋功能。
最近更新時間 穩定版 候選版 Beta 版 Alpha 版
2025 年 7 月 2 日 1.1.0 - - -

宣告依附元件

如要新增 AppSearch 的依附元件，必須將 Google Maven 存放區新增至您的專案。詳情請參閱 Google 的 Maven 存放區。

在應用程式或模組的 build.gradle 檔案中，新增您需要的構件依附元件：

Groovy

dependencies {
    def appsearch_version = "1.1.0"

    implementation "androidx.appsearch:appsearch:$appsearch_version"
    // Use kapt instead of annotationProcessor if writing Kotlin classes
    annotationProcessor "androidx.appsearch:appsearch-compiler:$appsearch_version"

    implementation "androidx.appsearch:appsearch-local-storage:$appsearch_version"
    // PlatformStorage is compatible with Android 12+ devices, and offers additional features
    // to LocalStorage.
    implementation "androidx.appsearch:appsearch-platform-storage:$appsearch_version"

    // PlayServicesStorage is compatible with all devices that support Google Play Services on
    // all API levels. It offers the same features as PlatformStorage and is the recommended
    // solution for lower API levels on which PlatformStorage is not supported.
    implementation "androidx.appsearch:appsearch-play-services-storage:$appsearch_version"
}

Kotlin

dependencies {
    val appsearch_version = "1.1.0"

    implementation("androidx.appsearch:appsearch:$appsearch_version")
    // Use annotationProcessor instead of kapt if writing Java classes
    kapt("androidx.appsearch:appsearch-compiler:$appsearch_version")

    implementation("androidx.appsearch:appsearch-local-storage:$appsearch_version")
    // PlatformStorage is compatible with Android 12+ devices, and offers additional features
    // to LocalStorage.
    implementation("androidx.appsearch:appsearch-platform-storage:$appsearch_version")

    // PlayServicesStorage is compatible with all devices that support Google Play Services on
    // all API levels. It offers the same features as PlatformStorage and is the recommended
    // solution for lower API levels on which PlatformStorage is not supported.
    implementation("androidx.appsearch:appsearch-play-services-storage:$appsearch_version")

}

如要進一步瞭解依附元件，請參閱「新增建構依附元件」一文。

意見回饋

您的意見可協助我們改善 Jetpack。如果您發現新問題，或是有改進這個程式庫的建議，請告訴我們。回報新問題前，請先查看這個程式庫的現有問題。只要按一下星號按鈕，即可投票給現有的問題。

建立新問題

詳情請參閱 Issue Tracker 文件。

1.1 版本

1.1.0 版本

2025 年 7 月 2 日

發布 androidx.appsearch:appsearch-*:1.1.0。1.1.0 版包含這些修訂項目。

1.1.0-rc01 版本

2025 年 5 月 20 日

發布 androidx.appsearch:appsearch-*:1.1.0-rc01。1.1.0-rc01 版包含這些修訂項目。

新功能

  • AppSearch 模組進入 RC。
  • 新增實驗性 API，可累積 PutDocumentsRequest#addTakenAction 方法的動作 (I7b726)
  • 新增 SearchResult#TextMatchInfo、SearchResult#EmbeddingMatchInfo；重新建構 SearchResult#MatchInfo，提供嵌入式內容比對資訊 (I8f78d)
  • 導入清單操作的排名函式 (Ifa4ab)

API 變更

  • 支援 blob 控制代碼屬性的 AppSearch 註解處理工具。(I9520b)
  • 更新 AppSearch 註解處理工具，支援量化。(Ie0c85)
  • 在 PlatformStorage 和 LocalStorage 中新增靜態 getFeatures() 方法 (I5a206)

修正錯誤

  • 這個程式庫現在使用 JSpecify 空值註解，這些註解屬於型別用途。Kotlin 開發人員應使用下列編譯器引數，強制執行正確用法：-Xjspecify-annotations=strict、-Xtype-enhancement-improvements-strict-mode (I91f42、b/326456246)

1.1.0-beta01 版本

2025 年 1 月 15 日

發布 androidx.appsearch:appsearch-*:1.1.0-beta01。1.1.0-beta01 版包含這些修訂項目。

新功能

  • AppSearch 模組進入 Beta 版。

API 變更

  • 由於穩定性問題，停用實驗性 AppSearch 刪除傳播 API。(Iea386)
  • 建立 GlobalSearchApplicationInfo API，這是實驗性質的選用方式，可供製作方和消費者表明對特定型別的興趣。(I116fd)
  • 實驗性 AST (查詢建構工具) API 的微小變更 (Ibd852)

修正錯誤

  • 這個程式庫現在使用 JSpecify 空值註解，這些註解屬於型別用途。Kotlin 開發人員應使用下列編譯器引數，強制執行正確用法：-Xjspecify-annotations=strict (這是 Kotlin 編譯器 2.1.0 版的預設值)。(Ic2976、b/326456246)
  • 將必要權限新增至 searchPersonCorpus (I4431d)

1.1.0-alpha07 版本

2024 年 12 月 11 日

發布 androidx.appsearch:appsearch-*:1.1.0-alpha07。1.1.0-alpha07 版包含這些修訂項目。

新功能

  • 在尚未穩定的新 API 介面中新增 ExperimentalAppSearchApi 註解。(Ib09f4)
  • 支援透過 AppSearchSession#openBlobForWriteAsync 和相關方法，有效率地儲存及共用二進位大型物件資料
  • 支援透過 matchScoreExpression 函式，依評分運算式篩選查詢結果 (Id525a)
  • 支援從父項文件將刪除作業傳播至子項文件。(Ia032d)
  • 支援嵌入量化 API，可提升嵌入效能，但品質會略有損失。(Id8a07)
  • 支援使用 SearchSpec 中的 addFilterDocumentIds API，將搜尋範圍限制在特定文件。(I7c6f1)

API 變更

  • 將父項類型資訊從 GenericDocument 移至 SearchResult。(I34a1d)
  • TakenAction API 支援新的動作類型，包括 DismissAction 和 ImpressionAction。(I0c6c7)
  • 新增 AppSearch 內建結構定義 WebPage。(I28127)

1.1.0-alpha06 版本

2024 年 10 月 16 日

發布 androidx.appsearch:appsearch-*:1.1.0-alpha06。1.1.0-alpha06 版包含這些修訂項目。

API 變更

  • 新增代表 PropertyDefined 查詢函式的節點。(I1aeaf)
  • 新增節點，代表數值搜尋和屬性限制。(I963a9)
  • 新增代表 GetSearchStringParameter 查詢函式的節點。(I4f99b)
  • 新增代表 HasProperty 查詢函式的節點。(I9c1c5)
  • 新增了介面，用於在 AST 中實作函式。(I9d42e)
  • 新增 AND 和 OR 運算子。(Iaa442)
  • 新增 NegationNode，在 AST 中表示查詢的邏輯否定。(Ia855a)
  • 在 AppSearch 中新增 Node 介面，用於定義節點。(If42fb)
  • 為 AppSearch 新增實驗性 API 註解。(I3e57c)

修正錯誤

  • 新增 TextNodes 以保留字詞。(Iefd02)

安全性修正

  • 自這項變更起，androidx 會針對 protobuf 4.28.2 進行編譯，以解決 CVE-2024-7254。請將 androidx.appsearch:appsearch-external-protobuf 的依附元件升級至最新的 1.1.0-alpha06，以解決安全漏洞風險。

1.1.0-alpha05 版本

2024 年 9 月 4 日

發布 androidx.appsearch:appsearch-*:1.1.0-alpha05。1.1.0-alpha05 版包含這些修訂項目。

API 變更

  • 淘汰不必要的 setEmbeddingSearchEnabled 和 getEmbeddingSearchEnabled。刪除 setListFilterTokenizeFunctionEnabled 和 getListFilterTokenizeFunctionEnabled。已刪除「tokenize」查詢函式。已替換為 getSearchStringParameter 查詢函式和 addSearchStringParameter 函式。(I09f5a)
  • 將 Alarm#getComputingDevice 重新命名為 getOriginatingDevice。(I63121)

1.1.0-alpha04 版本

2024 年 8 月 7 日

發布 androidx.appsearch:appsearch-*:1.1.0-alpha04。1.1.0-alpha04 版包含這些修訂項目。

新功能

  • 支援新的 PlayServicesStorage 實作方式，讓您在舊型裝置上使用 AppSearch，而不必付出 LocalStorage 造成 APK 大小大幅增加的代價。這項儲存空間實作方式是在 Play 服務應用程式中儲存應用程式資料。
  • 支援搭載 Android 15 的裝置使用新版 API。
  • 支援透過嵌入向量搜尋資料庫，允許模糊比對。(I2b41b)
  • 在 AppSearch 結構定義模型中支援父項型別和多型。(I06118)
  • 支援 TakenAction API，讓應用程式回報結果遭點選或放棄的時間，以便在後續搜尋中提升品質。(I54091)
  • 在註解處理工具中導入新的 @Document.BuilderProducer 註解，支援具有建構函式的類別。(Iec30a)
  • 支援更精細的控制，可決定要為巢狀文件的哪些屬性建立索引。(Iec30a)
  • 支援依特定文件屬性篩選搜尋結果。(Ib2659)
  • 支援更精細的瀏覽權限設定，允許瀏覽權限設定的 OR 和 AND。(I0274b)
  • 支援將資料的顯示權授予所有可查看擁有者應用程式存在狀態的應用程式 (公開顯示設定)。(I992e4)
  • 支援僅擷取在特定屬性中填入資料的結果。(I7d94f)
  • 支援在個人設定檔中擷取企業聯絡人。(Idd587)

API 變更

  • 在 AppSearch 的 Document.DocumentProperty 註解中新增 indexableNestedPropertiesList 和 inheritIndexableNestedPropertiesFromSuperclass 註解參數，即可為特定巢狀屬性路徑建立索引。(Iec30a)
  • 支援建構函式，可在 AppSearch 註解處理工具中建立建構工具例項 (I265c9)
  • 更新 AppSearch 註解處理工具，支援為多型設定父項型別 (I06118)
  • 新增 GetSchemaRequest 方法，用於清除瀏覽權限設定 (I38379)
  • 在 AppSearch 中支援多型 (Ida14a)addParentType
  • 新增其他排名運算式的 API (I5d9f4)
  • 新增 SearchAction API (I54091)
  • 為「AppSearch」類型新增說明欄位 (I84762)
  • 將嵌入式搜尋查詢和排名 API 導入 AppSearch (I0f6c3)
  • 移除 getDeletionPropagation (I21192)

1.1.0-alpha03 版本

2023 年 5 月 24 日

發布 androidx.appsearch:appsearch-*:1.1.0-alpha03。1.1.0-alpha03 版包含此連結所列的修訂項目。

新功能

  • 支援進階查詢 API、進階評分 API 和數字搜尋。(I02d48)
  • 新增 LocalStorage.createGlobalSearchSession API，可在單一應用程式的本機儲存空間中搜尋所有資料庫。(Id3c89)
  • 新增可依 ID 聯結文件的 API (Iaecfa)
  • 支援屬性權重，可在使用 RANKING_STRATEGY_RELEVANCE_SCORING 時標示特定屬性較為重要。(I069b9)
  • 在 AppSearch 中新增 Person 和 ContactPoint，用於查詢 Person 語料庫。(Ia58f9)
  • 新增以 http://schema.org/ImageObject 為範本的 ImageObject 文件類型。(I6a0c0)
  • 新增 VERBATIM 權杖化工具，允許新增屬性，而不必由 AppSearch 解譯。(I47bc0)
  • 新增 RFC822_TOKENIZATION 做為權杖化工具類型，可權杖化電子郵件地址。(I8a390)
  • 在偵錯檢視畫面中啟用全域搜尋。(I51fb2)

API 變更

  • 已移除傳回 ListenableFuture 且沒有 Async 後置字串的方法。(I0515f)
  • 新增透過 Document 類別設定投影的功能。(I94576)
  • 將欄位從 Thing 新增至 Alarm、AlarmInstance、Timer、Stopwatch、StopwatchLap、ContactPoint 和 Person (Id876c)

修正錯誤

  • 在 appsearch-platform-storage (Ia8e61) 中全面支援 Android 13 功能
  • 修正使用繼承時，覆寫結構定義名稱和私有欄位的問題。

1.1.0-alpha02 版本

2022 年 8 月 24 日

發布了 androidx.appsearch:appsearch-*:1.1.0-alpha02。查看 1.1.0-alpha02 版的修訂項。

新功能

  • 使用索引壓縮 (而非從頭開始重建索引) 加快最佳化程序
  • 將原生記錄標記從「icing」變更為「AppSearchIcing」，根據預設記錄 INFO 訊息

API 變更

  • 新增用於處理路徑的 PropertyPath 物件，以及可接受 PropertyPath 的新 addProjection 方法 (I45588)。
  • 已將 builtin:Thing 新增至 AppSearch 內建類型 (I55427)
  • 盡早避免 GenericDocument 中出現空白屬性名稱 (先前是在建立索引時，現在是在 GenericDocument.Builder.build() 時避免) (I9e780)

修正錯誤

  • 已移除不必要的字串格式，以改善 RELEVANCE 評分效能
  • 遇到無法讀取或已刪除的文件時，提高分頁效率
  • 為放棄的查詢實作了垃圾收集
  • 修正文件的巢狀索引支援。先前，系統會忽略 indexNestedProperties (Iae9a6)。

外部貢獻

  • Shea Smith：修正文件的巢狀索引支援 (Iae9a6)。

1.1.0-alpha01 版本

2022 年 6 月 15 日

發布 androidx.appsearch:appsearch-*:1.1.0-alpha01。1.1.0-alpha01 版本以私人的預先發布分支版本開發，並無公開修訂版本。

API 變更

  • 所有傳回 ListenableFuture 的方法都已重新命名，已加上 Async 後置字串。舉例來說，getSchema 已重新命名為 getSchemaAsync。舊版已淘汰，並將在日後推出的版本中移除。

新功能

  • 首次推出的 appsearch-buildin 類型。此專案包含一些以 schema.org 為基礎的內建類型，可讓用戶端更容易使用，而不是自行定義一般物件的類型。我們會在日後推出的版本中加入更多類型。
  • 可使用 ShortcutAdapter 轉換 AppSearch 文件至 ShortcutInfoCompat。因此，用戶端可使用 core-google-shortcuts 程式庫將 AppSearch 文件分享到 Google
  • 可沿用 @Document 類別的機制。欄位無法替換或修改，但可以使用 @Document 備註擴充新的類別以加入新的欄位。
  • 新推出的 Observer API 可讓用戶端在他們可存取的類型變更，或新增、修改或移除這些類型的文件時，接收通知。重要事項：目前的實作只會在應用程式執行時傳送通知。目前您無法檢查應用程式停止期間發生的變更。因此，建議您不要依賴此 API 取得完整性資訊。
  • Property parser API 可讓您完整處理及檢查 MatchInfo#getPropertyPath 傳回的屬性路徑。
  • 全域 getById 和全域 getSchema API，可從您已獲得瀏覽權限的其他應用程式擷取文件和結構定義。
  • 針對您具有存取權的資料，可擷取 getSchema 瀏覽權限資訊
  • 可授予含有特定 Android 權限的應用程式瀏覽權限 (限制為限定的許可清單權限)
  • 除了先前支援的樣式 hasFoo() 之外，註解處理工具中的布林值欄位也支援 isFoo() 樣式的 getter
  • 支援在 @RequiresFeature 保護的新功能。請使用 AppSearchSession#getFeatures 判定目前的後端支援的項目。
  • 移除個別文件的權杖上限 (約 13,000 個)
  • 允許比對非 ASCII 和非英數字元，例如：表情符號

修正錯誤

  • 修正覆寫與建立巢狀結構不相容的類型時，會導致 SetSchema 失敗的錯誤。
  • 進行修正以完整支援 @AutoValue 註解類別 (做為 AppSearch @Document 類別使用)
  • 修正有關文件類別重複清單和其他問題的一些當機情形
  • 修正在特定情況下會導致前置字串搜尋中斷的錯誤
  • 修正 GetStorageInfo 中會在發生 IO 錯誤時傳回不正確的值的細微錯誤
  • 修正讀取文件時發生的 BUSADDERR 問題
  • 修正顯示未格式化指紋造成的 Logcat 損毀問題
  • 修正因 IO 失敗而造成的 NPE
  • 修正 GetSchemaType、Get、Delete、DeleteByNamespace 和 DeleteBySchemaType 中的記憶體流失問題

1.0.0 版本

1.0.0-alpha04 版本

2021 年 11 月 3 日

發布 androidx.appsearch:appsearch-*:1.0.0-alpha04。1.0.0-alpha04 版本包含以下修訂項目。

新功能

  • Guava ListenableFuture 依附元件自動成為 API 依附元件

API 變更

  • 新增 SearchResult#getSubmatchRange() 和 SearchResult#getSubmatch() 以提供更多與每個相符項目相關的資訊。(I2fef6)
  • 詳細說明如何產生 PackageIdentifier 指紋，以依 packagename+certificate 共用資料

修正錯誤

  • 修正使用者在結果組合結束後嘗試擷取結果網頁時發生的當機問題
  • 修正如果只提供無效命名空間做為查詢篩選條件，就會查詢所有命名空間的問題
  • 修正如果只提供無效命名空間做為「依據查詢進行移除」的篩選條件，就會移除所有命名空間的問題
  • 修正文件過大時，在某個階段後文件資料停止編入索引的問題
  • 修正權杖化會捨棄含有非 ASCII 數字字元的區隔問題
  • 針對連續失敗的初始化嘗試來新增檢查功能，以協助排除無法成功初始化的潛在錯誤狀態。

1.0.0-alpha03 版本

2021 年 7 月 21 日

發布 androidx.appsearch:appsearch-*:1.0.0-alpha03。1.0.0-alpha03 版包含以下修訂項目。

新功能

  • 發布平台儲存空間後端，允許用戶端在 Android S 新推出的 android.app.appsearch.AppSearchManager 服務中使用 AppSearch API。詳情請參閱 AppSearch 開發人員指南。
  • AutoValue 的註解處理工具支援
  • 移除單一字串屬性的大小上限
  • 新的儲存空間格式，可縮短初始化延遲時間
  • 從舊到新儲存空間格式的一次性內部資料遷移作業

修正錯誤

  • 插入新文件時可正確地強制執行文件上限
  • 修正建立 AppSearchSession 時的當機問題
  • 修正 SetSchema 中未偵測到某些回溯不相容性情況及索引不相容問題的錯誤

1.0.0-alpha02 版本

2021 年 6 月 30 日

發布 androidx.appsearch:appsearch:1.0.0-alpha02、androidx.appsearch:appsearch-compiler:1.0.0-alpha02 和 androidx.appsearch:appsearch-local-storage:1.0.0-alpha02。1.0.0-alpha02 版本包含以下修訂項目。

新功能

  • 完整支援中文/日文/韓文/泰文
  • 縮減 androidx.appsearch:appsearch-local-storage 大小
  • 移除重複屬性的大小上限
  • 允許重複使用建構工具類別
  • 改善特定物件的 toString()，以簡化偵錯作業
  • Javadoc 文件改善項目

API 變更

  • SearchResult#getMatches 已重新命名為 SearchResult#getMatchInfos
  • @Document.Int64Property 已重新命名為 @Document.LongProperty

修正錯誤

  • 針對結果程式碼片段的計算進行改善與修正
  • 修正 AppSearchSession 初始化作業中的錯誤

1.0.0-alpha01 版本

2021 年 5 月 5 日

發布 androidx.appsearch:appsearch:1.0.0-alpha01、androidx.appsearch:appsearch-compiler:1.0.0-alpha01 和 androidx.appsearch:appsearch-local-storage:1.0.0-alpha01。1.0.0-alpha01 版本包含這些修訂版本。

新功能

AppSearch 搜尋程式庫可管理本機儲存的結構化資料，並且提供 API 供資料索引與擷取 (透過全文搜尋) 作業使用。您可以使用這項功能為使用者建構自訂應用程式內搜尋功能。初始版本為 1.0.0-alpha01。