Skip to content

Revised README #222

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.

Sign up for GitHub

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

Merged
merged 7 commits into from
Jan 30, 2025
Merged

Revised README #222

Changes from 1 commit
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
e1586f4
Revised README
Jibola Jan 17, 2025
3234a85
revised docs
Jibola Jan 27, 2025
f869a30
revisions to readme. Included limitations. removed marketing cruft
Jibola Jan 28, 2025
846c98f
removed DEV_NOTES and paired down README
Jibola Jan 28, 2025
6efce63
linter fixes
Jibola Jan 29, 2025
0d662e0
revised template explanation
Jibola Jan 30, 2025
9ef0714
Merge branch 'main' into revised-readme
Jibola Jan 30, 2025
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
82 changes: 62 additions & 20 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,13 +8,7 @@ explore and build. The best way to share this is via our [MongoDB Community Foru

The development version of this package supports Django 5.0.x. To install it:

`pip install django-mongodb-backend`

### Resources

Check back soon as we aim to provide more links that will dive deeper into our library!

* [Developer Notes](DEV_NOTES.md)
`pip install django-mongodb-backend~=5.0.0`
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't believe this works (or is what we want people to use). Did you see the version I proposed?

$ pip install django-mongodb-backend~=5.0.0
ERROR: Could not find a version that satisfies the requirement django-mongodb-backend~=5.0.0 (from versions: 5.0.0a1, 5.0.0a2, 5.0.0a3)

[notice] A new release of pip is available: 24.3.1 -> 25.0
[notice] To update, run: pip install --upgrade pip
ERROR: No matching distribution found for django-mongodb-backend~=5.0.0

Copy link
Collaborator

@aclark4life aclark4life Jan 28, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

s/~=/==/

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hadn't seen all the comments yet. Reviewing everything now and applying appropriate changes.



## Quickstart
Expand Down Expand Up @@ -52,12 +46,6 @@ Then, visit http://127.0.0.1:8000/. This page displays a "Congratulations!" mess

## Capabilities of Django Backend for MongoDB

- **Database Connectivity**

- Directly tune MongoDB connection settings within your Django configuration\!
- Work against a persisted cloud instance of MongoDB for free\!


- **Model MongoDB Documents Through Django’s ORM**

- Translate Django model instances to MongoDB documents.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Translate is a strange work. How about "Store Django model instances as MongoDB documents."?

Expand All @@ -75,12 +63,11 @@ Then, visit http://127.0.0.1:8000/. This page displays a "Congratulations!" mess


- **Querying Data**

- Querying API powered through the amazing MongoDB Aggregation Pipeline

- Supports most functions of the Django QuerySet API
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

chop "functions"

- Support Query Annotations and common SQL AGGREGATE operators
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What are "Query Annotations"? What does it mean to support SQL aggregate operators on MongoDB? I guess you mean QuerySet.annotate() and QuerySet.aggregate()... you already said most of the QuerySet API is supported....

- We support foreign keys and execute JOIN operations all in 1 database call
- Through our custom raw\_aggregate call, MQL operations like Vector Search, Atlas Search, and GeoSpatial querying still yield Django QuerySet results\!
Support foreign key usage and execute JOIN operations
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think "Supports" is the verb tense to use. Dash was inadvertently deleted. Add period.

- Through our custom raw\_aggregate call, MQL operations like Vector Search, Atlas Search, and GeoSpatial querying still yield Django QuerySet resutts,
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"A custom QuerySet.raw\_aggregate() method allows MQL operations..."
"resutts," -> "results."



- **Administrator Dashboard & Authentication**
Expand All @@ -89,10 +76,64 @@ Then, visit http://127.0.0.1:8000/. This page displays a "Congratulations!" mess
- Fully integrated with Django's authentication framework.
- Supports native user management features like creating users and sessions.

## Limitations of django-mongodb-backend
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"Django MongoDB Backend"


- **Management Commands**

- Use commands like `migrate`, `makemigrations`, `flush`, `sqlmigrate`, many more.
- Database Variables `ATOMIC_REQUESTS`, `AUTOCOMMIT`, `CONN_HEALTH_CHECKS`, `TIME_ZONE` not supported
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

variables -> settings
add period.
"are not"

- No support for GeoDjango
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"is not supported."

- Functions such as `Chr`, `ExtractQuarter`, `MD5`, `Now`, `Ord`, `Pad`, `Repeat`, `Reverse`, `Right`, `SHA1`, `SHA224`, `SHA256`, `SHA384`, `SHA512`, and `Sign`.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Database functions ... are not supported.

- The `tzinfo` parameter of the `Trunc` database functions does not work properly because MongoDB converts the result back to UTC.
- Schema Validation is not enforced. Refer to MongoDB documentation for how to enforce schema validation.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nobody said it was supported. Give a more helpful pointer if this really needs to be said?

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nobody said it was supported. Give a more helpful pointer if this really needs to be said?

I'd definitely prefer linking to unsupported features rather than listing them here.

- Django DDL Transactions are not supported.
- The `migrate --fake-initial` command is not supported due to the inability to introspect MongoDB collection schema.
- The asynchronous functionality of the Django API has not yet been tested.
- `BSONRegExp` has no custom field class. It is best represented as a `CharField`.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Are we going to implement it? I don't think we need to mention it.



#### **Model Limitations**

- `$vectorSearch` and `$search` and Geospatial index creation through the Django Indexes API is not yet available.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is already included in the roadmap, and it's not a core Django feature, so I wouldn't expect it if it wasn't mentioned.

- Updating indexes in `EmbeddedModels` do not work after the first table creation.

- **ArrayField**
- Does not support `EmbeddedModel` within `ArrayField`.

- **EmbeddedModel**
- Limited schema change support (no changing of embedded models).
- Embedded documents cannot take Django ForeignKeys.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

it's "all relational fields." This is already documented much more clearly in the docs.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I will link to the embedded-model.rst

- Arbitrary or untyped `EmbeddedModelField` is not supported. All fields must derive from an `EmbeddedModel` class.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There is no expectation of this though.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is a common pattern for MongoDB users, though.


- **JSONField**
- There is no way to distinguish between a JSON "null" and a SQL null in specific queries.
- Some queries with Q objects, e.g., `Q(value__foo="bar")`, don't work properly, particularly with `QuerySet.exclude()`.
- Filtering for a `None` key, e.g., `QuerySet.filter(value__j=None)`, incorrectly returns objects where the key doesn't exist.

- **DateTimeField**
- No support for microsecond granularity.

- **DurationField**:
- Stores milliseconds rather than microseconds.

- **Unavailable Fields**:
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Unsupported model fields
(could add AutoField as well)

- `GeneratedField`
- `ImageField`
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ImageField is supported



- **These QuerySet API methods do not work**
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd rather say "are unsupported" than "do not work."


- `distinct()`
- `dates()`
- `datetimes()`
- `prefetch_related()`
- `extra()`
- `QuerySet.delete()` and `update()` do not support queries that span multiple collections.


- **Django Management Commands that do not work**
- `createcachetable`
- `inspectdb`
- `optimizemigration`
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

optimizemigration works (has nothing to do with the database backend)

- `sqlflush`
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we can omit this since it can't be supported and this isn't a SQL backend.

- `sqlsequencereset`
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

sqlsequencereset is not applicable since this backend doesn't support AutoField.



## Future Commitments of Django Backend for MongoDB
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

aside: I think the roadmap would be better stored on a wiki page or something so it can be more easily updated, but if you have to put it here for now, okay.

Expand Down Expand Up @@ -133,6 +174,7 @@ Then, visit http://127.0.0.1:8000/. This page displays a "Congratulations!" mess

These future capabilities are intended to enhance the functionality of the Django Backend for MongoDB as it progresses towards a General Availability (GA) release. If you have any more specific questions or need further details, feel free to ask\!


### Issues & Help

We're glad to have such a vibrant community of users of Django MongoDB Backend. We recommend seeking support for general questions through the MongoDB Community Forums.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

link to the forums again?

Expand Down
Loading