Home

Awesome

py-jsonq

py-jsonq is a simple, elegant Python package to Query over any type of JSON Data. It'll make your life easier by giving the flavour of an ORM-like query on your JSON.

Installation

pip install pyjsonq

Usage

Just import the package before start using it.

As a Python Package:

from pyjsonq import JsonQ

You can start using this package right away by importing your Json data from a file:

JsonQ('data.json')

or

JsonQ(data={"id": 1, "name": "shaonty"}) # must assign data if you want to pass data instead of file_path

You can start Query your data using the various query methods such as where, or_where, where_in, where_not_in, where_starts_with, where_ends_with, where_contains and so on. Also you can aggregate your data after query using sum, count, group_by, sort_by, max, min etc.

Let's see a quick example:

# sample Json data
json_object = {
    products: [
        {
            id: 1,
            city: 'bsl',
            name: 'iPhone',
            cat: 1,
            price: 80000.5
        },
        {
            id: 2,
            city: null,
            name: 'macbook pro',
            cat: 1,
            price: 150000
        },
        {
            id: 3,
            city: 'dhk',
            name: 'Redmi 3S Prime',
            cat: 2,
            price: 12000
        },
        {
            id: 4,
            city: 'bsl',
            name: 'macbook air',
            cat: 2,
            price: 110000
        }
    ]
};

qe = JsonQ(file_path)
res = qe.at('products').where('cat', '=', 2).get()
print(res)

"""This will print

[
    {
        id: 3,
        city: 'dhk',
        name: 'Redmi 3S Prime',
        cat: 2,
        price: 12000
    },
    {
        id: 4,
        city: 'bsl',
        name: 'macbook air',
        cat: 2,
        price: 110000
    }
]
"""

Let's say we want to get the Summation of price of the Queried result. We can do it easily by calling the sum() method instead of get():

res = qe.at('products').where('cat', '=', 2).sum('price')
print(res)

"""It will print:

122000

"""

Let's explore the full API to see what else magic this library can do for you. Shall we?

API

Following API examples are shown based on the sample JSON data given here. To get a better idea of the examples see that JSON data first. Also detailed examples of each API can be found here.

List of API:

get()

This method will execute queries and will return the resulted data. You need to call it finally after using some query methods. Details can be found in other API examples.

from_file(file_path)

This method is the alternative of set json file path. Details can be found in other API examples.

example:

Let's say you have a file named data.json. You can set path like this:

qu = JsonQ().from_file('data.json').at('users').where('id', '=', 1).get()

at(path)

By default, query would be started from the root of the JSON Data you've given. If you want to first move to a nested path hierarchy of the data from where you want to start your query, you would use this method. Skipping the path parameter or giving '.' as parameter will also start query from the root Data.

example:

Let's say you want to start query over the values of 'users' property of your Json Data. You can do it like this:

qu = JsonQ(file_path).at('users').where('id', '=', 1).get()

If you want to traverse to more deep in hierarchy, you can do it like:

qe = JsonQ(file_path).at('users.5.visits').where('year', '=', 2011).get()

See a detail example here.

where(key, operator, value, case_insensitive)

example:

Let's say you want to find the 'users' who has id of 1. You can do it like this:

qu = JsonQ(file_path).at('users').where('id', '=', 1).get()

You can add multiple where conditions. It'll give the result by AND-ing between these multiple where conditions.

qe = JsonQ(file_path).at('users').where('id', '=', 1).where('location', '=', 'Sylhet').get()

qi = JsonQ(file_path).at('users').where('id', '=', 1).where('location', '=', 'sylhet', True).get()

See a detail example here.

or_where(key, operator, value)

Parameters of or_where() are the same as where(). The only difference between where() and or_where() is: condition given by the or_where() method will OR-ed the result with other conditions.

For example, if you want to find the users with id of 1 or 2, you can do it like this:

re = JsonQ(file_path).at('users').where('id', '=', 1).or_where('id', '=', 2).get()

See detail example here.

where_in(key, value)

This method will behave like where(key, 'in', value) method call.

where_not_in(key, value)

This method will behave like where(key, 'notin', value) method call.

where_null(key)

This method will behave like where(key, '=', 'None') method call.

where_not_null(key)

This method will behave like where(key, '!=', 'None') method call.

where_starts_with(key, value)

This method will behave like where(key, 'startswith', value) method call.

where_ends_with(key, value)

This method will behave like where(key, 'endswith', value) method call.

where_contains(key, val)

This method will behave like where(key, 'contains', val) method call.

sum(property)

example:

Let's say you want to find the sum of the 'price' of the 'products'. You can do it like this:

qe = JsonQ(file_path).at('products').sum('price')

If the data you are aggregating is plain list, you don't need to pass the 'property' parameter. See detail example here

count()

It will return the number of elements in the collection.

example:

Let's say you want to find how many elements are in the 'products' property. You can do it like:

qe = JsonQ(file_path).at('products').count()

See detail example here.

size()

This is an alias method of count().

max(property)

example:

Let's say you want to find the maximum of the 'price' of the 'products'. You can do it like this:

qu = JsonQ(file_path).at('products').max('price')

If the data you are querying is plain array, you don't need to pass the 'property' parameter. See detail example here

min(property)

example:

Let's say you want to find the minimum of the 'price' of the 'products'. You can do it like this:

qe = JsonQ(file_path).at('products').min('price')

If the data you are querying is plain array, you don't need to pass the 'property' parameter. See detail example here

avg(property)

example:

Let's say you want to find the average of the 'price' of the 'products'. You can do it like this:

qe = JsonQ(file_path).at('products').avg('price')

If the data you are querying is plain array, you don't need to pass the 'property' parameter. See detail example here

first()

It will return the first element of the collection.

example:

qe = JsonQ(file_path).at('products').first()

See detail example here.

last()

It will return the last element of the collection.

example:

qe = JsonQ(file_path).at('products').last()

See detail example here.

nth(index)

It will return the nth(n starts from 0) element of the collection. If the given index is a positive value, it will return the nth element from the beginning. If the given index is a negative value, it will return the nth element from the end.

example:

qe = JsonQ(file_path).at('products').nth(2)

See detail example here.

group_by(property)

example:

Let's say you want to group the 'users' data based on the 'location' property. You can do it like:

qe = JsonQ(file_path).at('users').group_by('location').get()

See detail example here.

sort(order)

Note: This method should be used for plain Array. If you want to sort an Array of Objects you should use the sortBy() method described later.

example:

Let's say you want to sort the 'arr' data. You can do it like:

qe = JsonQ(file_path).at('arr').sort().get()

See detail example here.

sort_by(property, order)

Note: This method should be used for Array of Objects. If you want to sort a plain Array you should use the sort() method described earlier.

example:

Let's say you want to sort the 'price' data of 'products'. You can do it like:

qe = JsonQ(file_path).at('products').sort_by('price').get()

See detail example here.

reset(data)

At any point, you might want to reset the Object instance to a completely different set of data and then query over it. You can use this method in that case.

See a detail example here.

clone()

It will return a complete clone of the Object instance.

See a detail example here.

chunk(size)

It will return a complete new array after chunking your array with specific size.

See a detail example here.

Bugs and Issues

If you encounter any bugs or issues, feel free to open an issue at github.

Also, you can shoot me an email to mailto:shaonty.dutta@gmail.com for suggestion or bugs.

Credit

Speical thanks to Nahid Bin Azhar for the inspiration and guidance for the package.

Others Platform