/ /

Driver C#/.NET

Docs Home

Librerías de clientes

Driver C#/.NET

Docs Home

Librerías de clientes

Driver C#/.NET

Especifique los campos a devolver

Overview

En esta guía, se puede aprender cómo especificar qué campos devolver de una operación de lectura utilizando una proyección. Una proyección es un documento que especifica qué campos devuelve MongoDB de una query.

Datos de muestra

Los ejemplos en esta página usan el sample_mflix.movies colección de la Conjuntos de datos de muestra de Atlas. Para aprender a crear un clúster gratuito de MongoDB Atlas y cargar los conjuntos de datos de muestra, consulta el Comience con el controlador .NET/C#.

La siguiente clase representa los documentos en la colección sample_mflix.movies:

public class Movie
{
    public ObjectId Id { get; set; }
    public string Title { get; set; }
    public List<string> Genres { get; set; }
    public string Type { get; set; }
    public string Plot { get; set; }
    public List<BsonDocument> Highlights { get; set; }
    
    public string Score { get; set; }
    [BsonElement("scoreDetails")]
    public SearchScoreDetails ScoreDetails { get; set; }
    
    [BsonElement("searchScoreDetails")]
    public SearchScoreDetails SearchScoreDetails { get; set; } 
    
    [BsonElement("paginationToken")]
    public string PaginationToken { get; set; }
    
    public List<string> Cast { get; set; }
    
    [BsonElement("plot_embedding")]
    public float[] PlotEmbedding { get; set; }
}

Nota

ConventionPack para Pascal Case

Las propiedades de la clase anterior están nombradas en Pascal case, pero los nombres de campo en la colección de MongoDB utilizan camel case. Para tener en cuenta esta diferencia, puedes utilizar el siguiente código para registrar un ConventionPack cuando se inicie tu aplicación:

var camelCaseConvention = new ConventionPack { new CamelCaseElementNameConvention() };
ConventionRegistry.Register("CamelCase", camelCaseConvention, type => true);

Crear una Proyección

Para crear una proyección, realiza los siguientes pasos:

Utiliza la propiedad estática Builders<TDocument>.Projection para crear un objeto ProjectionDefinitionBuilder<TDocument>, donde TDocument representa la clase de C# a la que se asignan los documentos de la colección. La clase ProjectionDefinitionBuilder proporciona una interfaz segura en cuanto al tipo para definir una proyección.
Encadene métodos de proyección desde el objeto ProjectionDefinitionBuilder<TDocument> para especificar qué campos incluir o excluir de los documentos devueltos.
Almacene el objeto ProjectionDefinition<TDocument> resultante en una variable.
Pasa la variable al método Project() luego de realizar la operación de búsqueda o agregación.

Las siguientes secciones describen los métodos que puedes encadenar desde tu objeto ProjectionDefinitionBuilder<TDocument>.

Métodos de proyección de campos

Los siguientes métodos le permiten especificar qué campos incluir o excluir de los documentos devueltos.

ElemMatch

El método ElemMatch() limita el contenido de un campo de arreglo en los resultados de la query para contener solo el primer elemento que cumpla una condición especificada. Esto equivale a proyectar un elemento de arreglo utilizando el operador $elemMatch en la API de query de MongoDB.

Para ver un ejemplo de código que use el método ElemMatch(), consulta $elemMatch en el manual de MongoDB Server.

expresión

El método Expression() permite especificar la estructura de los documentos devueltos mediante una expresión lambda. Esto equivale a especificar la estructura de los documentos devueltos en la etapa de agregación $project en la API de query de MongoDB.

Para obtener un ejemplo de código que use el método 'Expression()', consulta $project en el manual de MongoDB Server.

Nota

Exclusión de campo ID

Cuando utilizas una expresión lambda para crear una proyección, la salida excluye automáticamente el campo Id, a menos que lo incluyas explícitamente.

Exclude

El método Exclude() permite especificar un campo para excluir de los documentos devueltos. Esto equivale a excluir un campo en la etapa de agregación $project en la API de Query de MongoDB. No puede combinar instrucciones de inclusión y exclusión en una única proyección a menos que esté excluyendo el campo _id.

Para obtener un ejemplo de código que use el método 'Exclude()', consulta $project en el manual de MongoDB Server.

Nota

Excluir explícitamente el campo _id

Los documentos devueltos incluyen el campo _id a menos que lo excluya explícitamente. La única excepción a esto es cuando se utiliza el método Expression() para crear una proyección.

Incluir

El método Include() le permite especificar un campo para incluirlo en los documentos devueltos. Esto es equivalente a incluir un campo en la etapa de agregación $project en la API de query de MongoDB.

Para obtener un ejemplo de código que use el método 'Include()', consulta $project en el manual de MongoDB Server.

Porción

El método Slice() especifica el número de elementos de una lista o arreglo que se deben devolver en el campo de resultados de la query. Esto equivale a usar el operador $slice en la API de query de MongoDB.

El siguiente ejemplo de código utiliza el método Slice() para devolver los tres primeros elementos de la lista Cast en el arreglo cast del documento devuelto:

var filter = Builders<Movie>.Filter.Text("future");
var projection = Builders<Movie>
    .Projection
    .Slice(m => m.Cast, 3)
    .Include(m => m.Cast);
var results = movieCollection.Find(filter)
    .Project(projection)
    .Limit(1)
    .ToList();

{
  "_id": {
    "$oid": "573a1398f29313caabceb500"
  },
  "title": "Back to the Future Part II",
  "cast": [
    "Michael J. Fox",
    "Christopher Lloyd",
    "Lea Thompson"
  ]
}

Para devolver elementos desde el final de una colección, pasa un número entero negativo al método Slice(). El siguiente ejemplo de código devuelve los últimos tres elementos de la lista Cast en el arreglo cast del documento devuelto:

var filter = Builders<Movie>.Filter.Text("future");
var projection = Builders<Movie>
    .Projection
    .Slice(m => m.Cast, -3)
    .Include(m => m.Title);
var results = movieCollection.Find(filter)
    .Project(projection)
    .Limit(1)
    .ToList();

{
  "_id": {
    "$oid": "573a1398f29313caabceb500"
  },
  "title": "Back to the Future Part II",
  "cast": [
    "Lea Thompson",
    "Thomas F. Wilson"
  ]
}

Para saltar un número especificado de elementos en una colección, pasa el número de elementos a saltar como el primer parámetro y el número de elementos a retornar como el segundo parámetro. El siguiente ejemplo de código salta el primer elemento en la lista Cast y devuelve los siguientes tres elementos en el arreglo cast:

var filter = Builders<Movie>.Filter.Text("future");
var projection = Builders<Movie>
    .Projection
    .Slice(m => m.Cast, 1, 3) 
    .Include(m => m.Title);
var results = movieCollection.Find(filter)
    .Project(projection)
    .Limit(1)
    .ToList();

{
  "_id": {
    "$oid": "573a1398f29313caabceb500"
  },
  "title": "Back to the Future Part II",
  "cast": [
    "Christopher Lloyd",
    "Lea Thompson",
    "Thomas F. Wilson"
  ]
}

Para obtener más información sobre el operador $slice, consulta $slice en el manual del servidor de MongoDB Server.

Métodos de proyección de metadatos

Los siguientes métodos te permiten especificar qué campos de metadatos incluir o excluir de los documentos devueltos. Los campos de metadatos están ocultos por defecto.

MetaScore

El método MetaScore() incluye un valor numérico de puntaje en los documentos devueltos. Esto equivale a proyectar metadatos de puntuación utilizando un objeto { "$meta": "score" } en la API de query de MongoDB. El driver selecciona automáticamente los metadatos de puntuación subyacente apropiados (searchScore, vectorSearchScore o textScore) según el tipo de búsqueda que se realice. Se especifica el nombre del campo de salida pasando una expresión de propiedad al método.

El siguiente ejemplo de código proyecta el puntaje de cada documento como un valor numérico en una propiedad llamada Score:

var filter = Builders<Movie>.Search.Text(m => m.Title, "future");
var projection = Builders<Movie>.Projection
    .Include(m => m.Title)
    .Include(m => m.Plot)
    .MetaScore(m => m.Score);
var result = moviesCollection.Aggregate()
    .Search(filter)
    .Project<Movie>(projection)
    .Limit(1)
    .ToList();

[{
  "title" : "Bright Future",
  "plot" : "...",
  "score" : "..."
}]

MetaScoreDetails

El método MetaScoreDetails() incluye cualquier metadato disponible de detalles de puntuación en los documentos devueltos. Esto es equivalente a proyectar los metadatos de detalles de puntuación usando un objeto { "$meta": "scoreDetails" } en la API de MongoDB Query. Para recuperar los detalles de la puntuación, debes establecer ScoreDetails en true en un objeto SearchOptions y pasarlo al método Search().

El siguiente ejemplo de código proyecta los detalles de la puntuación de cada documento en una propiedad denominada ScoreDetails:

var filter = Builders<Movie>.Search.Text(m => m.Plot, "future");
var projection = Builders<Movie>.Projection
    .Include(m => m.Title)
    .Include(m => m.Plot)
    .MetaScoreDetails(m => m.ScoreDetails);
var result = moviesCollection.Aggregate()
    .Search(filter, new SearchOptions<Movie> { ScoreDetails = true })
    .Project<Movie>(projection)
    .Limit(1)
    .ToList();

[{
  "title" : "West",
  "plot" : "She Can See Her Future, But Can't Escape Her Past.",
  "scoreDetails" : {
    "value" : "...",
    "description" : "...",
    "details" : "..."
  }
}]

MetaSearchHighlights

Nota

MongoDB Search Only

Este método solo está disponible al proyectar los resultados de una MongoDB Search.

El MetaSearchHighlights() incluye destacados de búsqueda en los documentos devueltos. Esto equivale a proyectar los destacados de búsqueda utilizando un objeto { "$meta": "searchHighlights" } en la API de query de MongoDB. Para recuperar los aspectos destacados de la búsqueda, se debe crear un objeto SearchHighlightOptions que especifique el campo de búsqueda y luego pasar este objeto al método Search().

El siguiente ejemplo de código recupera los puntos destacados de búsqueda para el campo plot, y luego incluye estos puntos destacados en una propiedad llamada Highlights en los documentos devueltos:

var filter = Builders<Movie>.Search.Text(path: m => m.Plot, query: "future");
var projection = Builders<Movie>.Projection
    .Include(m => m.Title)
    .Include(m => m.Plot)
    .MetaSearchHighlights(m => m.Highlights);
var results = movieCollection
    .Aggregate()
    .Search(filter, new SearchHighlightOptions<Movie> (m => m.Plot))
    .Project(projection)
    .Limit(1)
    .ToList();

{
  "_id": {
    "$oid": "573a13def29313caabdb5661"
  },
  "plot": "She Can See Her Future, But Can't Escape Her Past.",
  "title": "West",
  "highlights": [
    {
      "score": 1.286744475364685,
      "path": "plot",
      "texts": [
        {
          "value": "She Can See Her ",
          "type": "text"
        },
        {
          "value": "Future",
          "type": "hit"
        },
        {
          "value": ", But Can't Escape Her Past.",
          "type": "text"
        }
      ]
    }
  ]
}

Para obtener más información sobre los destacados de la búsqueda, consulta Resaltar términos de búsqueda en los resultados en la documentación de Atlas.

MetaSearchScore

Nota

MongoDB Search Only

Este método solo está disponible al proyectar los resultados de una MongoDB Search.

El método MetaSearchScore() incluye las puntuaciones de búsqueda en los documentos devueltos. Esto equivale a proyectar puntuaciones de búsqueda utilizando un objeto { "$meta": "searchScore" } en la API de query de MongoDB.

El siguiente ejemplo de código proyecta la puntuación de búsqueda de cada documento en un campo denominado score:

var filter = Builders<Movie>.Search.Text(m => m.Plot, "future");
var projection = Builders<Movie>.Projection
    .Include(m => m.Title)
    .Include(m => m.Plot)
    .MetaSearchScore(m => m.Score);
var results = movieCollection
    .Aggregate()
    .Search(filter) 
    .Project(projection)
    .Limit(1)
    .ToList();

{
  "_id": {
    "$oid": "573a13def29313caabdb5661"
  },
  "plot": "She Can See Her Future, But Can't Escape Her Past.",
  "title": "West",
  "score": 2.8259084224700928
}

Para aprender más sobre las puntuaciones de búsqueda, vea Puntúe los Documentos en los Resultados.

Detalles de la puntuación de MetaSearch

Nota

MongoDB Search Only

Este método solo está disponible al proyectar los resultados de una MongoDB Search.

El MetaSearchScoreDetails() incluye detalles sobre las puntuaciones de búsqueda en los documentos devueltos. Esto equivale a proyectar los detalles de la puntuación de búsqueda usando un objeto { "$meta": "searchScoreDetails" } en la API de query de MongoDB.

Para recuperar los detalles de la puntuación, cree un objeto SearchOptions con su propiedad ScoreDetails establecida en true, y luego pase este objeto al método Search(). El siguiente ejemplo de código muestra este proceso al proyectar los detalles de puntuación de búsqueda de cada documento en un campo denominado searchScoreDetails:

var filter = Builders<Movie>.Search.Text(m => m.Plot, "future");
var projection = Builders<Movie>.Projection
    .Include(m => m.Title)
    .Include(m => m.Plot)
    .MetaSearchScore(m => m.Score)
    .MetaSearchScoreDetails(m => m.SearchScoreDetails);
var results = movieCollection
    .Aggregate()
    .Search(filter, new SearchOptions<Movie>() { ScoreDetails = true}) 
    .Project(projection)
    .Limit(1)
    .ToList();

{
  "_id": {
    "$oid": "573a13def29313caabdb5661"
  },
  ...
  "scoreDetails": {
    "value": 2.8259084224700928,
    "description": "$type:string/plot:future [BM25Similarity], result of:",
    "details": [
      {
        "value": 2.8259084224700928,
        "description": "score(freq=1.0), computed as boost * idf * tf from:",
        "details": [
         ...
}

Para obtener más información sobre los detalles del puntaje de búsqueda, consulta Devolver los detalles del puntaje en la documentación de Atlas.

MetaSearchSequenceToken

Nota

MongoDB Search Only

Este método solo está disponible al proyectar los resultados de una MongoDB Search.

El método MetaSearchSequenceToken() incluye un token en los documentos devueltos que representa un punto en la secuencia de búsqueda. Esto equivale a proyectar el token de secuencia de búsqueda mediante un objeto { "$meta": "searchSequenceToken" } en la API de query de MongoDB. Puedes usar este token para realizar búsquedas adicionales antes o después del punto especificado.

El siguiente ejemplo de código proyecta el token de secuencia de búsqueda de cada documento en una propiedad denominada PaginationToken:

var filter = Builders<Movie>.Search.Text(m => m.Plot, "future");
var projection = Builders<Movie>.Projection
    .Include(m => m.Title)
    .Include(m => m.Plot)
    .MetaSearchSequenceToken(m => m.PaginationToken);
var results = movieCollection
    .Aggregate()
    .Search(filter)
    .Limit(1)
    .Project(projection)
    .ToList();

{
  "_id": {
    "$oid": "573a13def29313caabdb5661"
  },
  "plot": "She Can See Her Future, But Can't Escape Her Past.",
  "title": "West",
  "paginationToken": "CIeaARWv2zRAIg5aDFc6E97ykxPKq9tWYQ=="
}

Para aprender más sobre los tokens de secuencia de búsqueda, consulte Paginación de resultados de búsqueda

MetaTextScore

El método MetaTextScore() incluye los puntajes de búsqueda $text en los documentos devueltos. Esto es equivalente a proyectar la puntuación de búsqueda de texto utilizando un objeto { "$meta": "textScore" } en la API de query de MongoDB.

Para un ejemplo de código que use el método MetaTextScore(), consulte $meta en el manual del servidor de MongoDB.

MetaVectorSearchScore

Nota

MongoDB Vector Search Only

Este método solo está disponible cuando se proyectan los resultados de una MongoDB Vector Search.

El método MetaVectorSearchScore() incluye las puntuaciones de MongoDB Vector Search en los documentos devueltos. Esto es equivalente a proyectar el puntaje de la Búsqueda Vectorial utilizando un objeto { "$meta": "vectorSearchScore" } en la API de query de MongoDB.

Para un ejemplo de código que utilice el método MetaVectorSearchScore(), consulta MongoDB Vector Search.

Para aprender más sobre las puntuaciones de MongoDB Vector Search, consulta Calificación de los documentos en los Resultados en la documentación de Atlas.

SearchMeta

Nota

MongoDB Search Only

Este método solo está disponible al proyectar los resultados de una MongoDB Search.

El método SearchMeta() incluye un documento de resultados de metadatos. La estructura de este documento depende del tipo de resultado. Esto equivale a proyectar el documento de resultados de metadatos usando la etapa de agregación $searchMeta o la variable de agregación $$SEARCH_META en la API de query de MongoDB.

Para obtener un ejemplo de código que use el método SearchMeta(), consulta Cómo utilizar facetas con MongoDB Search en la documentación de Atlas.

Para obtener más información sobre $searchMeta y $$SEARCH_META, consulta la siguiente documentación de Atlas:

Documentación de la API

Para aprender más sobre cualquiera de los métodos o tipos analizados en esta guía, consulta la siguiente documentación de API:

Volver

Especifica los documentos a devolver

Contabilizar documentos