*NOTE*: PostgreSQL is a bit capricious about data types, so MongoSqltries to guess it using the operand you provide. Hence, when filteringwith a property known to contain a ``float``-typed field, provide``float`` values to it.

MongoQuery==========

Source: `mongosql/query.py <mongosql query.py="">`__

Starting Up-----------

``MongoQuery`` is the interface to be used for querying with safe JSONobjects. It relies on ``MongoModel``: a wrapper for SqlAlchemy modelsthat holds cached data and build pieces for the query.

MongoSql is designed to help with data selection for the APIs, and theseusually offer CRUD operations.

To ease the pain of implementing CRUD for all of your models, MongoSQLcomes with a CRUD helper that exposes MongoSQL capabilities forquerying. Together with`RestfulView <https: github.com="" kolypto="" py-flask-jsontools#restfulview="">`__from`flask-jsontools <https: github.com="" kolypto="" py-flask-jsontools="">`__,CRUD controllers are extremely easy to build.

CrudHelper----------

Source: `mongosql/crud.py <mongosql crud.py="">`__

``CrudHelper`` is a helper class that contains parts of CRUD logic thatcan be used in CRUD views.

You just instantiate it over an SqlAlchemy model:

.. code:: python

from .models import User from mongosql import CrudHelper

user_crudhelper = CrudHelper(User)

and now the following methods are available:

- ``mquery(query, query_obj=None)``: Construct ```MongoQuery`` <#mongoquery>`__ for the model, using ``query`` as the intial Query. ``query_obj`` is the optional `Query Object <#query-object-syntax>`__.- ``create_model(entity)``: Create an SqlAlchemy model from ``entity`` dictionary.- ``update_model(model, entity)``: Update an existing SqlAlchemy model with some fields from the provided ``entity`` dictionary.

With PostgreSQL JSON fields, it has an additional feature: dictionaries are shallowly merged together. This way, ``update_model()`` allows you to add certain fields without loading the entity.

- ``replace_model(entity, prev_model=None)``: Replace an entity completely, using a model created from the ``entity`` dictionary.

``AssertionError`` is raised for validation errors, e.g. an unknownfield is provided by the user.

StrictCrudHelper----------------

Source: `mongosql/crud.py <mongosql crud.py="">`__

Usually it's not safe to allow changing all fields, loading allrelations, listing thousands of entities, etc.

``StrictCrudHelper`` subclasses ```CrudHelper`` <#crudhelper>`__ andadds strict limitations to the things the user can do with your models.

Its constructor accepts the following additional arguments:

- ``ro_fields=()``: List of read-only fields or field names. The user is not allowed to change or define these.- ``allow_relations=()``: List of relations of relation names the user is allowed to `join <#join-operation>`__.

All `joins <#join-operation>`__ in `Query Objects <#query-object-syntax>`__ are then checked against the list, and the user can never request a relation that's not explicitly allowed with this list.

It supports relations on the parent model, as well as relations on sub-models using the dot-notation syntax (see the example below).

- ``query_defaults=None``: Provide default values for the `Query Object <#query-object-syntax>`__ in case certain fields are not provided by the user.

A good idea is to specify the default sorting fields and direction. The user can override it with his custom `Query Objects <#query-object-syntax>`__.

- ``maxitems=None``: Set a hard limit on the number of entities the user can load.

This value cannot be overridden with a `Query Object <#query-object-syntax>`__: the user will never load more than ``maxitems`` entities with a single query.

``AssertionError`` is raised for validation errors when the user triesto hit the limits.

Having the limits specified, just use ```CrudHelper`` <#crudhelper>`__methods and enjoy security.

CrudViewMixin-------------

Source: `mongosql/crud.py <mongosql crud.py="">`__

```CrudHelper`` <#crudhelper>`__ itself if not the end-product: youstill need a view to manage your models.

``CrudViewMixin`` is a mixin for class-based views that leverages```CrudHelper`` <#crudhelper>`__ and ```MongoQuery`` <#mongoquery>`__ tocreate a perfect, dynamic API endpoint.

Have a look at`flask.ext.jsontools.RestfulView <https: github.com="" kolypto="" py-flask-jsontools#restfulview="">`__:they are designed to be a perfect couple, so our example will use both.

When subclassing ``CrudViewMixin``, you need to do the following:

1. Initialize the ``crudhelper`` attribute with a ```CrudHelper`` <#crudhelper>`__ or ```StrictCrudHelper`` <#strictcrudhelper>`__2. Override the ``_query()`` method, so ``CrudViewMixin`` knows how to get the database session3. Implement CRUD methods using ``_method_list|create|get|replace|update|delete()`` helpers4. If required, implement ``_save_hook()`` to handle cases when an entity is going to be saved (created, updated or replaced)

A full-featured and tested example:`tests/crud\_view.py <tests crud_view.py="">`__. It's still quite verbose,so make sure you create another base view for your application :)