Para agentes de IA: hay un índice de documentación disponible en https://www.mongodb.com/es/docs/llms.txt — versiones en markdown de todas las páginas están disponibles agregando .md a cualquier ruta URL.

$project (etapa de agregación)

$project

Pasa los documentos con los campos solicitados a la siguiente etapa en el pipeline. Los campos especificados pueden ser campos existentes de los documentos de entrada o campos recién calculados.

$project poder:

  • Incluir campos de los documentos de entrada.

  • Suprimir el campo _id.

  • Añadir nuevos campos o restablecer los valores de los campos existentes.

  • Excluir campos de los documentos de entrada.

Puedes usar $project para implementaciones alojadas en los siguientes entornos:

  • MongoDB Atlas: El servicio totalmente gestionado para implementaciones de MongoDB en la nube
  • MongoDB Enterprise: La versión basada en suscripción y autogestionada de MongoDB

  • MongoDB Community: La versión de MongoDB con código fuente disponible, de uso gratuito y autogestionada.

$project tiene la siguiente forma:

{ $project: { <specification(s)> } }

Las especificaciones $project tienen las siguientes formas:

formulario
Descripción

<field>: <1 or true>

Especifica la inclusión de un campo. Los enteros no nulos también se tratan como true.

_id: <0 or false>

Especifica la eliminación del campo _id.

Para excluir un campo de forma condicional, utiliza la variable REMOVE en su lugar. Para obtener más información, consulta Excluye campos de forma condicional.

<field>: <expression>

Añade un nuevo campo o restablece el valor de un campo existente.

Si la expresión se evalúa como $$REMOVE, el campo se excluye en la salida. Para obtener más información, se puede consultar Excluir campos de forma condicional.

<field>: <0 or false>

Especifica la exclusión de un campo.

Para excluir un campo de forma condicional, utiliza la variable REMOVE en su lugar. Para obtener más información, consulta Excluye campos de forma condicional.

Si especificas la exclusión de un campo distinto de _id, no podrás utilizar ninguna otra especificación $project. Esta restricción no se aplica a la exclusión condicional de un campo usando la variable REMOVE.

Para excluir campos, también puedes utilizar la etapa $unset.

  • Por defecto, los documentos de salida incluyen el campo _id. Para incluir otros campos de los documentos de entrada, especifíquelos explícitamente en $project.

  • Si especificas la inclusión de un campo que no existe en el documento, $project ignora esa inclusión y no añade el campo al documento.

Por defecto, el campo _id se incluye en los documentos de salida. Para excluir el campo _id de los documentos de salida, debe suprimir explícitamente el campo _id en $project.

Si se excluye un campo, todos los demás campos aparecen en los documentos de salida.

{ $project: { "<field1>": 0, "<field2>": 0, ... } } // Return all but the specified fields

Si excluyes un campo distinto de _id, no podrás utilizar otras formas de especificación $project. Si excluyes campos, no puedes especificar la inclusión de campos, restablecer el valor de campos existentes o agregar campos nuevos. Esta restricción no se aplica a la exclusión condicional de un campo usando la variable REMOVE.

Para excluir campos, también puede usar $unset.

Puedes usar la variable REMOVE en expresiones de agregación para suprimir condicionalmente un campo. Para un ejemplo, ve Excluir campos condicionalmente.

Nota

MongoDB también proporciona $addFields para añadir nuevos campos a los documentos.

Para agregar un nuevo campo o restablecer el valor de un campo existente, especifique el nombre del campo y establezca su valor en una expresión. Para obtener más información sobre las expresiones, consulte Expresiones.

Para establecer un campo en un literal numérico o booleano en lugar de una expresión que se resuelva en un literal, utilice el operador $literal. De lo contrario, $project trata el literal como un indicador para incluir o excluir el campo.

Al especificar un nuevo campo y establecer el valor en la ruta de campo de un campo existente, se puede renombrar un campo de manera efectiva.

La etapa $project admite el uso de los corchetes [] para crear directamente nuevos campos de arreglo. Si especificas campos de arreglo que no existen en un documento, la operación sustituye null como valor de ese campo. Para ver un ejemplo, consulta Proyecto nuevos campos de arreglo.

No puedes utilizar un índice de arreglo con la etapa $project.

Para Proyecto, añadir/restablecer un campo dentro de un documento incrustado, puede utilizar notación de puntos:

"contact.address.country": <1 or 0 or expression>

También puede anidar los campos:

contact: { address: { country: <1 or 0 or expression> } }

Cuando anidas campos, no puedes utilizar la notación de puntos dentro del documento incrustado para especificar el campo. Por ejemplo, contact: { "address.country": <1 or 0 or expression> } es inválido.

No puede especificar tanto un documento incrustado como un campo dentro de ese documento incrustado en la misma proyección.

La siguiente etapa $project falla con un error Path collision porque intenta proyectar tanto el documento incrustado contact como el campo contact.address.country:

{ $project: { contact: 1, "contact.address.country": 1 } }

El error ocurre independientemente del orden en que se especifiquen el campo principal y el campo incrustado. El siguiente $project falla con el mismo error:

{ $project: { "contact.address.country": 1, contact: 1 } }

Cuando se usa una etapa $project, normalmente debería ser la última etapa del pipeline, utilizada para especificar qué campos devolver al cliente.

Usar una etapa $project al principio o en medio de un pipeline para reducir el número de campos que se pasan a las etapas posteriores del pipeline es poco probable que mejore el rendimiento, ya que la base de datos realiza esta optimización automáticamente.

MongoDB devuelve un error si a la etapa $project se le pasa un documento vacío.

Por ejemplo, la siguiente pipeline devuelve un error:

db.myCollection.aggregate( [ { $project: { }} ] )

No puedes utilizar un índice de arreglo con la etapa $project.

Los ejemplos de esta página utilizan datos del conjunto de datos sample_mflix. Para obtener más información sobre cómo cargar este conjunto de datos en la implementación autogestionada de MongoDB, consultar Cargar el conjunto de datos de muestra. Si realizó alguna modificación en las bases de datos de muestra, es posible que deba descartar y volver a crear las bases de datos para ejecutar los ejemplos de esta página.

La siguiente etapa $project incluye solo los campos _id, title y rated:

db.movies.aggregate( [ { $match: { title: "The Great Train Robbery" } }, { $project: { title: 1, rated: 1 } }, { $limit: 1 }] )
[ { _id: ObjectId('573a1390f29313caabcd42e8'), title: 'The Great Train Robbery', rated: 'TV-G' }]

MongoDB incluye el campo _id por defecto. Para excluir el campo _id de la etapa $project, configure el campo _id en 0 en el documento de proyección.

La siguiente etapa $project excluye el campo _id pero incluye los campos title y rated:

db.movies.aggregate( [ { $match: { title: "The Great Train Robbery" } }, { $project : { _id: 0, title : 1, rated : 1 } }, { $limit: 1 }] )
[ { title: 'The Great Train Robbery', rated: 'TV-G' } ]

La siguiente etapa $project excluye el campo rated de la salida:

db.movies.aggregate( [ { $match: { title: "The Great Train Robbery" } }, { $project : { "rated": 0 } }, { $limit: 1 }] )

De manera alternativa, utiliza la etapa $unset para excluir campos.

La siguiente etapa $project excluye los campos imdb.id y type de la salida:

db.movies.aggregate( [ { $match: { title: "The Great Train Robbery" } }, { $project: { "imdb.id": 0, "type": 0 } }, { $limit: 1 }] )
[ { _id: ObjectId('573a1390f29313caabcd42e8'), plot: 'A group of bandits stage a brazen train hold-up, only to find a determined posse hot on their heels.', genres: [ 'Short', 'Western' ], runtime: 11, cast: [ 'A.C. Abadie', "Gilbert M. 'Broncho Billy' Anderson", 'George Barnes', 'Justus D. Barnes' ], poster: 'https://m.media-amazon.com/images/M/MV5BMTU3NjE5NzYtYTYyNS00MDVmLWIwYjgtMmYwYWIxZDYyNzU2XkEyXkFqcGdeQXVyNzQzNzQxNzI@._V1_SY1000_SX677_AL_.jpg', title: 'The Great Train Robbery', fullplot: "Among the earliest existing films in American cinema - notable as the first film that presented a narrative story to tell - it depicts a group of cowboy outlaws who hold up a train and rob the passengers. They are then pursued by a Sheriff's posse. Several scenes have color included - all hand tinted.", languages: [ 'English' ], released: ISODate('1903-12-01T00:00:00.000Z'), directors: [ 'Edwin S. Porter' ], rated: 'TV-G', awards: { wins: 1, nominations: 0, text: '1 win.' }, lastupdated: '2015-08-13 00:27:59.177000000', year: 1903, imdb: { rating: 7.4, votes: 9847 }, countries: [ 'USA' ], tomatoes: { viewer: { rating: 3.7, numReviews: 2559, meter: 75 }, fresh: 6, critic: { rating: 7.6, numReviews: 6, meter: 100 }, rotten: 0, lastUpdated: ISODate('2015-08-08T19:16:10.000Z') }, num_mflix_comments: 0 }]

Alternativamente, se puede anidar la especificación de exclusión en un documento:

db.movies.aggregate( [ { $match: { title: "The Great Train Robbery" } }, { $project: { "imdb": { "id": 0 }, "type" : 0 } }, { $limit: 1 }] )
[ { _id: ObjectId('573a1390f29313caabcd42e8'), plot: 'A group of bandits stage a brazen train hold-up, only to find a determined posse hot on their heels.', genres: [ 'Short', 'Western' ], runtime: 11, cast: [ 'A.C. Abadie', "Gilbert M. 'Broncho Billy' Anderson", 'George Barnes', 'Justus D. Barnes' ], poster: 'https://m.media-amazon.com/images/M/MV5BMTU3NjE5NzYtYTYyNS00MDVmLWIwYjgtMmYwYWIxZDYyNzU2XkEyXkFqcGdeQXVyNzQzNzQxNzI@._V1_SY1000_SX677_AL_.jpg', title: 'The Great Train Robbery', fullplot: "Among the earliest existing films in American cinema - notable as the first film that presented a narrative story to tell - it depicts a group of cowboy outlaws who hold up a train and rob the passengers. They are then pursued by a Sheriff's posse. Several scenes have color included - all hand tinted.", languages: [ 'English' ], released: ISODate('1903-12-01T00:00:00.000Z'), directors: [ 'Edwin S. Porter' ], rated: 'TV-G', awards: { wins: 1, nominations: 0, text: '1 win.' }, lastupdated: '2015-08-13 00:27:59.177000000', year: 1903, imdb: { rating: 7.4, votes: 9847 }, countries: [ 'USA' ], tomatoes: { viewer: { rating: 3.7, numReviews: 2559, meter: 75 }, fresh: 6, critic: { rating: 7.6, numReviews: 6, meter: 100 }, rotten: 0, lastUpdated: ISODate('2015-08-08T19:16:10.000Z') }, num_mflix_comments: 0 }]

De manera alternativa, utiliza la etapa $unset para excluir campos.

Puedes usar la variable REMOVE en expresiones de agregación para suprimir condicionalmente un campo.

La siguiente $project etapa utiliza la variable REMOVE para excluir el campo imdb.votes si es igual a null o es una string vacía:

db.movies.aggregate( [ { $match: { title: "This Is Spinal Tap" } }, { $project: { title: 1, "imdb.rating": 1, "imdb.id": 1, "imdb.votes": { $cond: { if: { $in: [ "$imdb.votes", [ null, "" ] ] }, then: "$$REMOVE", else: "$imdb.votes" } } } }, { $limit: 1 }] )
[ { _id: ObjectId('573a1398f29313caabce94a3'), title: 'This Is Spinal Tap', imdb: { rating: 8, id: 88258 } }]

Como imdb.votes es una string vacía para este document, MongoDB excluye el campo de la salida.

Tip

Comparación con $addFields

Puedes usar la plataforma $addFields o $project para remover campos de documentos. El mejor enfoque depende de su pipeline y de cuánto del documento original desea conservar.

Para ver un ejemplo de uso de $$REMOVE en una etapa $addFields, consulte Remover campos.

Los documentos en la colección movies contienen un document imdb incrustado con los campos rating, votes y id. Para incluir únicamente el campo rating del document imdb, utiliza la notación de punto:

db.movies.aggregate( [ { $match: { title: "The Great Train Robbery" } }, { $project: { "imdb.rating": 1 } }, { $limit: 1 }] )
[ { _id: ObjectId('573a1390f29313caabcd42e8'), imdb: { rating: 7.4 } }]

O bien, anide la especificación de inclusión en un document:

db.movies.aggregate( [ { $match: { title: "The Great Train Robbery" } }, { $project: { imdb: { rating: 1 } } }, { $limit: 1 }] )
[ { _id: ObjectId('573a1390f29313caabcd42e8'), imdb: { rating: 7.4 } }]

La siguiente etapa $project agrega los campos leadActor y releaseYear:

db.movies.aggregate( [ { $match: { title: "The Great Train Robbery" } }, { $project: { title: 1, leadActor: { $arrayElemAt: [ "$cast", 0 ] }, releaseYear: "$year" } }, { $limit: 1 }] )
[ { _id: ObjectId('573a1390f29313caabcd42e8'), title: 'The Great Train Robbery', leadActor: 'A.C. Abadie', releaseYear: 1903 }]

La siguiente operación proyecta los campos year y runtime como elementos en un nuevo campo myArray:

db.movies.aggregate( [ { $match: { title: "The Great Train Robbery" } }, { $project: { myArray: [ "$year", "$runtime" ] } }, { $limit: 1 }] )
[ { _id: ObjectId('573a1390f29313caabcd42e8'), myArray: [ 1903, 11 ] }]

Si la especificación del arreglo incluye campos que no existen en un documento, la operación sustituye null por el valor de ese campo.

Por ejemplo, con el mismo documento que antes, la siguiente operación proyecta los campos year, runtime y un campo inexistente $someField como elementos en un nuevo campo myArray:

db.movies.aggregate( [ { $match: { title: "The Great Train Robbery" } }, { $project: { myArray: [ "$year", "$runtime", "$someField" ] } }, { $limit: 1 }] )
[ { _id: ObjectId('573a1390f29313caabcd42e8'), myArray: [ 1903, 11, null ] }]

Para obtener más información sobre las tareas comunes de agregación, consulte Tutoriales completos de la pipeline de agregación.

Para aprender más sobre las expresiones y variables de esta página, consulta: