/ /

Executar uma query de pesquisa do MongoDB

Visão geral

Neste guia, você aprenderá a fazer pesquisas em seus documentos usando o recurso de pesquisa do MongoDB. A biblioteca PHP permite que você execute query de pesquisa do MongoDB Search usando o Construtor de Agregação.

To learn more about MongoDB Search, see the MongoDB Search Overview. The MongoDB Search implementation for the PHP library internally uses the $search aggregation operator to perform queries. To learn more about this operator, see the $search reference in the Atlas documentation.

Observação

MongoDB Vector Search

Para realizar pesquisas sobre incorporações vetoriais no MongoDB, você pode usar a API de pesquisa vetorial do MongoDB. Para saber mais sobre esse recurso, consulte o Guia Executar uma pesquisa vetorial do MongoDB.

Importante

Requisitos da versão do Atlas e Community Edition

O $search operador de pipeline de agregação está disponível somente para coleções hospedadas em clusters do MongoDB Atlas que executam o MongoDB 4 v.2 ou posterior, ou em clusters do MongoDB Community Edition que executam o MongoDB8 v.2 ou posterior. Para saber mais sobre a configuração necessária e a funcionalidade desse operador, consulte a documentação do MongoDB Search.

Índice de pesquisa do MongoDB

Antes de executar query de pesquisa do MongoDB Search, você deve criar um índice de pesquisa do MongoDB Search em sua coleção. Para aprender mais sobre como criar esse tipo de índice, consulte o guia Índices de pesquisa do MongoDB.

Estágio de agregação da pesquisa

Importe as seguintes classes para o seu aplicativo para executar querys de pesquisa do MongoDB usando o Construtor de Agregação:

use MongoDB\Builder\Search;
use MongoDB\Builder\Stage;

Para criar um estágio $search em seu pipeline de agregação , execute as seguintes ações:

Crie uma array para armazenar os estágios do pipeline.
Chame o método Stage::search() para criar o estágio MongoDB pesquisa.
Dentro do corpo do método search(), use métodos da classe de construtores Search para construir seus critérios da query de pesquisa.

O código a seguir demonstra o modelo para a construção de queries de pesquisa básicas do MongoDB Search:

$pipeline = [
    Stage::search(
        /* MongoDB Search query specifications
        Search::compound(...) */
    ),
];

Exemplos de query de pesquisa do MongoDB

Nesta seção, você pode aprender a executar diferentes tipos de query de pesquisa do MongoDB Search usando o construtor de agregação. Os exemplos nesta seção utilizam dados de amostra da coleção sample_restaurants.restaurants.

Query composta com filtro

Utilize o método Search::compound() para unir dois ou mais operadores em uma única query. Este método aceita argumentos nomeados para suas cláusulas, como must e filter. Em cada cláusula, utilize o método Search::text() para especificar as cadeias de caracteres a serem procuradas ao realizar a pesquisa de texto completo.

Este exemplo executa uma query de pesquisa do MongoDB Search que tem as seguintes especificações:

Inclui uma cláusula must para pesquisar o campo name para a string "kitchen"
Inclui uma cláusula should para classificar altamente documentos em que o campo cuisine inclui "american"
Inclui um campo filter para incluir apenas documentos nos quais o valor borough é "Queens" nos resultados

$pipeline = [
    Stage::search(
        Search::compound(
            must: [
                Search::text(
                    query: 'kitchen',
                    path: 'name',
                ),
            ],
            should: [
                Search::text(
                    query: 'american',
                    path: 'cuisine',
                ),
            ],
            filter: [
                Search::text(
                    query: 'Queens',
                    path: 'borough',
                ),
            ],
        ),
    ),
    Stage::project(
        borough: 1,
        cuisine: 1,
        name: 1,
    ),
    Stage::limit(3),
];
$cursor = $collection->aggregate($pipeline);
foreach ($cursor as $doc) {
    echo json_encode($doc), PHP_EOL;
}

{"_id":...,"borough":"Queens","cuisine":"American","name":"Kitchen Door"}
{"_id":...,"borough":"Queens","cuisine":"American","name":"Cc Kitchen"}
{"_id":...,"borough":"Queens","cuisine":"American","name":"Suite Kitchen"}
// Results truncated

Query de preenchimento automático

A biblioteca PHP oferece o método Search::autocomplete() para executar pesquisas de preenchimento automático em documentos nas suas coleções.

Para saber mais sobre esse tipo de query de pesquisa, consulte a referência de preenchimento automático na documentação do Atlas.

Observação

Seu índice de pesquisa do MongoDB deve ser configurado para queries de preenchimento automático. Para saber mais, consulte Como criar índice de campos para preenchimento automático na documentação do Atlas.

O código a seguir executa uma query de preenchimento automático da pesquisa MongoDB para a string "Lucy" no campo name:

$pipeline = [
    Stage::search(
        Search::autocomplete(
            query: 'Lucy',
            path: 'name',
        ),
    ),
    Stage::limit(3),
    Stage::project(_id: 0, name: 1),
];
$cursor = $collection->aggregate($pipeline);
foreach ($cursor as $doc) {
    echo json_encode($doc), PHP_EOL;
}

{"name":"Juicy Lucy"}
{"name":"Lucy'S Vietnamese Kitchen"}
{"name":"Lucy'S Cantina Royale"}
// Results Truncated

Você também pode passar os seguintes parâmetros opcionais para o método autocomplete() para customizar a query:

Parâmetro opcional	Descrição	Valor padrão
`fuzzy`	Permite a pesquisa difusa e as opções de pesquisa difusa	`false`
`tokenOrder`	Especifica a ordem na qual pesquisar tokens	`'any'`

To learn more about these parameters, see the Options section of the autocomplete operator reference in the Atlas documentation.

opções de pesquisa

Você pode utilizar o método search() para executar muitos tipos de queries de pesquisa do MongoDB Search. Dependendo da query desejada, você pode passar os seguintes parâmetros opcionais para search():

Parâmetro opcional	Tipo	Descrição
`index`	`string`	Fornece o nome do índice de pesquisa MongoDB a ser usado
`highlight`	`array`	Especifica as opções de realce para exibir os termos de pesquisa em seu contexto original
`concurrent`	`bool`	Paraleliza a query de pesquisa entre segmentos em nós de pesquisa dedicados
`count`	`string`	Especifica as opções de contagem para recuperar uma contagem dos resultados
`searchAfter`	`string`	Especifica um ponto de referência para retornar documentos que começam imediatamente após esse ponto
`searchBefore`	`string`	Especifica um ponto de referência para retornar documentos que começam imediatamente antes desse ponto
`scoreDetails`	`bool`	Especifica se um detalhamento da pontuação para os resultados deve ser recuperado
`sort`	`array`	Especifica os campos nos quais classificar os resultados
`returnStoredSource`	`bool`	Especifica se uma pesquisa completa do documento deve ser executada no banco de dados de backend ou se deseja retornar apenas campos de origem armazenados diretamente da Pesquisa MongoDB

To learn more about these parameters, see the Fields section of the $search operator reference in the Atlas documentation.

Voltar

Executar um comando de banco de dados

MongoDB Vector Search