executar uma query de pesquisa Atlas

Visão geral

Neste guia, você pode aprender como usar o Backend do Django MongoDB para executar consultas do Atlas Search em uma coleção. O Atlas Search permite realizar pesquisas de texto completo em collections hospedadas no MongoDB Atlas. Os índices do Atlas Search especificam o comportamento da busca 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 Theater modelo do 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 Atlas

Importante

Requisitos de índice

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

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

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

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

As seções seguintes mostram como executar queries do Atlas Search usando cada classe de expressão suportada.

SearchEquals

Importante

Requisitos adicionais de índice

Antes de usar a expressão SearchEquals em uma query do Atlas Search, crie um índice do Atlas Search que indexe o campo relevante como o tipo token. Você não pode usar a classe SearchIndex do Django MongoDB Backend para criar esse índice, mas pode usar os métodos do driver do PyMongo operando diretamente em seu MongoClient. Para saber mais, consulte Operações do MongoClient no guia Executar queries de banco de dados brutos.

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 expressão SearchAutocomplete em uma query do Atlas Search, crie um índice do Atlas Search que indexe o campo relevante como o tipo autocomplete. Você não pode usar a classe SearchIndex do Django MongoDB Backend para criar esse índice, mas pode usar os métodos do driver do PyMongo operando diretamente em seu MongoClient. Para saber mais, consulte Operações do MongoClient no guia Executar queries de banco de dados brutos.

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 utilizar a expressão SearchIn em uma query do Atlas Search , crie um índice do Atlas Search no campo relevante. Se você estiver consultando um campo string, deverá indexá-lo como o tipo de token. Você não pode usar a classe SearchIndex do Django MongoDB Backend para criar esse índice, mas pode usar os métodos do driver do PyMongo operando diretamente em seu MongoClient. Para saber mais, consulte Operações do MongoClient no guia Executar queries de banco de dados brutos.

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ônimo definido no índice do Atlas Search.
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 utilizar a expressão SearchRange em uma query do Atlas Search , crie um índice do Atlas Search no campo relevante. Se você estiver consultando um campo string, deverá indexá-lo como o tipo de token. Você não pode usar a classe SearchIndex do Django MongoDB Backend para criar esse índice, mas pode usar os métodos do driver do PyMongo operando diretamente em seu MongoClient. Para saber mais, consulte Operações do MongoClient no guia Executar queries de banco de dados brutos.

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 expressão SearchGeoShape em uma query do Atlas Search, crie um índice do Atlas Search que indexe o campo relevante como o tipo geoespacial com a propriedade indexShapes definida como true. Você não pode usar a classe SearchIndex do Django MongoDB Backend para criar esse índice, mas pode usar os métodos do driver do PyMongo operando diretamente em seu MongoClient. Para saber mais, consulte Operações do MongoClient no guia Executar queries de banco de dados brutos.

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 expressão SearchGeoWithin em uma query do Atlas Search, crie um índice do Atlas Search que indexe o campo de query como o tipo geoespacial. Você não pode usar a classe SearchIndex do Django MongoDB Backend para criar esse índice, mas pode usar os métodos do driver do PyMongo operando diretamente em seu MongoClient. Para saber mais, consulte Operações do MongoClient no guia Executar queries de banco de dados brutos.

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 no Atlas Search que combinam múltiplas expressões de pesquisa das seguintes maneiras:

Usar a classe CompoundExpression
Usar operadores bitwise

Usar a classe CompoundExpression

A expressão CompoundExpression permite usar a lógica booleana para combinar várias expressões do Atlas Search . 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 utilizar os seguintes operadores bitwise para combinar expressões Atlas Search :

&: 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 do Atlas Search . 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 Atlas Search, consulte Índices do Atlas Search no guia Criar índices.

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

Voltar

Executar queries brutas

Atlas Vector Search