Notion DB를 SQL로 조회하다 막힌 6가지와 해결 과정

도입 — Notion DB SQL 쿼리, 첫 줄부터 에러가 납니다

Notion DB SQL 쿼리를 처음 쓰면 대부분 같은 순서로 막혀요. 뷰 필터를 걸어놓고 SQL로 조회했는데 원하지 않는 행까지 다 따라오거나, 한글 컬럼명을 그대로 써서 파싱 에러를 만나거나, 체크박스 조건이 계속 안 먹히는 식으로요. 이 글은 Notion 콘텐츠 캘린더를 MCP의 SQL(SQLite 문법) 모드로 직접 조회하는 자동화를 만들면서 실제로 부딪힌 여섯 가지 함정과, 각각을 피해가는 방법을 정리한 글입니다.

왜 뷰 필터 대신 SQL을 쓰게 되는가

콘텐츠 캘린더처럼 카테고리·상태·발행일이 섞인 DB를 자동화 파이프라인에 붙이다 보면, "상태=발행이면서 카테고리가 같은 것만" 같은 조합 조건이 금방 필요해집니다. 뷰를 그때그때 새로 만들기에는 번거롭고, 백엔드에서 메모리에 올려놓고 필터링하려면 API 호출을 여러 번 해야 하죠. SQL 모드는 이 조건을 한 줄 쿼리로 끝낼 수 있게 해줍니다.

실제로 부딪힌 여섯 가지 함정

1. 데이터소스 URL 자체가 테이블명입니다. 일반 SQL처럼 DB명·테이블명을 따로 쓰는 게 아니라, collection://... 형태의 데이터소스 URL 자체를 FROM 절에 그대로 씁니다. 이 URL은 fetch로 데이터베이스를 먼저 조회해야 <data-source> 태그에서 얻을 수 있습니다. 이 단계를 건너뛰고 눈에 보이는 이름만 적으면 스키마가 없다는 에러만 마주하게 됩니다.
2. 뷰의 필터·정렬은 자동으로 상속되지 않습니다. 화면에서 특정 뷰에 필터를 걸어놓았더라도, SQL 쿼리는 그 필터를 상속받지 않습니다. WHERE 절에 필요한 조건을 전부 명시적으로 다시 써야 하고, 이걸 놓치면 원치 않는 행까지 다 긁어옵니다.
3. 한글 프로퍼티명은 반드시 큰따옴표로 감싸야 합니다. "상태", "카테고리"처럼 프로퍼티명이 한글이거나 공백이 섞여 있으면, 큰따옴표 없이는 파싱 자체가 실패합니다.
4. 체크박스는 TRUE/FALSE가 아니라 전용 문자열입니다. 체크박스 프로퍼티를 비교할 때는 __YES__/__NO__라는, 처음 보면 당황스러운 전용 문자열을 써야 합니다.
5. 날짜 비교는 정규화가 필요합니다. 텍스트로 저장된 타임스탬프를 그대로 비교하면 정렬이나 범위 조건이 어긋날 수 있어, datetime()/date() 함수로 감싸야 맞는 결과가 나옵니다.
6. 속도 제한과 멀티 데이터소스 제약이 있습니다. 단일 데이터소스 SQL 쿼리는 Free·Plus 플랜에서 시간당 호출 제한이 걸리고, 여러 데이터소스를 조인하는 쿼리는 Notion AI가 포함된 Enterprise 플랜이 있어야 합니다. Notion 공식 문서 기준으로는 정확한 "시간당 횟수"보다 초당 요청 수로 안내되는데, 연결(커넥션) 단위로는 평균 초당 3회, 워크스페이스 전체로는 플랜에 따라 스케일되는 공유 한도가 별도로 적용되는 구조입니다. 이 공유 한도 때문에 연결 단위 제한 안에 있어도 막힐 수 있으니, 병렬 호출을 줄이고 순차 조회 위주로 설계하는 편이 안전합니다.

실제로 돌려보니 이 다섯 가지(1~5번)를 반영한 쿼리는 대략 이런 모양입니다.

SELECT "제목", "상태", "발행일"
FROM "collection://32d925a8-1833-427f-a13a-e8900c7a3725"
WHERE "상태" = ?
  AND "완료여부" = ?
  AND datetime("발행일") >= datetime(?)

위처럼 파라미터를 ?로 바인딩하고 값을 배열로 넘기는 방식이, 문자열 연결보다 안전하고 위 다섯 가지 함정을 한 번에 피해가는 데도 유리합니다.

주의사항 / 흔한 실수

함정 증상 해결

함정	증상	해결
테이블명 오인식	"테이블을 찾을 수 없다" 류의 스키마 에러	fetch로 먼저 데이터소스 URL을 확보하고 그대로 FROM에 사용
뷰 필터 상속 가정	의도보다 많은 행이 조회됨	WHERE에 조건을 매번 명시적으로 작성
따옴표 누락	파싱 에러	한글·공백 포함 컬럼명은 항상 큰따옴표로 감싸기
체크박스 TRUE/FALSE 비교	조건이 조용히 실패(대상 0건)	__YES__/__NO__ 문자열로 교체
날짜 문자열 직접 비교	정렬·범위가 기대와 다름	datetime()/date()로 정규화 후 비교
대규모 조인 시도	요금제 제한에 걸림	단일 데이터소스로 분해해 각각 조회 후 코드에서 병합

마무리

Notion DB를 SQL로 다루려면, 테이블명 대신 데이터소스 URL을 쓸 것, 뷰 필터를 믿지 말고 WHERE에 다 적을 것, 한글 컬럼명은 큰따옴표로, 체크박스는 전용 문자열로, 날짜는 정규화해서 비교할 것, 그리고 대규모 조인은 요금제 제약을 염두에 둘 것. 이 여섯 가지만 기억해도 체감 시행착오의 대부분을 피해갈 수 있습니다.

노션 API를 콘텐츠 자동화에 붙이는 전체 구조가 궁금하다면 "다음 콘텐츠 만들어줘" 한 마디로 돌아가는 노션 자동화 설계기도 함께 참고해보세요.

"다음 콘텐츠 만들어줘" 한 마디로 돌아가는 노션 자동화 설계기

 

자주 묻는 질문

SQL 모드와 뷰 모드, 언제 무엇을 써야 하나요?

단순 목록·필터만 필요하면 뷰 모드가 더 간단합니다. 여러 조건 조합, 집계, 조인이 필요하면 SQL 모드가 훨씬 빠릅니다.

멀티 데이터소스 조인이 안 될 때는 어떻게 하나요?

요금제 제약이라면, 각 데이터소스를 따로 조회해서 코드(예: Python 딕셔너리)에서 병합하는 우회가 가능합니다.

---

[핵심요약]

Notion DB SQL 조회 실수 6가지와 회피법 정리