/ /

$meta (operador de expressão )

Definição

$meta

Retorna os metadados associados a um documento, por exemplo, "textScore" ao executar pesquisa de texto.

Uma expressão $meta tem a seguinte sintaxe:

{ $meta: <metaDataKeyword> }

A expressão $meta pode especificar os seguintes valores como <metaDataKeyword>:

Keyword	Descrição
`"textScore"`	Retorna a pontuação associada à query `$text` correspondente a cada documento correspondente. A pontuação de texto indica quão bem o documento correspondeu ao termo ou termos de pesquisa. `{ $meta: "textScore" }` deve ser usado em conjunto com uma query `$text`. Em versões anteriores, se não usado em conjunto com uma consulta `$text`, retornará uma pontuação nula. `$text` fornece recursos de query de texto para implantações autogerenciadas (não Atlas). Para dados hospedados no MongoDB Atlas, o MongoDB oferece uma solução aprimorada de query de texto completo, Atlas Search.
`"indexKey"`	Retorna uma chave de índice para o documento se um índice não texto for usado. A expressão `{ $meta: "indexKey" }` é somente para fins de depuração e não para lógica de aplicativo, e é preferida em comparação com `cursor.returnKey()`.

Keyword

Descrição

"textScore"

Retorna a pontuação associada à query $text correspondente a cada documento correspondente. A pontuação de texto indica quão bem o documento correspondeu ao termo ou termos de pesquisa.

{ $meta: "textScore" } deve ser usado em conjunto com uma query $text.

Em versões anteriores, se não usado em conjunto com uma consulta $text, retornará uma pontuação nula.

$text fornece recursos de query de texto para implantações autogerenciadas (não Atlas). Para dados hospedados no MongoDB Atlas, o MongoDB oferece uma solução aprimorada de query de texto completo, Atlas Search.

"indexKey"

Retorna uma chave de índice para o documento se um índice não texto for usado. A expressão { $meta: "indexKey" } é somente para fins de depuração e não para lógica de aplicativo, e é preferida em comparação com cursor.returnKey().

O MongoDB Atlas Search fornece palavras-chave $meta adicionais, como:

Consulte a documentação do Atlas Search para obter detalhes.

Importante

As seguintes palavras-chave $meta não são aceitas na API Estável V1:

"textScore"
"indexKey"
"searchScore"
"searchHighlights"
"searchSequenceToken"
"searchScoreDetails"

Comportamento

Metadados de pontuação de texto `$meta: "textScore"`

Requer pesquisa $text

A expressão { $meta: "textScore" } deve ser usada em conjunto com $text. Por exemplo:
- Na agregação, você deve especificar um estágio $match com uma query $text no pipeline para usar a expressão { $meta: "textScore" } nos estágios posteriores. Se você não especificar a query $text no estágio $match, a operação falhará.
- No achado, você deve especificar o operador $text no predicado de query para usar { $meta: "textScore" }. Se você não especificar o operador $text no predicado da consulta, a operação falhará.
Observação
$text fornece recursos de query de texto para implantações autogerenciadas (não Atlas). Para dados hospedados no MongoDB Atlas, o MongoDB oferece uma solução aprimorada de query de texto completo, Atlas Search.

Disponibilidade

Na aggregation, a expressão { $meta: "textScore" } pode ser incluída em vários estágios que aceitam expressões de aggregation, como $project, $group $sort etc.
No achado, a expressão { $meta: "textScore" } pode ser incluída na projeção e em sort().

Uso na projeção

A expressão { $meta: "textScore" } pode fazer parte do documento de projeção para incluir os metadados de pontuação de texto.
A expressão $meta pode estar presente em uma inclusão ou uma projeção de exclusão.
Se você definir a expressão para um nome de campo que já existe no documento, o valor de metadados projetado substituirá o valor existente.

Filtre na pontuação de texto

Na agregação, após um estágio que gera um campo com o valor da pontuação de texto, você poderá especificar uma condição de query ou operar no campo em estágios subsequentes. Por exemplo, consulte $text no Pipeline de agregação em implantações autogerenciadas.
No achado, você não pode especificar uma condição de query na pontuação de texto. Em vez disso, use aggregation.

Uso na classificação

A expressão { $meta: "textScore" } pode ser usada como parte de uma operação de classificação para classificar por metadados da pontuação de texto; ou seja,
- Na aggregation, $sort estágio.
- No achado, método sort().
Os metadados "textScore" são classificados em ordem decrescente.
Para usar em uma operação de classificação, defina a expressão { $meta: "textScore" } como um nome de campo arbitrário. O nome do campo é desconsiderado pelo sistema de query.

Classificar sem projeção

Na aggregation, você pode classificar os documentos resultantes por { $meta: "textScore" } sem também ter que projetar o textScore.
Na operação find, você pode ordenar os documentos resultantes por { $meta: "textScore" } sem precisar projetar também o textScore.

Classificar com projeção

Na agregação, se você incluir a expressão { $meta: "textScore" } tanto na projeção quanto na classificação, a projeção e a classificação poderão ter nomes de campo diferentes para a expressão. O nome do campo na classificação é desconsiderado pelo sistema de query.
No achado, se você incluir a expressão { $meta: "textScore" } tanto na projeção quanto na classificação, a projeção e a classificação poderão ter nomes de campo diferentes para a expressão. O nome do campo na classificação é desconsiderado pelo sistema de query.

Metadados da chave do índice $meta: "indexKey" (aggregation e localizar)

Uso

A expressão { $meta: "indexKey" } serve apenas para fins de depuração e não para lógica de aplicativo.
A expressão { $meta: "indexKey" } é preferível a cursor.returnKey().

Disponibilidade

No aggregation, a expressão { $meta: "indexKey" } pode ser incluída em vários estágios que aceitam expressões de aggregation, como $project, $group $sortByCount etc., mas não $sort. No entanto, com um aggregation pipeline, você pode primeiro projetar a expressão { $meta: "indexKey" } (como em um $project, $addFields etc.) e, em seguida, classificar por esse campo em um estágio $sort subsequente.
No achado, a expressão { $meta: "indexKey" } só está disponível como parte do documento de projeção .

Valor de retorno

O valor retornado depende de como o banco de dados decide representar valores em um índice e pode mudar entre versões. O valor representado pode não ser o valor real do campo.
O valor retornado depende do plano de execução escolhido pelo sistema. Por exemplo, se houver dois índices possíveis que podem ser usados para responder à query, o valor dos metadados "indexKey" dependerá de qual índice for selecionado.
Se um índice não for utilizado, a expressão { $meta: "indexKey" } não retornará um valor e o campo não será incluído como parte da saída.

Exemplos

`$meta: "textScore"`

Cria uma collection articles com os seguintes documentos:

db.articles.insertMany([
   { "_id" : 1, "title" : "cakes and ale" },
   { "_id" : 2, "title" : "more cakes" },
   { "_id" : 3, "title" : "bread" },
   { "_id" : 4, "title" : "some cakes" },
   { "_id" : 5, "title" : "two cakes to go" },
   { "_id" : 6, "title" : "pie" }
])

Crie um índice de texto no campo title:

db.articles.createIndex( { title: "text"} )

A seguinte operação de agregação executa uma pesquisa de texto e utiliza o operador $meta para agrupar pela pontuação de texto da pesquisa:

db.articles.aggregate(
   [
     { $match: { $text: { $search: "cake" } } },
     { $group: { _id: { $meta: "textScore" }, count: { $sum: 1 } } }
   ]
)

A operação retorna os seguintes resultados:

{ "_id" : 0.75, "count" : 1 }
{ "_id" : 0.6666666666666666, "count" : 1 }
{ "_id" : 1, "count" : 2 }

Para mais exemplos, consulte $text no pipeline de agregação em implantações autogerenciadas.

A query a seguir executa uma pesquisa de texto para o termo cake e usa o operador $meta no documento de projeção para incluir a pontuação atribuída a cada documento correspondente:

db.articles.find(
   { $text: { $search: "cake" } },
   { score: { $meta: "textScore" } }
)

A operação retorna os seguintes documentos com a pontuação do texto:

{ "_id" : 4, "title" : "some cakes", "score" : 1 }
{ "_id" : 1, "title" : "cakes and ale", "score" : 0.75 }
{ "_id" : 5, "title" : "two cakes to go", "score" : 0.6666666666666666 }
{ "_id" : 2, "title" : "more cakes", "score" : 1 }

Para obter exemplos adicionais de projeções e classificações "textScore", consulte Exemplos de pontuação de relevância.

`$meta: "indexKey"`

Observação

A expressão { $meta: "indexKey" } serve apenas para fins de depuração e não para lógica de aplicativo. O MongoDB retorna o valor associado ao índice escolhido pelo sistema de query. Ele pode escolher um índice diferente após a execução subsequente.

Para o índice selecionado, o valor retornado depende de como o banco de dados decide representar valores em um índice e pode mudar entre versões. O valor representado pode não ser o valor real do campo.

Cria uma collection orders com os seguintes documentos:

db.orders.insertMany([
   { "item" : "abc", "price" : Decimal128("12"), "quantity" : 2, "type": "apparel" },
   { "item" : "jkl", "price" : Decimal128("20"), "quantity" : 1, "type": "electronics" },
   { "item" : "abc", "price" : Decimal128("10"), "quantity" : 5, "type": "apparel" }
])

Crie o seguinte índice composto nos campos type e item:

db.orders.createIndex( { type: 1, item: 1 } )

A operação de agregação a seguir localiza todos os documentos com type igual a apparel e usa o operador $meta para incluir o valor da chave de índice para o documento correspondente, caso um índice tenha sido usado:

db.orders.aggregate(
   [
     { $match: { type: "apparel" } },
     { $addFields: { idxKey: { $meta: "indexKey" } } }
   ]
)

A operação a seguir localiza todos os documentos com type igual a apparel e usa o operador $meta para incluir o valor da chave de índice para o documento correspondente, caso um índice tenha sido usado:

db.orders.find( { type: "apparel" }, { idxKey: { $meta: "indexKey" } } )

A operação retorna os documentos correspondentes com sua chave de índice correspondente:

{
   "_id" : ObjectId("5e98a33ceaf5e9dcf2b8dcde"),
   "item" : "abc",
   "price" : Decimal128("12"),
   "quantity" : 2,
   "type" : "apparel",
   "idxKey" : { "type" : "apparel", "item" : "abc" }
}
{
   "_id" : ObjectId("5e98a33ceaf5e9dcf2b8dce0"),
   "item" : "abc",
   "price" : Decimal128("10"),
   "quantity" : 5,
   "type" : "apparel",
   "idxKey" : { "type" : "apparel", "item" : "abc" }
}

Se o índice não for usado, { $meta: "indexKey" } não retornará nada.

Por exemplo, a operação a seguir não usa um índice, pois não existe nenhum índice no campo price compatível com a condição de correspondência:

db.orders.aggregate(
   [
   { $match: { price: { $gte: Decimal128("10") } } },
   { $addFields: { idxKey: { $meta: "indexKey" } } }
   ]
)

Por exemplo, a operação a seguir não usa um índice, pois não existe nenhum índice no campo price compatível com a condição de correspondência:

db.orders.find(
   { price: { $gte: Decimal128("10") } },
   { idxKey: { $meta: "indexKey" } }
)

A operação retorna os documentos correspondentes sem o campo idxKey:

{
   "_id" : ObjectId("5e98a33ceaf5e9dcf2b8dcde"),
   "item" : "abc",
   "price" : NumberDecimal("12"),
   "quantity" : 2,
   "type" : "apparel"
}
{
   "_id" : ObjectId("5e98a33ceaf5e9dcf2b8dcdf"),
   "item" : "jkl",
   "price" : NumberDecimal("20"),
   "quantity" : 1,
   "type" : "electronics"
}
{
   "_id" : ObjectId("5e98a33ceaf5e9dcf2b8dce0"),
   "item" : "abc",
   "price" : NumberDecimal("10"),
   "quantity" : 5,
   "type" : "apparel"
}

Os exemplos de C# nesta página utilizam o banco de dados sample_mflix a partir dos conjuntos de dados de amostra do Atlas. Para saber como criar um cluster MongoDB Atlas gratuito e carregar os conjuntos de dados de exemplo, consulte Introdução na documentação do driver MongoDB .NET/C#.

A seguinte classe Movie modela os documentos na collection sample_mflix.movies:

public class Movie
{
    public ObjectId Id { get; set; }
    public string Plot { get; set; }
    
    public List<string> Genres { get; set; }
    
    public int Runtime { get; set; }
    
    public List<string> Cast { get; set; }
    
    public string Title { get; set; }
    [BsonElement("lastupdated")]
    public DateTime LastUpdated { get; set; }
    
    public string Rated { get; set; }
    public int Year { get; set; }
    
    public ImdbData Imdb { get; set; }
    public string Type { get; set; }
    public int Index { get; set; }
    
    public string[] Comments { get; set; }
    public List<BsonDocument> Highlights { get; set; }
    
    public float Score { get; set; }
    [BsonElement("scoreDetails")]
    public SearchScoreDetails ScoreDetails { get; set; }
    
    [BsonElement("searchScoreDetails")]
    public SearchScoreDetails SearchScoreDetails { get; set; }
    
    [BsonElement("paginationToken")]
    public string PaginationToken { get; set; }
    
    [BsonElement("plot_embedding")]
    public float[] PlotEmbedding { get; set; }
}

Observação

ConventionPack para Pascal Case

As classes C# nesta página usam Pascal case para seus nomes de propriedade, mas os nomes de campo na coleção MongoDB usam Camel case. Para considerar essa diferença, você pode usar o seguinte código para registrar um ConventionPack quando o aplicativo iniciar:

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

Para incluir a pontuação da pesquisa de texto usando o driver .NET/C#, chame o método MetaTextScore() no construtor de projeção.

Primeiro, execute o código a seguir para criar um índice de texto no campo Title:

var indexModel = new CreateIndexModel<Movie>(
    Builders<Movie>.IndexKeys.Text(m => m.Title));
movieCollection.Indexes.CreateOne(indexModel);

Em seguida, adicione o seguinte código ao seu aplicativo. O código executa uma pesquisa de texto para o termo "future" e usa o método MetaTextScore() para incluir a pontuação atribuída a cada documento correspondente. O código então classifica os resultados em ordem decrescente pela pontuação do texto e retorna o documento com a pontuação mais alta.

var filter = Builders<Movie>.Filter.Text("future");
var projection = Builders<Movie>.Projection
    .Include(m => m.Title)
    .Include(m => m.Plot)
    .MetaTextScore(m => m.Score);
var result = movieCollection.Find(filter)
    .Sort(Builders<Movie>.Sort.MetaTextScore("score"))
    .Project(projection)
    .FirstOrDefault();

A operação anterior retorna o seguinte documento:

{
  "_id": {
    "$oid": "573a1398f29313caabceb500"
  },
  "plot": "After visiting 2015, Marty McFly must repeat his visit to 1955 to
   prevent disastrous changes to 1985... without interfering with his first trip.",
  "title": "Back to the Future Part II",
  "score": 1.59375
}

Voltar

$maxN-array-element

$minN-array-element

$meta (operador de expressão )

Definição

Importante

Comportamento

Metadados de pontuação de texto $meta: "textScore"

Requer pesquisa $text

Observação

Disponibilidade

Uso na projeção

Filtre na pontuação de texto

Uso na classificação

Classificar sem projeção

Classificar com projeção

Metadados da chave do índice $meta: "indexKey" (aggregation e localizar)

Uso

Disponibilidade

Valor de retorno

Exemplos

$meta: "textScore"

$meta: "indexKey"

Observação

Observação

ConventionPack para Pascal Case

Metadados de pontuação de texto `$meta: "textScore"`

`$meta: "textScore"`

`$meta: "indexKey"`