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

> Cómo usar MongoDB en una aplicación Laravel. Cubrimos la instalación del driver, la configuración, los modelos Eloquent, el query builder y el uso como driver de caché y de colas.

## Introducción

[MongoDB](https://www.mongodb.com/resources/products/fundamentals/why-use-mongodb) es una de las bases de datos NoSQL orientadas a documentos más populares. Destaca por su alto rendimiento de escritura (ideal para analítica e IoT), alta disponibilidad (failover automático con réplicas), escalado horizontal (sharding) y un potente lenguaje de consulta (agregaciones, búsqueda de texto completo y consultas geoespaciales).

A diferencia del formato filas/columnas de una base de datos SQL, cada registro en MongoDB es un documento en formato BSON (JSON binario). La aplicación puede recuperar estos datos en formato JSON.

```mermaid theme={null}
flowchart LR
    A["Aplicación<br>Laravel"] --> B["Paquete<br>mongodb/laravel-mongodb"]
    B --> C["Driver PHP de MongoDB"]
    C --> D["Servidor MongoDB"]

    subgraph features ["Principales usos"]
        E["Modelos Eloquent"]
        F["Query Builder"]
        G["Driver de caché"]
        H["Driver de colas"]
        I["Almacenamiento con GridFS"]
        J["Búsqueda vectorial"]
        K["Búsqueda de texto (Scout)"]
    end

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

<Info>
  Para usar MongoDB con Laravel, se recomienda el paquete `mongodb/laravel-mongodb`, mantenido oficialmente por MongoDB. Ofrece una integración muy completa con Eloquent y con las distintas funcionalidades de Laravel.
</Info>

## Instalación

### Driver PHP de MongoDB

Para conectarte a MongoDB necesitas la extensión de PHP `mongodb`. Con [Laravel Herd](https://herd.laravel.com) o `php.new` ya viene instalada. Si la instalas manualmente, usa PECL.

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

Consulta la [guía de instalación de la extensión PHP MongoDB](https://www.php.net/manual/es/mongodb.installation.php) para más detalles.

<Warning>
  Comprueba que la extensión PHP `mongodb` esté activa tanto en CLI como en el servidor web. Las configuraciones pueden diferir.
</Warning>

### Arrancar el servidor MongoDB

Puedes usar MongoDB Community Server para desarrollo local. Consulta la [guía de instalación oficial](https://docs.mongodb.com/manual/administration/install-community/) para Windows, macOS, Linux y Docker.

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

Para hosting en la nube puedes usar [MongoDB Atlas](https://www.mongodb.com/cloud/atlas). Para acceder a un cluster de Atlas desde local necesitas añadir tu IP a la lista de acceso del proyecto.

### Instalación del paquete laravel-mongodb

Instala el paquete `mongodb/laravel-mongodb` con Composer.

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

## Configuración

### Variables de entorno

Añade la información de conexión a MongoDB en `.env`.

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

Si utilizas MongoDB Atlas, cambia la cadena de conexión a la de 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

Añade la conexión `mongodb` al array `connections` en `config/database.php`.

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

    // ... conexiones existentes ...

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

],
```

<Tip>
  Si combinas una base de datos relacional como MySQL con MongoDB, deja `default` como está y añade simplemente la conexión `mongodb`. Podrás cambiar de conexión por modelo.
</Tip>

## Funcionalidades principales

### Modelos Eloquent

Extendiendo `MongoDB\Laravel\Eloquent\Model` puedes trabajar con MongoDB de forma casi idéntica a un modelo Eloquent normal.

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

namespace App\Models;

use MongoDB\Laravel\Eloquent\Model;

class Article extends Model
{
    protected $connection = 'mongodb';
    protected $collection = 'articles'; // Nombre de la colección (se deduce del nombre de clase si se omite)

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

<Info>
  MongoDB no tiene esquema fijo, por lo que no hacen falta migraciones. Al guardar un documento se crea automáticamente la colección.
</Info>

#### Operaciones CRUD básicas

Se opera con la misma API que Eloquent normal.

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

// Crear
$article = Article::create([
    'title' => 'Introducción a MongoDB',
    'body' => 'MongoDB es una base de datos orientada a documentos.',
    'tags' => ['nosql', 'mongodb', 'laravel'],
    'published_at' => now(),
]);

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

// Actualizar
$article->update(['title' => 'Introducción a MongoDB (revisada)']);

// Eliminar
$article->delete();
```

#### Arrays y documentos embebidos

Puedes trabajar directamente con arrays y documentos embebidos, uno de los puntos fuertes de MongoDB.

```php theme={null}
// Push a un campo array
$article->push('tags', 'database');

// Pull desde un campo array
$article->pull('tags', 'nosql');

// Consulta sobre documentos embebidos
$articles = Article::where('meta.author', 'Taylor')->get();
```

### Query Builder

Con el query builder de MongoDB puedes escribir consultas complejas. Consulta la [documentación del query builder de laravel-mongodb](https://www.mongodb.com/docs/drivers/php/laravel-mongodb/current/query-builder/) para más detalles.

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

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

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

### Driver de caché

El driver de caché de MongoDB elimina automáticamente las entradas caducadas usando índices TTL. Consulta la [documentación del driver de caché](https://www.mongodb.com/docs/drivers/php/laravel-mongodb/current/cache/).

Añade el store en `config/cache.php`.

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

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

],
```

Cambia el driver de caché a MongoDB en `.env`.

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

### Driver de colas

MongoDB puede usarse como driver de colas. Consulta la [documentación del driver de colas](https://www.mongodb.com/docs/drivers/php/laravel-mongodb/current/queues/).

Añade la conexión en `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,
    ],

],
```

Cambia la conexión de colas a MongoDB en `.env`.

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

### Almacenamiento de archivos con GridFS

Con GridFS de MongoDB puedes almacenar archivos usando el [adaptador GridFS para Flysystem](https://flysystem.thephpleague.com/docs/adapter/gridfs/). Consulta la [documentación de GridFS](https://www.mongodb.com/docs/drivers/php/laravel-mongodb/current/filesystems/).

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

Añade el disco en `config/filesystems.php`.

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

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

],
```

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

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

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

### Búsqueda vectorial (Vector Search)

Con [MongoDB Atlas Vector Search](https://www.mongodb.com/docs/drivers/php/laravel-mongodb/current/fundamentals/vector-search/) puedes hacer búsquedas por similitud mediante embeddings vectoriales. Se vectorizan datos (texto, imagen, audio…) y se guardan; luego se recuperan los documentos más cercanos al vector de consulta. Es una función pensada para IA / machine learning.

<Info>
  La búsqueda vectorial solo está disponible en **MongoDB Atlas**. No funciona con MongoDB Community Server local ni con entornos auto-hospedados. Debes crear previamente un índice de Vector Search en la consola de Atlas.
</Info>

El método `vectorSearch` está disponible en el query builder.

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

// Genera el embedding desde una cadena de consulta (por ejemplo, con la API de OpenAI)
$queryVector = getEmbedding('¿Qué es MongoDB?'); // array float[]

$results = Article::query()->vectorSearch(
    index: 'vector_index',   // Nombre del índice Vector Search de Atlas
    path: 'embedding',       // Nombre del campo que contiene el vector
    queryVector: $queryVector,
    limit: 10,               // Número de documentos a devolver
    numCandidates: 100,      // Número de candidatos (para búsqueda ANN)
);

// Cada documento incluye vectorSearchScore
foreach ($results as $result) {
    echo $result->title . ': ' . $result->vectorSearchScore;
}
```

### Búsqueda de texto completo (motor Scout)

Puedes usar el motor Scout `mongodb` para aprovechar la búsqueda de texto completo de [Laravel Scout](/es/scout) con MongoDB. Internamente usa **MongoDB Atlas Search** y admite búsquedas difusas y con comodines. Consulta la [documentación del motor Scout](https://www.mongodb.com/docs/drivers/php/laravel-mongodb/current/scout/).

<Info>
  El motor Scout de MongoDB también requiere **MongoDB Atlas**. La colección del índice de Scout debe ser distinta de la del modelo. Se aplica automáticamente el `prefix` de `config/scout.php` (por defecto, el nombre de la aplicación).
</Info>

Configura el driver de Scout como `mongodb` en `.env`.

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

Añade el trait `Searchable` al modelo.

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

class Article extends Model
{
    use Searchable;

    // Indica qué campos se incluyen en el índice
    public function toSearchableArray(): array
    {
        return [
            'title' => $this->title,
            'body'  => $this->body,
            'tags'  => $this->tags,
        ];
    }
}
```

Crea el índice de Scout e importa los datos existentes.

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

Realiza búsquedas con la API estándar de Scout.

```php theme={null}
// Búsqueda de texto completo
$results = Article::search('MongoDB Laravel')->get();

// Búsqueda con filtros
$results = Article::search('query builder')
    ->where('status', 'published')
    ->paginate(15);
```

## Uso combinado con MySQL

En Laravel puedes usar MySQL y MongoDB a la vez. Indica la conexión con la propiedad `$connection` en cada modelo.

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

```php theme={null}
// Modelo Eloquent normal que usa MySQL
class User extends \Illuminate\Database\Eloquent\Model
{
    protected $connection = 'mysql';
}

// Modelo que usa MongoDB
class Article extends \MongoDB\Laravel\Eloquent\Model
{
    protected $connection = 'mongodb';
}
```

<Info>
  Si quieres definir relaciones entre modelos de MySQL y de MongoDB, consulta las [relaciones híbridas](https://www.mongodb.com/docs/drivers/php/laravel-mongodb/current/eloquent-models/relationships/).
</Info>

## Resumen

<AccordionGroup>
  <Accordion title="Lista de comprobación de instalación">
    1. Instala la extensión de PHP con `pecl install mongodb`
    2. Arranca el servidor MongoDB (local, Docker o Atlas)
    3. Instala el paquete con `composer require mongodb/laravel-mongodb`
    4. Configura `MONGODB_URI` y `MONGODB_DATABASE` en `.env`
    5. Añade la conexión `mongodb` en `config/database.php`
  </Accordion>

  <Accordion title="Cuándo usar MongoDB o MySQL">
    | Característica  | MongoDB                                            | MySQL                                     |
    | --------------- | -------------------------------------------------- | ----------------------------------------- |
    | Modelo de datos | Documento (JSON/BSON)                              | Tabla (filas y columnas)                  |
    | Esquema         | Sin esquema (flexible)                             | Esquema fijo                              |
    | Escalado        | Fácil escalado horizontal                          | Predominantemente vertical                |
    | Transacciones   | Multi-documento (v4+)                              | ACID completo                             |
    | Casos ideales   | Logs, analítica, IoT, datos de estructura flexible | Datos estructurados, relaciones complejas |
  </Accordion>

  <Accordion title="Uso por funcionalidad">
    | Funcionalidad              | Configuración                                                   |
    | -------------------------- | --------------------------------------------------------------- |
    | Modelo Eloquent            | Extender `MongoDB\Laravel\Eloquent\Model`                       |
    | Query builder              | `DB::connection('mongodb')->collection(...)`                    |
    | Caché                      | `config/cache.php` + `CACHE_STORE=mongodb`                      |
    | Colas                      | `config/queue.php` + `QUEUE_CONNECTION=mongodb`                 |
    | Almacenamiento de archivos | `config/filesystems.php` + adaptador GridFS                     |
    | Búsqueda vectorial         | `Model::query()->vectorSearch(...)` (Atlas obligatorio)         |
    | Búsqueda de texto          | `SCOUT_DRIVER=mongodb` + trait `Searchable` (Atlas obligatorio) |
  </Accordion>
</AccordionGroup>

## Próximos pasos

<CardGroup cols={2}>
  <Card title="Documentación oficial de laravel-mongodb" icon="book" href="https://www.mongodb.com/docs/drivers/php/laravel-mongodb/">
    Referencia detallada de todas las funciones: Eloquent, query builder, relaciones, etc.
  </Card>

  <Card title="Guía rápida" icon="rocket" href="https://www.mongodb.com/docs/drivers/php/laravel-mongodb/current/quick-start/">
    Aprende rápidamente el uso básico de MongoDB con Laravel
  </Card>

  <Card title="Configuración de base de datos" icon="database" href="/es/database">
    Bases de la configuración de conexiones a base de datos en Laravel
  </Card>

  <Card title="Introducción a Eloquent" icon="table" href="/es/eloquent">
    Uso básico del ORM Eloquent
  </Card>
</CardGroup>


## Related topics

- [Búsqueda](/es/search.md)