$scoreFusion (agregação)

Os estágios $rankFusion e $scoreFusion estão disponíveis como recursos de pré-visualização. Para saber mais, consulte Recursos de visualização.

Importante

$scoreFusion está disponível apenas para implementações que utilizam MongoDB 8.2+.

Definição

$scoreFusion

$scoreFusion primeiro executa todos os pipelines de entrada de forma independente e, em seguida, deduplica e combina os resultados do pipeline de entrada em um conjunto de resultados de pontuação final.

$scoreFusion gera um conjunto classificado de documentos com base nas pontuações e pesos dos documentos de suas pipelines de entrada. Você pode especificar uma expressão aritmética para calcular a pontuação com base nas pontuações de entrada do estágio do pipeline. Por padrão, ele usa a média das pontuações dos documentos dos diferentes estágios do pipeline de entrada.

Use $scoreFusion para pesquisar documentos em uma única collection com base em vários critérios e recuperar um conjunto de resultados de pontuação final que leva em conta todos os critérios especificados.

Sintaxe

O estágio tem a seguinte sintaxe:

{ $scoreFusion: {
    input: {
      pipelines: {
            <input-pipeline-name>: <expression>,
            <input-pipeline-name>: <expression>,
            ...
      },
      normalization: "none|sigmoid|minMaxScaler"
    },
    combination: {
      weights: {
            <input-pipeline-name>: <numeric expression>,
            <input-pipeline-name>: <numeric expression>,
            ...
      },
      method: "avg|expression",
      expression: <expression>
    }
} }

Campos

$scoreFusion usa os seguintes campos:

Campo	Tipo	Descrição
`input`	Objeto	Define a entrada que `$scoreFusion` combina.
`input.pipelines`	Objeto	Contém um mapa de nomes de pipeline para os estágios de agregação que definem esse pipeline. `input.pipelines` devem conter pelo menos um pipeline. Você deve especificar `$score` para o pipeline de entrada se o pipeline de entrada não retornar uma pontuação. Todos os pipelines devem operar na mesma coleção e devem ter um nome exclusivo. Para obter mais informações sobre restrições de pipeline de entrada, consulte Pipelines de Entrada e Nomes de Pipeline de Entrada.
`input.normalization`	String	Normaliza a pontuação para o intervalo de `0` a `1` antes de combinar os resultados. O valor pode ser: `none` - para não normalizar. `sigmoid` - para aplicar a expressão `$sigmoid` . `minMaxScaler` - para aplicar o operador de blocos `$minMaxScaler` .
`combination`	Objeto	Opcional. Define como combinar os resultados do pipeline `input`.
`combination.weights`	Objeto	Opcional. Os pesos a serem aplicados às pontuações normalizadas do pipeline de entrada ao combinar os resultados. Corresponde aos pipelines de entrada, um por pipeline. O peso padrão é `1` se o peso de qualquer pipeline não for especificado. Cada valor de peso deve ser um número não negativo (inteiro ou decimal). O peso pode ser `0`.
`combination.method`	String	Opcional. Especifica o método para combinar pontuações. O valor pode ser: `avg` - para calcular a média das pontuações de entrada. `expression` - para aplicar uma expressão de agregação personalizada que você especifica no campo `combination.expression`. Se omitido, o padrão é `avg`.
`combination.expression`	Expressão aritmética	Opcional. Especifica a lógica para combinar as pontuações de entrada. Esta é a expressão personalizada que é utilizada quando `combination.method` está configurado para `expression`. Na expressão, use o nome do pipeline de entrada para representar a pontuação de entrada correspondente a um documento. Mutualmente exclusivo com `combination.weights`.
`scoreDetails`	Boolean	Opcional. Especifica se incluir informações de pontuação detalhadas de cada pipeline de entrada nos metadados do documento de saída. Se omitido, o padrão é `false`.

Comportamento

Collections

Você só pode usar $scoreFusion com uma única collection. Você não pode usar este estágio de agregação em um escopo de banco de dados .

De-Duplication

$scoreFusion elimina a duplicação dos resultados em vários pipelines de entrada na saída final. Cada documento de entrada exclusivo aparece no máximo uma vez na saída $scoreFusion, independentemente do número de vezes que o documento aparece nas saídas do pipeline de entrada.

Pipelines de Entrada

Cada pipeline input deve ser um Pipeline de Seleção e um Pipeline de Pontuação.

Pipeline de seleção

Um pipeline de seleção recupera um conjunto de documentos de uma coleção sem realizar nenhuma modificação após a recuperação. $scoreFusion compara documentos em diferentes pipelines de entrada, o que exige que todos os pipelines de entrada gerem os mesmos documentos não modificados.

Um pipeline de seleção deve conter apenas os seguintes estágios:

Tipo	Estágios
Estágios de pesquisa	`$match`, incluindo `$match` com pesquisa de texto legado `$geoNear` `$search` `$vectorSearch` Observação Se você usar `$geoNear` em um pipeline de seleção, não poderá especificar `includeLogs` ou `distanceField` porque esses campos modificam documentos.
Estágios de pedidos	`$sort`
Estágios de paginação	`$skip` `$limit`

Pipeline de Pontuação

Um pipeline de pontuação classifica ou ordena documentos com base na pontuação dos documentos. $scoreFusion usa a ordem dos resultados do pipeline com pontuação para influenciar as pontuações de saída. A pontuação dos pipelines deve atender a um dos seguintes critérios:

Comece com um dos seguintes estágios ordenados:
- $search
- $vectorSearch
- $match com pesquisa de texto legado
- $geoNear
Contém um estágio explícito se o pipeline anterior não retornar inerentemente uma $score pontuação.

Nomes de Pipeline de Entrada

Os nomes de pipeline em input devem atender às seguintes restrições:

Não deve ser uma string vazia
Não deve começar com um $
Não deve conter o delimitador de caracteres ASCII nulo \0 em qualquer lugar na string
Não deve conter um .

detalhe da pontuação

Se você definir scoreDetails como true, $scoreFusion criará um campo de metadados scoreDetails para cada documento. O campo scoreDetails contém informações sobre a classificação final.

Observação

Ao definir scoreDetails como true, $scoreFusion define o campo de metadados scoreDetails para cada documento. Por padrão, ele não gera automaticamente o metacampo scoreDetails .

Para visualizar o campo de metadados scoreDetails , você deve defini-lo explicitamente por meio da expressão$metaem um estágio como$project , $addFieldsou$set.

O campo scoreDetails contém os seguintes subcampos:

Campo	Descrição
`value`	O valor numérico da pontuação para este documento.
`description`	Uma descrição de como `$scoreFusion` calculou a pontuação final.
`normalization`	O método de normalização utilizado para normalizar a pontuação.
`combination`	O método de combinação e a expressão usados para combinar os resultados do pipeline.
`details`	Uma array em que cada entrada da array contém informações sobre os pipelines de entrada que resultam neste documento.

Cada entrada de array no campo details contém os seguintes subcampos:

Campo	Descrição
`inputPipelineName`	O nome do pipeline de entrada que gera este documento.
`inputPipelineRawScore`	A pontuação do documento do pipeline antes da normalização.
`weight`	O peso do pipeline de entrada.
`value`	Opcional. Se o pipeline de entrada gerar um `{ $meta: 'score' }` para esse documento, , `value` conterá `{ $meta: 'score' }`.
`details`	O campo `scoreDetails` do pipeline de entrada. Se o pipeline de entrada não gerar um campo `scoreDetails`, esse campo será uma array vazia.

Aviso

O MongoDB não garante nenhum formato de saída específico para scoreDetails.

Exemplo

Os seguintes blocos de código mostram o campo scoreDetails para uma operação $scoreFusion com os pipelines de entrada $search, $vectorSearch e $match:

  scoreDetails: {
  value: 7.847857250621068,
  description: 'the value calculated by combining the scores (either normalized or raw) across input pipelines from which this document is output from:',
  normalization: 'sigmoid',
  combination: {
    method: 'custom expression',
    expression: "{ string: { $sum: [ { $multiply: [ '$$searchOne', 10 ] }, '$$searchTwo' ] } }"
  },
  details: [
    {
      inputPipelineName: 'searchOne',
      inputPipelineRawScore: 0.7987099885940552,
      weight: 1,
      value: 0.6896984675751023,
      details: []
    },
    {
      inputPipelineName: 'searchTwo',
      inputPipelineRawScore: 2.9629626274108887,
      weight: 1,
      value: 0.950872574870045,
      details: []
    }
  ]
}

Explicação de resultados

O MongoDB converte $scoreFusion operações de em um conjunto de estágios de agregação existentes que, em combinação, calculam o resultado de saída antes da execução da query. Os Resultados Explicados de uma $scoreFusion operação mostram a execução completa dos estágios de agregação subjacentes que o $scoreFusion usa para compor o resultado final.

Exemplos

Este exemplo utiliza uma coleção com incorporações e campos de texto. Crie search e vectorSearch índices de tipo na coleção.

A seguinte definição de índice indexa automaticamente todos os campos dinamicamente indexáveis na coleção para executar $search queries do em relação aos campos indexados.

índice de pesquisa

db.embedded_movies.createSearchIndex(
   "<INDEX_NAME>",
   {
      mappings: { dynamic: true }
   }
)

A seguinte definição de índice indexa o campo com as incorporações na coleção para executar queries do neste $vectorSearch campo.

Índice de pesquisa vetorial

db.embedded_movies.createSearchIndex(
   "<INDEX_NAME>",
   "vectorSearch",
   {
      "fields": [
         {
            "type": "vector",
            "path": "<FIELD_NAME>",
            "numDimensions": <NUMBER_OF_DIMENSIONS>,
            "similarity": "dotProduct"
         }
      ]
   }
);

O seguinte pipeline de agregação utiliza $scoreFusion com os seguintes pipelines de entrada:

Pipeline	Número de documentos devolvidos	Descrição
`searchOne`	20	Executa uma pesquisa vetorial no campo indexado como tipo `vector` para o termo especificado como incorporações. A query considera até 500 vizinhos mais próximos, mas limita os resultados a 20 documentos.
`searchTwo`	20	Executa uma pesquisa de texto completo para o mesmo termo e limita os resultados a 20 documentos.

1 db.embedded_movies.aggregate( [
2    {
3       $scoreFusion: {
4          input: {
5             pipelines: {
6                searchOne: [
7                   {
8                      "$vectorSearch": {
9                         "index": "<INDEX_NAME>",
10                         "path": "<FIELD_NAME>",
11                         "queryVector": <QUERY_EMBEDDINGS>,
12                         "numCandidates": <NUMBER_OF_NEAREST_NEIGHBORS_TO_CONSIDER>,
13                         "limit": <NUBMER_OF_DOCUMENTS_TO_RETURN>
14                      }
15                   }
16                ],
17                searchTwo: [
18                   {
19                      "$search": {
20                         "index": "<INDEX_NAME>",
21                         "text": {
22                            "query": "<QUERY_TERM>",
23                            "path": "<FIELD_NAME>"
24                         }
25                      }
26                   },
27                ]
28             },
29             normalization: "sigmoid"
30          },
31          combination: {
32             method: "expression",
33             expression: {
34                $sum: [
35                  {$multiply: [ "$$searchOne", 10]}, "$$searchTwo"
36                ]
37             }
38          },
39          "scoreDetails": true
40       }
41    },
42    {
43       "$project": {
44          _id: 1,
45          title: 1,
46          plot: 1,
47          scoreDetails: {"$meta": "scoreDetails"}
48       }
49    },
50    { $limit: 20 }
51 ] )

Este pipeline executa as seguintes ações:

Executa os pipelines input
Combina os resultados retornados
Gera os primeiros 20 documentos que são os 20 principais resultados classificados do $scoreFusion pipeline

Voltar

$score

$search

1	db.embedded_movies.aggregate( [
2	{
3	$scoreFusion: {
4	input: {
5	pipelines: {
6	searchOne: [
7	{
8	"$vectorSearch": {
9	"index": "<INDEX_NAME>",
10	"path": "<FIELD_NAME>",
11	"queryVector": <QUERY_EMBEDDINGS>,
12	"numCandidates": <NUMBER_OF_NEAREST_NEIGHBORS_TO_CONSIDER>,
13	"limit": <NUBMER_OF_DOCUMENTS_TO_RETURN>
14	}
15	}
16	],
17	searchTwo: [
18	{
19	"$search": {
20	"index": "<INDEX_NAME>",
21	"text": {
22	"query": "<QUERY_TERM>",
23	"path": "<FIELD_NAME>"
24	}
25	}
26	},
27	]
28	},
29	normalization: "sigmoid"
30	},
31	combination: {
32	method: "expression",
33	expression: {
34	$sum: [
35	{$multiply: [ "$$searchOne", 10]}, "$$searchTwo"
36	]
37	}
38	},
39	"scoreDetails": true
40	}
41	},
42	{
43	"$project": {
44	_id: 1,
45	title: 1,
46	plot: 1,
47	scoreDetails: {"$meta": "scoreDetails"}
48	}
49	},
50	{ $limit: 20 }
51	] )