AppSearch

AppSearch 是一个设备端搜索库，用于管理本地存储的结构化数据，提供用于索引数据和使用全文搜索检索数据的 API。使用它可以为您的用户构建自定义的应用内搜索功能。
最新更新 稳定版 发布候选版 Beta 版 Alpha 版
2025 年 5 月 20 日 - 1.1.0-rc01 - -

声明依赖项

要添加对 AppSearch 的依赖，您必须将 Google Maven 仓库添加到您的项目中。如需了解详情，请参阅 Google 的 Maven 仓库。

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

Groovy

dependencies {
    def appsearch_version = "1.1.0-rc01"

    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-rc01"

    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.1

版本 1.1.0-rc01

2025 年 5 月 20 日

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

新功能

  • AppSearch 模块进入 RC 阶段。
  • 为 PutDocumentsRequest#addTakenAction 方法添加了一个新的实验性 API，用于累积操作 (I7b726)
  • 添加 SearchResult#TextMatchInfo、SearchResult#EmbeddingMatchInfo；重构 SearchResult#MatchInfo 以提供嵌入匹配的匹配信息 (I8f78d)
  • 引入用于列表操作的排名函数 (Ifa4ab)

API 变更

  • 支持 AppSearch 注解处理器处理 Blob 句柄属性。 (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（从 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 包含这些提交。

新功能

  • 将 ExperimentalAppSearchApi 注解添加到尚未稳定的新 API 接口。 (Ib09f4)
  • 通过 AppSearchSession#openBlobForWriteAsync 和相关方法，支持高效存储和共享二进制 Blob 数据。
  • 通过 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)

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 服务应用中来工作。
  • 支持在运行 Android 15 的设备上使用新 API。
  • 支持通过嵌入向量搜索数据库，实现模糊匹配。 (I2b41b)
  • 支持 AppSearch 架构模型中的父类型和多态性。 (I06118)
  • 支持 TakenAction API，该 API 允许应用报告结果何时被点击或放弃，以便在后续搜索中提升质量。 (I54091)
  • 通过引入新的 @Document.BuilderProducer 注解，支持注解处理器中的带构建器类。 (Iec30a)
  • 支持更细粒度地控制嵌套文档的哪些属性被索引。 (Iec30a)
  • 支持将搜索过滤到某些文档属性。 (Ib2659)
  • 通过允许可见性设置的 OR 和 AND 操作，支持更细粒度的可见性设置。 (I0274b)
  • 支持向所有能看到拥有应用（公共可见性）存在的应用授予数据可见性。 (I992e4)
  • 支持仅检索在某个属性中填充了数据的结果。 (I7d94f)
  • 支持在个人资料中检索企业联系人。 (Idd587)

API 变更

  • 将 indexableNestedPropertiesList 和 inheritIndexableNestedPropertiesFromSuperclass 注解参数添加到 AppSearch 的 Document.DocumentProperty 注解中，以允许索引特定的嵌套属性路径。 (Iec30a)
  • 支持构建器构造函数在 AppSearch 注解处理器中创建构建器实例。 (I265c9)
  • 更新 AppSearch 注解处理器以支持为多态性设置父类型。 (I06118)
  • 添加了 GetSchemaRequest 方法用于清除可见性设置。 (I38379)
  • 在 AppSearch 中支持 addParentType 以实现多态性。 (Ida14a)
  • 添加了用于额外排名表达式的 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)
  • 添加了新的文档类型 ImageObject，模仿自 http://schema.org/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)
  • 修复了使用继承时覆盖架构名称和私有字段的问题。

版本 1.1.0-alpha02

2022 年 8 月 24 日

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

新功能

  • 使用索引压缩而非从头开始重建索引来加快优化过程
  • 将原生日志标签从“icing”更改为“AppSearchIcing”，默认记录 INFO 消息

API 变更

  • 添加了新的 PropertyPath 对象用于处理路径，以及新的 addProjection 方法以接受 PropertyPath。 (I45588)
  • 将 builtin:Thing 添加到 AppSearch 内置类型。 (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 来确保完整性。
  • 属性解析器 API，允许您完全处理和检查 MatchInfo#getPropertyPath 返回的属性路径。
  • 全局 getById 和全局 getSchema API，用于从已授予您可见性的其他应用中检索文档和架构。
  • 能够在 getSchema 中检索您有权访问的数据的可见性信息。
  • 能够向持有特定 Android 权限的应用授予可见性（仅限于一小部分允许列表权限）。
  • 除了以前支持的 hasFoo() 样式外，还支持注解处理器中布尔字段的 isFoo() 样式 getter。
  • 支持 @RequiresFeature 后保护的新功能。使用 AppSearchSession#getFeatures 来确定当前后端支持哪些功能。
  • 移除单个文档约 13k 令牌的限制。
  • 允许匹配非 ASCII+非字母数字字符，例如表情符号。

Bug 修复

  • 修复了在覆盖嵌套不兼容类型时导致 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 指纹的文档。

Bug 修复

  • 修复了用户在结果集末尾尝试获取结果页时崩溃的问题。
  • 修复了在只提供了无效命名空间作为查询过滤器时，所有命名空间都被查询的问题。
  • 修复了在只提供了无效命名空间作为按查询移除过滤器时，所有命名空间都被移除的问题。
  • 修复了对于非常大的文档，文档数据在某个点之后停止索引的问题。
  • 修复了分词会丢弃包含非 ASCII 数字字符的段的问题。
  • 添加了对连续初始化失败尝试的检查，以帮助摆脱阻止成功初始化的潜在不良状态。

版本 1.0.0-alpha03

2021 年 7 月 21 日

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

新功能

  • 发布了平台存储后端，允许客户端将 AppSearch API 与 Android S 中推出的新 android.app.appsearch.AppSearchManager 服务一起使用。如需了解更多详情，请访问 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 的大小已减小。
  • 移除了重复属性的最大大小限制。
  • 允许重用构建器类。
  • 改进了某些对象的 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。