what is query.clone(), queryset.clone() for in django?

Question

I see clone() being used extensively in django code

queryset.query.clone()  
queryset.clone()

What is it for and should I mimic the behavior in my queryset or manager methods?

Answer 1

As Kevin points out in his answer, the clone() method is not a documented part of the Django API. However, the all() method is fully documented, and does what you probably wanted from clone().

all()

Returns a copy of the current QuerySet (or QuerySet subclass). This can be useful in situations where you might want to pass in either a model manager or a QuerySet and do further filtering on the result. After calling all() on either object, you’ll definitely have a QuerySet to work with.

When a QuerySet is evaluated, it typically caches its results. If the data in the database might have changed since a QuerySet was evaluated, you can get updated results for the same query by calling all() on a previously evaluated QuerySet.

Answer 2

There are two main reasons for clone():

1. It allows chaining. When you chain querysets together (for example, multiple filter() calls), you want a fresh copy of the queryset each time that you can modify.

2. It allows you to avoid stale cache results. Since querysets cache their results when they are evaluated, if you want to make sure you hit the database again you need to clone the queryset.

If you know what you're doing you could use it, but note that it isn't a public API. In this interesting Django developers thread the developers talk about whether or not clone() should be public. They decide against it, in part because:

The biggest problem with public .clone() method is that the private ._clone() doesn't do just cloning. There are some cases where cloning also changes how the QuerySet behaves.