[In-depth] django queryset + SQL

3년차 백엔드 개발자로서 항상 써왔던 orm이지만, 쓰던것만 사용하다보니 잘 사용하지 않는 queyset 활용 방법에 대해서는 조금 무지했던 것 같다. 그래서 공식 document를 보고 차근차근 하나하나 정리를 해보며 한번 더 머리에 새길려고 한다.

 

---

[Queryset API]

 

filter(*args, **kwargs): 조건에 맞는 객체들만 담은 queryset을 반환, 여러 조건을 주면 AND 조건으로 묶인다.

- lookups (method: filter(), exclude(), get())

exact: 정확한 일치 -> SQL: SELECT ... WHERE id = 14;

iexact: 대소문자 구분 없는 정확한 일치-> SQL:SELECT ... WHERE name ILIKE 'beatles blog';

contains: 포함 여부-> SQL: SELECT ... WHERE headline LIKE '%Lemon%';

icontains: 대소문자 무시 포함 여부-> SQL: SELECT ... WHERE headline ILIKE '%Lemon%';

in: 리스트/쿼리셋에 포함 여부-> SQL: SELECT ... WHERE id in (1, 3, 4);

gt, gte, lt, lte: ~보다 크다, ~보다 크거나 같다, ~보다 작다, ~보다 작거나 같다-> SQL: SELECT ... WHERE price >= 1000;

startswith: 해당 문자열로 시작-> SQL: SELECT ... WHERE name LIKE 'Kim%';

istartswith: 대소문자 구문 없이 시작-> SQL: SELECT ... WHERE LOWER(name) LIKE 'kim%'

endswith: 해당 문자열로 끝남-> SQL: SELECT ... WHERE name LIKE '%Kim';

iendswith: 대소문자 구분 없이 끝남-> SQL: SELECT ... WHERE LOWER(name) LIKE '%kim'

range: 범위 조회-> SQL: SELECT ... WHERE date BETWEEN '2025-01-01' AND '2025-12-31'

date, month, year, day: 날짜, 월, 년, 일-> SQL: SELECT ... WHERE DATE(timestamp) = '2025-09-30', WHERE EXTRACT(MONTH FROM order_date) = 9, WHERE EXTRACT(YEAR FROM order_date) = 2025, WHERE EXTRACT(DAY FROM order_date) = 30

week: 주차-> SQL: SELECT ... WHERE EXTRACT(WEEK FROM order_date) = 40

iso_year: ISO 연도-> SQL: SELECT ... WHERE EXTRACT(ISOYEAR FROM order_date) = 2025

iso_week_day: ISO 요일 (1=월, 7=일)-> SQL: SELECT ... WHERE EXTRACT(ISODOW FROM order_date) = 1

quarter: 분기 (1~4)-> SQL: SELECT ... WHERE EXTRACT(QUARTER FROM order_date) = 3

time, hour, minute, second: 시간, 시, 분, 초-> SQL: SELECT ... WHERE CAST(timestamp AS time) = '14:30:00', WHERE EXTRACT(HOUR FROM timestamp) = 14, WHERE EXTRACT(MINUTE FROM timestamp) = 30, WHERE EXTRACT(SECOND FROM timestamp) = 0

is_null: null 여부-> SQL: SELECT ... WHERE last_login IS NULL

regex: 정규식 매칭-> SQL: SELECT ... WHERE username ~ '^[A-Z]'

iregex: 대소문자 구분 없는 정규식 매칭-> SQL: SELECT ...WHERE username ~* '^[a-z]'

 

exclude(*args, **kwargs): 조건에 맞는 객체들을 제외한 queryset을 반환한다.

 

annotate(*args, **kwargs): queryset의 각 객체에 계산된 필드를 추가한다. 집계, 조건, 단순 값 등 다양한 값을 각 객체에 붙인다. 원본 모델에는 없는 임시 필드를 생성한다고 생각하면 된다. alies도 지정 가능하다.

 

alias(*args, **kwargs): annotate()와 유사하지만 객체에 값을 추가하지 않고, 표현식을 나중에 재사용할 수 있도록 저장한다. 결과값 자체가 필요 없지만 다른 queryset 메서드 등에서 활용할 때 유용하다. 사용하지 않는 값을 DB에서 선택하지 않기 때문에 성능 최적화 면에서도 유용하다.

from django.db.models import Count, F
# 1. alias로 표현식 정의
blogs = Blog.objects.alias(entries=Count("entry"))
# 2. alias를 filter에서 활용
blogs_with_many_entries = blogs.filter(entries__gt=5)

# Blog 객체마다 Entry 개수를 계산(alias), 이를 annotate로 실제 필드처럼 쓰고, 마지막에 모든 Blog의 Entry 총합을 구한다.
Blog.objects.alias(entries=Count("entry")).annotate(
    entries=F("entries")
).aggregate(Sum("entries"))

 

order_by(*fileds): queryset의 정렬을 지원한다. 기본적으로 queryset은 모델의 Meta.ordering에서 지정한 순서로 정렬된다. 무작위 정렬에는 "?"이 사용되며 DB에 따라 성능이 저하될 수 있는 가능성이 있다. nulls_first / nulls_last로 null 정렬 제어가 가능하다. 또한 distinct()와 함께 사용 시 관계 필드 정렬이 예상과 다르게 작동할 수 있다. 대소문자 구분 없이 정렬하기 위해서는 Lower()를 사용한다. 또 예를 들어 Objects.order_by("A").order_by("B")를 하게 되면 마지막 order_by만 적용된다.

 

reverse(): queryset의 순서를 뒤바꾸고 싶을 때 사용한다.qs.reverse().reverse() 이런식으로 호출하면 원래 순서로 돌아오게 된다.

 

distinct(*fields): qQuerySet에서 중복된 행(row)을 제거할 때 사용하는 메서드로, SQL의 SELECT DISTINCT와 대응된다. 일반적으로 단순한 쿼리에서는 중복이 거의 발생하지 않지만, 여러 테이블을 조인하거나 복잡한 쿼리를 수행할 경우 중복된 결과가 나타날 수 있어 이때 distinct()를 사용하면 중복을 제거할 수 있다. 다만, order_by()와 함께 사용할 경우 주의가 필요하다. order_by()에서 지정한 필드들이 SQL의 SELECT 절에 포함되기 때문에, 겉보기에는 중복이 제거되지 않은 것처럼 보일 수 있으며, 예상과 다른 결과가 나타날 수 있다. 또한, values()와 함께 사용할 때도 정렬 기준이 values()에 포함되어 있지 않으면 중복 제거가 의도한 대로 동작하지 않을 수 있다. 따라서 distinct()를 사용할 때는 쿼리의 정렬 기준과 선택된 컬럼을 함께 고려해야 한다.

 

values(): queryset를 순회할 때 모델 인스턴스 대신 딕셔너리를 반환하도록 하는 메서드, 각 딕셔너리는 모델 객체를 나타내며 key는 모델의 필드 이름과 대응된다. 기본적으로 모든 필드를 반환하지만 values("")로 지정도 가능하다.키워드 인자로 계산식이나 표현식도 포함 가능(values(lower_name=Lower("name"))) 하다. 관계 필드도 조회 가능하지만, 다대다나 역참조는 결과가 곱해질 수도 있다.

 

values_list(): values()와 유사하지만 딕셔너리 대신 튜플을 반환한다. 단일 필드 조회시 flat=True를 지정하면 튜플 대신 단일 값으로 반환되며 named=True를 지정하면 namedTuple로 반환 가능하다.

 

dates(field, kind, order='ASC'): queryset에서 특정 날짜 필드의 모든 날짜를 datetime.date 객체 리스트로 반환한다. field는 모델의 DateFiled 이름, kind는 반환할 날짜 단위 지정 ("year", "month", "week", "day"), order는 정렬 순서이다. 결과 리스트에는 지정한 단위로 중복 제거 후 반환되며 filter와 함께 사용하면 특정 조건에 맞는 날짜만 추출할 수 있다.

 

datetimes(field, kind, order='ASC', tzinfo=None): queryset에서 특정 DatetimeField의 모든 날짜/시간을 datetime.datetime 객체 리스트로 변환하며, kind에는 반환할 단위 ("year", "month", "week", "day", "hour", "minute", "second")가 들어가며 지정한 단위로 truncated되어 반환한다. tzinfo는 반환 전 시간대를 변환할 tzinfo 객체로, None이면 현재 Django 시간대를 사용한다. timezone.utc이 들어가면 utc 시간대로 변환된다.

 

none(): 절대 결과를 반환하지 않는 빈 queryset 생성하며, isinstance(Entry.objects.none(), EmptyQuerySet)  # True 이런식으로 사용된다.

 

all(): 현재 queryset의 복사본을 반환하며, 기본적으로 많이 사용된다.

 

union(*other_qs, all=False): sql의 UNION 연산자를 사용해 두 개 이상의 queryset 결과를 합치는 메서드이다. 기본 동작은 중복값을 제거하고 합친다. 중복을 허용하려면 all=True 인자를 사용한다. 첫 번째 기준 queryset으로 모델을 반환한다.

 

intersection(*other_qs): sql의 INTERSECT 연산과 동일하다. 여러 queryset에서 공통으로 존재하는 값만 반환한다. 기본적으로 중복은 제거된다. 첫 번째 기준 queryset으로 모델을 반환한다.

qs1 = Author.objects.values_list("name")           # [('Alice',), ('Bob',), ('Charlie',)]
qs2 = Entry.objects.values_list("headline")       # [('Bob',), ('Zebra News',), ('Charlie',)]
qs3 = Extra.objects.values_list("title")          # [('Charlie',), ('Alice',)]

qs_common = qs1.intersection(qs2, qs3)
print(list(qs_common))  # [('Charlie',)]

 

difference(*other_qs): sql의 EXCEPT 연산과 동일하다. 첫 번째 queryset에는 존재하지만, 다른 Queryset에는 없는 값들만 반환한다. 첫 번째 기준 queryset으로 모델을 반환한다.

 

extra(): django orm만으로 표현하기 어려운 복잡한 SQL 구문을 queryset에 직접추가할 때 사용, 최후의 수단으로 사용하길 권장한다. 오래된 API이기 때문에 향후 없어질 예정이라고 한다.

 

defer(*fields): 모델의 일부 필드를 나중에 불러오도록 지연시키는 것이다. 모델에 데이터가 많고 일부 필드는 무겁거나 필요 없는 경우에 사용한다.

 

only(*fields): 즉시 불러올 필드만 지정하며, 나머지는 defer이 적용된다. 거의 모든 필드를 지연시키고 필드 일부만 즉시 가져옥 싶을 때 사용한다.

 

using(alias): 여러 DB를 사용할 때 특정 DB를 선택하는 것이다. 예를 들어 Entry.objects.using("backup") 식으로 사용한다. 예를 들어 django 프로젝트에 DATABASES = {'defualt': {}, 'backup': {}} 이렇게 두 개의 DB가 있다고 가정한다.  DB 지정 없이 조회하면 항상 default DB에서 가져온다. 특정 DB를 사용하기 위해 첫번째 줄 처럼 지정하면 backup DB에서 데이터를 가져온다. 즉, 동일한 모델 Entry라도 DB를 바꿔서 조회가 가능하다. **** 하지만 Entry.objects.using("backup").create(title="Test") 처럼 DB를 바꾸면 쓰기도 해당 DB에서 이루어지기 때문에 주로 읽기 전용 쿼리에서 사용된다.

 

raw(raw_query, params=(), translations=None, using=None): SQL을 직접 실행하고, 결과를 모델 인스턴스로 반환한다.

# ORM으로 안되는 복잡한 쿼리
entries = Entry.objects.raw("SELECT * FROM entry WHERE rating > %s", [5])
for e in entries:
    print(e.title)

 

---

[Queryset method]

 

get(*args, **kwargs): 조건에 맞는 객체 하나를 가져온다. 무조건 하나만 존재해야하며, 객체가 없을 땐DoesNotExist, 객체가 여러개일 땐 MultipleObjectsReturned 에러가 발생한다.

 

create(): 객체를 생성함과 동시에 저장까지 한번에 수행한다. pk를 수동으로 지정해서 중복되면 IntegrityError가 발생한다.

 

get_or_create(): 객체가 존재하면 가져오고 없으면 생성한다. 반환값에 obj, created에서는 created가 True면 새로 생성된 값이다. 키워드 인자가 유일해야 동시성 문제 방지가 가능하며 여러 개 발견되면 마찬가지로 MultipleObjectsReturned 에러가 발생한다.

 

update_or_create(): 객체가 존재하면 업데이트하고, 없으면 새로 생성한다. defaults는 업데이트 시 필드고 create_defuaults는 생성 시의 필드이다.

 

bulk_create(): 여러 객체를 한번에 DB에 저장한다.

objs = Entry.objects.bulk_create([
    Entry(headline="This is a test"),
    Entry(headline="This is only a test"),
])

 

bulk_update(): 여러 객체를 효율적으로 업데이트 가능하다.

objs[0].headline = "Updated 1"
objs[1].headline = "Updated 2"
Entry.objects.bulk_update(objs, ["headline"])

 

count(): DB의 개수 조회가 가능하다. 이미 queryset이 평가된 경우 len()이 더 빠르다.

 

in_bulk(): pk 또는 특정 유니크 필드를 기준으로 딕셔너리로 반환된다.

 

iterator(): 메모리 효율적으로 결과를 한 번에 읽지 않고 순회한다. 대용량 데이터 처리에 유용하다.

 

latest() / earliest(): 특정 필드 기준으로 가장 최신 / 가장 오래된 객체를 반환한다. 

 

first() / last(): queryset의 첫 번째 / 마지막 객체를 반환하며 객체가 없으면 None을 반환한다.

 

aggregate(): queryset의 집계를 dict으로 반환한다.

 

exists(): 조건에 맞는 객체가 있으면 True를 반환하며, if queryset: 보다 데이터베이스의 부하가 적다.

 

contains(): queryset에 특정 객체가 포함돼 있는지 확인한다.

 

update(): 조건에 맞는 객체를 한번에 sql로 업데이트한다. save() 반복 호출이 불필요하기 때문에 효율적이다.

Entry.objects.filter(pub_date__year=2010).update(comments_on=False)

 

delete(): 조건에 맞는 객체를 한번에 삭제한다.

 

as_manager(): queryset 메서드를 가진 커스텀 Manager를 생성한다.

MyQuerySet.as_manager()

# 사용예시

from django.db import models

# 1. 커스텀 QuerySet 정의
class EntryQuerySet(models.QuerySet):
    def published(self):
        return self.filter(is_published=True)
    
    def recent(self):
        return self.order_by('-created_at')

# 2. QuerySet 메서드를 Manager로 변환
class Entry(models.Model):
    title = models.CharField(max_length=200)
    is_published = models.BooleanField(default=False)
    created_at = models.DateTimeField(auto_now_add=True)

    objects = EntryQuerySet.as_manager()

 

explain(): 쿼리 실행의 계획을 조회한다.

print(Entry.objects.filter(title="My Blog").explain())

 

reference: django document https://docs.djangoproject.com/en/5.2/