Skip to main content
Help us improve PyPI by participating in user testing. All experience levels needed!

A utility library that provides a MongoDB-like query language for querying python collections. It's mainly intended to parse objects structured as fundamental types in a similar fashion to what is produced by JSON or YAML parsers.

Project description

https://travis-ci.org/kapouille/mongoquery.svg?branch=master

A utility library that provides a MongoDB-like query language for querying python collections. It’s mainly intended to parse objects structured as fundamental types in a similar fashion to what is produced by JSON or YAML parsers. It follows the specification of queries for MongoDB version 3.4.

Usage

Example:

from mongoquery import Query, QueryError

records = [
    {"a": 5, "b": 5, "c": None},
    {"a": 3, "b": None, "c": 8},
    {"a": None, "b": 3, "c": 9},
    {"a": 1, "b": 2, "c": 3},
    {"a": 2, "c": 5},
    {"a": 3, "b": 2},
    {"a": 4},
    {"b": 2, "c": 4},
    {"b": 2},
    {"c": 6}
]

a_is_3 = Query({"a": 3})

# match a single object
matched = a_is_3.match(record[1])
assert matched

matched = a_is_3.match(record[0])
assert not matched

# filter elements
filtered = filter(
    a_is_3.match,
    records
)
assert filtered == [records[1], records[5]]

# incorrect filters raise QueryError
try:
    matched = query({"$foo": 2}).match(record[1])
except QueryError:
    pass  # => "$foo" operator isn't supported

Query syntax

The syntax of queries matches closely the one of MongoDB queries, and translates it to python using the following rules:

  • operators and field identifiers are expressed as strings. For instance, the following MongoDB query:

    {
        memos: {
            $elemMatch: {
                memo: 'on time',
                by: 'billing'
            }
        }
    }
    

    Translates straightforwardly to the following Python dict:

    {
        "memos": {
            "$elemMatch": {
                "memo": 'on time',
                "by": 'billing'
            }
        }
    }
    
  • regular expressions are expected to be expressed as string containing the MongoDB regular expression syntax. For instance:

    {description: {$regex: /^S/m}}
    

    Translates to the following Python dict:

    {"description": {"$regex": "/^S/m"}}
    
  • the boolean, null syntax used in MongoDB follows the JavaScript syntax. It is expected the python equivalents are used. For instance:

    {a: {$exists: true}, b: null}
    

    Translates to the following Python dict:

    {"a": {"$exists": True}, "b": None}
    

Functional differences with MongoDB’s queries

There are a few features that are not supported by mongoquery:
  • Only the "/pattern/<options>" syntax is supported for $regex. As a consequence, $options isn’t supported.
  • $text hasn’t been implemented.
  • Due to the pure python nature of this library, $where isn’t supported.
  • The Geospatial operators $geoIntersects, $geoWithin, $nearSphere, and $near are not implemented.
  • Projection operators $`, $elemMatch, $meta, and $slice are not implemented (only querying is implemented)
  • $type is limited to recognising generic python types, it won’t look into recognising the format of the data (for instance, it doesn’t check Object ID’s format, only that they are strings)

Project details


Release history Release notifications

This version
History Node

1.3.3

History Node

1.3.2

History Node

1.3.0

History Node

1.2.0

History Node

1.1.0

History Node

1.0.2

History Node

1.0.1

History Node

1.0

History Node

0.1.3

History Node

0.1.2

History Node

0.1.1

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Filename, size & hash SHA256 hash help File type Python version Upload date
mongoquery-1.3.3.tar.gz (6.2 kB) Copy SHA256 hash SHA256 Source None Jan 23, 2018

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging CloudAMQP CloudAMQP RabbitMQ AWS AWS Cloud computing Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page