★ FEATURED ARTICLE 后端数据库【免费下载链接】laravel-mongodbA MongoDB based Eloquent model and Query builder for Laravel (Moloquent)项目地址https://gitcode.com/gh_mirrors/la/laravel-mongodb点击查看免费下载本文基于mongodb/laravel-mongodb仓库的 Atlas Search 技术指南系统讲解在 Laravel MongoDB 项目中如何为集合接入 Atlas Search 全文检索先厘清「Scout 是可选的」这一核心前提再分别给出「原生$search聚合」与「Laravel Scout」两条落地路径的完整配置、索引创建与查询代码并结合仓库源码Scout 引擎、Schema Blueprint、服务提供者与集成测试说明底层实现原理与边界。读完本文你将能够独立判断何时该用 Scout、何时该写原生聚合并能在自己的模型中一键接入全文搜索、范围过滤与向量检索。1. 核心前提Atlas Search 下 Scout 是可选的许多从 MySQL 迁移到 MongoDB 的开发者会下意识地把「全文搜索」等同于「安装 Laravel Scout」。但在 Atlas Search 场景下这个前提不成立只要集合上建了 Atlas Search 索引就不需要任何同步管道。Atlas 直接对集合本身建立索引文档在插入或更新时会被自动索引无需运行 Scout 的 import 任务也不需要维护一份独立的索引数据副本。只有当你需要以下能力时才考虑引入 Laravel ScoutSearchabletrait 提供的一行式 APIModel::search()开箱即用的paginate()分页跨驱动可移植性同一套 Scout 代码可切换 SQL 驱动或兼容 Scout 的第三方搜索引擎。两种方案的选择依据原文档给出了一张简洁的对照表方案适用场景原生$search聚合需要完全控制查询、需要范围过滤range filter、纯 Atlas 应用——无需 ScoutLaravel Scout需要Model::search()的便捷 API、paginate()分页、跨驱动可移植性判断口诀要控制力与范围过滤走原生聚合要便捷 API 与分页走 Scout。2. 原生 Atlas Search无需 Scout不引入任何额外依赖直接在模型的集合上通过Model::raw()执行聚合管道即可完成全文检索。没有独立的索引步骤也没有 import 步骤——集合本身就被 Atlas Search 索引。?php use App\Models\Product; $results Product::raw(fn ($c) $c-aggregate([ [$search [ index default, text [query wireless headphones, path [name, description]], ]], [$match [price [$lte 200]]], [$limit 10], ]));这段代码展示了原生方案的两个鲜明优势自由组合后续管道阶段$search之后可以随意接$match如这里的价格上限 200、$sort、$group、$facet等任意聚合阶段范围过滤因此毫无障碍不需要单独的索引维护代码$search引用的是集合上已存在的 Atlas Search 索引此处索引名为default文档更新即自动索引。从源码看Model::raw()经由 Eloquent Builder 的 raw() 方法 转发到查询构建器当回调返回游标时会把原始文档 hydrate 为模型实例因此返回结果是标准的 Eloquent 模型集合可以直接在 Blade 模板或 API 资源中使用。另外如果不想用raw()闭包Eloquent 构建器也提供了更声明式的search()方法例如在 Eloquent Builder 中定义$results Book::search( sort: [title 1], operator: MongoDB\Builder\Search::text(title, systems), );它等价于$this-toBase()-search(...)后对结果hydrate()相关聚合能力search、vectorSearch、autocomplete在 查询构建器 中均有完整实现均可用于不引入 Scout 的场景。3. Laravel Scout 集成当你确定需要Model::search()的便捷性、分页与跨驱动可移植性时按以下步骤接入 Scout。3.1 安装composer require laravel/scout php artisan vendor:publish --providerLaravel\Scout\ScoutServiceProvider发布后会生成config/scout.php配置文件。3.2 配置在config/scout.php中指定 MongoDB 驱动与连接// config/scout.php return [ driver env(SCOUT_DRIVER, mongodb), mongodb [ connection env(SCOUT_MONGODB_CONNECTION, mongodb), ], ];并在.env中设置SCOUT_DRIVERmongodb还可以补充两个可选配置项scout.mongodb.index-definitions为指定集合提供自定义的 Atlas Search 索引定义数组形式键为集合名、值为完整定义引擎创建索引时会优先使用它scout.prefix为 Scout 索引集合添加前缀避免索引集合与模型业务集合同名冲突详见下文「写入集合与搜索集合」一节。这些配置如何生效可以看 服务提供者的 registerScoutEngine() 实现它向EngineManager注册名为mongodb的驱动创建ScoutEngine时依次读取scout.mongodb.connection默认mongodb、scout.soft_delete默认false与scout.mongodb.index-definitions默认[]。3.3 定义 Searchable 模型模型继承MongoDB\Laravel\Eloquent\Model并使用Laravel\Scout\Searchabletrait?php namespace App\Models; use Laravel\Scout\Searchable; use MongoDB\Laravel\Eloquent\Model; final class Product extends Model { use Searchable; protected $fillable [name, description, price, tags]; public function toSearchableArray(): array { return [ name $this-name, description $this-description, tags $this-tags, price (float) $this-price, ]; } public function searchableAs(): string { // Return the collection name; Scout uses scout as the Atlas Search index name by default. return products; } }要点说明toSearchableArray()决定哪些字段进入索引、以什么类型存储——这里把price显式转为float确保它被索引为数字类型后续才能做范围过滤或数值排序searchableAs()返回的集合名是Atlas Search 索引所依附的集合引擎据此定位搜索集合。3.4 创建 Atlas Search 索引在迁移文件中通过Schema::connection(mongodb)-create()的searchIndex()方法创建索引。第二个参数是索引名Scout 引擎默认使用scoutSchema::connection(mongodb)-create(products, function (Blueprint $c): void { $c-searchIndex([ mappings [ dynamic false, fields [ name [type string], description [type string], tags [type string], price [type number], ], ], ], scout); });这里dynamic false表示只索引显式声明的字段字段类型与toSearchableArray()保持一致。searchIndex()的底层实现在 Schema Blueprint它直接调用 MongoDB 驱动集合的createSearchIndex($definition, [name $name, type search])。除了searchIndex()同一文件还提供了配套的vectorSearchIndex()创建向量索引与dropSearchIndex()删除索引覆盖完整的索引生命周期管理。仓库的 SchemaTest 验证了searchIndex()创建、读取含lucene.whitespace分析器配置与dropSearchIndex()删除的完整流程。3.5 执行搜索$results Product::search(wireless headphones)-get(); $page Product::search(headphones)-paginate(15);search()返回Product模型集合paginate()基于 Atlas Search 的计数元数据实现分页。3.6 Scout 查询的边界仅支持等值过滤MongoDB 引擎下的 Scoutwhere()只支持等值过滤不支持范围过滤。这是 Scout 抽象与 Atlas Search 能力的核心差异// WRONG — range filter not supported via Scout $results Product::search(headphones)-where(price, , 200)-get(); // CORRECT — use raw aggregation for range filters $results Product::raw(fn ($c) $c-aggregate([ [$search [index scout, text [query headphones, path name]]], [$match [price [$lte 200]]], ]));从引擎源码可以确认这一边界在 ScoutEngine 的 performSearch() 中$builder-wheres的每个字段被转换为compound.filter下的equals操作符whereIn转换为inwhereNotIn转换为mustNot.in——全部是精确值匹配没有range的映射分支。因此凡是需要「价格 ≤ 200」「日期在某区间」这类场景都应回到原生聚合管道在$search之后追加$match。4. 深入源码ScoutEngine 如何把search()翻译成聚合管道MongoDB\Laravel\Scout\ScoutEngine完整实现是 Scout 抽象的 MongoDB 落地实现理解它能让你在排错时心里有数。4.1 索引名与默认定义引擎固定使用名为scout的 Atlas Search 索引INDEX_NAME scout若scout.mongodb.index-definitions未提供该集合的定义则使用默认定义[mappings [dynamic true]]定义中必须包含mappings键否则抛出InvalidArgumentExceptioncreateIndex 实现。创建索引前引擎会先createCollection($name)确保集合存在创建后默认同步等待索引达到READY状态超时 300 秒因为 Atlas Search 索引管理操作是异步的。引擎内还有配套的wait()辅助方法实现见此处每秒轮询一次索引状态。4.2 查询的复合结构每次search()都会被翻译为如下的$search聚合阶段performSearch 源码compound.should两个子句text全文检索path使用wildcard: *所有字段开启fuzzy.maxEdits 2模糊匹配并boost加权 5wildcard对query . *做通配符匹配allowAnalyzedField: true近似 SQL 的LIKE语义minimumShouldMatch: 1至少命中其中一个子句。filter/mustNot承载where()的等值过滤equals、whereInin与whereNotInmustNot这些条件不贡献相关度分数。计数count: [type lowerBound]随后通过$addFields把$$SEARCH_META.count.lowerBound写入__count字段供getTotalCount()实现分页总数实现见此处。4.3 相关度排序与_score引擎支持按相关度排序orderBy(_score, desc)会被映射为sort: [score [$meta searchScore]]。同时有两个硬性约束校验逻辑不能同时按名为score的普通字段和 Atlas 的_score相关度排序_score不允许升序排序相关度分数恒为降序。4.4 写入集合与搜索集合的隔离引擎区分两个集合getIndexableCollection写入集合indexableAs()默认由searchableAs()派生update()通过bulkWrite执行updateOneupsert空的可搜索数组则deleteOne搜索集合searchableAs()。如果模型自身的业务表恰好与indexableAs()指向同一集合、且使用同一数据库引擎会抛出LogicException提示必须设置scout.prefix配置或改用独立的 MongoDB 数据库——这正是 ScoutIntegrationTest 专门验证的隔离约束。此外模型启用软删除时引擎会把__soft_deleted元数据转为布尔类型写入便于where(__soft_deleted, false)过滤。4.5 命令行工作流仓库的 ScoutIntegrationTest 展示了一套完整的命令工作流php artisan scout:delete-index App\Models\ScoutUser # 删除索引删除集合 php artisan scout:import App\Models\ScoutUser # 导入/重建数据 php artisan scout:index App\Models\ScoutUser # 创建搜索索引异步等待 READY测试还覆盖了search()基本查询、游标查询、query()回调过滤、keys()、paginate()、按相关度排序、按「相关度 字段」混合排序等场景可以作为自己集成时的行为参照。5. 进阶Vector Search 与混合检索Atlas Search 文档中引用了仓库内独立的 Vector Search 指南用于语义检索、自动嵌入与混合检索场景。核心要点如下自动嵌入autoEmbed索引字段声明type: autoEmbed后Atlas 在插入/更新时自动生成向量PHP 侧零嵌入代码查询时直接传文本query手动嵌入自行用 OpenAI 等 SDK 生成向量存入embedding字段查询时传queryVectorvectorSearch()同时支持query/queryVector两种入参见查询构建器实现混合检索通过原生聚合把$search与$vectorSearch组合进$rankFusion实现全文 语义的加权融合排序。vectorSearchIndex()建索引、Book::vectorSearch()查询的完整闭环仓库在 AtlasSearchTest 中有端到端验证含cosine/euclidean相似度与自动嵌入用例。6. 总结与决策速查你的需求推荐方案一行式search()、paginate()、跨驱动代码Laravel ScoutSCOUT_DRIVERmongodb范围过滤、完全控制管道、纯 Atlas 应用原生$search聚合Model::raw()语义检索 / 向量召回vectorSearchIndex()vectorSearch()全文 语义混合排序$rankFusion聚合最后提醒三点工程实践Atlas Search 索引创建是异步的迁移完成后请等待索引进入READY引擎默认等 300 秒测试中通过 waitForSearchIndexesReady 轮询queryable状态记住 Scoutwhere()只支持等值过滤范围过滤永远回退到原生聚合注意隔离 Scout 索引集合与模型业务集合scout.prefix或独立数据库避免触发引擎的保护性异常。赞分享后端数据库【免费下载链接】laravel-mongodbA MongoDB based Eloquent model and Query builder for Laravel (Moloquent)项目地址https://gitcode.com/gh_mirrors/la/laravel-mongodb点击查看免费下载相关推荐Photo Abstract Editorial 完整上手指南新手也能把普通照片变成抽象编辑作品Photo Abstract Editorial 完整上手指南新手也能把普通照片变成抽象编辑作品 把普通照片变成有艺术感的抽象编辑作品听起来需要专业设计功底AI 技能媒体生成AI 应用快速入门指南5步学会使用TRIBE v2 Subcortical进行fMRI预测快速入门指南5步学会使用TRIBE v2 Subcortical进行fMRI预测 TRIBE v2 Subcortical 是一个强大的神经科学预测模型专门laravel-mongodb与Laravel Scout集成全文检索优化laravel mongodb与Laravel Scout集成全文检索优化 在现代Web应用中高效的全文检索功能是提升用户体验的关键。当你还在为MongoD后端数据库创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
阅读完成 · 觉得有帮助？
