/ /

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, consulte Introducción al 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 se nombran en Pascal, pero los nombres de campo de la colección MongoDB usan CamelCase. Para compensar esta diferencia, puede usar el siguiente código para registrar un ConventionPack al iniciar la 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.
Pase la variable al método Project() después 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 matriz en los resultados de la consulta para que contenga únicamente el primer elemento que cumpla una condición especificada. Esto equivale a proyectar un elemento de matriz mediante el operador $elemMatch en la API de consultas 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 de la API de consultas 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 excluirlo de los documentos devueltos. Esto equivale a excluir un campo en la etapa de agregación $project de la API de consultas de MongoDB. No se pueden combinar declaraciones de inclusión y exclusión en una sola proyección a menos que se excluya 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 es cuando se usa el método Expression() para crear una proyección.

Incluir

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

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

Rebanada

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 omitir un número específico de elementos en una colección, pase el número de elementos a omitir como primer parámetro y el número de elementos a devolver como segundo parámetro. El siguiente ejemplo de código omite el primer elemento de la lista Cast y devuelve los tres elementos siguientes del array 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.

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, a continuación, páselo al método Search(). El siguiente ejemplo de código muestra este proceso proyectando los detalles de la puntuación de búsqueda de cada documento en un campo llamado 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 ver un ejemplo de código que utiliza el SearchMeta() método, consulte Cómo usar facetas con la búsqueda de MongoDB 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