Menu Docs
Página inicial do Docs
/
Manual do MongoDB
/
Operações de agregação
/
Referência
/
Operadores

$meta

Nesta página

  • Definição
  • Comportamento
  • Exemplos

Definição

$meta

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

A expressão $meta tem a seguinte sintaxe:

{ $meta: <metaDataKeyword> }

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

Palavra chave
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 query $text , retornará uma pontuação nula.

Observação

$text fornece recursos de query de texto para sistemas autogerenciados (não Atlas). Para dados hospedados no MongoDB Atlas, o MongoDB oferece uma solução de query de texto completo aprimorada, 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" (Disponível a partir do MongoDB 7.0.5 e 6.0.13)

Comportamento

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

Requer pesquisa $text

  • A expressão { $meta: "textScore" } deve ser utilizada em conjunto com $text. Por exemplo:

    • Na aggregation, 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 de query, a operação falhará.

    Observação

    $text fornece recursos de query de texto para sistemas autogerenciados (não Atlas). Para dados hospedados no MongoDB Atlas, o MongoDB oferece uma solução de query de texto completo aprimorada, 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 aggregation, 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 Aggregation Pipeline em sistemas autogerenciados.

  • 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 usado, 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 obter mais exemplos, consulte $text no Aggregation Pipeline sobre implementaçõ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 exemplos adicionais de projeções e classificações do "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" : NumberDecimal("12"), "quantity" : 2, "type": "apparel" },
   { "item" : "jkl", "price" : NumberDecimal("20"), "quantity" : 1, "type": "electronics" },
   { "item" : "abc", "price" : NumberDecimal("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" : NumberDecimal("12"),
   "quantity" : 2,
   "type" : "apparel",
   "idxKey" : { "type" : "apparel", "item" : "abc" }
}
{
   "_id" : ObjectId("5e98a33ceaf5e9dcf2b8dce0"),
   "item" : "abc",
   "price" : NumberDecimal("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: NumberDecimal("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: NumberDecimal("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"
}

Voltar

$mergeObjects