/ /

Backend de Django MongoDB

Interacción con los datos

Docs Home

Librerías de clientes

Python

Backend de Django MongoDB

Interacción con los datos

Ejecuta una MongoDB Search query

Overview

En esta guía, puedes aprender cómo usar Django MongoDB Backend para ejecutar consultas de Búsqueda en MongoDB en una colección. MongoDB Search te permite realizar búsquedas de texto completo en tus colecciones de MongoDB. Los índices de MongoDB Search especifican el comportamiento de la búsqueda y qué campos se deben indexar.

Datos de muestra

Los ejemplos en esta guía utilizan los modelos Movie y Theater, que representan las colecciones sample_mflix.movies y sample_mflix.theaters de los conjuntos de datos de muestra de Atlas. Las clases del modelo tienen las siguientes definiciones:

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

Tip

Campos de GeoDjango

El modelo Theater utiliza un GeoDjango PointField llamado geo para almacenar datos geoespaciales. Para obtener más información sobre los campos de GeoDjango, consulta la guía Modelar datos geoespaciales.

Los modelos Movie y Theater incluyen una clase interna Meta, que especifica los metadatos del modelo, y un método __str__(), que define la representación en string del modelo. Para conocer estas funcionalidades del modelo, consulta Definir un modelo en la guía Crear modelos.

Ejecutar ejemplos de código

Puedes usar la shell interactiva de Python para ejecutar los ejemplos de código. Para ingresar a la shell, ejecute el siguiente comando desde el directorio raíz de su Proyecto:

python manage.py shell

Después de ingresar al shell de Python, asegúrese de importar los siguientes modelos y 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 aprender a crear una aplicación de Django que use el modelo Movie y el shell interactivo de Python para interactuar con documentos de MongoDB, visita el tutorial de Introducción a Django MongoDB Backend.

Ejecuta una MongoDB Search query

Importante

Requisitos de índice

Antes de ejecutar una query de MongoDB Search, debes crear un índice de búsqueda en los campos relevantes. Para aprender cómo crear índices de búsqueda, consulta Índices de búsqueda en la guía Crear índices.

Para ejecutar una consulta de MongoDB Search, utiliza el método annotate() de la API QuerySet de Django. Pasa los criterios de MongoDB Search, incluido el operador de búsqueda, como argumento score a annotate(). El siguiente código muestra la sintaxis básica para ejecutar una consulta de búsqueda:

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

Para especificar operadores de búsqueda, utiliza las clases de expresión proporcionadas por el módulo django_mongodb_backend.expressions. Cada clase corresponde a un operador de búsqueda.

Las siguientes secciones muestran cómo ejecutar consultas de búsqueda mediante cada clase de expresión admitida.

SearchEquals

Importante

Requisitos adicionales de índices

Antes de usar la expresión SearchEquals en una consulta de búsqueda, crea un índice de búsqueda que indexe el campo relevante como el tipo de token. A partir de Django MongoDB Backend v5.2.2, puedes utilizar el argumento field_mappings para crear este índice.

La expresión SearchEquals coincide con los documentos en los que un campo es igual a un valor especificado. Esto corresponde al operador igual en MongoDB.

Para utilizar este operador, pasa los siguientes argumentos al constructor SearchEquals():

pathEl nombre del campo a buscar. Puedes especificar un valor de string o una instancia F.
value: El valor a coincidir. Puedes especificar un valor de string o una instancia Value
score(Opcional) Una instancia de SearchScoreOption que configura la puntuación de relevancia.

El siguiente ejemplo utiliza el operador SearchEquals para consultar la colección sample_mflix.movies para documentos que tengan un valor title de "Finding Nemo":

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

Auto-completado de búsqueda

Importante

Requisitos adicionales de índices

Antes de utilizar la expresión SearchAutocomplete en una consulta de búsqueda, crea un índice de búsqueda que indexe el campo relevante como el tipo de autocompletado. A partir de Django MongoDB Backend v5.2.2, puede usar el argumento field_mappings para crear este índice.

La expresión SearchAutocomplete busca una palabra o frase que contenga una secuencia de caracteres de una string de entrada incompleta. Esto corresponde al operador autocomplete de MongoDB.

Para utilizar este operador, pasa los siguientes argumentos al constructor SearchAutocomplete():

pathEl nombre del campo a buscar. Puedes especificar un valor de string o una instancia F.
query: La input string a autocompletar. Puede especificar un valor de string o una instancia de Value.
fuzzy(Opcional) Un diccionario que habilita la coincidencia difusa y permite configurar su comportamiento. Por ejemplo, puede especificar {"maxEdits": 1} para permitir un cambio de carácter antes de que coincida con el término de búsqueda. Para ver todos los valores disponibles, consulta las opciones de autocompletado en la documentación de MongoDB Atlas.
token_order: (Opcional) Una string que configura el comportamiento de la secuencia de tokens. Puedes establecer este valor en "sequential" o "any".
score(Opcional) Una instancia de SearchScoreOption que configura la puntuación de relevancia.

El siguiente ejemplo utiliza la expresión SearchAutocomplete para consultar la colección sample_mflix.movies en busca de documentos que tengan un valor title que comience con "First":

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

SearchExists

La expresión SearchExists coincide con documentos en los que existe un campo específico. Esto corresponde al operador de MongoDB exists.

Para utilizar este operador, pasa los siguientes argumentos al constructor SearchExists():

path: El nombre del campo que coincide. Puedes especificar un valor de string o una instancia F.
score(Opcional) Una instancia de SearchScoreOption que configura la puntuación de relevancia.

El siguiente ejemplo utiliza la expresión SearchExists para consultar la colección sample_mflix.movies en busca de documentos que tengan un campo plot:

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

Buscar en

Importante

Requisitos adicionales de índices

Antes de usar la expresión SearchIn en una consulta de búsqueda, crea un índice de búsqueda en el campo relevante. Si se está consultando un campo string, se debe indexar como el tipo de token. A partir de Django MongoDB Backend v5.2.2, puede utilizar el argumento field_mappings para crear este índice.

La expresión SearchIn coincide con los documentos en los que el valor de un campo está en una lista dada. Esto corresponde al operador in de MongoDB.

Para utilizar este operador, pasa los siguientes argumentos al constructor SearchIn():

pathEl nombre del campo a buscar. Puedes especificar un valor de string o una instancia F.
valueLa lista de valores para hacer coincidir. Puedes especificar una lista de valores o una instancia Value.
score(Opcional) Una instancia de SearchScoreOption que configura la puntuación de relevancia.

El siguiente ejemplo utiliza la expresión SearchIn para consultar la colección de sample_mflix.movies documentos que tengan un valor runtime de 100, 200o 300 minutos:

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

SearchPhrase

La expresión SearchPhrase coincide con secuencias exactas o casi exactas de términos en un campo. Esto corresponde al operador frase de MongoDB.

Para utilizar este operador, pasa los siguientes argumentos al constructor SearchPhrase():

pathEl nombre del campo a buscar. Puedes especificar un valor de string o una instancia F.
query: La frase a hacer coincidir Puedes especificar un string o una lista de strings.
slop: (Opcional) El número máximo de términos permitidos entre términos de frases.
synonyms=(Opcional) El nombre de una asignación de sinónimos definida en el índice de Búsqueda.
score(Opcional) Una instancia de SearchScoreOption que configura la puntuación de relevancia.

El siguiente ejemplo utiliza la expresión SearchPhrase para consultar la colección sample_mflix.movies en busca de documentos que tengan la frase "space adventure" en su campo plot, permitiendo hasta 2 palabras entre estos términos:

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

SearchQueryString

El operador SearchQueryString le permite realizar búsquedas de texto, comodines, expresiones regulares, difusas y de rango en los campos string. Esto corresponde al operador de queryString de MongoDB.

Para utilizar este operador, pasa los siguientes argumentos al constructor SearchQueryString():

pathEl nombre del campo a buscar. Puedes especificar un valor de string o una instancia F.
query: La string del query al estilo Lucene. Para obtener más información sobre la sintaxis de query de Lucene, consulta la documentación de Apache Lucene.
score(Opcional) Una instancia de SearchScoreOption que configura la puntuación de relevancia.

El siguiente ejemplo utiliza la expresión SearchQueryString para consultar la colección sample_mflix.movies en busca de documentos que coincidan con una consulta de estilo Lucene en el campo plot:

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

SearchRange

Importante

Requisitos adicionales de índices

Antes de usar la expresión SearchRange en una consulta de búsqueda, crea un índice de búsqueda en el campo relevante. Si se está consultando un campo string, se debe indexar como el tipo de token. A partir de Django MongoDB Backend v5.2.2, puede utilizar el argumento field_mappings para crear este índice.

La expresión SearchRange busca valores dentro de un rango especificado. Se puede proporcionar un rango de valores numéricos, fechas, string o ObjectId. Esto corresponde al operador de rango de MongoDB.

Para utilizar este operador, pasa los siguientes argumentos al constructor SearchRange():

pathEl nombre del campo a buscar. Puedes especificar un valor de string o una instancia F.
lt: (Opcional) Límite superior exclusivo (<)
lte(Opcional) Límite superior inclusivo (<=)
gt(Opcional) Cota inferior exclusiva (>)
gte(Opcional) Límite inferior inclusivo (>=)
score(Opcional) Una instancia de SearchScoreOption que configura la puntuación de relevancia.

El siguiente ejemplo utiliza la expresión SearchRange para consultar la colección sample_mflix.movies en busca de documentos que tengan un valor de runtime entre 90 y 120 minutos.

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

SearchRegex

La expresión SearchRegex coincide con los valores del campo string mediante una expresión regular. Esto corresponde al operador expresión regular de MongoDB.

Para utilizar este operador, pasa los siguientes argumentos al constructor SearchRegex():

pathEl nombre del campo a buscar. Puedes especificar un valor de string o una instancia F.
query: La string de la expresión regular que se usa para buscar en el contenido del campo.
allow_analyzed_field:: (Opcional) Un valor booleano que indica si se permite la coincidencia en campos analizados. El valor por defecto es False.
score(Opcional) Una instancia de SearchScoreOption que configura la puntuación de relevancia.

El siguiente ejemplo usa la expresión SearchRegex para consultar la colección sample_mflix.movies en busca de documentos que tengan un valor title que incluya la palabra "winter":

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

SearchText

La expresión SearchText realiza una búsqueda de texto completo en campos de string. Esto corresponde al operador de texto de MongoDB.

Para utilizar este operador, pasa los siguientes argumentos al constructor SearchText():

pathEl nombre del campo a buscar. Puedes especificar un valor de string o una instancia F.
query: El término o frase de búsqueda.
fuzzy(Opcional) Un diccionario que habilita la coincidencia difusa y permite configurar su comportamiento. Por ejemplo, puedes especificar {"maxEdits": 1} para permitir un cambio de un carácter antes de hacer coincidir el término de búsqueda.
match_criteriaOpcional: Se recomienda a los usuarios que tengan en cuenta si quieren que el sistema busque documentos que contengan "all" o "any" de los términos de búsqueda. El valor por defecto es "any".
synonyms: (Opcional) El nombre de una asignación de sinónimos definida en tu índice de Atlas.
score(Opcional) Una instancia de SearchScoreOption que configura la puntuación de relevancia.

El siguiente ejemplo utiliza la expresión SearchText para consultar la colección sample_mflix.movies en busca de documentos que tengan "sudden disappearance" en su campo plot, con coincidencia difusa habilitada:

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

SearchWildcard

La expresión SearchWildcard coincide con las cadenas usando patrones de comodines. Esto corresponde al operador wildcard de MongoDB.

Para utilizar este operador, pasa los siguientes argumentos al constructor SearchWildcard():

pathEl nombre del campo a buscar. Puedes especificar un valor de string o una instancia F.
query: Una cadena comodín que puede incluir el carácter *, para coincidir con cualquier secuencia de caracteres, y el carácter ?, para coincidir con cualquier carácter único.
allow_analyzed_field: (Opcional) Un valor booleano que permite la coincidencia con campos analizados. El valor por defecto es False.
score(Opcional) Una instancia de SearchScoreOption que configura la puntuación de relevancia.

En el siguiente ejemplo se utiliza la expresión SearchWildcard para query la colección sample_mflix.movies de documentos que tengan un title que empiece por "Star" y termine por cualquier carácter:

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

SearchGeoShape

Importante

Requisitos adicionales de índices

Antes de utilizar la expresión SearchGeoShape en una consulta de búsqueda, crea un índice de búsqueda que indexe el campo relevante como el tipo geo con la propiedad indexShapes establecida en true. A partir de Django MongoDB Backend v5.2.2, puedes utilizar el argumento field_mappings para crear este índice.

La expresión SearchGeoShape filtra documentos en función de relaciones espaciales con una forma. Esto corresponde al operador geoShape de MongoDB.

Para utilizar este operador, pasa los siguientes argumentos al constructor SearchGeoShape():

pathEl nombre del campo a buscar. Puedes especificar un valor de string o una instancia F.
relationLa relación espacial para probar. Los valores válidos incluyen "within", "intersects" y "disjoint".
geometry: Un objeto de geometría GeoJSON para comparar.
score(Opcional) Una instancia de SearchScoreOption que configura la puntuación de relevancia.

El siguiente ejemplo usa la expresión SearchGeoShape para consultar la colección sample_mflix.theaters en busca de documentos que tengan un valor geo dentro de un 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
))

BúsquedaGeoDentro

Importante

Requisitos adicionales de índices

Antes de utilizar la expresión SearchGeoWithin en una consulta de búsqueda, crea un índice de búsqueda que indexe el campo de consulta como el tipo geo. A partir de Django MongoDB Backend v5.2.2, puede usar el argumento field_mappings para crear este índice.

La expresión SearchGeoWithin filtra documentos con campos geográficos contenidos dentro de una forma especificada. Corresponde al operador geoWithin de MongoDB.

Para utilizar este operador, pasa los siguientes argumentos al constructor SearchGeoWithin():

pathEl nombre del campo a buscar. Puedes especificar un valor de string o una instancia F.
kind: El tipo de geometría GeoJSON: "circle", "box" o "geometry".
geometry: La geometría GeoJSON que define el límite espacial.
score(Opcional) Una instancia de SearchScoreOption que configura la puntuación de relevancia.

El siguiente ejemplo utiliza el operador SearchGeoWithin para query la colección sample_mflix.theaters en busca de documentos que tengan un valor geo dentro de un 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

La expresión SearchMoreLikeThis encuentra documentos similares a los ejemplos proporcionados. Esto corresponde al operador másComoEsto de MongoDB.

Para utilizar este operador, pasa los siguientes argumentos al constructor SearchMoreLikeThis():

documents: Una lista de documentos de ejemplo o expresiones que sirven como referencias para la comparación de similitud.
score(Opcional) Una instancia de SearchScoreOption que configura la puntuación de relevancia.

El siguiente ejemplo utiliza la expresión SearchMoreLikeThis para consultar la colección sample_mflix.movies de documentos que son similares a un documento de ejemplo proporcionado:

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

Combinar expresiones

Puedes realizar consultas de MongoDB Search que combinen múltiples expresiones de búsqueda de las siguientes maneras:

Utiliza la Clase CompoundExpression
Usar operadores bitwise

Utiliza la Clase CompoundExpression

La expresión CompoundExpression te permite utilizar la lógica booleana para combinar múltiples expresiones de búsqueda. Esto corresponde al operador compuesto de MongoDB.

Debes pasar uno o más de los siguientes argumentos al constructor CompoundExpression():

must: Una lista de expresiones que los documentos deben coincidir
should: Una lista de expresiones que los documentos deberían cumplir
must_not: Una lista de expresiones que los documentos no deben coincidir
filter: Una lista de expresiones que filtran los resultados

También puede pasar los siguientes argumentos opcionales:

minimum_should_match: El número mínimo de should cláusulas que los documentos deben cumplir
score: Una instancia SearchScoreOption que configura la puntuación de relevancia

Este ejemplo usa la expresión CompoundExpression para consultar la colección sample_mflix.movies por documentos que cumplan con los siguientes criterios:

plot el campo existe
plot el campo contiene el texto "fast-paced"
genres el campo no contiene "Romance" ni "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

Puedes usar los siguientes operadores bit a bit para combinar expresiones de búsqueda:

&: Representa una operación lógica AND.
|: Representa una operación lógica OR
~: Representa una operación lógica NOT

Este ejemplo usa el operador | para consultar la colección sample_mflix.movies en busca de documentos que coincidan con uno o ambos de los siguientes criterios:

plot el campo contiene el texto "heartwarming"
genres El campo contiene "Romance" o "Comedy"

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

Configura puntuaciones de relevancia

MongoDB asigna una puntuación de relevancia a cada documento devuelto en una consulta de búsqueda. Los documentos incluidos en un conjunto de resultados se ordenan de mayor a menor puntuación de relevancia.

Puede utilizar la expresión SearchScoreOption para personalizar cómo MongoDB calcula y aplica los puntajes de relevancia. El constructor SearchScoreOption() acepta los siguientes argumentos:

boost: aumenta la puntuación de los documentos que coinciden con una expresión especificada
constant: Aplica una puntuación fija a todas las coincidencias
function: Aplica una función para calcular la puntuación
pathCalifica documentos en función del valor de un campo

Tip

Para obtener más información sobre las puntuaciones de relevancia, consulte scoring-ref en la documentación de MongoDB Atlas.

El siguiente ejemplo aumenta la puntuación de relevancia de los documentos que coinciden con la expresión SearchEquals por un factor de 3:

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

Información Adicional

Para obtener más información sobre la creación de índices de búsqueda en MongoDB, véase Índices de búsqueda en la guía Crear índices.

Para obtener más información sobre las consultas de búsqueda de MongoDB, consulte atlas-search en la documentación de MongoDB Atlas.

Volver

Realizar consultas en bruto

Búsqueda vectorial de MongoDB