Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add a "Setting up MongoDB" guide to the docs and update README #849

Merged
merged 4 commits into from
Aug 30, 2023
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@

# ![Maggma](docs/logo_w_text.svg)

[![testing](https://github.com/materialsproject/maggma/workflows/testing/badge.svg)](https://github.com/materialsproject/maggma/actions?query=workflow%3Atesting) [![codecov](https://codecov.io/gh/materialsproject/maggma/branch/main/graph/badge.svg)](https://codecov.io/gh/materialsproject/maggma) [![Language grade: Python](https://img.shields.io/lgtm/grade/python/g/materialsproject/maggma.svg?logo=lgtm&logoWidth=18)](https://lgtm.com/projects/g/materialsproject/maggma/context:python)
[![testing](https://github.com/materialsproject/maggma/workflows/testing/badge.svg)](https://github.com/materialsproject/maggma/actions?query=workflow%3Atesting) [![codecov](https://codecov.io/gh/materialsproject/maggma/branch/main/graph/badge.svg)](https://codecov.io/gh/materialsproject/maggma) [![Language grade: Python]

A files-to-API data pipeline for scientific applications using Python and MongoDB
A files-to-API data pipeline for scientific applications using Python, supporting a variety of data stores including MongoDB [and many others](https://materialsproject.github.io/maggma/getting_started/stores/#list-of-stores).
32 changes: 32 additions & 0 deletions docs/getting_started/mongodb.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
# Setting up MongoDB

Many users find MongoDB to best suit their data storage needs. While MongoDB [can be installed locally](https://www.mongodb.com/docs/manual/installation/), the easiest route is often to create a Mongo database via a cloud storage solution called [MongoDB Atlas](https://www.mongodb.com/atlas), which has a free tier. The setup instructions for using Maggma with MongoDB Atlas are described below:

1. Sign up for a free account on [MongoDB Atlas](https://www.mongodb.com/atlas).
2. Once logged in, select the "Create a Project" option and give your project a name (e.g. "MyProject"). Add your email address as the Project Owner.
3. Click the "Build a Database" button under the "Deployment > Database" section and choose the free (i.e. M0) option. Give your cluster a unique name (e.g. "MyCluster").
4. Select "Create" and enter your desired login credentials that you will use to access your database. You are probably best off not using special characters here since it will be URL-encoded. You should also use different credentials than your usual, since it's not uncommon to share credentials with trusted colleagues. Select "Finish and Close" when done.
5. Go to the "Collections" tab of your cluster, which is where you will create a database (e.g. "my_database") and corresponding data collection (e.g. "my_collection") by clicking the "Add My Own Data" button.
6. Under the "Security > Network Access" section, edit the IP Access List to allow access from anywhere for maximum flexibility.
7. Finally, retrieve your MongoDB URI, which is the address of your MongoDB cluster. You can find your database's URI by clicking the "Database" section in the sidebar and then selecting "Connect > Compass" and copying the link of the form `mongodb+srv://<username>:<password>@<host>`.

To test that you can connect to your database, run the following code:

```python
from maggma.stores import MongoURIStore

# Define your database credentials
store = MongoURIStore(
"mongodb+srv://<username>:<password>@<host>",
"my_collection",
database="my_database",
)

# Query the database
with store:
print(store.count())
```

!!! Note

If you are using a self-hosted Mongo database, you will probably want to use a [`MongoStore`](https://materialsproject.github.io/maggma/reference/stores/#maggma.stores.mongolike.MongoStore) instead of the [`MongoURIStore`](https://materialsproject.github.io/maggma/reference/stores/#maggma.stores.mongolike.MongoURIStore), which takes slightly different arguments.
1 change: 1 addition & 0 deletions mkdocs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,7 @@ nav:
- Advanced Builders: getting_started/advanced_builder.md
- Working with MapBuilder: getting_started/map_builder.md
- Working with GroupBuilder: getting_started/group_builder.md
- Setting up MongoDB: getting_started/mongodb.md
- Reference:
Core:
Store: reference/core_store.md
Expand Down