> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# MongoDB

> 在 Laravel 應用程式中使用 MongoDB。從驅動安裝與設定、Eloquent 模型、Query Builder，到作為快取 / 佇列驅動的用法皆有介紹。

## 簡介

[MongoDB](https://www.mongodb.com/resources/products/fundamentals/why-use-mongodb) 是最受歡迎的 NoSQL 文件導向資料庫之一。特色包含高寫入效能（適合分析與 IoT）、高可用性（透過 replica set 自動故障轉移）、水平擴充（sharding），以及強大的查詢語言（聚合、全文檢索、地理空間查詢）。

與 SQL 資料庫的列 / 欄形式不同，MongoDB 的每筆資料都是 BSON（binary JSON）形式的文件。應用程式可以以 JSON 格式取得這些資料。

```mermaid theme={null}
flowchart LR
    A["Laravel<br>應用程式"] --> B["mongodb/laravel-mongodb<br>套件"]
    B --> C["MongoDB PHP 驅動"]
    C --> D["MongoDB 伺服器"]

    subgraph features ["主要用途"]
        E["Eloquent 模型"]
        F["Query Builder"]
        G["快取驅動"]
        H["佇列驅動"]
        I["GridFS 檔案儲存"]
        J["向量搜尋"]
        K["全文檢索 (Scout)"]
    end

    B --> E
    B --> F
    B --> G
    B --> H
    B --> I
    B --> J
    B --> K
```

<Info>
  在 Laravel 中使用 MongoDB，建議使用官方維護的 `mongodb/laravel-mongodb` 套件。它提供與 Eloquent 及 Laravel 各功能的豐富整合。
</Info>

## 安裝

### MongoDB PHP 驅動

要連線至 MongoDB 需要 `mongodb` PHP 擴充。若你使用 [Laravel Herd](https://herd.laravel.com) 或 `php.new`，通常已預先安裝。手動安裝請透過 PECL：

```shell theme={null}
pecl install mongodb
```

詳細請參閱 [MongoDB PHP 擴充安裝指南](https://www.php.net/manual/en/mongodb.installation.php)。

<Warning>
  請確認 `mongodb` PHP 擴充在 CLI 與 Web 伺服器兩邊都已啟用，因為設定可能不同。
</Warning>

### 啟動 MongoDB 伺服器

MongoDB Community Server 可用於本機開發。Windows、macOS、Linux、Docker 的安裝方式請參閱[官方安裝指南](https://docs.mongodb.com/manual/administration/install-community/)。

**使用 Docker 時：**

```yaml theme={null}
# docker-compose.yml
services:
  mongodb:
    image: mongo:8
    ports:
      - "27017:27017"
    environment:
      MONGO_INITDB_ROOT_USERNAME: root
      MONGO_INITDB_ROOT_PASSWORD: password
      MONGO_INITDB_DATABASE: laravel_app
    volumes:
      - mongodb_data:/data/db

volumes:
  mongodb_data:
```

```shell theme={null}
docker compose up -d
```

雲端託管可使用 [MongoDB Atlas](https://www.mongodb.com/cloud/atlas)。要從本機連線至 Atlas cluster，需將自己的 IP 加入專案的 IP 存取名單。

### 安裝 laravel-mongodb 套件

以 Composer 安裝 `mongodb/laravel-mongodb`：

```shell theme={null}
composer require mongodb/laravel-mongodb
```

## 設定

### 環境變數

在 `.env` 加入 MongoDB 的連線資訊。

```ini theme={null}
MONGODB_URI="mongodb://localhost:27017"
MONGODB_DATABASE="laravel_app"
```

若使用 MongoDB Atlas，請將連線字串換成 Atlas 的：

```ini theme={null}
MONGODB_URI="mongodb+srv://<username>:<password>@<cluster>.mongodb.net/<dbname>?retryWrites=true&w=majority"
MONGODB_DATABASE="laravel_app"
```

### config/database.php

在 `config/database.php` 的 `connections` 陣列加入 `mongodb`：

```php theme={null}
'connections' => [

    // ... 既有連線設定 ...

    'mongodb' => [
        'driver' => 'mongodb',
        'dsn' => env('MONGODB_URI', 'mongodb://localhost:27017'),
        'database' => env('MONGODB_DATABASE', 'laravel_app'),
    ],

],
```

<Tip>
  若要同時使用 MySQL 等關聯式資料庫與 MongoDB，`default` 保持不變，只要加入 `mongodb` 連線即可。可依模型切換連線。
</Tip>

## 主要功能

### Eloquent 模型

繼承 `MongoDB\Laravel\Eloquent\Model` 即可用幾乎相同的操作方式使用 MongoDB。

```php theme={null}
<?php

namespace App\Models;

use MongoDB\Laravel\Eloquent\Model;

class Article extends Model
{
    protected $connection = 'mongodb';
    protected $collection = 'articles'; // Collection 名（省略時由類別名自動產生）

    protected $fillable = [
        'title',
        'body',
        'tags',
        'published_at',
    ];
}
```

<Info>
  MongoDB 為 schema-less，不需要 migration。儲存文件時 collection 會自動建立。
</Info>

#### 基本 CRUD 操作

可以與一般 Eloquent 一樣使用相同的 API。

```php theme={null}
use App\Models\Article;

// 建立
$article = Article::create([
    'title' => 'MongoDB 入門',
    'body' => 'MongoDB 是一款文件導向資料庫。',
    'tags' => ['nosql', 'mongodb', 'laravel'],
    'published_at' => now(),
]);

// 取得
$article = Article::find('64f1a2b3c4d5e6f7a8b9c0d1');
$articles = Article::where('tags', 'nosql')->get();

// 更新
$article->update(['title' => '改訂版 MongoDB 入門']);

// 刪除
$article->delete();
```

#### 陣列與內嵌文件

可直接運用 MongoDB 的陣列與內嵌文件優勢：

```php theme={null}
// 對陣列欄位 push
$article->push('tags', 'database');

// 從陣列欄位 pull
$article->pull('tags', 'nosql');

// 對內嵌文件查詢
$articles = Article::where('meta.author', 'Taylor')->get();
```

### Query Builder

可用 MongoDB 的 Query Builder 撰寫較複雜的查詢，詳細請見 [laravel-mongodb Query Builder 文件](https://www.mongodb.com/docs/drivers/php/laravel-mongodb/current/query-builder/)。

```php theme={null}
use Illuminate\Support\Facades\DB;

// 基本查詢
$articles = DB::connection('mongodb')
    ->collection('articles')
    ->where('tags', 'laravel')
    ->orderBy('published_at', 'desc')
    ->limit(10)
    ->get();

// 匯總管線
$stats = DB::connection('mongodb')
    ->collection('orders')
    ->raw(function ($collection) {
        return $collection->aggregate([
            ['$group' => ['_id' => '$status', 'total' => ['$sum' => '$amount']]],
            ['$sort' => ['total' => -1]],
        ]);
    });
```

### 快取驅動

MongoDB 快取驅動會透過 TTL 索引自動刪除過期項目。詳細請見[快取驅動文件](https://www.mongodb.com/docs/drivers/php/laravel-mongodb/current/cache/)。

在 `config/cache.php` 加入 store：

```php theme={null}
'stores' => [

    'mongodb' => [
        'driver' => 'mongodb',
        'connection' => 'mongodb',
        'collection' => 'cache',
    ],

],
```

`.env` 中將快取驅動改為 MongoDB：

```ini theme={null}
CACHE_STORE=mongodb
```

### 佇列驅動

也可以將 MongoDB 作為佇列驅動使用。詳細請見[佇列驅動文件](https://www.mongodb.com/docs/drivers/php/laravel-mongodb/current/queues/)。

在 `config/queue.php` 加入連線：

```php theme={null}
'connections' => [

    'mongodb' => [
        'driver' => 'mongodb',
        'connection' => 'mongodb',
        'collection' => 'jobs',
        'queue' => env('MONGODB_QUEUE', 'default'),
        'retry_after' => (int) env('MONGODB_QUEUE_RETRY_AFTER', 90),
        'after_commit' => false,
    ],

],
```

`.env` 中改為 MongoDB：

```ini theme={null}
QUEUE_CONNECTION=mongodb
```

### 以 GridFS 儲存檔案

可使用 MongoDB 的 GridFS 儲存檔案，需要 [Flysystem 的 GridFS adapter](https://flysystem.thephpleague.com/docs/adapter/gridfs/)。詳細請見 [GridFS 文件](https://www.mongodb.com/docs/drivers/php/laravel-mongodb/current/filesystems/)。

```shell theme={null}
composer require league/flysystem-gridfs
```

在 `config/filesystems.php` 加入 disk：

```php theme={null}
'disks' => [

    'gridfs' => [
        'driver' => 'gridfs',
        'connection' => 'mongodb',
        'database' => env('MONGODB_DATABASE', 'laravel_app'),
    ],

],
```

```php theme={null}
use Illuminate\Support\Facades\Storage;

// 上傳檔案
Storage::disk('gridfs')->put('file.pdf', $contents);

// 取得檔案
$contents = Storage::disk('gridfs')->get('file.pdf');
```

### 向量搜尋（Vector Search）

透過 [MongoDB Atlas Vector Search](https://www.mongodb.com/docs/drivers/php/laravel-mongodb/current/fundamentals/vector-search/) 可依向量嵌入進行相似度搜尋。將文字、圖片、音訊等資料向量化後儲存，找出最接近查詢向量的文件；這是為 AI / 機器學習量身打造的搜尋機能。

<Info>
  向量搜尋僅能在 **MongoDB Atlas** 使用，本機 MongoDB Community Server 或自架環境無法使用。事先需在 Atlas 主控台建立 Vector Search 索引。
</Info>

在 Query Builder 中使用 `vectorSearch`：

```php theme={null}
use App\Models\Article;

// 由查詢字串生成 embedding（例如：OpenAI API 等）
$queryVector = getEmbedding('MongoDB 是什麼'); // float[] 陣列

$results = Article::query()->vectorSearch(
    index: 'vector_index',   // Atlas Vector Search 索引名
    path: 'embedding',       // 儲存向量的欄位名
    queryVector: $queryVector,
    limit: 10,               // 回傳文件數
    numCandidates: 100,      // 候選數（ANN 搜尋時指定）
);

// 每個文件會附上 vectorSearchScore
foreach ($results as $result) {
    echo $result->title . ': ' . $result->vectorSearchScore;
}
```

### 全文檢索（Scout 引擎）

可透過 `mongodb` Scout 引擎在 MongoDB 使用 [Laravel Scout](/zh-TW/scout) 的全文檢索。內部使用 **MongoDB Atlas Search**，支援模糊搜尋與萬用字元搜尋。詳細請見 [Scout 引擎文件](https://www.mongodb.com/docs/drivers/php/laravel-mongodb/current/scout/)。

<Info>
  MongoDB Scout 引擎同樣僅能於 **MongoDB Atlas** 使用。Scout 的索引 collection 必須與模型的 collection 分開。`config/scout.php` 的 `prefix`（預設為應用程式名稱）會自動套用。
</Info>

於 `.env` 將 Scout 驅動設為 `mongodb`：

```ini theme={null}
SCOUT_DRIVER=mongodb
```

在模型上加入 `Searchable` trait：

```php theme={null}
use Laravel\Scout\Searchable;
use MongoDB\Laravel\Eloquent\Model;

class Article extends Model
{
    use Searchable;

    // 指定要納入索引的欄位
    public function toSearchableArray(): array
    {
        return [
            'title' => $this->title,
            'body'  => $this->body,
            'tags'  => $this->tags,
        ];
    }
}
```

建立 Scout 索引並匯入既有資料：

```shell theme={null}
php artisan scout:index articles
php artisan scout:import "App\Models\Article"
```

使用標準 Scout API 進行搜尋：

```php theme={null}
// 全文檢索
$results = Article::search('MongoDB Laravel')->get();

// 附條件搜尋
$results = Article::search('Query Builder')
    ->where('status', 'published')
    ->paginate(15);
```

## 與 MySQL 並用

在 Laravel 中可同時使用 MySQL 與 MongoDB，於模型以 `$connection` 屬性指定連線。

```mermaid theme={null}
flowchart TD
    A["Laravel 應用程式"] --> B["UserController"]
    A --> C["ArticleController"]
    B --> D["User 模型\n$connection = 'mysql'"]
    C --> E["Article 模型\n$connection = 'mongodb'"]
    D --> F["MySQL"]
    E --> G["MongoDB"]
```

```php theme={null}
// 一般 Eloquent 模型，使用 MySQL
class User extends \Illuminate\Database\Eloquent\Model
{
    protected $connection = 'mysql';
}

// 使用 MongoDB 的模型
class Article extends \MongoDB\Laravel\Eloquent\Model
{
    protected $connection = 'mongodb';
}
```

<Info>
  若要在 MySQL 模型與 MongoDB 模型之間建立關聯，請參考[混合關聯（Hybrid Relations）](https://www.mongodb.com/docs/drivers/php/laravel-mongodb/current/eloquent-models/relationships/)。
</Info>

## 總結

<AccordionGroup>
  <Accordion title="安裝檢查清單">
    1. `pecl install mongodb` 安裝 PHP 擴充
    2. 啟動 MongoDB 伺服器（本機或 Docker、或 Atlas）
    3. `composer require mongodb/laravel-mongodb` 安裝套件
    4. 於 `.env` 設定 `MONGODB_URI` 與 `MONGODB_DATABASE`
    5. 於 `config/database.php` 加入 `mongodb` 連線
  </Accordion>

  <Accordion title="MongoDB 與 MySQL 的取捨">
    | 特性     | MongoDB                | MySQL      |
    | ------ | ---------------------- | ---------- |
    | 資料模型   | 文件（JSON/BSON）          | 表格（列 / 欄）  |
    | schema | schema-less（靈活）        | 固定 schema  |
    | 擴充     | 水平擴充容易                 | 以垂直擴充為主    |
    | 交易     | 多文件（v4+）               | 完整 ACID    |
    | 適用情境   | 日誌 / 分析 / IoT / 靈活結構資料 | 結構化資料、複雜關聯 |
  </Accordion>

  <Accordion title="功能整理">
    | 功能            | 設定位置                                                 |
    | ------------- | ---------------------------------------------------- |
    | Eloquent 模型   | 繼承 `MongoDB\Laravel\Eloquent\Model`                  |
    | Query Builder | `DB::connection('mongodb')->collection(...)`         |
    | 快取            | `config/cache.php` + `CACHE_STORE=mongodb`           |
    | 佇列            | `config/queue.php` + `QUEUE_CONNECTION=mongodb`      |
    | 檔案儲存          | `config/filesystems.php` + GridFS adapter            |
    | 向量搜尋          | `Model::query()->vectorSearch(...)`（需 Atlas）         |
    | 全文檢索          | `SCOUT_DRIVER=mongodb` + `Searchable` trait（需 Atlas） |
  </Accordion>
</AccordionGroup>

## 下一步

<CardGroup cols={2}>
  <Card title="laravel-mongodb 官方文件" icon="book" href="https://www.mongodb.com/docs/drivers/php/laravel-mongodb/">
    Eloquent、Query Builder、關聯等所有功能的詳細參考。
  </Card>

  <Card title="快速上手" icon="rocket" href="https://www.mongodb.com/docs/drivers/php/laravel-mongodb/current/quick-start/">
    快速學習 MongoDB 與 Laravel 的基本用法。
  </Card>

  <Card title="資料庫設定" icon="database" href="/zh-TW/database">
    Laravel 資料庫連線設定的基礎。
  </Card>

  <Card title="Eloquent 入門" icon="table" href="/zh-TW/eloquent">
    Eloquent ORM 的基本用法。
  </Card>
</CardGroup>


## Related topics

- [搜尋](/zh-TW/search.md)