服务对象与地域限制
PuppyIP 仅面向海外合规企业及其授权人员提供服务，不面向中国大陆地区开放或提供代理服务。本服务仅限用于中国大陆境外的合法业务活动，严禁在中国大陆境内使用本服务。
代理 IP 或服务器位于境外，不改变上述限制。不得通过中转、转接、共享或转售向中国大陆境内的最终使用者提供本服务。使用前请阅读用户服务协议。
本文要点
- Cloudflare 于 2026 年 11 月 12 日公布 D1 数据源 Beta；查询返回的每一行会成为一个独立文档。
- 通过 API 或 Workers 连接时，D1 数据库须与 AI Search 位于同一账户；还需要返回 id 的只读查询和必填的 service token_id。
- 查询必须是单条 SELECT 或 WITH，返回非空且唯一的 id；不得加入 ORDER BY、LIMIT、分号、绑定参数或其他被拒内容。
- 查询失败或返回零行时，同步会报错并保留旧项目；路径排除仍会读取 D1，每次完整同步至少读取两遍结果。
先确认 Beta 状态和连接条件
Cloudflare 在 2026 年 11 月 12 日宣布 AI Search 支持 D1 数据源（Beta）。你提供一条只读查询，AI Search 会把结果中的每一行索引为一个独立文档；计划同步用于跟进新增、变更和移除的行。公告说明了功能阶段与基本方式，但没有证明任何具体账户已经开通或完成验证。 具体账户、国家或地区的适用情况、计划资格及最终费用仍需按账户与当前计费规则核对，本文不作保证。
在控制台创建实例时，选择 D1 数据库、填写查询并选择文档模板，再点 Test query 检查一行结果及其列；这个测试发生在创建之前，不等于完整同步验收。使用 REST API 或 Workers binding 时，D1 数据库必须和 AI Search 位于同一 Cloudflare 账户，查询须返回 id 列，并提供 service API token 的 token_id。token_id 始终必填；该令牌的 AI Search Index Engine 权限包含 D1 Read。
创建前，AI Search 会检查数据库、令牌、查询和结果列；任何一项失败，请求会报错且不会创建实例。
按 D1 数据源规则写查询
查询必须是一条只读语句，并以 SELECT 或 WITH 开始；括号要配对。不能使用分号、-- 或 /* 注释标记，也不能使用 ?、:name、@name、$name 等绑定参数。INSERT、UPDATE、DELETE、REPLACE、PRAGMA 等关键字，以及以 sqlite_、_cf_ 或 pragma_ 开头的名称都会被拒绝；这些检查也会扫描字符串字面值，所以 replace() 同样会被挡下。
结果至少一行、至多 100,000 行，并且必须有唯一、非 NULL、非空的 id；该列须全为文本，或全为 -9,007,199,254,740,991 至 9,007,199,254,740,991 之间的整数。不要写 ORDER BY 或 LIMIT，AI Search 会按 id 分页读取。假设 articles 表有这些列，查询可以写作 SELECT id, title, body AS content FROM articles WHERE published = 1。这个示例仅说明查询形状，本文没有执行它；查询最长为 10,000 个字符。
把列名当作文档字段契约
每个结果列都要有唯一名称。id 用来识别跨次同步的行；title 会成为标题，content 会成为正文，meta_<name> 会成为可用于检索筛选的自定义元数据；其他列则按所选模板作为带标签的字段呈现。优先返回稳定、已建索引的主键作为 id；改动行的 id 会删除旧项目并新建一个项目。
id 最长为 512 个 UTF-8 字节，每行渲染出的文档最多 64 KiB。最多返回五个 meta_ 列；列名会先转为小写；meta_ 后的元数据名须以字母开头，只含字母、数字和下划线，最长 64 个字符，且不能使用 timestamp、folder、filename、file 或 row_id 等保留名。单个元数据值最长 500 个字符，超出部分会被截断；每行包含 id 在内的元数据 JSON 最多 8,000 字节。
理解同步何时保留或删除项目
D1 实例按同步间隔运行任务：新行会被索引，变更行会重新索引，未变更行会跳过。查询不再返回的行只会在 AI Search 读完整个结果后删除；因此部分结果还没读完时，不应把它当作清理完成。
如果查询失败或返回零行，同步任务会以错误结束，已有索引项目会保留。不要用意外的空结果来清空帮助库，也不要把“调度已启动”当成内容已可搜索；查询、模板或路径规则的变更会触发同步，但数据源数据库本身无法在更新中更换。
用 WHERE 过滤，并保留更新请求中的路径规则
include_items 和 exclude_items 按每行生成的项目键匹配，例如 42.md。它们不会让 D1 少读被排除的行；Cloudflare 说明 AI Search 仍会从 D1 读取这些行。若要减少扫描范围，通常在 SQL 查询里用 WHERE 限定真正需要建立索引的记录。
更新实例时，如果省略 query 或 template，现有值会保留；但发送 source_params 对象会替换 include_items 和 exclude_items。需要沿用路径规则时，更新请求要再次带上它们。核对查询与筛选配置后再提交，因为相关变更会启动一次同步。
把读取量和文件上限纳入小样本验收
每次同步至少用 service API token 读取完整查询结果两遍：先检查 id，再按页读取；这些行会计入 D1 的读取量。稳定且有索引的 id 有助于让 D1 按页读取，计算出来的 id 可能使每页都扫描完整结果。只返回需要的字段，并避免把频繁变动的计数器等列放入结果，以免无关变化触发重新索引。
D1 数据源同时受实例文件数限制约束；有效上限取适用限制中的较低值。达到上限时，行会按 id 顺序索引到上限为止，而且该次同步不会删除项目。可先用少量获授权的帮助记录检查控制台单行测试、同步任务结果与生成文档，再逐步扩大范围。本文没有连接真实 D1 数据库或测试账户配置。
资料来源
常见问题
已有的 meta_ 字段以后可以删除或改类型吗？
更新查询时可以新增 meta_ 列，但不能移除已有列或改变其类型。AI Search 会自动生成 custom_metadata 模式；若手动传入该模式，字段和类型必须与查询结果一致。整数或实数对应 number，其他类型对应 text。
项目文件名变化后，怎样回查 D1 原始行？
每个文本块的 row_id 元数据保留完整原始 id。只有符合字符和长度条件的 id 才直接生成 <id>.md；其他 id 会使用清理后的前缀加哈希。不要仅靠文件名还原原始 id，可结合 Items API 列表或下载结果核对。