AppSearch

AppSearch 是一款用于管理本地存储结构化数据的设备端搜索库，提供用于索引数据和通过全文搜索检索数据的 API。可使用它为您的用户构建自定义应用内搜索功能。
最新更新 稳定版本 版本候选版 (RC) Beta 版本 Alpha 版本
2026 年 3 月 25 日 1.1.0 - - 1.2.0-alpha01

声明依赖项

要添加对 AppSearch 的依赖，必须将 Google Maven 代码库添加到项目中。阅读 Google 的 Maven 代码库以了解更多信息。

在应用或模块的 build.gradle 文件中，为您需要的工件添加依赖项

Groovy

dependencies {
    def appsearch_version = "1.2.0-alpha01"

    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.2.0-alpha01"

    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 变得更好。如果您发现新问题或有改进此库的想法，请告诉我们。在创建新问题之前，请先查看此库中的现有问题。您可以点击星标按钮为现有问题投票。

创建新问题

如需了解详情，请参阅 问题跟踪器文档。

版本 1.2

版本 1.2.0-alpha01

2026 年 3 月 25 日

androidx.appsearch:appsearch-*:1.2.0-alpha01 已发布。版本 1.2.0-alpha01 包含这些提交。

API 变更

Bug 修复

  • 将库迁移至使用 Java 11 作为目标。这意味着生成的字节码将是 Java 11（类文件版本 55），并且可能需要脱糖才能使用该库。(If4c2a, b/457821470)
  • SearchFeatures 和 RankingFeatures。(I54b7d, b/387291182)
  • 使用新的删除传播标志 (If21ae, b/384947619)
  • 添加了更详细的内部日志记录 (I10604, b/448872333)
  • 将 allowoptimization 重新添加回 AppSarchDocumentClassMap 的 proguard keep 规则中 (I0bd88, b/440484133)
  • 修复了优化构建中的一个错误：由于横向类合并，对 AppSearch 文档类的引用可能会被无关类替换 (I93f20, b/440484133)
  • 添加了 ISOLATED_STORAGE (隔离存储) 特性 (Ifb963)

版本 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 以提供向量嵌入 (embeddings) 匹配的匹配信息 (I8f78d)
  • 引入用于列表操作的排名函数 (Ifa4ab)

API 变更

  • 支持 blob 句柄属性的 AppSearch 注解处理器。(I9520b)
  • 更新 AppSearch 注解处理器以支持量化。(Ie0c85)
  • 为 PlatformStorage 和 LocalStorage 添加了静态 getFeatures() 方法 (I5a206)

Bug 修复

  • 此库现在使用 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)

Bug 修复

  • 此库现在使用 JSpecify 可空性注解，这些注解是类型用法。Kotlin 开发人员应使用以下编译器参数来强制正确使用：-Xjspecify-annotations=strict（从 2.1.0 版 Kotlin 编译器开始，这是默认设置）。(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 及其相关方法高效存储和共享二进制 blob 数据
  • 支持通过 matchScoreExpression 函数按评分表达式过滤查询结果 (Id525a)
  • 支持将删除从父文档传播到子文档。(Ia032d)
  • 支持向量嵌入量化 API，以在轻微损失质量的情况下提高嵌入性能。(Id8a07)
  • 支持使用 SearchSpec 中的 addFilterDocumentIds API 将搜索限制在某些文档。(I7c6f1)

API 变更

  • 将父类型信息从 GenericDocument 移至 SearchResult。(I34a1d)
  • 支持 TakenAction API 中的新动作类型，包括 DismissAction 和 ImpressionAction。(I0c6c7)
  • 添加了新的 AppSearch 内置 schema 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)

Bug 修复

  • 添加了用于保存术语的 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 Services 应用中。
  • 支持运行 Android 15 的设备上的新 API。
  • 支持通过向量嵌入检索数据库，从而允许模糊匹配。(I2b41b)
  • 在 AppSearch schema 模型中支持父类型和多态。(I06118)
  • 支持 TakenAction API，允许应用报告结果何时被点击或放弃，以便在后续搜索中提高质量。(I54091)
  • 通过引入新的 @Document.BuilderProducer 注解，在注解处理器中支持带有 builder 的类。(Iec30a)
  • 支持更精细地控制嵌套文档的哪些属性被索引。(Iec30a)
  • 支持按某些文档属性过滤搜索。(Ib2659)
  • 通过允许可见性设置的 OR 和 AND，支持更精细的可见性设置。(I0274b)
  • 支持向所有能看到所属应用存在的应用授予数据可见性（公开可见性）。(I992e4)
  • 支持仅检索在特定属性中填充了数据的结果。(I7d94f)
  • 支持在个人资料中检索企业联系人。(Idd587)

API 变更

  • 向 AppSearch 的 Document.DocumentProperty 注解添加了 indexableNestedPropertiesList 和 inheritIndexableNestedPropertiesFromSuperclass 注解参数，以允许索引特定的嵌套属性路径。(Iec30a)
  • 在 AppSearch 注解处理器中支持 builder 构造函数来创建 builder 实例 (I265c9)
  • 更新 AppSearch 注解处理器以支持为多态设置父类型 (I06118)
  • 添加了用于清除可见性设置的 GetSchemaRequest 方法 (I38379)
  • 在 AppSearch 中支持 addParentType 以实现多态 (Ida14a)
  • 添加了用于额外排名表达式的 API (I5d9f4)
  • 添加了 SearchAction API (I54091)
  • 为 AppSearch 类型添加了描述 (description) 字段 (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 连接 (join) 文档的 API (Iaecfa)
  • 在使用 RANKING_STRATEGY_RELEVANCE_SCORING 时，支持通过属性权重来标记某些属性更重要。(I069b9)
  • 在 AppSearch 中添加 Person (人物) 和 ContactPoint (联系方式)，用于查询人物库。(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)

Bug 修复

  • 在 appsearch-platform-storage 中全面支持 Android 13 特性 (Ia8e61)
  • 修复了使用继承时覆盖 schema 名称和私有字段的问题。

版本 1.1.0-alpha02

2022 年 8 月 24 日

androidx.appsearch:appsearch-*:1.1.0-alpha02 已发布。版本 1.1.0-alpha02 包含这些提交。

新功能

  • 使用索引压缩而非从头重建索引，从而加快了 Optimize (优化) 过程
  • 将原生日志标记从 "icing" 更改为 "AppSearchIcing"，默认记录 INFO 消息

API 变更

  • 添加了用于处理路径的新 PropertyPath 对象，以及接收 PropertyPath 的新 addProjection 方法。(I45588)
  • 向 AppSearch 内置类型添加了 builtin:Thing (I55427)
  • 更早地阻止 GenericDocument 中空的属性名称——以前在索引时阻止，现在在 GenericDocument.Builder.build() 时阻止 (I9e780)

Bug 修复

  • 删除了不必要的字符串格式化，以提高 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-builtin-types 的首次发布。此项目包含一些基于 schema.org 的内置类型，客户可能会发现使用这些类型比为常见对象定义自己的类型更方便。未来的版本将添加更多类型。
  • 能够使用 ShortcutAdapter 将 AppSearch 文档转换为 ShortcutInfoCompat。这为客户提供了一种使用 core-google-shortcuts 库将 AppSearch 文档分享到 Google 的方法
  • 能够对 @Document 类使用继承。字段不能被替换或修改，但可以通过扩展带 @Document 注解的类来添加新字段。
  • 新的 Observer (观察者) API，允许客户在他们有权访问的类型发生变化，或者添加、修改、移除这些类型的文档时注册通知。重要提示：当前的实现仅在应用运行时发送通知。目前无法检查应用停止期间发生的更改。因此，您不应依赖此 API 确保完整性。
  • Property parser (属性解析器) API，允许您完全处理和检查 MatchInfo#getPropertyPath 返回的属性路径。
  • 全局 getById 和全局 getSchema API，用于从已授予您可见性的其他应用中检索文档和 schema。
  • 能够在 getSchema 中为您有权访问的数据检索可见性信息
  • 能够向持有某种 Android 权限的应用授予可见性（仅限于一小组白名单权限）
  • 在注解处理器中为布尔字段支持 isFoo() 样式的 getter，此外还支持之前的 hasFoo() 样式
  • 支持受 @RequiresFeature 保护的新特性。使用 AppSearchSession#getFeatures 来确定当前后端支持哪些特性。
  • 取消单个文档约 13k 的 token 限制
  • 允许匹配非 ASCII 且非字母数字的字符，例如 emoji 表情符号

Bug 修复

  • 修复了在覆盖嵌套的不兼容类型时，SetSchema 会失败的错误。
  • 修复了全面支持将 @AutoValue 注解的类用作 AppSearch @Document 类的错误
  • 修复了一些与重复的 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 指纹以通过包名+证书分享数据的文档

Bug 修复

  • 修复了如果用户尝试在结果集结束后获取结果页会崩溃的问题
  • 修复了如果仅提供无效命名空间作为查询过滤器，则所有命名空间都会被查询的问题
  • 修复了如果仅提供无效命名空间作为“按查询移除”过滤器，则所有命名空间都会被移除的问题
  • 修复了对于超大文档，文档数据在某一点后停止被索引的问题
  • 修复了分词会丢失包含非 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
  • 取消单个字符串属性的最大大小限制
  • 新的存储格式以减少初始化延迟
  • 一次性的内部数据迁移，从旧存储格式迁移到新存储格式

Bug 修复

  • 插入新文档时正确强制执行最大文档限制
  • 修复了创建 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 的大小
  • 取消重复属性的最大大小限制
  • 允许重复使用 builder 类
  • 改进了某些对象的 toString()，以便更轻松地进行调试
  • 改进了 Javadoc 文档

API 变更

  • SearchResult#getMatches 更名为 SearchResult#getMatchInfos
  • @Document.Int64Property 更名为 @Document.LongProperty

Bug 修复

  • 改进并修复了结果摘要的计算
  • 修复了 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。