In this chapter you'll learn how Django connects to the database and stores data in it. Let's dive in!

What is a QuerySet?

A QuerySet is, in essence, a list of objects of a given Model. QuerySets allow you to read the data from the database, filter it and order it.

It's easiest to learn by example. Let's try this, shall we?

Django shell

Open up your local console and type this command:

(myvenv) ~/myblog$ python manage.py shell

The effect should be like this:

(InteractiveConsole)
>>>

You're now in Django's interactive console. It's just like the Python prompt, but with some additional Django magic. :) You can use all the Python commands here too, of course.

All objects

Let's try to display all of our posts first. You can do that with the following command:

>>> Post.objects.all()
Traceback (most recent call last):
      File "<console>", line 1, in <module>
NameError: name 'Post' is not defined

Oops! An error showed up. It tells us that there is no Post. It's correct – we forgot to import it first!

>>> from blog.models import Post

We import the model Post from blog.models. Let's try displaying all posts again:

>>> Post.objects.all()
<QuerySet [<Post: my post title>, <Post: another post title>]>

This is a list of the posts we created earlier! We created these posts using the Django admin interface. Note that your posts may have different titles! But now we want to create new posts using Python, so how do we do that?

Create object

This is how you create a new Post object in database:

>>> Post.objects.create(author=me, title='Sample title', text='Test')

But we have one missing ingredient here: me. We need to pass an instance of User model as an author. How do we do that?

Let's import User model first:

>>> from django.contrib.auth.models import User

What users do we have in our database? Try this:

>>> User.objects.all()
<QuerySet [<User: commonlounge>]>

This is the superuser we created earlier! Let's get an instance of the user now:

>>> me = User.objects.get(username='commonlounge')

As you can see, we now get a User with a username that equals 'commonlounge'. Neat! Of course, you have to adjust this line to use your own username.

Now we can finally create our post:

>>> Post.objects.create(author=me, title='Sample title', text='Test')
<Post: Sample title>

Hurray! Wanna check if it worked?

>>> Post.objects.all()
<QuerySet [<Post: my post title>, <Post: another post title>, <Post: Sample title>]>

There it is, one more post in the list!

Add more posts

You can now have a little fun and add more posts to see how it works. Add two or three more and then go ahead to the next part.

Filter objects

A big part of QuerySets is the ability to filter them. Let's say we want to find all posts that user commonlounge authored. We will use filter instead of all in Post.objects.all(). In parentheses we state what condition(s) a blog post needs to meet to end up in our queryset. In our case, the condition is that author should be equal to me. The way to write it in Django is author=me. Now our piece of code looks like this:

>>> Post.objects.filter(author=me)
<QuerySet [<Post: Sample title>, <Post: Post number 2>, <Post: My 3rd post!>, <Post: 4th title of post>]>

Or maybe we want to see all the posts that contain the word 'title' in the title field?

>>> Post.objects.filter(title__contains='title')
<QuerySet [<Post: Sample title>, <Post: 4th title of post>]>

There are two underscore characters (_) betweentitle and contains. Django's ORM uses this rule to separate field names ("title") and operations or filters ("contains"). If you use only one underscore, you'll get an error like "FieldError: Cannot resolve keyword title_contains".

You can also get a list of all published posts. We do this by filtering all the posts that havepublished_dateset in the past:

>>> from django.utils import timezone
>>> Post.objects.filter(published_date__lte=timezone.now())
<QuerySet []>

Unfortunately, the post we added from the Python console is not published yet. But we can change that! First get an instance of a post we want to publish:

>>> post = Post.objects.get(title="Sample title")

And then publish it with our publish method:

>>> post.publish()

Now try to get list of published posts again (press the up arrow key three times and hit enter):

>>> Post.objects.filter(published_date__lte=timezone.now())
<QuerySet [<Post: Sample title>]>

Ordering objects

QuerySets also allow you to order the list of objects. Let's try to order them by created_date field:

>>> Post.objects.order_by('created_date')
<QuerySet [<Post: Sample title>, <Post: Post number 2>, <Post: My 3rd post!>, <Post: 4th title of post>]>

We can also reverse the ordering by adding - at the beginning:

>>> Post.objects.order_by('-created_date')
<QuerySet [<Post: 4th title of post>,  <Post: My 3rd post!>, <Post: Post number 2>, <Post: Sample title>]>

Chaining QuerySets

You can also combine QuerySets by chaining them together:

>>> Post.objects.filter(published_date__lte=timezone.now()).order_by('published_date')
<QuerySet [<Post: Post number 2>, <Post: My 3rd post!>, <Post: 4th title of post>, <Post: Sample title>]>

This is really powerful and lets you write quite complex queries.

Cool! You're now ready for the next part! To close the shell, type this:

>>> exit()
$