Para agentes de IA: um índice de documentação está disponível em https://www.mongodb.com/pt-br/docs/llms.txt — as versões de markdown de todas as páginas estão disponíveis anexando .md a qualquer caminho de URL.
Make the MongoDB docs better! We value your opinion. Share your feedback for a chance to win $100.
MongoDB Branding Shape
Click here >
Menu Docs
Página inicial do Docs
/ /
opções de pesquisa
Página inicial do Docs
/ /
Referência de query
/
opções de pesquisa
Página inicial do Docs
/
Desenvolvimento
/
Pesquisa
/
Queries e índices
/
Referência de query
/
opções de pesquisa

Consulte, filtre e recupere arrays de objetos

Você pode usar a opção returnScope para definir o contexto da query e retornar arrays de objetos como documentos individuais.

Requisitos

Para recuperar objetos aninhados como documentos individuais usando returnScope, você deve:

  • Índice os arrays de objetos como o tipo embeddedDocuments.

  • Defina storedSource para os campos aninhados que você deseja recuperar. A pesquisa do MongoDB retorna apenas os campos definidos no storedSource.

  • Defina a opção returnStoredSource como true na query.

Sintaxe

returnScope tem a seguinte sintaxe em suas queries:

{
  $search: {
   "<operator>": {
      <operator-specification>,
   },
   "returnScope": {
      "path": "<embedded-documents-field-to-retrieve>"
   },
   "returnStoredSource": true
  }
}
{
  $searchMeta: {
   "returnScope": {
      "path": "<embedded-documents-field-to-retrieve>"
   },
   "returnStoredSource": true
  },
  "facet": {
    "<operator>": {
      <operator-specification>,
   },
    "facets": {
      <facet-definition>
    }
  }
}

Para saber mais sobre sintaxe de query, consulte $search.

Comportamento

A opção returnScope define o contexto de recuperação para a query. Se você especificar returnScope em sua query, o MongoDB Search pontua, classifica e conta cada documento incorporado como se fosse um documento individual.

Considerações

Quando você usa a opção returnScope, o MongoDB pesquisa retorna apenas os campos que você configurou como storedSource dentro do embeddedDocument. Os campos fora do caminho embeddedDocument (como os campos no nível da raiz) e os campos que não estão configurados como storedSource não são retornados.

Na especificação do operador, você deve especificar o caminho completo para o campo que deseja fazer a query. Ao usar a opção returnScope, você deve garantir que todos os caminhos de especificações do operador estejam aninhados em returnScope.path. Para fazer query em um campo fora do returnScope.path, você deve usar o operador hasAncestor ou hasRoot. Para aprender mais, consulte:

Recuperar o ID do documento raiz

Quando você usa returnScope em uma query, o MongoDB Search preenche um campo de metadados searchRootDocumentId. Você pode usar o campo de metadados searchRootDocumentId em clusters que executam o MongoDB 8.3 ou posterior. Este campo contém o identificador do documento raiz que contém cada documento incorporado retornado. Para projetar esse valor, use a expressão $meta com a palavra-chave searchRootDocumentId.

O MongoDB Search preenche searchRootDocumentId somente quando sua query define returnStoredSource: true e returnScope.path. Se você fizer referência a searchRootDocumentId em uma query que não especifica returnScope, a query falhará com o seguinte erro:

query requires $search root document id metadata, but it is not
available

Use searchRootDocumentId se quiser:

  • Buscar campos do documento pai após filtrar nos documentos filho.

  • Agrupe documentos filho por seu pai.

Não use searchRootDocumentId se:

  • Você precisa apenas de campos dos documentos filhos correspondentes.

  • Você deseja retornar o documento pai para cada documento filho no conjunto de resultados, pois isso pode ser caro.

Exemplos

Os exemplos a seguir demonstram como usar a opção returnScope em consultas. Os exemplos usam o conjunto de dados de amostra sample_training.companies. Se você carregar os dados no seu cluster e criar o índice de amostra nos campos da coleção, poderá tentar as seguintes consultas nos dados de amostra.

Índice de amostra

1{
2  "mappings": { 
3    "dynamic": false,
4    "fields": { 
5      "funding_rounds": { 
6        "type": "embeddedDocuments",
7        "dynamic": true,
8        "fields": {
9          "investments": {
10            "type": "embeddedDocuments",
11            "dynamic": true
12          }
13        },
14        "storedSource": {
15          "include": [
16            "round_code", 
17            "raised_currency_code",
18            "raised_amount",
19            "investments.person",
20            "investments.financial_org"
21          ] 
22        }
23      } 
24    }
25  }
26}

A definição de índice anterior configura a pesquisa do MongoDB para:

  • Indexe os campos funding_rounds e funding_rounds.investments como o tipo embeddedDocuments.

  • Indexe todos os campos indexáveis dinamicamente aninhados no array de objetos funding_rounds e funding_rounds.investments.

  • Armazene os seguintes campos em mongot:

    • funding_rounds.round_code

    • funding_rounds.raised_currency_code

    • funding_rounds.raised_amount

    • funding_rounds.investments.person

    • funding_rounds.investments.financial_org

Você pode usar o embeddedDocument Operador para realizar queries elemento a elemento em ambos os campos funding_rounds e funding_rounds.investments. As seções a seguir demonstram algumas queries de amostra que usam a opção returnScope para recuperar os campos embeddedDocuments como documentos individuais.

Estrutura de documento de amostra da coleção sample_training.companies
{
  ...,
  "funding_rounds": [
    {
      "id": <integer>,
      "round_code": "<string>",
      "source_url": "<string>",
      "source_description": "<string>",
      "raised_amount": <integer>,
      "raised_currency_code": "<string>",
      "funded_year": <integer>,
      "funded_month": "<string>",
      "funded_day": "<string>",
      "investments": [
         {
           "company": "<string>",
           "financial_org": {
             "name": "<string>",
             "permalink": "<string>"
           },
           "person": {
             "first_name": "<string>",
             "last_name": "<string>",
             "permalink": "<string>"
           }
         },
         ...
      ]
    },
    ...
  ],
  ...
}

Exemplos de queries

As seções seguintes demonstram queries de exemplo que usam a opção returnScope para recuperar campos em campos do tipo embeddedDocuments que foram armazenados em mongot.

Consulta Simples

Consulte e recupere campos de documentos incorporados.

A query a seguir usa o range (Operador de Pesquisa do MongoDB) para consultar o campo funding_rounds.raised_amount para uma quantidade maior e igual a 5000000 e menor e igual a 10000000. Define o escopo da consulta como funding_rounds campo usando a opção returnScope. Retorna todos os campos armazenados dentro da array de objetos funding_rounds, incluindo campos na array de objetos funding_rounds.investments que foram armazenados usando a opção returnStoredSource. Limita o número de resultados a apenas 5 funding_rounds documentos.

1db.companies.aggregate(
2  {
3    "$search": {
4      "range": {
5        "path": "funding_rounds.raised_amount",
6        "gte": 5000000,
7        "lte": 10000000
8      },
9      "returnStoredSource": true,
10      "returnScope": {
11        "path": "funding_rounds"
12      }
13    }
14  },
15  {
16    "$limit": 5
17  }
18)
[
  {
    round_code: 'a',
    raised_amount: 5250000,
    raised_currency_code: 'USD',
    investments: [
      {
        financial_org: {
          name: 'Frazier Technology Ventures',
          permalink: 'frazier-technology-ventures'
        },
        person: null
      },
      {
        financial_org: { name: 'Trinity Ventures', permalink: 'trinity-ventures' },
        person: null
      }
    ]
  },
  {
    round_code: 'b',
    raised_amount: 9500000,
    raised_currency_code: 'USD',
    investments: [
      {
        financial_org: { name: 'Accel Partners', permalink: 'accel-partners' },
        person: null
      },
      {
        financial_org: {
          name: 'Frazier Technology Ventures',
          permalink: 'frazier-technology-ventures'
        },
        person: null
      },
      {
        financial_org: { name: 'Trinity Ventures', permalink: 'trinity-ventures' },
        person: null
      }
    ]
  },
  {
    round_code: 'a',
    raised_amount: 5000000,
    raised_currency_code: 'USD',
    investments: [
      {
        financial_org: {
          name: 'Charles River Ventures',
          permalink: 'charles-river-ventures'
        },
        person: null
      },
      {
        financial_org: {
          name: 'Union Square Ventures',
          permalink: 'union-square-ventures'
        },
        person: null
      },
      {
        financial_org: null,
        person: {
          first_name: 'Marc',
          last_name: 'Andreessen',
          permalink: 'marc-andreessen'
        }
      },
      {
        financial_org: null,
        person: {
          first_name: 'Dick',
          last_name: 'Costolo',
          permalink: 'dick-costolo'
        }
      },
      {
        financial_org: null,
        person: {
          first_name: 'Naval',
          last_name: 'Ravikant',
          permalink: 'naval-ravikant'
        }
      },
      {
        financial_org: null,
        person: {
          first_name: 'Ron',
          last_name: 'Conway',
          permalink: 'ron-conway'
        }
      },
      {
        financial_org: null,
        person: {
          first_name: 'Chris',
          last_name: 'Sacca',
          permalink: 'chris-sacca'
        }
      },
      {
        financial_org: null,
        person: {
          first_name: 'Greg',
          last_name: 'Yaitanes',
          permalink: 'greg-yaitanes'
        }
      },
      {
        financial_org: null,
        person: {
          first_name: 'Brian',
          last_name: 'Pokorny',
          permalink: 'brian-pokorny'
        }
      },
      {
        financial_org: { name: 'SV Angel', permalink: 'sv-angel' },
        person: null
      }
    ]
  },
  {
    round_code: 'e',
    raised_amount: 5166511,
    raised_currency_code: 'USD',
    investments: []
  },
  {
    round_code: 'b',
    raised_amount: 9000000,
    raised_currency_code: 'USD',
    investments: [
      {
        financial_org: {
          name: 'Charles River Ventures',
          permalink: 'charles-river-ventures'
        },
        person: null
      },
      {
        financial_org: { name: 'Redpoint Ventures', permalink: 'redpoint-ventures' },
        person: null
      },
      {
        financial_org: {
          name: 'The Kinsey Hills Group',
          permalink: 'kinsey-hills-group'
        },
        person: null
      }
    ]
  }
]

query composta

Consulte e recupere vários campos de documentos incorporados.

A query a seguir usa o compound operador para pesquisar vários níveis de campos embeddedDocuments aninhados na mesma query:

  • Deve corresponder a "funding_rounds.raised_currency_code" com USD

  • Deve corresponder funding_rounds.investments.financial_org.name a Trinity Ventures

Ele retorna todos os campo armazenar dentro do array de objeto funding_rounds, incluindo os campo no funding_rounds.investments. Limita o número de resultados a apenas 5 funding_rounds documentos.

1db.companies.aggregate(
2  {
3    "$search": {
4      "compound": {
5        "must": [{
6          "text": {
7            "path": "funding_rounds.raised_currency_code",
8            "query": "usd"
9          }
10        }],
11        "should": [{
12          "phrase": {
13            "path": "funding_rounds.investments.financial_org",
14            "query": "Trinity Ventures",
15          }
16        }]
17      },
18      "returnStoredSource": true,
19      "returnScope": {
20        "path": "funding_rounds"
21      }
22    }
23  },
24  {
25    "$limit": 5
26  }
27)
[
  {
    round_code: 'a',
    raised_amount: 5250000,
    raised_currency_code: 'USD',
    investments: [
      {
        financial_org: {
          name: 'Frazier Technology Ventures',
          permalink: 'frazier-technology-ventures'
        },
        person: null
      },
      {
        financial_org: { name: 'Trinity Ventures', permalink: 'trinity-ventures' },
        person: null
      }
    ]
  },
  {
    round_code: 'b',
    raised_amount: 9500000,
    raised_currency_code: 'USD',
    investments: [
      {
        financial_org: { name: 'Accel Partners', permalink: 'accel-partners' },
        person: null
      },
      {
        financial_org: {
          name: 'Frazier Technology Ventures',
          permalink: 'frazier-technology-ventures'
        },
        person: null
      },
      {
        financial_org: { name: 'Trinity Ventures', permalink: 'trinity-ventures' },
        person: null
      }
    ]
  },
  {
    round_code: 'c',
    raised_amount: 25000000,
    raised_currency_code: 'USD',
    investments: [
      {
        financial_org: { name: 'DAG Ventures', permalink: 'dag-ventures' },
        person: null
      },
      {
        financial_org: { name: 'Accel Partners', permalink: 'accel-partners' },
        person: null
      },
      {
        financial_org: { name: 'Trinity Ventures', permalink: 'trinity-ventures' },
        person: null
      },
      {
        financial_org: {
          name: 'Frazier Technology Ventures',
          permalink: 'frazier-technology-ventures'
        },
        person: null
      }
    ]
  },
  {
    round_code: 'angel',
    raised_amount: 500000,
    raised_currency_code: 'USD',
    investments: [
      {
        financial_org: null,
        person: {
          first_name: 'Peter',
          last_name: 'Thiel',
          permalink: 'peter-thiel'
        }
      },
      {
        financial_org: null,
        person: {
          first_name: 'Reid',
          last_name: 'Hoffman',
          permalink: 'reid-hoffman'
        }
      }
    ]
  },
  {
    round_code: 'a',
    raised_amount: 12700000,
    raised_currency_code: 'USD',
    investments: [
      {
        financial_org: { name: 'Accel Partners', permalink: 'accel-partners' },
        person: null
      },
      {
        financial_org: null,
        person: {
          first_name: 'Mark',
          last_name: 'Pincus',
          permalink: 'mark-pincus'
        }
      },
      {
        financial_org: null,
        person: {
          first_name: 'Reid',
          last_name: 'Hoffman',
          permalink: 'reid-hoffman'
        }
      }
    ]
  }
]

Agrupar filhos por pai

Agrupe os filhos por pai usando o campo meta searchRootDocumentId.

A seguinte query usa o range (Operador de Pesquisa do MongoDB) para consultar o campo funding_rounds.raised_amount por valores maiores ou iguais a 5000000 e menores ou iguais a 10000000. Ele define o escopo da query como campo funding_rounds usando a opção returnScope. Ele agrupa os funding_rounds correspondentes em cada empresa-mãe usando o meta campo searchRootDocumentId como chave de grupo e calcula a média raised_amount por empresa no campo avgRaisedAmount. Ele classifica os resultados por avgRaisedAmount em ordem decrescente e limita o número de resultados a 10 empresas.

1db.companies.aggregate([
2  {
3    "$search": {
4      "returnStoredSource": true,
5      "returnScope": {
6        "path": "funding_rounds"
7      },
8      "range": {
9        "path": "funding_rounds.raised_amount",
10        "gte": 5000000,
11        "lte": 10000000
12      }
13    }
14  },
15  {
16    "$group": {
17      "_id": { "$meta": "searchRootDocumentId" },
18      "funding_rounds": {
19        "$push": {
20          "round_code": "$round_code",
21          "raised_amount": "$raised_amount",
22          "raised_currency_code": "$raised_currency_code"
23        }
24      },
25      "avgRaisedAmount": { "$avg": "$raised_amount" }
26    }
27  },
28  { "$sort": { "avgRaisedAmount": -1 } },
29  { "$limit": 10 }
30])
[
  {
    _id: ObjectId('52cdef7d4bab8bd675298f82'),
    funding_rounds: [
      {
        round_code: 'a',
        raised_amount: 10000000,
        raised_currency_code: 'USD'
      }
    ],
    avgRaisedAmount: 10000000
  },
  {
    _id: ObjectId('52cdef7e4bab8bd67529af80'),
    funding_rounds: [
      {
        round_code: 'b',
        raised_amount: 10000000,
        raised_currency_code: 'USD'
      }
    ],
    avgRaisedAmount: 10000000
  },
  {
    _id: ObjectId('52cdef7f4bab8bd67529be3d'),
    funding_rounds: [
      {
        round_code: 'a',
        raised_amount: 10000000,
        raised_currency_code: 'USD'
      }
    ],
    avgRaisedAmount: 10000000
  },
  {
    _id: ObjectId('52cdef7f4bab8bd67529c52d'),
    funding_rounds: [
      {
        round_code: 'unattributed',
        raised_amount: 10000000,
        raised_currency_code: 'USD'
      }
    ],
    avgRaisedAmount: 10000000
  },
  {
    _id: ObjectId('52cdef7e4bab8bd67529ab31'),
    funding_rounds: [
      {
        round_code: 'c',
        raised_amount: 10000000,
        raised_currency_code: 'USD'
      },
      {
        round_code: 'a',
        raised_amount: 10000000,
        raised_currency_code: 'USD'
      }
    ],
    avgRaisedAmount: 10000000
  },
  {
    _id: ObjectId('52cdef7e4bab8bd67529aa94'),
    funding_rounds: [
      {
        round_code: 'b',
        raised_amount: 10000000,
        raised_currency_code: 'USD'
      }
    ],
    avgRaisedAmount: 10000000
  },
  {
    _id: ObjectId('52cdef7f4bab8bd67529be6f'),
    funding_rounds: [
      {
        round_code: 'a',
        raised_amount: 10000000,
        raised_currency_code: 'USD'
      }
    ],
    avgRaisedAmount: 10000000
  },
  {
    _id: ObjectId('52cdef7c4bab8bd6752985cb'),
    funding_rounds: [
      {
        round_code: 'd',
        raised_amount: 10000000,
        raised_currency_code: 'USD'
      }
    ],
    avgRaisedAmount: 10000000
  },
  {
    _id: ObjectId('52cdef7d4bab8bd675299fd1'),
    funding_rounds: [
      {
        round_code: 'c',
        raised_amount: 10000000,
        raised_currency_code: 'USD'
      }
    ],
    avgRaisedAmount: 10000000
  },
  {
    _id: ObjectId('52cdef7f4bab8bd67529c2c8'),
    funding_rounds: [
      {
        round_code: 'debt_round',
        raised_amount: 10000000,
        raised_currency_code: 'USD'
      }
    ],
    avgRaisedAmount: 10000000
  }
]

Buscar campos pai após o filtro

Recupere os campos do documento pai após o filtro nos campos do documento incorporado.

A seguinte query usa o range (MongoDB Search Operator) para consultar o campo funding_rounds.raised_amount por valores maiores ou iguais a 5000000 e menores ou iguais a 10000000. Ela define o escopo da query como o campo funding_rounds usando a opção returnScope. Ela classifica os funding_rounds correspondentes por raised_amount em ordem decrescente e limita os resultados às 10 principais rodadas de financiamento. Em seguida, ela usa o meta campo searchRootDocumentId para unir cada rodada de financiamento à sua empresa-mãe na coleção companies e retorna o name da empresa junto com os campos round_code, raised_amount e raised_currency_code da rodada de financiamento.

1db.companies.aggregate([
2  {
3    "$search": {
4      "returnStoredSource": true,
5      "returnScope": {
6        "path": "funding_rounds"
7      },
8      "range": {
9        "path": "funding_rounds.raised_amount",
10        "gte": 5000000,
11        "lte": 10000000
12      }
13    }
14  },
15  { "$sort": { "raised_amount": -1 } },
16  { "$limit": 10 },
17  { "$addFields": { "root_id": { "$meta": "searchRootDocumentId" } } },
18  {
19    "$lookup": {
20      "from": "companies",
21      "localField": "root_id",
22      "foreignField": "_id",
23      "as": "company"
24    }
25  },
26  { "$unwind": "$company" },
27  {
28    "$project": {
29      "_id": 0,
30      "round_code": 1,
31      "raised_amount": 1,
32      "raised_currency_code": 1,
33      "company.name": 1
34    }
35  }
36])
[
  {
    round_code: 'partial',
    raised_amount: 10000000,
    raised_currency_code: 'USD',
    company: { name: 'WeFi' }
  },
  {
    round_code: 'b',
    raised_amount: 10000000,
    raised_currency_code: 'USD',
    company: { name: 'LinkedIn' }
  },
  {
    round_code: 'a',
    raised_amount: 10000000,
    raised_currency_code: 'USD',
    company: { name: 'Lotame' }
  },
  {
    round_code: 'c',
    raised_amount: 10000000,
    raised_currency_code: 'USD',
    company: { name: 'OpenX' }
  },
  {
    round_code: 'b',
    raised_amount: 10000000,
    raised_currency_code: 'USD',
    company: { name: 'AddThis' }
  },
  {
    round_code: 'a',
    raised_amount: 10000000,
    raised_currency_code: 'USD',
    company: { name: 'Terabitz' }
  },
  {
    round_code: 'b',
    raised_amount: 10000000,
    raised_currency_code: 'USD',
    company: { name: 'Six Apart' }
  },
  {
    round_code: 'a',
    raised_amount: 10000000,
    raised_currency_code: 'USD',
    company: { name: 'Snocap' }
  },
  {
    round_code: 'b',
    raised_amount: 10000000,
    raised_currency_code: 'USD',
    company: { name: 'Wikia' }
  },
  {
    round_code: 'unattributed',
    raised_amount: 10000000,
    raised_currency_code: 'USD',
    company: { name: 'Mashery' }
  }
]

Voltar

searchSequenceToken

Próximo

Opções de desempenho

Nesta página