Asking questions to the database

This tutorial assumes you already installed the source.

We assume you are in directory “public-contracts”, as the installation part ended there, and that you start a Python session from there (e.g. enter “python” in the terminal).


To use Django, we have to setup it first. In the module set_up of package main/tools, we provide a function to that, which we now use:

>>> from import set_up_django_environment
>>> set_up_django_environment('main.settings_for_script')

This sets up a minimal Django environment using the settings main/, a minimal configuration to use the database.

Accessing the database

In this API, objects are Django models, which we need to import:

>>> from contracts import models

Look at this contract in the official database. It has the number “791452”. Lets pick it up:

>>> contract = models.Contract.objects.get(base_id=791452)

Now, lets start with its price:

>>> print(contract.price)

and its description:

>>> print(contract.description)

Lets now pick the entity that made this contract. In this case there is only one, but in general there can be more: a contract has a ManyToMany relationship with entities because each contract can have several entities (a joint contract), but also each entity can have several contracts.

In fact, each contract has two ManyToMany: the entities that paid, and the entities that were paid.

Lets say we want the entity that paid this contract. In that case, we pick the set of all entities that paid, and select the first one:

>>> entity =[0]
>>> print(entity)

Let’s now pick the contracts that this entity made. To that, we use the “contracts_made” of the entity:

>>> entity_contracts = entity.contracts_made.all()

Lets count the number of these contracts:

>>> print(entity_contracts.count())

You can check that this number matches the number in the official database. (there can be small error when there were contracts added today; our database is synchronized in the end of the day).

Now, how much is the price of all those contracts?

To answer that, we have to aggregate the prices. The syntax in Django is the following:

>>> from django.db.models import Sum
>>> total_price = entity_contracts.aggregate(our_sum=Sum('price'))['our_sum']
>>> print(total_price)

Again, you can check on the official website.

As a final example, we are going to use a filter. Lets say you want all the above contracts, but restricted to prices higher than 10.000€. For this, we need to “filter” these contracts:

>>> expensive_contracts = entity_contracts.filter(price__gt=10000*100)
>>> print(expensive_contracts.count())

The “price__gt” means price (g)reater (t)han, and we multiply by 100 because prices are in euro cents.

For now, that’s it. You now have the minimal knowledge to ask your own questions. In section here you can find references of all models.


  • The syntax we use here (e.g. “contracts_made”) is Django API.
  • If you don’t know Django, you can look at the existing source code of the website and start from there.
  • You can find the documentation of the API here.

If some problem occur, please add an issue so we can help you and improve these instructions.