Find
Find one
The find_one
method is available in both AsyncDbEngine
and DbEngine
classes of the PyODMongo library. This method is used to retrieve a single object from the database based on specified criteria.
from pyodmongo import AsyncDbEngine, DbModel
from typing import ClassVar
import asyncio
engine = AsyncDbEngine(mongo_uri="mongodb://localhost:27017", db_name="my_db")
class Product(DbModel):
name: str
price: float
is_available: bool
_collection: ClassVar = "products"
async def main():
query = Product.name == "Box"
box: Product = await engine.find_one(Model=Product, query=query)
asyncio.run(main())
from pyodmongo import DbEngine, DbModel
from typing import ClassVar
engine = DbEngine(mongo_uri="mongodb://localhost:27017", db_name="my_db")
class Product(DbModel):
name: str
price: float
is_available: bool
_collection: ClassVar = "products"
query = Product.name == "Box"
box: Product = engine.find_one(Model=Product, query=query)
Arguments
Model: DbModel
: The class that inherits fromDbModel
to be used for forming the retrieved object from the database.query: ComparisonOperator | LogicalOperator
: The query used to filter the objects in the database.raw_query: dict
: An optional query in the dictionary format compatible with MongoDB.sort: SortOperator
: An optional parameter that specifies the sort order of the results. Each tuple in the list contains a field name and a direction (1
for ascending,-1
for descending). This parameter allows for sorting the results based on one or more fields, helping in organizing the retrieved data as per specific requirements.raw_sort: dict
: An optional parameter similar tosort
but uses a dictionary format directly compatible with MongoDB sort specifications. It's particularly useful when complex sorting criteria are needed that are directly supported by MongoDB. This can provide more direct control over the sorting process in the database query.populate: bool
: A boolean flag that determines whether the returned object will have its relationship fields populated with other objects or will only contain theid
field.as_dict: bool
: A boolean flag that, when set toTrue
, returns the response as a dictionary instead of instantiated objects. This is particularly useful when a lightweight, serializable format is required, such as for JSON responses in web applications, or when the consumer prefers to work with basic data structures rather than complex object models.tz_info: timezone
: An optional parameter that specifies the time zone information for anydatetime
fields in the retrieved objects. This parameter is crucial when dealing with records in different time zones and ensures that thedatetime
values are correctly adjusted to the specified time zone. If not set, thedatetime
fields will be returned in the default time zone of the database or the application server.
Warning
If query
is passed, raw_query
will not be considered.
Find many
The find_many
method in the PyODMongo library is similar to the find_one
method, but it retrieves a list of objects that match the specified criteria.
from pyodmongo import AsyncDbEngine, DbModel
from typing import ClassVar
import asyncio
engine = AsyncDbEngine(mongo_uri="mongodb://localhost:27017", db_name="my_db")
class Product(DbModel):
name: str
price: float
is_available: bool
_collection: ClassVar = "products"
async def main():
query = (Product.price >= 50) & (Product.price < 100)
products: list[Product] = await engine.find_many(Model=Product, query=query)
asyncio.run(main())
from pyodmongo import DbEngine, DbModel
from typing import ClassVar
engine = DbEngine(mongo_uri="mongodb://localhost:27017", db_name="my_db")
class Product(DbModel):
name: str
price: float
is_available: bool
_collection: ClassVar = "products"
query = (Product.price >= 50) & (Product.price < 100)
products: list[Product] = engine.find_many(Model=Product, query=query)
Arguments
Additionally, it includes three extra arguments for pagination control:
paginate: bool
: A boolean flag that specifies whether the response should be paginated or a regular list.current_page: int
: Ifpaginate=True
, this argument determines the page of results to be retrieved.docs_per_page: int
: Ifpaginate=True
, this argument determines the maximum number of objects per page in the query results.
Paginate
When you set paginate=True
in the find_many
method of PyODMongo, the result of the query will be encapsulated in an object of type ResponsePaginate
. This allows for efficient and organized retrieval of query results across multiple pages. The ResponsePaginate
object contains the following attributes:
current_page: int
: Indicates the current page of the search results.page_quantity: int
: Represents the total number of pages in the search results.docs_quantity: int
: Specifies the total count of objects found in the search.docs: list[Any]
: Contains the list of objects retrieved for the current page.
This pagination mechanism is particularly useful when dealing with large datasets, as it allows you to break down the results into manageable chunks and navigate through them with ease.
from pyodmongo import AsyncDbEngine, DbModel, ResponsePaginate
from typing import ClassVar
import asyncio
engine = AsyncDbEngine(mongo_uri="mongodb://localhost:27017", db_name="my_db")
class Product(DbModel):
name: str
price: float
is_available: bool
_collection: ClassVar = "products"
async def main():
query = (Product.price >= 50) & (Product.price < 100)
response: ResponsePaginate = await engine.find_many(
Model=Product, query=query, paginate=True, current_page=2, docs_per_page=100
)
asyncio.run(main())
from pyodmongo import DbEngine, DbModel, ResponsePaginate
from typing import ClassVar
engine = DbEngine(mongo_uri="mongodb://localhost:27017", db_name="my_db")
class Product(DbModel):
name: str
price: float
is_available: bool
_collection: ClassVar = "products"
query = (Product.price >= 50) & (Product.price < 100)
response: ResponsePaginate = engine.find_many(
Model=Product, query=query, paginate=True, current_page=2, docs_per_page=100
)
Populate
The populate feature in the PyODMongo library is a powerful mechanism for automatically populating all references within an object, including nested references. This feature simplifies working with related data in MongoDB and allows you to access linked documents without having to manually retrieve them one by one. The populate functionality has the following behavior:
- When you enable
populate=True
infind_one
orfind_many
, PyODMongo will populate all references within that object. - If the references themselves have additional references, PyODMongo will recursively populate those as well, traversing through all levels of reference.
- Reference lists are also populated.
Note
To ensure excellent performance, PyODMongo leverages the power of MongoDB's Aggregation framework under the hood. The Aggregation framework is a powerful and efficient tool for processing and transforming data within MongoDB.