Welcome to MongoFire’s documentation!#

Installation#

Note

Before installing MongoFire, you first need to install MongoDB on your machine. I’m going to install it on a Linux machine if you’re on windows or macOS you can install it from here MongoDB installation

Let’s first install MongoDB. You can install it as follows:

sudo apt install mongodb

Now let’s start MongoDB server

sudo systemctl start mongodb

Let’s check if the server is running

sudo systemctl status mongodb

If you see active (running), then everything is fine and you can continue with me.

Now lets install MongoFire. You can install it as follows:

pip3 install mongofire

Quick start#

You need first to initialize the client in your main.py file:

from mongofire import MongoFire
MongoFire.initialize('mongodb://localhost:27017/')

And then you can use it in any file in your project like this:

from mongofire import MongoDB
db = MongoDB('myAppDatabase')

Set a Document#

To create or overwrite a single document, use the following example:

data = {
    'name': 'Mohamed',
    'age': 20,
}

db.collection('users').document('my_custom_uid').set(data)

If the document does not exist, it will be created. If the document does exist, its contents will be overwritten with the newly provided data, unless you specify that the data should be merged into the existing document, as follows:

doc_ref = db.collection('users').document('my_custom_uid')
doc_ref.set({'gender': 'male'}, merge=True)

Update a Document#

If you want to update any field in the document, you can use the update method. You can increment values, push or pull items from the list, rename fields, and more.

from mongofire import Field, FieldValue
db.collection('users').document('my_uid').update({
    'name': Field.rename('username'),
    'age': FieldValue.increment(1),
})

Add a Document#

Sometimes the document ID doesn’t make sense, and it’s okay to be random. In that case, you can use the add method instead of the set method.

status, doc_ref = db.collection('users').add({
    'name': 'Max',
    'age': 30,
})

You can get the randomly generated ID by doc_ref.id.

Delete a Document#

Delete any document as follows:

db.collection('users').document('doc_id').delete()

Usage#

MongoFire#

You can use MongoFire class to initialize the server. You can do this as follows:

from mongofire import MongoFire
MongoFire.initialize('mongodb://localhost:27017/')

You can only initialize the server once, so be sure to use this code in your main.py file.

Note

If you want to get the mongodb original client, you can do it like this:

from mongofire import MongoFire
client = MongoFire.initialize('mongodb://localhost:27017/')

You can now use it as a normal pymongo provider.

After initialize MongoFire, you can now easily access databases from any file in your project using the MongoDB class.

MongoDB#

You can access any database from any file in your project as follows:

from mongofire import MongoDB

db = MongoDB('MyDatabaseName')

Now with db object you can do anything. You can read write, delete update, etc.

Note

The db object contains a mongo object, you can access the original database object of pymongo.

Here is an example of how to do that:

db.mongo # < This is Database object for pymongo

Now suppose we have a collection of users in our mongo database and we need to add a new user to it. You can do this as follows:

from mongofire import MongoDB

db = MongoDB('MyDatabaseName')

db.collection("users").document('my_custom_user_id').set(
    {
        'name': 'Mohamed',
        'age': 20,
    }
)

To understand how document and set method works, check out the MongoDBDocument class.

Now suppose we need to get all users older than 18 years old. You can do this as follows:

from mongofire import MongoDB

db = MongoDB('MyDatabaseName')

query = db.collection('users').where('age', '>', 18)

for user in query.stream():
    print(user.id)
    print(user.data.to_dict())

If you need to understand how collection and queries actually work in MongoFire, check out the MongoDBCollection class

MongoDBCollection#

from mongofire import MongoDB

db = MongoDB('myDatabase')

coll_ref = db.collection('users')

This is how you can access collections in MongoFire

add#

Let’s add list of users to our users collection

users = [
    {
        'name': 'Mohamed',
        'age': 20,
    },
    {
        'name': 'Ali',
        'age': 16,
    },
    {
        'name': 'Ahmed',
        'age': 30,
    },
]

for user in users:
    status, doc_ref = coll_ref.add(user)
    print(doc_ref.id, status.acknowledged)

The add method will generate a random id for each user document if you want to use a custom id check out the set method

where#

The where method will help you work with multiple documents. You can query for any documents You can update and delete You can do anything.

Let’s say you need to add a new field for all users between 13 and 19 years old. You can do this as follows:

query = coll_ref.where('age', '>', 13)
query = query.where('age', '<', 19)

status = query.update({'isTeenager', True})

If you want to read query data, do the following:

# read stream
for teenager in coll_ref.where('isTeenager', '==', True).stream()
    print(teenager.data.to_pretty())

# read
for teenager in coll_ref.where('isTeenager', '==', True).get()
    print(teenager.data.to_pretty())

And you can delete like this:

query = coll_ref.where('isTeenager', '==', True)
status = query.delete()

These are all query operators that MongoFire support

Operater	Mongo	Description
`==`	`$eq`	equal to
`!=`	`$ne`	not equal to
`<`	`$lt`	less than
`<=`	`$lte`	less than or equal to
`>`	`$gt`	greater than
`>=`	`$gte`	greater than or equal to
`array-contains`	`$all`	list items contains all list items
`array-contains-any`	`$in`	list items contains to any items in the list
`in`	`$in`	value equal to any items in the list
`not-in`	`$nin`	value not equal to any items in the list

document#

If you only want to work with single document, check out the MongoDBDocument class.

MongoDBDocument#

from mongofire import MongoDB
db = MongoDB('myAppDatabase')

set#

To create or overwrite a single document, use the following example:

data = {
    'name': 'Mohamed',
    'age': 20,
}

db.collection('users').document('my_custom_uid').set(data)

doc_ref = db.collection('users').document('my_custom_uid')
doc_ref.set({'gender': 'male'}, merge=True)

update#

If you want to update any field in the document, you can use the update method. You can increment values, push or pull items from the list, rename fields, and more.

from mongofire import Field, FieldValue
db.collection('users').document('my_uid').update({
    'name': Field.rename('username'),
    'age': FieldValue.increment(1),
})

To learn more about push, pull, increment, decrement, etc., check out Field and FieldValue classes.

get#

To get single document data, use the following example:

doc = db.collection('users').document('my_custom_uid').get()
print(doc.data.to_dict())

To get only specific fields from the document, use the following example:

doc = db.collection('users').document('my_custom_uid').get('hobbies', 'age')
print(doc.data.to_dict())

delete#

Delete any document as follows:

db.collection('users').document('doc_id').delete()

Field#

from mongofire import MongoDB, Field
db = MongoDB('myAppDatabase')

unset#

To unset (delete) field, use the following example:

db.collection('users').document('user_id').update({
    'email': Field.unset(),
})

rename#

To rename field, use the following example:

db.collection('users').document('user_id').update({
    'name': Field.rename('username')
})

FieldValue#

from mongofire import MongoDB, FieldValue
db = MongoDB('myAppDatabase')

increment#

To increment field value, use the following example:

db.collection('users').document('user_id').update({
    'age': FieldValue.increment(1),
})

decrement#

To decrement field value, use the following example:

db.collection('users').document('user_id').update({
    'salary': FieldValue.decrement(200),
})

push#

To add items to field value, use the following example:

db.collection('users').document('user_id').update({
    'searchKeywords': FieldValue.push(['google', 'facebook']),
})

pull#

To delete items from field value, use the following example:

db.collection('users').document('user_id').update({
    'searchKeywords': FieldValue.pull(['google']),
})

add_to_set#

To add items to a field value and ensure that there are no duplicate items, use the following example:

db.collection('users').document('user_id').update({
    'searchKeywords': FieldValue.add_to_set({'google'}),
})

This will add the keyword google to the searchKeywords field if it does not exist otherwise it will be ignored