Menu Docs
Página inicial do Docs
/ /
Interaja com dados
Página inicial do Docs
/ /
Backend do Django MongoDB
/
Interaja com dados
Página inicial do Docs
/
Bibliotecas do cliente
/
Python
/
Backend do Django MongoDB
/
Interaja com dados

Executar uma query de pesquisa do MongoDB

Visão geral

Neste guia, você pode aprender como usar o Backend do Django MongoDB para executar queries do MongoDB Search em uma coleção. O MongoDB Search permite realizar pesquisas de texto completo em suas collections do MongoDB . Os índices de pesquisa do MongoDB especificam o comportamento da pesquisa e quais campos indexar.

Dados de amostra

Os exemplos nesta aba usam os modelos Movie e Theater, que representam as collections sample_mflix.movies e sample_mflix.theaters dos conjuntos de dados de amostra do Atlas. As classes de modelo têm as seguintes definições:

from django.db import models
from django.contrib.gis.db import models
from django_mongodb_backend.fields import ArrayField
class Movie(models.Model):
    title = models.CharField(max_length=200)
    plot = models.TextField(blank=True)
    runtime = models.IntegerField(default=0)
    genres = ArrayField(models.CharField(max_length=100), null=True, blank=True)
    class Meta:
        db_table = "movies"
        managed = False
    def __str__(self):
        return self.title
class Theater(models.Model):
    theater_id = models.IntegerField(default=0, db_column="theaterId")
    geo = models.PointField(db_column="location.geo")
    class Meta:
        db_table = "theaters"
        managed = False
    
    def __str__(self):
        return self.theater_id

Dica

Campos GeoDjango

O modelo do Theater utiliza um GeoDjango PointField denominado geo para armazenar dados geoespaciais. Para saber mais sobre os campos GeoDjango, consulte o guia Dados geoespaciais do modelo.

Os modelos Movie e Theater incluem uma classe Meta interna, que especifica os metadados do modelo, e um método __str__(), que define a representação de string do modelo. Para saber mais sobre esses recursos de modelo, consulte Definir um modelo no guia Criar modelos.

Exemplos de código de execução

Você pode usar o shell interativo do Python para executar os exemplos de código. Para entrar na shell, execute o seguinte comando no diretório raiz do seu projeto:

python manage.py shell

Depois de inserir o shell do Python, certifique-se de importar os seguintes modelos e módulos:

from <your application name>.models import Movie, Theater
from django_mongodb_backend.expressions import (
     SearchEquals, SearchAutocomplete, SearchExists, SearchIn,
     SearchPhrase, SearchQueryString, SearchRange, SearchRegex,
     SearchText, SearchWildcard, SearchGeoShape, SearchGeoWithin,
     SearchMoreLikeThis, CompoundExpression, SearchScoreOption
)

Para saber como criar um aplicação Django que use o modelo Movie e o shell interativo Python para interagir com documentos do MongoDB, acesse o tutorial de Introdução.

Executar uma query de pesquisa do MongoDB

Importante

Requisitos de índice

Antes de executar uma query do MongoDB Search, você deve criar um índice de pesquisa nos campos relevantes. Para saber como criar índices de pesquisa, consulte Índices de pesquisa no guia Criar índices.

Para executar uma query no MongoDB Search, use o método annotate() da API QuerySet do Django. Passe seus critérios de pesquisa do MongoDB , incluindo seu operador de pesquisa, como um argumento score para annotate(). O seguinte código mostra a sintaxe básica para executar uma query de pesquisa:

Model.objects.annotate(
   score=<Search Operator>(path="<field name", <additional arguments>)
)

Para especificar operadores de pesquisa, use as classes de expressão fornecidas pelo módulo django_mongodb_backend.expressions. Cada classe corresponde a um operador de pesquisa.

As seções seguintes mostram como executar queries de pesquisa utilizando cada classe de expressão suportada.

SearchEquals

Importante

Requisitos adicionais de índice

Antes de usar a SearchEquals expressão em uma query de pesquisa, crie um índice de pesquisa que indexe o campo relevante como o tipo de token. A partir do Django MongoDB Backend5.2.2 v, você pode usar o argumento field_mappings para criar esse índice.

A expressão SearchEquals corresponde a documentos em que um campo é igual a um valor especificado. Isso corresponde ao operador igual do MongoDB.

Para utilizar este operador, passe os seguintes argumentos para o construtor SearchEquals():

  • path: O nome do campo a ser pesquisado. Você pode especificar um valor de string ou uma F instância.

  • value: O valor a ser correspondido. Você pode especificar um valor de string ou uma Value instância.

  • score: (Opcional) Uma instância SearchScoreOption que configura a pontuação de relevância.

O exemplo a seguir usa o operador SearchEquals para consultar a collection sample_mflix.movies para documentos que tenham um valor title de "Finding Nemo":

Movie.objects.annotate(score=SearchEquals(path="title", value="Finding Nemo"))

SearchAutocomplete

Importante

Requisitos adicionais de índice

Antes de usar a SearchAutocomplete expressão em uma query de pesquisa, crie um índice de pesquisa que indexe o campo relevante como o tipo de preenchimento automático. A partir do Django MongoDB Backend5.2.2 v, você pode usar o argumento field_mappings para criar esse índice.

A expressão SearchAutocomplete procura uma palavra ou frase que contém uma sequência de caracteres de uma string de entrada incompleta. Corresponde ao operador de preenchimento automático do MongoDB.

Para utilizar este operador, passe os seguintes argumentos para o construtor SearchAutocomplete():

  • path: O nome do campo a ser pesquisado. Você pode especificar um valor de string ou uma F instância.

  • query: A string de entrada para o preenchimento automático. Você pode especificar um valor de string ou uma Value instância.

  • fuzzy: (Opcional) Um dicionário que habilita a correspondência difusa e permite configurar seu comportamento. Por exemplo, você pode especificar {"maxEdits": 1} para permitir a alteração de um caractere antes de corresponder ao termo de pesquisa . Para visualizar todos os valores disponíveis, consulte as opções de preenchimento automático na documentação do MongoDB Atlas.

  • token_order: (Opcional) Uma string que configura o comportamento da sequência de token. Você pode definir esse valor como "sequential" ou "any".

  • score: (Opcional) Uma instância SearchScoreOption que configura a pontuação de relevância.

O exemplo seguinte utiliza a expressão SearchAutocomplete para fazer query da collection sample_mflix.movies para documentos que têm um valor title começando com "First":

Movie.objects.annotate(score=SearchAutocomplete(path="title", query="First"))

SearchExists

A expressão SearchExists corresponde a documentos nos quais existe um campo especificado. Isso corresponde ao operador MongoDB exists.

Para utilizar este operador, passe os seguintes argumentos para o construtor SearchExists():

  • path: O nome do campo a ser correspondido. Você pode especificar um valor de string ou uma F instância.

  • score: (Opcional) Uma instância SearchScoreOption que configura a pontuação de relevância.

O exemplo seguinte utiliza a expressão SearchExists para consultar a collection sample_mflix.movies para documentos que tenham um campo plot :

Movie.objects.annotate(score=SearchExists(path="plot"))

SearchIn

Importante

Requisitos adicionais de índice

Antes de usar a SearchIn expressão em uma query de pesquisa, crie um índice de pesquisa no campo relevante. Se você estiver consultando um string campo, deverá indexá-lo como o tipo de token. A partir de Django MongoDB Backend v,5.2.2 você pode usar o argumento field_mappings para criar esse índice.

A expressão SearchIn corresponde a documentos nos quais o valor de um campo está em uma determinada lista. Corresponde ao operador MongoDB in.

Para utilizar este operador, passe os seguintes argumentos para o construtor SearchIn():

  • path: O nome do campo a ser pesquisado. Você pode especificar um valor de string ou uma F instância.

  • value: A lista de valores a serem correspondidos. Você pode especificar uma lista de valores ou uma Value instância.

  • score: (Opcional) Uma instância SearchScoreOption que configura a pontuação de relevância.

O exemplo seguinte utiliza a expressão SearchIn para consultar a collection sample_mflix.movies para documentos que tenham um valor runtime de 100, 200 ou 300 minutos:

Movie.objects.annotate(score=SearchIn(path="runtime", value=[100, 200, 300]))

SearchPhrase

A expressão SearchPhrase corresponde a sequências exatas ou quase exatas de termos em um campo. Corresponde ao operador de frase do MongoDB.

Para utilizar este operador, passe os seguintes argumentos para o construtor SearchPhrase():

  • path: O nome do campo a ser pesquisado. Você pode especificar um valor de string ou uma F instância.

  • query: A frase a ser correspondida. Você pode especificar uma string ou uma lista de strings.

  • slop: (Opcional) O número máximo de termos permitidos entre termos de frase.

  • synonyms: (Opcional) O nome de um mapeamento de sinônimos definido em seu índice de pesquisa.

  • score: (Opcional) Uma instância SearchScoreOption que configura a pontuação de relevância.

O exemplo a seguir usa a expressão SearchPhrase para fazer query da collection sample_mflix.movies para documentos que tenham a frase "space adventure" em seu campo plot , permitindo até 2 palavras entre esses termos:

Movie.objects.annotate(score=SearchPhrase(path="plot", query="space adventure", slop=2))

SearchQueryString

O operador SearchQueryString permite executar pesquisas de texto, curinga, expressão regular, difusa e intervalo em campos do string. Corresponde ao operador queryString do MongoDB.

Para utilizar este operador, passe os seguintes argumentos para o construtor SearchQueryString():

  • path: O nome do campo a ser pesquisado. Você pode especificar um valor de string ou uma F instância.

  • query: A string de query no estilo Lucene. Para saber mais sobre a sintaxe de consulta do Lucene, consulte a documentação do Apache Lucene.

  • score: (Opcional) Uma instância SearchScoreOption que configura a pontuação de relevância.

O exemplo a seguir usa a expressão SearchQueryString para consultar a coleção sample_mflix.movies para documentos que correspondem a uma query de estilo Lucene no campo plot :

Movie.objects.annotate(score=SearchQueryString(path="plot", query="romance AND (paris OR tokyo)"))

Search Range

Importante

Requisitos adicionais de índice

Antes de usar a SearchRange expressão em uma query de pesquisa, crie um índice de pesquisa no campo relevante. Se você estiver consultando um string campo, deverá indexá-lo como o tipo de token. A partir de Django MongoDB Backend v,5.2.2 você pode usar o argumento field_mappings para criar esse índice.

A expressão SearchRange pesquisa valores dentro de uma faixa especificada. Você pode fornecer um intervalo de valores numéricos, de data, de string ou de ObjectId. Corresponde ao operador de faixa do MongoDB.

Para utilizar este operador, passe os seguintes argumentos para o construtor SearchRange():

  • path: O nome do campo a ser pesquisado. Você pode especificar um valor de string ou uma F instância.

  • lt: (Opcional) Limite superior exclusivo (<)

  • lte: (Opcional) Limite superior inclusivo (<=)

  • gt: (Opcional) Limite inferior exclusivo (>)

  • gte: (Opcional) Limite inferior inclusivo (>=)

  • score: (Opcional) Uma instância SearchScoreOption que configura a pontuação de relevância.

O exemplo seguinte utiliza a expressão SearchRange para consultar a collection sample_mflix.movies para documentos que tenham um valor de runtime entre 90 e 120 minutos.

Movie.objects.annotate(score=SearchRange(path="runtime", gt=90, lt=120))

SearchRegex

A expressão SearchRegex corresponde aos valores do campo de string usando uma expressão regular. Isso corresponde ao operador regex do MongoDB.

Para utilizar este operador, passe os seguintes argumentos para o construtor SearchRegex():

  • path: O nome do campo a ser pesquisado. Você pode especificar um valor de string ou uma F instância.

  • query: a string de expressão regular usada para pesquisar o conteúdo do campo .

  • allow_analyzed_field: (Opcional) Um valor booleano que indica se a correspondência com os campos analisados deve ser permitida. O valor padrão é False.

  • score: (Opcional) Uma instância SearchScoreOption que configura a pontuação de relevância.

O exemplo seguinte utiliza a expressão SearchRegex para fazer uma query da collection sample_mflix.movies para documentos que tenham um valor title que inclua a palavra "winter":

Movie.objects.annotate(score=SearchRegex(path="title", query=r".*winter.*"))

Texto de pesquisa

A expressão SearchText executa uma pesquisa de texto completo nos campos da string. Corresponde ao operador de texto do MongoDB.

Para utilizar este operador, passe os seguintes argumentos para o construtor SearchText():

  • path: O nome do campo a ser pesquisado. Você pode especificar um valor de string ou uma F instância.

  • query: o termo ou frase de pesquisa.

  • fuzzy: (Opcional) Um dicionário que habilita a correspondência difusa e permite configurar seu comportamento. Por exemplo, você pode especificar {"maxEdits": 1} para permitir a alteração de um caractere antes de corresponder ao termo de pesquisa .

  • match_criteria: (Opcional) Se deseja corresponder a documentos que contêm "all" ou "any" dos termos de pesquisa. O valor padrão é "any".

  • synonyms: (Opcional) O nome de um mapeamento de sinônimo definido no índice do Atlas .

  • score: (Opcional) Uma instância SearchScoreOption que configura a pontuação de relevância.

O exemplo a seguir usa a expressão SearchText para fazer query da collection sample_mflix.movies para documentos que tenham "sudden disappearance" em seu campo plot , com a correspondência difusa ativada:

Movie.objects.annotate(score=SearchText(
    path="plot", 
    query="sudden disappearance", 
    fuzzy={"maxEdits": 2}, 
    match_criteria="all"
))

SearchWildcard

A expressão SearchWildcard corresponde a strings usando padrões curinga. Corresponde ao operador curinga do MongoDB.

Para utilizar este operador, passe os seguintes argumentos para o construtor SearchWildcard():

  • path: O nome do campo a ser pesquisado. Você pode especificar um valor de string ou uma F instância.

  • query: uma string curinga que pode incluir o caractere *, para corresponder a qualquer sequência de caracteres, e o caractere ?, para corresponder a qualquer caractere único.

  • allow_analyzed_field: (Opcional) Um valor booleano que permite a correspondência com campos analisados. O valor padrão é False.

  • score: (Opcional) Uma instância SearchScoreOption que configura a pontuação de relevância.

O exemplo seguinte utiliza a expressão SearchWildcard para fazer query da collection sample_mflix.movies para documentos que tenham um title que começa com "Star" e termina com qualquer caractere:

Movie.objects.annotate(score=SearchWildcard(path="title", query="Star*"))

SearchGeoShape

Importante

Requisitos adicionais de índice

Antes de utilizar a SearchGeoShape expressão em uma query de Pesquisa, crie um índice de Pesquisa que indexe o campo relevante como o tipo geoespacial com a indexShapes propriedade definida true como. A partir de Django MongoDB Backend v,5.2.2 você pode usar o argumento field_mappings para criar esse índice.

A expressão SearchGeoShape filtra documentos com base em relações espaciais com uma forma. Corresponde ao operador geoShape do MongoDB.

Para utilizar este operador, passe os seguintes argumentos para o construtor SearchGeoShape():

  • path: O nome do campo a ser pesquisado. Você pode especificar um valor de string ou uma F instância.

  • relation: A relação especial para testar. Os valores válidos incluem "within", "intersects" e "disjoint".

  • geometry: Um objeto de geometria GeoJSON para comparar.

  • score: (Opcional) Uma instância SearchScoreOption que configura a pontuação de relevância.

O exemplo seguinte utiliza a expressão SearchGeoShape para fazer query da collection sample_mflix.theaters para documentos que tenham um valor de geo dentro de um polígono especificado:

chicago = {
    "type": "Polygon",
    "coordinates": [
        [
            [-87.851, 41.976],
            [-87.851, 41.653],
            [-87.651, 41.653],
            [-87.651, 41.976],
            [-87.851, 41.976],
        ]
    ]
}
theaters = Theater.objects.annotate(score=SearchGeoShape(
    path="geo", 
    relation="within", 
    geometry=chicago
))

SearchGeoWithin

Importante

Requisitos adicionais de índice

Antes de utilizar a SearchGeoWithin expressão em uma query de Pesquisa, crie um índice de Pesquisa que indexe o campo de query como o tipo geoespacial. A partir do Django MongoDB Backend v,5.2.2 você pode usar o argumento field_mappings para criar esse índice.

A expressão SearchGeoWithin filtra documentos com campos geográficos contidos dentro de uma forma especificada. Isto corresponde ao operador geoWithin MongoDB.

Para utilizar este operador, passe os seguintes argumentos para o construtor SearchGeoWithin():

  • path: O nome do campo a ser pesquisado. Você pode especificar um valor de string ou uma F instância.

  • kind: o tipo de geometria GeoJSON: "circle", "box" ou "geometry".

  • geometry: A geometria GeoJSON definindo o limite geoespacial.

  • score: (Opcional) Uma instância SearchScoreOption que configura a pontuação de relevância.

O exemplo seguinte utiliza o operador SearchGeoWithin para consultar a collection sample_mflix.theaters para documentos que tenham um valor de geo dentro de um círculo especificado:

circle = {
    "center": {"type": "Point", "coordinates": [-73.98, 40.75]},
    "radius": 5000
}
theaters = Theater.objects.annotate(score=SearchGeoWithin(
    path="geo", 
    kind="circle", 
    geometry=circle
))

SearchMoreLikeThis

A expressão SearchMoreLikeThis encontra documentos semelhantes aos exemplos fornecidos. Corresponde ao operador MongoDB moreLikeThis.

Para utilizar este operador, passe os seguintes argumentos para o construtor SearchMoreLikeThis():

  • documents: Uma lista de exemplo de documentos ou expressões que servem como referências para similaridade.

  • score: (Opcional) Uma instância SearchScoreOption que configura a pontuação de relevância.

O exemplo seguinte utiliza a expressão SearchMoreLikeThis para fazer uma query da collection sample_mflix.movies para documentos que são semelhantes a um documento de exemplo fornecido:

Movie.objects.annotate(score=SearchMoreLikeThis([
    {"title": "The Godfather"}, {"genres": ["Crime", "Drama"]}
]))

Combinar Expressões

Você pode executar queries do MongoDB Search que combinam múltiplas expressões de pesquisa das seguintes maneiras:

Usar a classe CompoundExpression

A CompoundExpression expressão permite usar a lógica booleana para combinar várias expressões de pesquisa. Corresponde ao operador composto MongoDB .

Você deve passar um ou mais dos seguintes argumentos para o construtor CompoundExpression():

  • must: Uma lista de expressões às quais os documentos devem corresponder

  • should: Uma lista de expressões que os documentos devem corresponder

  • must_not: Uma lista de expressões que os documentos não devem corresponder

  • filter: Uma lista de expressões que filtram os resultados

Você também pode passar os seguintes argumentos opcionais:

  • minimum_should_match: O número mínimo de should cláusulas que os documentos devem corresponder

  • score: Uma instância SearchScoreOption que configura a pontuação de relevância

Este exemplo utiliza a expressão CompoundExpression para fazer query da collection sample_mflix.movies para documentos que correspondam aos seguintes critérios:

  • plot o campo existe

  • plot campo contém o texto "fast-paced"

  • genres o campo não contém "Romance" ou "Comedy"

plot_exists = SearchExists(path="plot")
plot_text = SearchText(path="plot", query="fast-paced")
genres_range = SearchIn(path="genres", value=["Romance", "Comedy"])
Movie.objects.annotate(
    score=CompoundExpression(
        must=[plot_exists, plot_text],
        must_not=[genres_range]
    )
)

Usar operadores bitwise

Você pode usar os seguintes operadores bitwise para combinar expressões de pesquisa:

  • &: representa uma operação lógica E

  • |: representa uma operação lógica OU

  • ~: representa uma operação lógica NÃO

Este exemplo utiliza o operador | para consultar a collection sample_mflix.movies para documentos que correspondam a um ou ambos os critérios a seguir:

  • plot campo contém o texto "heartwarming"

  • genres o campo contém "Romance" ou "Comedy"

expr = SearchText(path="plot", query="heartwarming") | SearchIn(path="genres", value=["Romance", "Comedy"])
Movie.objects.annotate(score=expr)

Configurar pontuações de relevância

O MongoDB atribui uma pontuação de relevância a cada documento retornado em uma query de pesquisa. Os documentos incluídos em um conjunto de resultados são ordenados da pontuação de relevância mais alta para a mais baixa.

Você pode utilizar a expressão SearchScoreOption para personalizar como o MongoDB calcula e aplica pontuações de relevância. O construtor SearchScoreOption() aceita os seguintes argumentos:

  • boost: Aumenta a pontuação de documentos que correspondem a uma expressão especificada

  • constant: Aplica uma pontuação fixa para todas as correspondências

  • function: aplica uma função para calcular a pontuação

  • path: pontua documentos com base no valor de um campo

Dica

Para saber mais sobre as pontuações de relevância, consulte Pontuação dos documentos nos Resultados na documentação do MongoDB Atlas.

O exemplo a seguir aumenta a pontuação de relevância de documentos que correspondem à expressão SearchEquals por um fator de 3:

boost = SearchScoreOption({"boost": {"value": 3}})
Movie.objects.annotate(
    score=SearchEquals(
        path="title",
        value="Life of Pi",
        score=boost
    )
)

Informações adicionais

Para saber mais sobre como criar índices do MongoDB Search, consulte Índices de pesquisa no guia Criar índices.

Para saber mais sobre queries de pesquisa do MongoDB , consulte Visão geral da pesquisa do MongoDB na documentação do MongoDB Atlas .

Voltar

Executar queries brutas

Próximo

MongoDB Vector Search

Nesta página