mongo_model
app.contrib.mongoDB.mongo_model
Un Módulo de Python que expone una clase base, para generar una instancia con metodos sencillos y gestionar a MongoDB, usando pymongo.
Para más información, te recomendamos leer la documentación del Proyecto.
- https://pymongo.readthedocs.io/en/stable/index.html
- https://pymongo.readthedocs.io/en/stable/api/pymongo/results.html
- https://www.mongodb.com/docs/manual/reference/method/ObjectId/
- https://github.com/ijl/orjson
- https://www.mongodb.com/docs/manual/reference/geojson
- https://www.mongodb.com/docs/manual/aggregation
- https://www.mongodb.com/docs/manual/geospatial-queries
- https://www.mongodb.com/docs/manual/reference/operator/query/near/#mongodb-query-op.-near
- https://www.mongodb.com/docs/manual/reference/operator/query/centerSphere/#mongodb-query-op.-centerSphere
- https://stackoverflow.com/questions/25734092/query-locations-within-a-radius-in-mongodb
- https://www.mongodb.com/docs/manual/reference/operator/query/geoWithin/
- https://www.mongodb.com/docs/manual/reference/operator/query/box/#definition
- https://www.mongodb.com/docs/manual/reference/operator/query/polygon/#mongodb-query-op.-polygon
- https://www.mongodb.com/docs/manual/indexes/#indexes
- https://www.mongodb.com/docs/manual/geospatial-queries/#geospatial-indexes
- https://www.mongodb.com/docs/manual/core/index-unique/
- https://www.mongodb.com/docs/manual/core/2dsphere/
MongoModel
Genera una instancia con metodos sencillos para el manejo de MongoDB usando MongoClient de pymongo.
Attributes:
Name | Type | Description |
---|---|---|
_db | Any | donde almacena el objeto de conexión. |
_prefix | str | El prefijo para las colecciones. |
Raises:
Type | Description |
---|---|
TypeCheckError | error de comprobación de tipos |
maximum recursion depth exceeded | en caso de que no se pueda definir el valor de retorno de la propiedad |
Examples:
__tablename__: str
property
Extrae el nombre de la colección, definido en el campo __tablename__
, de la clase que se extiende de MongoModel
.
Raises:
Type | Description |
---|---|
TypeCheckError | error de tipos emitido por typeguard |
maximum recursion depth exceeded | error de recursion en caso de que no se pueda definir el valor de retorno de la propiedad |
Returns:
Type | Description |
---|---|
str | el nombre de la colección, ó |
Examples:
__init__(conn=None)
Constructor de la clase MongoModel.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
conn | Request | una instancia de | None |
Raises:
Type | Description |
---|---|
RuntimeError | en caso de que no se pueda generar una conexión a la Base de Datos |
Exception | cualquier otra Excepción al momento de crear la conexión |
get_timestamp()
Genera un objeto de tipo bson.timestamp
.
Returns:
Type | Description |
---|---|
Optional[Timestamp] | un objeto de tipo |
Examples:
mongo_id(key=None)
Genera un objeto de tipo bson.objectid
, en modo legacy para compatibilidad con mongoDB.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
key | str | un campo de tipo string, por defecto | None |
Returns:
Type | Description |
---|---|
ObjectId | un objeto de tipo bson.objectid, ó |
Examples:
generate_id()
Genera un UUID basado en uuid.uuid4()
en vez de bson.objectid
, para utilizar ObjectId
utilice el método mongo_id
.
Returns:
Type | Description |
---|---|
Any | un |
Examples:
get_prefix()
Obtiene un objeto de tipo Collection
de MongoDB, adicionalmente valida si se definió un prefijo para la Base de Datos, en cuyo caso se le agrega al nombre de la colección.
Notes
- Puede generar raises de tipo
typeguard.TypeCheckError
ómaximum recursion depth exceeded
en caso de que no se pueda definir el valor de retorno de la propiedad__tablename__
.
Returns:
Type | Description |
---|---|
Collection | un objeto de tipo Collection, ó |
Examples:
custom_encoder(obj)
Método utilizado por orjson
para validar algunos tipos de datos, mientras se decodifica los resultados de la consulta a la Base de Datos.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
obj | Any | un objeto Para serializar una subclase o tipos arbitrarios | required |
Notes
- Esta es una función recursiva.
Para más información, consulta:
Returns:
Type | Description |
---|---|
Any | un tipo soportado por |
Examples:
build_response(data)
Convierte los resultados obtenidos de MongoDB en un diccionario, ó lista de diccionarios utilizando bson
y orjson
para la conversión de tipos.
Adicionalmente busca y elimina los objetos vacíos dentro de la lista de resultados.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
data | Any | la data a convertir | required |
Returns:
Type | Description |
---|---|
Any | usualmente un diccionario, lista de diccionarios ó |
Examples:
get_all(select_fields=None, limit=0, filters=None)
async
Obtiene todos los documentos de una colección, adicionalmente permite una lista de campos a devolver y un limite para la cantidad de documentos consultados.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
select_fields | list[str] | una lista con los posibles campos de los registros a retornar. por defecto | None |
limit | int | define el limite de registros a consultar. por defecto | 0 |
filters | dict[str, Any] | un diccionario con valores, para realizar un filtro. | None |
Returns:
Type | Description |
---|---|
Any | usualmente una lista de diccionarios con el resultado de la consulta, ó |
Examples:
as_dict()
Convierte la instancia de clase, en un diccionario y elimina algunos campos no necesarios.
Returns:
Type | Description |
---|---|
dict | un diccionario con la lista de claves/valor de la colección |
Examples:
save()
async
Guarda un objeto (de tipo MongoModel) ó un diccionario en la Base de Datos, adicionalmente agrega el campo created_at
en caso de no estar presente.
Raises:
Type | Description |
---|---|
PyMongoError | excepciones generadas por PyMongo. |
Returns:
Type | Description |
---|---|
Any | el id del documento almacenado, ó |
Examples:
multi_save(data)
async
Guarda múltiples objetos/diccionarios en la Base de datos, adicionalmente agrega los campos _id
y created_at
a cada objeto/diccionario de la lista.
Para información sobre los limites, consulte el módulo app.config.db.mongo
Parameters:
Name | Type | Description | Default |
---|---|---|---|
data | list[dict[str, Any] | object] | una lista que contiene múltiples objetos/diccionarios para almacenar | required |
Raises:
Type | Description |
---|---|
PyMongoError | excepciones generadas por PyMongo. |
Returns:
Type | Description |
---|---|
Optional[list[Any]] | una lista con los id de los documentos almacenados ó |
Examples:
raw_multi_save(table_name, data)
async
Guarda múltiples diccionarios en la Base de datos.
Para información sobre los limites, consulte el módulo app.config.db.mongo
Parameters:
Name | Type | Description | Default |
---|---|---|---|
table_name | str | el nombre de la colección(tabla) | required |
data | list[dict[str, Any] | object] | una lista que contiene múltiples objetos/diccionarios para almacenar | required |
Warning
-
Este método genera los
_id
de cada documento utilizandoObjectId()
de MongoDB, si no se quiere esto, envíe el campo_id
en cada documento. -
Recomendamos usar la función
generate_id
para crear el campo_id
. -
Este método NO realiza validaciones más allá de los limites de
BATCH_LIMIT
y tipos de datos enviados por los parámetros, se recomienda validar todos los datos antes de guardar.
Raises:
Type | Description |
---|---|
PyMongoError | excepciones generadas por PyMongo. |
Returns:
Type | Description |
---|---|
Optional[list[Any]] | una lista con los id de los documentos almacenados ó |
Examples:
save_and_set(key, data)
async
Guarda un objeto (de tipo MongoModel) ó un diccionario en la Base de Datos, con un ID definido por el usuario. Adicionalmente agrega el campo created_at
en caso de no estar presente.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
key | str | un campo de tipo string para convertirlo en el id único del registro, recomendamos usar la función | required |
data | (object, dict[str, Any]) | un objeto (de tipo MongoModel) ó un diccionario. | required |
Warning
este metódo esta en revisión, puede cambiar en el futuro.
Raises:
Type | Description |
---|---|
PyMongoError | excepciones generadas por PyMongo. |
Returns:
Type | Description |
---|---|
Any | el id del documento almacenado, ó |
Examples:
get_by_id(key, select_fields=None, filters=None)
async
Obtiene un registro de la Base de Datos por su ID, opcionalmente permite definir una lista de campos a devolver y filtros sobre el documento.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
key | str | el id único del registro a consultar | required |
select_fields | list[str] | una lista de campos a devolver, por defecto | None |
filters | dict[str, Any] | un diccionario con valores, para realizar filtros sobre el documento, por defecto | None |
Notes
- Esta consulta realiza el filtro inicial sobre el campo id del registro (
key
), y luego aplica el resto de validaciones, con el campo de filtro (filters
). - Es posible que el registro consultado exista con el id proporcionado (
key
) pero al aplicar el campofilters
el resultado sea nulo, en cuyo caso se deberá revisar los filtros enviados a la consulta.
Raises:
Type | Description |
---|---|
PyMongoError | excepciones generadas por PyMongo. |
Returns:
Type | Description |
---|---|
Any | un diccionario con el documento consultado, ó |
Examples:
get_by(filters, select_fields=None, limit=0)
async
Obtiene registros de la Base de Datos definidos por el campo de filtros (filters
), opcionalmente permite definir una lista de campos a devolver y un limite de registros.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
filters | dict[str, Any] | un diccionario (campos clave/valor), para realizar el filtro | required |
select_fields | list[str] | una lista con los posibles campos de los registros a retornar. por defecto | None |
limit | int | define el limite de registros a consultar. por defecto | 0 |
Notes
- Es posible especificar filtros un poco más avanzados como
$or
,$eq
,$in
etc.
Para más información:
Raises:
Type | Description |
---|---|
PyMongoError | excepciones generadas por PyMongo. |
Returns:
Type | Description |
---|---|
Any | usualmente una lista de diccionarios con el resultado de la consulta, ó |
Examples:
update(key, data)
async
Actualiza un registro de la Base de Datos.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
key | str | el id único del registro a actualizar | required |
data | (object, dict[str, Any]) | un objeto (de tipo MongoModel) ó un diccionario. con los campos/valores a actualizar | required |
Warning
este metódo esta en revisión, puede cambiar en el futuro.
Returns:
Type | Description |
---|---|
Any | un objeto de tipo |
Raises:
Type | Description |
---|---|
PyMongoError | excepciones generadas por PyMongo. |
Examples:
remove(key, filters=None, mode=None)
async
Elimina un registro de la Base de Datos.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
key | str | el id único del registro a eliminar/actualizar (según el modo) | required |
filters | dict[str, Any] | un diccionario con valores para realizar filtros al momento de eliminar | None |
mode | DeleteMode | determina si el registro será eliminado de la Base de Datos ó actualizado, por defecto | None |
Warning
este metódo esta en revisión, puede cambiar en el futuro.
Notes
-
El campo
mode
determina si el registro será eliminado de la Base de Datos ó actualizado. -
Los modos admitidos se establecen en la Clase
DeleteMode
en el móduloapp.common.enums
- Soft: en el registro, se fija el estado DefaultStatus.Deleted en el campo
status
. - Hard: el registro es eliminado de la Base de Datos.
- Soft: en el registro, se fija el estado DefaultStatus.Deleted en el campo
-
Esta consulta realiza el filtro inicial sobre el campo id del registro (
key
), y luego aplica el resto de validaciones, con el campo de filtro (filters
). -
Es posible que el registro consultado exista con el id proporcionado (
key
) pero al aplicar el campofilters
el resultado sea nulo, en cuyo caso se deberá revisar los filtros enviados a la consulta.
Raises:
Type | Description |
---|---|
PyMongoError | excepciones generadas por PyMongo. |
Returns:
Type | Description |
---|---|
Any | Nulo si el registro fue eliminado/actualizado con exito, de lo contrario un mensaje de error |
Examples:
remove_multi(filters, mode=None)
async
Elimina múltiples registros de la Base de datos.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
filters | object | dict[str, Any] | un diccionario con valores para realizar filtros al momento de eliminar | required |
mode | DeleteMode | determina si el registro será eliminado de la Base de Datos ó actualizado, por defecto | None |
Warning
- Este método NO realiza validaciones más allá de los parámetros y tipos de datos enviados, se recomienda validar todos los datos antes de invocar a este método.
Raises:
Type | Description |
---|---|
PyMongoError | excepciones generadas por PyMongo. |
Returns:
Type | Description |
---|---|
Optional[Any] | Un objeto de tipo |
Examples:
custom_query(filters, select_fields=None, exclude_fields=None, sort_by=None, limit=0)
async
Obtiene registros de la Base de Datos, con base a filtros definidos por el usuario, adicionalmente se puede fijar una lista de campos a devolver, una lista de campos para ordenar la consulta y un limite para los registros consultados.
Warning
este metódo:
- se encuentra en revisión, puede cambiar en el futuro.
- se necesitan más pruebas y ejemplos.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
filters | dict[str, Any] | un diccionario con valores, para realizar el filtro | required |
select_fields | Optional[list[str]] | una lista de campos a devolver. por defecto None. | None |
exclude_fields | Optional[list[str]] | una lista de campos a excluir de los resultados de la consulta, por defecto None. | None |
sort_by | Optional[list[str]] | una lista de campos por los cuales ordenar los resultados. por defecto | None |
limit | int | define el limite de registros a consultar. por defecto 0. | 0 |
Returns:
Type | Description |
---|---|
Any | usualmente un diccionario con el resultado de la consulta, o un mensaje de error |
Examples:
raw_query(table_name, filters=None, select_fields=None, exclude_fields=None, sort_by=None, limit=0)
async
Permite realizar consultas personalizadas sobre cualquier colección de la Base de Datos, con base a filtros definidos por el usuario, adicionalmente se puede fijar una lista de campos a devolver, una lista de campos para ordenar la consulta y un limite para los registros consultados
Warning
este metódo:
- se encuentra en revisión, puede cambiar en el futuro.
- se necesitan más pruebas y ejemplos.
Notes
Este método difiere de custom_query
en que se puede realizar sobre cualquier colección (tabla), especificada por el parámetro table_name
Parameters:
Name | Type | Description | Default |
---|---|---|---|
table_name | str | el nombre de la colección | required |
filters | dict[str, Any] | un diccionario con valores, para realizar el filtro | None |
select_fields | list[str] | una lista de campos a devolver, por defecto None. | None |
exclude_fields | list[str] | una lista de campos a excluir de los resultados de la consulta, por defecto None. | None |
sort_by | list[str] | una lista de campos por los cuales ordenar los resultados, por defecto None. | None |
limit | int | define el limite de registros a consultar. por defecto 0. | 0 |
Returns:
Type | Description |
---|---|
Any | usualmente un diccionario con el resultado de la consulta, ó un mensaje de error |
Examples:
to_geopoint(longitude, latitude)
Convierte una coordenada en un objeto espacial de tipo Point
.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
longitude | float | la longitud | required |
latitude | float | la latitud | required |
Returns:
Type | Description |
---|---|
Any | un objeto espacial( |
Examples:
from_geopoint(geo_point, as_list=False)
Devuelve las coordenadas de un objeto espacial de tipo Point
.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
geo_point | dict | un objeto de tipo | required |
as_list | bool | especifica sí la respuesta será un diccionario ó una lista, por defecto | False |
Returns:
Type | Description |
---|---|
Any | las coordenadas en un diccionario, lista, ó |
Examples:
get_schema(get_id=False)
async
Obtiene el schema de la colección, utilizando una consulta de agregación.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
get_id | bool | define si el resultado es un objeto con toda la información, por defecto | False |
Returns:
Type | Description |
---|---|
Any | usualmente un diccionario con el resultado de la consulta, ó un mensaje de error |
Examples:
delete_table(table_name, drop=False)
async
Elimina una colección (tabla) ó todos sus documentos (registros)
Warning
este metódo:
- se encuentra en revisión, puede cambiar en el futuro.
- se necesitan más pruebas y ejemplos.
Notes
- tenga en cuenta que esta acción, no se puede deshacer.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
table_name | str | el nombre de la colección | required |
drop | bool | especifica si eliminará la colección, por defecto | False |
Raises:
Type | Description |
---|---|
TypeCheckError | error de tipos emitido por |
maximum recursion depth exceeded | error de recursion, en caso de que no se pueda definir el valor de retorno de la propiedad |
Returns:
Type | Description |
---|---|
Any | usualmente un diccionario con el resultado de la consulta, ó un mensaje de error |
Examples:
get_all_collections()
async
geo_nearest_query(select_fields, geo_field, geo_point, min_mts=0, max_mts=1000)
async
Realiza una consulta radial utilizando $near
y $geometry
de MongoDB.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
select_fields | list[str] | una lista con los posibles, campos de los registros a retornar | required |
geo_field | str | un campo de tipo | required |
geo_point | dict | un objeto espacial de tipo | required |
min_mts | int | limita los resultados a aquellos documentos que se encuentran al menos a la distancia especificada del punto central, por defecto | 0 |
max_mts | int | limita los resultados a los documentos que se encuentran como máximo a la distancia especificada del punto central, por defecto | 1000 |
Warning
este metódo:
- se encuentra en revisión, puede cambiar en el futuro.
- se necesita más pruebas y ejemplos.
Notes
$near
: requiere un índice geoespacial.2dsphere index
: si se especifica un punto GeoJSON, para este caso.
Para más información, consulta:
- https://www.mongodb.com/docs/manual/geospatial-queries
- https://www.mongodb.com/docs/manual/reference/operator/query/near/#mongodb-query-op.-near
- https://www.mongodb.com/docs/manual/reference/operator/query/centerSphere/#mongodb-query-op.-centerSphere
- https://stackoverflow.com/questions/25734092/query-locations-within-a-radius-in-mongodb
Returns:
Type | Description |
---|---|
Any | usualmente una lista de elementos con el resultado de la consulta, ó un mensaje de error |
Examples:
geo_within_bbox(select_fields, geo_field, bounding_box)
async
Realiza una consulta espacial, y devuelve todos los documentos que se encuentren dentro de los límites de un bounding box(abreviado 'bbox')
.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
select_fields | list[str] | una lista con los posibles campos de los registros a retornar | required |
geo_field | str | un campo de tipo | required |
bounding_box | list[dict] | una lista de objetos espaciales de tipo | required |
Warning
este metódo:
- se encuentra en revisión, puede cambiar en el futuro.
- se necesitan más pruebas y ejemplos.
Notes
Para más información, consulta:
Returns:
Type | Description |
---|---|
Any | usualmente una lista de elementos con el resultado de la consulta, ó un mensaje de error |
Examples:
geo_within_sphere(select_fields, geo_field, geo_point, distance=1000)
async
Realiza una consulta espacial, y devuelve todos los documentos que se encuentren dentro de los límites de un círculo que utiliza geometría esférica.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
select_fields | list[str] | una lista con los posibles campos de los registros a retornar | required |
geo_field | str | un campo de tipo | required |
geo_point | dict | un objeto espacial de tipo | required |
distance | int | la distancia desde el centro del circulo, en metros, por defecto | 1000 |
Warning
este metódo:
- se encuentra en revisión, puede cambiar en el futuro.
- se necesitan más pruebas y ejemplos.
Notes
$geoWithin
y$centerSphere
utilizan lamilla
como unidad de medida para realizar las consultas, este método, solicita la distancia enmetros
y realiza la conversión internamente.
Para más información, te recomendamos leer la documentación del Proyecto.
Returns:
Type | Description |
---|---|
Any | usualmente una lista de elementos con el resultado de la consulta, |
Any | ó un mensaje de error |
Examples:
geo_within_polygon(select_fields, geo_field, poly_fields)
async
Realiza una consulta espacial, y devuelve todos los documentos que se encuentren dentro de los límites de un polígono.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
select_fields | list[str] | una lista con los posibles campos de los registros a retornar | required |
geo_field | str | un campo de tipo | required |
poly_fields | list | una lista de objetos espaciales de tipo | required |
Warning
este metódo:
- se encuentra en revisión, puede cambiar en el futuro.
- se necesitan más pruebas y ejemplos.
Notes
Para más información, consulta:
Returns:
Type | Description |
---|---|
Any | usualmente una lista de elementos con el resultado de la consulta, ó un mensaje de error |
Examples:
create_index(field, index_type, unique=False)
async
Crea un índice para una colección en la Base de Datos.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
field | str | el nombre del campo para crear el índice | required |
index_type | Literal | un literal con los tipos de índice a utilizar | required |
unique | bool | especifica si el índice será único, garantizando que los campos indexados no almacenan valores duplicados, por defecto | False |
Warning
este metódo:
- se encuentra en revisión, puede cambiar en el futuro.
- se necesitan más pruebas y ejemplos.
Notes
- de momento solo se permite crear índices de tipo:
text
hashed
2d
2dsphere
Para más información, consulta:
Returns:
Type | Description |
---|---|
Any | usualmente un string con el nombre del índice, ó un mensaje de error |
Examples: