AppSearch

AppSearch

用户指南  代码示例

API 参考文档
androidx.appsearch.annotation
androidx.appsearch.app
androidx.appsearch.exceptions
androidx.appsearch.localstorage
androidx.appsearch.platformstorage

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

}

如需详细了解依赖项，请参阅添加 build 依赖项。

反馈

您的反馈将帮助我们改进 Jetpack。如果您发现了新问题，或对此库有任何改进建议，请告诉我们。创建新问题前，请先查看此库中的现有问题。您可以点击星标按钮，为现有问题投票。

创建新问题

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

版本 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)

bug 修复

• 此库现在使用类型使用的 JSpecify nullness 注释。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 nullness 注释。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 surface 添加 ExperimentalAppSearchApi 注释。(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 变更

• 向 AppSearch 的 Document.DocumentProperty 注释添加了 indexableNestedPropertiesList 和 inheritIndexableNestedPropertiesFromSuperclass 注释参数，以允许对特定的嵌套属性路径进行索引。(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)
• 添加了 Person 和 ContactPoint，以便在 AppSearch 中查询 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 对象，以及用于接受 PropertyPath 的新 addProjection 方法。(I45588)
• 向 AppSearch 内置类型添加了 builtin:Thing (I55427)
• 更快速地阻止 GenericDocument 中出现空的属性名称（以前是在编入索引时进行阻止，现在是在 GenericDocument.Builder.build() 时进行阻止）(I9e780)

bug 修复

• 移除了不必要的字符串格式，以提高 RELEVANCE 的评分性能
• 遇到不可读或已删除的文档时，可更高效地进行分页
• 针对已放弃的查询实现了垃圾回收
• 修复了 Documents 的嵌套索引编制支持。之前，系统会忽略 indexNestedProperties。(Iae9a6)

外部贡献

• Shea Smith：修复了 Documents 的嵌套索引编制支持。(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 确定当前后端支持的功能。
• 移除了对单个文档的约 13000 个令牌限制
• 允许匹配非 ASCII + 非字母数字字符，例如表情符号

bug 修复

• 修复了覆盖嵌套不兼容类型时 SetSchema 失败的 bug。
• 修复了相应错误，以完全支持将用 @AutoValue 注解的类用作 AppSearch @Document 类
• 修复了与重复的 Document 类列表和其他问题相关的一些崩溃问题
• 修复了在某些情况下会导致前缀搜索崩溃的 bug
• 修复了遇到 IO 故障时在 GetStorageInfo 中返回错误值的次要 bug
• 修复了阅读文档时出现的 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 中的 bug：未检测到某些向后不兼容和索引不兼容的情况

版本 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 初始化中的 bug

版本 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。