> ## 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

> Wie Sie MongoDB in einer Laravel-Anwendung einsetzen. Von der Treiber-Installation über die Konfiguration bis zu Eloquent-Modellen, dem Query Builder sowie der Nutzung als Cache- und Queue-Treiber.

## Einführung

[MongoDB](https://www.mongodb.com/resources/products/fundamentals/why-use-mongodb) ist eine der beliebtesten NoSQL-Dokumentendatenbanken. Sie zeichnet sich durch hohe Schreibleistung (ideal für Analytics und IoT), hohe Verfügbarkeit (automatisches Failover per Replica Set), horizontale Skalierung (Sharding) und eine leistungsstarke Query-Sprache (Aggregation, Volltextsuche, Geo-Abfragen) aus.

Anders als das Zeilen-/Spalten-Modell in SQL-Datenbanken ist jeder Datensatz in MongoDB ein Dokument im BSON-Format (binäres JSON). Die Anwendung kann diese Daten im JSON-Format lesen.

```mermaid theme={null}
flowchart LR
    A["Laravel-<br>Anwendung"] --> B["Paket<br>mongodb/laravel-mongodb"]
    B --> C["MongoDB PHP-Treiber"]
    C --> D["MongoDB-Server"]

    subgraph features ["Typische Anwendungen"]
        E["Eloquent-Modelle"]
        F["Query Builder"]
        G["Cache-Treiber"]
        H["Queue-Treiber"]
        I["GridFS-Dateispeicher"]
        J["Vektorsuche"]
        K["Volltextsuche (Scout)"]
    end

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

<Info>
  Für den Einsatz von MongoDB mit Laravel empfehlen wir das offizielle, von MongoDB gepflegte Paket `mongodb/laravel-mongodb`. Es bietet eine umfassende Integration mit Eloquent und weiteren Laravel-Funktionen.
</Info>

## Installation

### MongoDB PHP-Treiber

Um sich mit MongoDB zu verbinden, benötigen Sie die PHP-Erweiterung `mongodb`. Bei Nutzung von [Laravel Herd](https://herd.laravel.com) oder `php.new` ist sie bereits installiert. Für die manuelle Installation verwenden Sie PECL.

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

Details zur Installation finden Sie im [Installations-Leitfaden der MongoDB-PHP-Erweiterung](https://www.php.net/manual/en/mongodb.installation.php).

<Warning>
  Stellen Sie sicher, dass die PHP-Erweiterung `mongodb` sowohl für die CLI als auch für den Webserver aktiviert ist. Die Konfigurationen können sich unterscheiden.
</Warning>

### MongoDB-Server starten

Für die lokale Entwicklung eignet sich der MongoDB Community Server. Installationshinweise für Windows, macOS, Linux und Docker finden Sie im [offiziellen Installationshandbuch](https://docs.mongodb.com/manual/administration/install-community/).

**Mit 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
```

Für Cloud-Hosting steht [MongoDB Atlas](https://www.mongodb.com/cloud/atlas) zur Verfügung. Um von lokal auf einen Atlas-Cluster zuzugreifen, müssen Sie Ihre IP-Adresse in die IP-Zugriffsliste des Projekts aufnehmen.

### Das Paket laravel-mongodb installieren

Installieren Sie das Paket `mongodb/laravel-mongodb` mit Composer.

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

## Konfiguration

### Umgebungsvariablen

Ergänzen Sie in der `.env`-Datei die Verbindungsdaten für MongoDB.

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

Wenn Sie MongoDB Atlas verwenden, ersetzen Sie den Connection-String durch den von 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

Fügen Sie im Array `connections` in `config/database.php` eine `mongodb`-Verbindung hinzu.

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

    // ... bestehende Verbindungen ...

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

],
```

<Tip>
  Wenn Sie MySQL o. Ä. gemeinsam mit MongoDB einsetzen, lassen Sie `default` unverändert und fügen einfach die `mongodb`-Verbindung hinzu. Sie können die Verbindung je Modell wechseln.
</Tip>

## Kernfunktionen

### Eloquent-Modelle

Indem Sie von `MongoDB\Laravel\Eloquent\Model` erben, können Sie MongoDB nahezu genauso bedienen wie normale Eloquent-Modelle.

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

namespace App\Models;

use MongoDB\Laravel\Eloquent\Model;

class Article extends Model
{
    protected $connection = 'mongodb';
    protected $collection = 'articles'; // Collection-Name (wenn weggelassen, aus dem Klassennamen abgeleitet)

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

<Info>
  Da MongoDB schemalos ist, sind keine Migrationen nötig. Beim Speichern eines Dokuments wird die Collection automatisch angelegt.
</Info>

#### Grundlegende CRUD-Operationen

Sie verwenden dieselbe API wie beim normalen Eloquent.

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

// Anlegen
$article = Article::create([
    'title' => 'Einführung in MongoDB',
    'body' => 'MongoDB ist eine dokumentenorientierte Datenbank.',
    'tags' => ['nosql', 'mongodb', 'laravel'],
    'published_at' => now(),
]);

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

// Aktualisieren
$article->update(['title' => 'Einführung in MongoDB (überarbeitet)']);

// Löschen
$article->delete();
```

#### Arrays und eingebettete Dokumente

Sie können Arrays und eingebettete Dokumente – eine Stärke von MongoDB – direkt verwenden.

```php theme={null}
// Wert an ein Array-Feld anhängen
$article->push('tags', 'database');

// Wert aus einem Array-Feld entfernen
$article->pull('tags', 'nosql');

// Abfrage auf einem eingebetteten Dokument
$articles = Article::where('meta.author', 'Taylor')->get();
```

### Query Builder

Mit dem Query Builder von MongoDB lassen sich komplexe Abfragen formulieren. Details finden Sie in der [Query-Builder-Dokumentation von laravel-mongodb](https://www.mongodb.com/docs/drivers/php/laravel-mongodb/current/query-builder/).

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

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

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

### Cache-Treiber

Der MongoDB-Cache-Treiber nutzt TTL-Indizes und entfernt abgelaufene Einträge automatisch. Siehe die [Cache-Treiber-Dokumentation](https://www.mongodb.com/docs/drivers/php/laravel-mongodb/current/cache/) für Details.

Fügen Sie in `config/cache.php` einen Store hinzu.

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

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

],
```

Stellen Sie in der `.env` den Cache-Treiber auf MongoDB.

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

### Queue-Treiber

Sie können MongoDB als Queue-Treiber verwenden. Details finden Sie in der [Queue-Treiber-Dokumentation](https://www.mongodb.com/docs/drivers/php/laravel-mongodb/current/queues/).

Fügen Sie in `config/queue.php` die Verbindung hinzu.

```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,
    ],

],
```

Setzen Sie die Queue-Verbindung in der `.env` auf MongoDB.

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

### Dateispeicherung mit GridFS

Mit GridFS von MongoDB können Sie Dateien speichern. Verwendet wird der [GridFS-Adapter für Flysystem](https://flysystem.thephpleague.com/docs/adapter/gridfs/). Details siehe [GridFS-Dokumentation](https://www.mongodb.com/docs/drivers/php/laravel-mongodb/current/filesystems/).

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

Fügen Sie in `config/filesystems.php` einen Disk hinzu.

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

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

],
```

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

// Datei hochladen
Storage::disk('gridfs')->put('file.pdf', $contents);

// Datei laden
$contents = Storage::disk('gridfs')->get('file.pdf');
```

### Vektorsuche (Vector Search)

Mit [MongoDB Atlas Vector Search](https://www.mongodb.com/docs/drivers/php/laravel-mongodb/current/fundamentals/vector-search/) können Sie Ähnlichkeitssuchen über Vektor-Embeddings durchführen. Sie speichern zum Beispiel Text-, Bild- oder Audio-Daten als Vektoren und finden die dem Query-Vektor am nächsten liegenden Dokumente – ein Suchfeature für KI und Machine Learning.

<Info>
  Die Vektorsuche ist ausschließlich auf **MongoDB Atlas** verfügbar. In einem lokalen MongoDB Community Server oder in selbst gehosteten Umgebungen lässt sie sich nicht verwenden. Sie müssen vorab in der Atlas-Konsole einen Vector-Search-Index anlegen.
</Info>

Die Methode `vectorSearch` steht am Query Builder zur Verfügung.

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

// Embedding aus einem Query-String erzeugen (z. B. per OpenAI API)
$queryVector = getEmbedding('Was ist MongoDB'); // float[]-Array

$results = Article::query()->vectorSearch(
    index: 'vector_index',   // Name des Atlas-Vector-Search-Index
    path: 'embedding',       // Feld, in dem der Vektor gespeichert ist
    queryVector: $queryVector,
    limit: 10,               // Anzahl zurückgegebener Dokumente
    numCandidates: 100,      // Anzahl der Kandidaten (für ANN-Suche)
);

// Jedes Dokument erhält einen vectorSearchScore
foreach ($results as $result) {
    echo $result->title . ': ' . $result->vectorSearchScore;
}
```

### Volltextsuche (Scout-Engine)

Mit der Scout-Engine `mongodb` können Sie die Volltextsuche von [Laravel Scout](/de/scout) mit MongoDB nutzen. Intern wird **MongoDB Atlas Search** verwendet – inklusive Unterstützung für Fuzzy- und Wildcard-Suche. Details finden Sie in der [Scout-Engine-Dokumentation](https://www.mongodb.com/docs/drivers/php/laravel-mongodb/current/scout/).

<Info>
  Auch die MongoDB-Scout-Engine ist nur auf **MongoDB Atlas** verfügbar. Die Scout-Index-Collection muss eine andere Collection sein als die des Modells. Die Einstellung `prefix` in `config/scout.php` (standardmäßig der App-Name) wird automatisch angewendet.
</Info>

Stellen Sie den Scout-Treiber in der `.env` auf `mongodb`.

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

Fügen Sie dem Modell das Trait `Searchable` hinzu.

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

class Article extends Model
{
    use Searchable;

    // Legt die Felder fest, die in den Suchindex aufgenommen werden
    public function toSearchableArray(): array
    {
        return [
            'title' => $this->title,
            'body'  => $this->body,
            'tags'  => $this->tags,
        ];
    }
}
```

Legen Sie den Scout-Index an und importieren Sie die vorhandenen Daten.

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

Suchen können Sie mit der Standard-API von Scout.

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

// Suche mit Filter
$results = Article::search('Query Builder')
    ->where('status', 'published')
    ->paginate(15);
```

## Zusammen mit MySQL nutzen

In Laravel können MySQL und MongoDB parallel verwendet werden. Pro Modell geben Sie die Verbindung über die Eigenschaft `$connection` an.

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

```php theme={null}
// Reguläres Eloquent-Modell mit MySQL
class User extends \Illuminate\Database\Eloquent\Model
{
    protected $connection = 'mysql';
}

// Modell mit MongoDB
class Article extends \MongoDB\Laravel\Eloquent\Model
{
    protected $connection = 'mongodb';
}
```

<Info>
  Wenn Sie Beziehungen zwischen MySQL- und MongoDB-Modellen abbilden möchten, siehe [Hybride Beziehungen](https://www.mongodb.com/docs/drivers/php/laravel-mongodb/current/eloquent-models/relationships/).
</Info>

## Zusammenfassung

<AccordionGroup>
  <Accordion title="Installations-Checkliste">
    1. PHP-Erweiterung mit `pecl install mongodb` installieren
    2. MongoDB-Server starten (lokal, per Docker oder Atlas)
    3. Paket mit `composer require mongodb/laravel-mongodb` installieren
    4. `MONGODB_URI` und `MONGODB_DATABASE` in der `.env` setzen
    5. `mongodb`-Verbindung in `config/database.php` hinzufügen
  </Accordion>

  <Accordion title="MongoDB vs. MySQL">
    | Merkmal            | MongoDB                                        | MySQL                                     |
    | ------------------ | ---------------------------------------------- | ----------------------------------------- |
    | Datenmodell        | Dokumente (JSON/BSON)                          | Tabellen (Zeilen/Spalten)                 |
    | Schema             | Schemalos (flexibel)                           | Festes Schema                             |
    | Skalierung         | Horizontale Skalierung einfach                 | Meist vertikale Skalierung                |
    | Transaktionen      | Multi-Document (ab v4)                         | Vollständig ACID                          |
    | Typische Anwendung | Logs, Analytics, IoT, flexible Datenstrukturen | Strukturierte Daten, komplexe Beziehungen |
  </Accordion>

  <Accordion title="Funktionsübersicht">
    | Funktion         | Konfigurationsort                                                |
    | ---------------- | ---------------------------------------------------------------- |
    | Eloquent-Modelle | `MongoDB\Laravel\Eloquent\Model` erweitern                       |
    | Query Builder    | `DB::connection('mongodb')->collection(...)`                     |
    | Cache            | `config/cache.php` + `CACHE_STORE=mongodb`                       |
    | Queue            | `config/queue.php` + `QUEUE_CONNECTION=mongodb`                  |
    | Dateispeicher    | `config/filesystems.php` + GridFS-Adapter                        |
    | Vektorsuche      | `Model::query()->vectorSearch(...)` (Atlas erforderlich)         |
    | Volltextsuche    | `SCOUT_DRIVER=mongodb` + `Searchable`-Trait (Atlas erforderlich) |
  </Accordion>
</AccordionGroup>

## Nächste Schritte

<CardGroup cols={2}>
  <Card title="Offizielle Dokumentation von laravel-mongodb" icon="book" href="https://www.mongodb.com/docs/drivers/php/laravel-mongodb/">
    Vollständige Referenz zu Eloquent, Query Builder, Beziehungen und mehr
  </Card>

  <Card title="Schnellstart" icon="rocket" href="https://www.mongodb.com/docs/drivers/php/laravel-mongodb/current/quick-start/">
    Die Grundlagen von MongoDB mit Laravel schnell lernen
  </Card>

  <Card title="Datenbank-Konfiguration" icon="database" href="/de/database">
    Grundlagen zur Konfiguration von Datenbankverbindungen in Laravel
  </Card>

  <Card title="Einführung in Eloquent" icon="table" href="/de/eloquent">
    Grundlegende Nutzung des Eloquent ORM
  </Card>
</CardGroup>


## Related topics

- [Suche](/de/search.md)