Getting Started¶

Installing¶

AIOMotorEngine can be installed with pip, using:

$ pip install https://github.com/ilex/aiomotorengine/archive/master.zip

Connecting to a Database¶

aiomotorengine.connection.connect(db, alias='default', **kwargs)[source]¶

Connect to the database specified by the ‘db’ argument.

Connection settings may be provided here as well if the database is not running on the default port on localhost. If authentication is needed, provide username and password arguments as well.

Multiple databases are supported by using aliases. Provide a separate alias to connect to a different instance of mongod.

Extra keyword-arguments are passed to Motor when connecting to the database.

# create an asyncio event loop

io_loop = asyncio.get_event_loop()
connect("test", host="localhost", port=27017, io_loop=io_loop)  # you only need to keep track of the
                                                               # DB instance if you connect to multiple databases.

Modeling a Document¶

class User(Document):
    first_name = StringField(required=True)
    last_name = StringField(required=True)

class Employee(User):
    employee_id = IntField(required=True)

Creating a new instance¶

async def create_employee():
    emp = Employee(first_name="Bernardo", last_name="Heynemann", employee_id=1532)
    emp = await emp.save()
    assert emp is not None
    assert emp.employee_id == 1532

io_loop.run_until_complete(create_employee())

Updating an instance¶

Updating an instance is as easy as changing a property and calling save again:

async def update_employee():
    emp = Employee(first_name="Bernardo", last_name="Heynemann", employee_id=1532)
    await emp.save()
    emp.employee_id = 1534
    await emp.save()
    assert emp.employee_id == 1534

io_loop.run_until_complete(update_employee())

Getting an instance¶

To get an object by id, you must specify the ObjectId that the instance got created with. This method takes a string as well and transforms it into a bson.objectid.ObjectId.

async def load_employee():
    emp = Employee(first_name="Bernardo", last_name="Heynemann", employee_id=1538)
    await emp.save()
    emp2 = await Employee.objects.get(emp._id)
    assert emp2 is not None
    assert emp2.employee_id == 1538

io_loop.run_until_complete(load_employee())

Querying collections¶

To query a collection in mongo, we use the find_all method.

If you want to filter a collection, just chain calls to filter:

To limit a queryset to just return a maximum number of documents, use the limit method:

Ordering the results is achieved with the order_by method:

All of these options can be combined to really tune how to get items:

async def create_employee():
    emp = Employee(first_name="Bernardo", last_name="Heynemann", employee_id=1538)
    await emp.save()
    # return the first 10 employees ordered by last_name that joined after 2010
    employees = await Employee.objects \
          .limit(10) \
          .order_by("last_name") \
          .filter(last_name="Heynemann") \
          .find_all()

    assert len(employees) > 0
    assert employees[0].last_name == "Heynemann"

io_loop.run_until_complete(create_employee())

Counting documents in collections¶

async def count_employees():
    number_of_employees = await Employee.objects.count()
    assert number_of_employees == 0

io_loop.run_until_complete(count_employees())