faceta

Nesta página

Compatibilidade

Definição
Sintaxe
Campos
Definição de Facet
Facets de String
Facets Numéricos
Facetas de data
Resultados de facet
SEARCH_META Variável de agregação
Limitações
Exemplos

Compatibilidade

facet está disponível apenas em clusters Atlas que executam uma das seguintes versões:

MongoDB 5.0.4+
MongoDB 6.0+
MongoDB 7.0+
Observação
Para executar queries de facets em collections fragmentadas, o cluster deve executar o MongoDB v6.0 ou superior.

Você não pode executar queries facet com explain.

Definição

facet

O coletor facet agrupa resultados por valores ou intervalos nos campos facetados especificados e retorna a contagem para cada um desses grupos.

Você pode usar facet com os estágios $search e $searchMeta. O MongoDB recomenda utilizar o facet com o estágio $searchMeta para recuperar os resultados de metadados somente para a query. Para recuperar resultados de metadados e de query usando o estágio $search, você deve usar a variável de agregação $$SEARCH_META. Consulte Variável de agregação SEARCH_META para saber mais.

Sintaxe

facet tem a seguinte sintaxe:

{
  "$searchMeta"|"$search": {
    "index": <index name>, // optional, defaults to "default"
    "facet": {
      "operator": {
        <operator-specifications>
      },
      "facets": {
        <facet-definitions>
      }
    }
  }
}

Campos

Campo	Tipo	Obrigatório?	Descrição
`facets`	documento	sim	Informações para agrupar os dados de cada faceta. Você deve especificar pelo menos uma Definição de faceta.
`operator`	documento	no	Operador para usar para executar a faceta. Se omitido, o Atlas Search executa a faceta sobre todos os documentos na coleção.

Definição de Facet

O documento de definição do facet contém o nome do facet e as opções específicas para um tipo de facet. A Atlas Search suporta os seguintes tipos de facetas:

Facets de String
Facets Numéricos
Facetas de data

Facets de String

As facetas de strings permitem restringir os resultados do Atlas Search com base nos valores de strings mais frequentes no campo de string especificado. Observe que o campo de string deve ser indexado como stringFacet. Para atribuir facetas aos campos string em documentos incorporados, você também deve indexar os campos principais como o tipo de documento.

Observação

Quando facetas são utilizadas em um campo de string dentro de documentos incorporados, o Atlas Search retorna a contagem de facetas somente para o número de documentos principais correspondentes.

Sintaxe

Os facets de string têm a seguinte sintaxe:

{
  "$searchMeta": {
    "facet":{
      "operator": {
        <operator-specification>
      },
      "facets": {
        "<facet-name>" : {
          "type" : "string",
          "path" : "<field-path>",
          "numBuckets" : <number-of-categories>,
        }
      }
    }
  }
}

Opções

Opção	Tipo	Descrição	Obrigatório?
`numBuckets`	int	Número máximo de categorias facetas para retornar nos resultados. O valor deve ser menor ou igual a `1000`. Se especificado, a Atlas Search poderá retornar menos categorias do que o solicitado se os dados forem agrupados em menos categorias do que o número solicitado. Se omitido, padrão para `10`, o que significa que Atlas Search retornará somente as `10` principais categorias de faceta por contagem.	no
`path`	string	Caminho ativado para facet. Você pode especificar um campo que é indexado como um stringFacet.	sim
`type`	string	Tipo de facet. O valor deve ser `string`.	sim

Exemplo

O exemplo a seguir usa um índice chamado default na coleção sample_mflix.movies. O campo genres na coleção é indexado como o tipo stringFacet e o campo year é indexado como o tipo número.

{
  "mappings": {
    "dynamic": false,
    "fields": {
      "genres": {
        "type": "stringFacet"
      },
      "year": {
        "type": "number"
      }
    }
  }
}

A query utiliza o estágio $searchMeta para pesquisar o campo year na coleção movies para filmes de 2000 a 2015 e recuperar uma contagem do número de filmes em cada gênero.

db.movies.aggregate([
  {
    "$searchMeta": {
      "facet": {
        "operator": {
          "range": {
            "path": "year",
            "gte": 2000,
            "lte": 2015
          }
        },
        "facets": {
          "genresFacet": {
            "type": "string",
            "path": "genres"
          }
        }
      }
    }
  }
])

Esta query retorna os seguintes resultados:

[
  {
    count: { lowerBound: Long("13718") },
    facet: {
      genresFacet: {
        buckets: [
          { _id: 'Drama', count: Long("7759") },
          { _id: 'Comedy', count: Long("3937") },
          { _id: 'Romance', count: Long("1916") },
          { _id: 'Thriller', count: Long("1705") },
          { _id: 'Documentary', count: Long("1703") },
          { _id: 'Action', count: Long("1558") },
          { _id: 'Crime', count: Long("1475") },
          { _id: 'Adventure', count: Long("1111") },
          { _id: 'Horror', count: Long("1008") },
          { _id: 'Biography', count: Long("877") }
        ]
      }
    }
  }
]

Para saber mais sobre esses resultados, consulte Resultados de faceta.

Facets Numéricos

As facets numéricas permitem que você determine a frequência dos valores numéricos nos resultados da procurar, dividindo os resultados em intervalos separados de números.

Observação

Limitação

Não é possível utilizar facetas em campos numéricos em documentos incorporados.

Sintaxe

Os facets numéricos têm a seguinte sintaxe:

{
  "$searchMeta": {
    "facet":{
      "operator": {
        <operator-specification>
      },
      "facets": {
        "<facet-name>" : {
          "type" : "number",
          "path" : "<field-path>",
          "boundaries" : <array-of-numbers>,
          "default": "<bucket-name>"
        }
      }
    }
  }
}

Opções

Opção	Tipo	Descrição	Obrigatório?
`boundaries`	array de números	Lista de valores numéricos, em ordem crescente, que especificam os limites para cada bloco. Você deve especificar pelo menos dois limites. Cada par adjacente de valores age como o limite inferior inclusivo e o limite superior exclusivo para o bloco. Você pode especificar qualquer combinação de valores dos seguintes tipos de BSON: Inteiro de `int32` bits () Inteiro de 64 bits (`int64`) Ponto flutuante binário de 64 bits (`double`	sim
`default`	string	Nome de um bucket adicional que conta os documentos retornados do operador que não se enquadram nos limites especificados. Se omitido, o Atlas Search também inclui os resultados do operador de faceta que não se enquadram em um bucket especificado, mas não o inclui em nenhuma contagem de bucket.	no
`path`	string	Caminho do campo para a facet. Você pode especificar um campo que é indexado como o tipo numberFacet.	sim
`type`	string	Tipo de facet. O valor deve ser `number`.	sim

Exemplo

O exemplo a seguir usa um índice chamado default na coleção sample_mflix.movies. O campo year na coleção é indexado como numberFacet e tipos de números.

{
  "mappings": {
    "dynamic": false,
    "fields": {
      "year": [
        {
          "type": "numberFacet"
        },
        {
          "type": "number"
        }
      ]
    }
  }
}

A query usa o estágio $searchMeta para procurar o campo year na collection movies para filmes entre os anos 1980 2000 e recuperar resultados de metadados para a query. A query especifica três buckets:

1980, limite inferior inclusivo para este bucket
1990, limite superior exclusivo para o bucket 1980 e limite inferior inclusivo para este bucket
2000, limite superior exclusivo para o bucket 1990

A query também especifica um bucket de default chamado other para recuperar resultados da query que não se enquadram em nenhum dos limites especificados.

db.movies.aggregate([
  {
    "$searchMeta": {
      "facet": {
        "operator": {
          "range": {
            "path": "year",
            "gte": 1980,
            "lte": 2000
          }
        },
        "facets": {
          "yearFacet": {
            "type": "number",
            "path": "year",
            "boundaries": [1980,1990,2000],
            "default": "other"
          }
        }
      }
    }
  }
])

Esta query retorna os seguintes resultados:

[
  {
    count: { lowerBound: Long('6095') },
    facet: {
      yearFacet: {
        buckets: [
          { _id: 1980, count: Long('1956') },
          { _id: 1990, count: Long('3558') },
          { _id: 'other', count: Long('581') }
        ]
      }
    }
  }
]

Para saber mais sobre esses resultados, consulte Resultados de faceta.

Facetas de data

Facets de datas permitem limitar resultados de pesquisa com base em uma data.

Observação

Limitação

Você não pode atribuir facetas aos campos de data em documentos incorporados.

Sintaxe

Os facets de data têm a seguinte sintaxe:

{
  "$searchMeta": {
    "facet":{
      "operator": {
        <operator-specification>
      },
      "facets": {
        "<facet-name>" : {
          "type" : "date",
          "path" : "<field-path>",
          "boundaries" : <array-of-dates>,
          "default": "<bucket-name>"
        }
      }
    }
  }
}

Opções

Opção	Tipo	Descrição	Obrigatório?
`boundaries`	array de números	Lista de valores de data que especificam os limites para cada bucket. Você deve especificar: Pelo menos dois limites Valores em ordem crescente, com a data mais antiga primeiro Cada par adjacente de valores atua como o limite inferior inclusivo e o limite superior exclusivo para o bucket.	sim
`default`	string	Nome de um compartimento adicional que conta os documentos retornados do operador que não se enquadram nos limites especificados. Se omitido, o Atlas Search incluirá os resultados do operador de faceta que também não se enquadram em um bucket especificado, mas o Atlas Search não incluirá esses resultados em nenhuma contagem de bucket.	no
`path`	string	Caminho do campo para a facet. Você pode especificar um campo que é indexado como um tipo dateFacet.	sim
`type`	string	Tipo de facet. O valor deve ser `date`.	sim

Exemplo

O exemplo a seguir usa um índice chamado default na coleção sample_mflix.movies. O campo released na coleção é indexado como dateFacet e tipos de data.

{
  "mappings": {
    "dynamic": false,
    "fields": {
      "released": [
        {
          "type": "dateFacet"
        },
        {
          "type": "date"
        }
      ]
    }
  }
}

A query usa o estágio $searchMeta para pesquisar filmes entre os anos 2000 a 2015 no campo released na collection movies e recuperar resultados de metadados para a string de query. A query especifica quatro buckets:

2000-01-01, limite inferior inclusivo para este bucket
2005-01-01, limite superior exclusivo para o bucket 2000-01-01 e limite inferior inclusivo para este bucket
2010-01-01, limite superior exclusivo para o bucket 2005-01-01 e limite inferior inclusivo para este bucket
2015-01-01, limite superior exclusivo para o bucket 2010-01-01

A query também especifica um bucket de default chamado other para recuperar resultados da query que não se enquadram em nenhum dos limites especificados.

db.movies.aggregate([
  {
    "$searchMeta": {
      "facet": {
        "operator": {
          "range": {
            "path": "released",
            "gte": ISODate("2000-01-01T00:00:00.000Z"),
            "lte": ISODate("2015-01-31T00:00:00.000Z")
          }
        },
        "facets": {
          "yearFacet": {
            "type": "date",
            "path": "released",
            "boundaries": [ISODate("2000-01-01"), ISODate("2005-01-01"), ISODate("2010-01-01"), ISODate("2015-01-01")],
            "default": "other"
          }
        }
      }
    }
  }
])

Esta query retorna os seguintes resultados:

[
  {
    count: { lowerBound: Long('11922') },
    facet: {
      yearFacet: {
        buckets: [
          {
            _id: ISODate('2000-01-01T00:00:00.000Z'),
            count: Long('3028')
          },
          {
            _id: ISODate('2005-01-01T00:00:00.000Z'),
            count: Long('3953')
          },
          {
            _id: ISODate('2010-01-01T00:00:00.000Z'),
            count: Long('4832')
          },
          { _id: 'other', count: Long('109') }
        ]
      }
    }
  }
]

Para saber mais sobre esses resultados, consulte Resultados de faceta.

Resultados de facet

Para uma query de facet, o Atlas Search retorna um mapeamento dos nomes de faceta definidos para uma array de compartimentos para essa faceta nos resultados. O documento de resultado do facet contém a opção buckets, que é uma array de buckets resultantes para o facet. Cada documento de bucket de atributos na array possui os seguintes campos:

Opção	Tipo	Descrição
`_id`	objeto	Identificador único que identifica este bucket de facet. Este valor corresponde ao tipo de dados que está sendo facetado.
`count`	int	Contagem de documentos neste facet bucket. Para saber mais sobre o campo `count`, consulte Resultados da pesquisa do Atlas Search.

`SEARCH_META` Variável de agregação

Quando você executa sua query utilizando o estágio $search, o Atlas Search armazena os resultados de metadados na variável $$SEARCH_META e retorna somente os resultados da pesquisa. É possível usar a variável $$SEARCH_META em todas as fases do pipeline de agregação compatíveis para visualizar os resultados de metadados da sua query $search.

O MongoDB recomenda utilizar a variável $$SEARCH_META somente se você precisar dos resultados da pesquisa e dos resultados de metadados. Caso contrário, use o:

$search estágio apenas para os resultados da pesquisa.
$searchMeta estágio apenas para os resultados dos metadados.

Limitações

Aplicam-se as seguintes limitações:

Você pode executar queries de facets somente em um único campo. Não é possível executar queries de atributos em grupos de campos.
Você pode executar queries de faceta em collections fragmentadas em clusters que executam apenas o MongoDB v6.0.

Exemplos

Os exemplos a seguir usam a collection sample_mflix.movies . O exemplo de resultados de metadados demonstra como executar uma query de $searchMeta com facet para recuperar somente os metadados nos resultados. O exemplo de metadados e os resultados da pesquisa demonstram como executar uma query de $search com facet e a variável de aggregation $SEARCH_META para recuperar os resultados de pesquisa e dos metadados.

A definição de índice especifica o seguinte para os campos indexarem:

Nome do campo	Tipo de Dados
`directors`	stringFacet
`year`	Faceta numérica
`released`	data

{
  "mappings": {
    "dynamic": false,
    "fields": {
      "directors": {
        "type": "stringFacet"
      },
      "year": {
        "type": "numberFacet"
      },
      "released": {
        "type": "date"
      }
    }
  }
}

As pesquisas de query a seguir para filmes lançados entre 1º de janeiro de 2000 e 31 de janeiro de 2015. Ela solicita metadados no campo directors e year.

db.movies.aggregate([
  {
    "$searchMeta": {
      "facet": {
        "operator": {
          "range": {
            "path": "released",
            "gte": ISODate("2000-01-01T00:00:00.000Z"),
            "lte": ISODate("2015-01-31T00:00:00.000Z")
          }
        },
        "facets": {
          "directorsFacet": {
            "type": "string",
            "path": "directors",
            "numBuckets" : 7
          },
          "yearFacet" : {
            "type" : "number",
            "path" : "year",
            "boundaries" : [2000,2005,2010, 2015]
          }
        }
      }
    }
  }
])

O Atlas Search retorna os seguintes resultados:

[
  {
    "count" : { "lowerBound" : NumberLong(13064) },
    "facet" : {
      "yearFacet" : {
        "buckets" : [
          { "_id" : 2000, "count" : NumberLong(3283) },
          { "_id" : 2005, "count" : NumberLong(4365) },
          { "_id" : 2010, "count" : NumberLong(5123) }
        ]
      },
      "directorsFacet" : {
        "buckets" : [
         { "_id" : "Takashi Miike", "count" : NumberLong(29) },
          { "_id" : "Johnnie To", "count" : NumberLong(23) },
          { "_id" : "Steven Soderbergh", "count" : NumberLong(21) },
          { "_id" : "Michael Winterbottom", "count" : NumberLong(19) },
          { "_id" : "Ken Loach", "count" : NumberLong(16) },
          { "_id" : "Ki-duk Kim", "count" : NumberLong(16) },
          { "_id" : "Ridley Scott", "count" : NumberLong(15) }
        ]
      }
    }
  }
]

Os resultados mostram uma contagem dos seguintes itens na collection sample_mflix.movies:

Número de filmes do ano 2000, limite inferior inclusivo, até 2015, limite superior excluindo, que o Atlas Search retornou para a query
Número de filmes para cada diretor que o Atlas Search retornou para a query

A definição de índice especifica o seguinte para os campos indexarem:

Nome do campo	Tipo de Dados
`genres`	stringFacet
`released`	data

{
  "mappings": {
    "dynamic": false,
    "fields": {
      "genres": {
        "type": "stringFacet"
      },
      "released": {
        "type": "date"
      }
    }
  }
}

A query a seguir pesquisa filmes lançados perto de 01 de julho de 1999 usando o estágio $search . A consulta inclui um estágio $facet para processar os documentos de entrada usando os seguintes estágios de subpipeline:

Etapa $project para excluir todos os campos nos documentos, exceto os campos title e released no campo de saída docs.
$limit estágio para fazer o seguinte:
- Limite a saída do estágio $search a 2 documentos
- Limite a saída ao documento 1 no campo de saída meta.
Observação
O limite deve ser pequeno para que os resultados caibam em um documento de 16 MB .
o estágio $replaceWith para incluir os resultados de metadados armazenados na variável $$SEARCH_META no campo de saída meta

A query também inclui um estágio $set para adicionar o campo meta.

Observação

Para ver os resultados de metadados da consulta a seguir, o Atlas Search deve retornar documentos que correspondam à consulta.

db.movies.aggregate([
  {
    "$search": {
      "facet": {
        "operator": {
          "near": {
            "path": "released",
            "origin": ISODate("1999-07-01T00:00:00.000+00:00"),
            "pivot": 7776000000
          }
        },
        "facets": {
          "genresFacet": {
            "type": "string",
            "path": "genres"
          }
        }
      }
    }
  },
  { "$limit": 2 },
  {
    "$facet": {
      "docs": [
        { "$project":
          {
            "title": 1,
            "released": 1
          }
        }
      ],
      "meta": [
        {"$replaceWith": "$$SEARCH_META"},
        {"$limit": 1}
      ]
    }
  },
  {
    "$set": {
      "meta": {
        "$arrayElemAt": ["$meta", 0]
      }
    }
  }
])

A query retorna os seguintes resultados:

[
  {
    docs: [
      {
        _id: ObjectId("573a1393f29313caabcde1ae"),
        title: 'Begone Dull Care',
        released: ISODate("1999-07-01T00:00:00.000Z")
      },
      {
        _id: ObjectId("573a13a9f29313caabd2048a"),
        title: 'Fara',
        released: ISODate("1999-07-01T00:00:00.000Z")
      }
    ],
    meta: {
      count: { lowerBound: Long("20878") },
      facet: {
        genresFacet: {
          buckets: [
            { _id: 'Drama', count: Long('12149') },
            { _id: 'Comedy', count: Long('6436') },
            { _id: 'Romance', count: Long('3274') },
            { _id: 'Crime', count: Long('2429') },
            { _id: 'Thriller', count: Long('2400') },
            { _id: 'Action', count: Long('2349') },
            { _id: 'Adventure', count: Long('1876') },
            { _id: 'Documentary', count: Long('1755') },
            { _id: 'Horror', count: Long('1432') },
            { _id: 'Biography', count: Long('1244') }
          ]
        }
      }
    }
  }
]

Para saber mais sobre esses resultados, consulte Resultados de faceta.

Voltar

existe

geoShape

Compatibilidade

Observação

Definição

Sintaxe

Campos

Definição de Facet

Facets de String

Observação

Sintaxe

Opções

Exemplo

Exemplo

Facets Numéricos

Observação

Limitação

Sintaxe

Opções

Exemplo

Exemplo

Facetas de data

Observação

Limitação

Sintaxe

Opções

Exemplo

Exemplo

Resultados de facet

SEARCH_META Variável de agregação

Limitações

Exemplos

Observação

Observação

`SEARCH_META` Variável de agregação