Skip to content

Notion API 데이터베이스 질의

개요

웹빌더가 "노션이 웹사이트가 된다"고 하려면, 노션 데이터베이스에 담긴 구조화된 콘텐츠를 읽어야 해요. Notion에서 데이터베이스(Database) 란 "워크스페이스 안에서 필터·정렬·조직할 수 있는 페이지들의 모음"이에요. 각 행(row)은 곧 하나의 페이지고, 그 페이지들이 속성을 가져요. API는 이 데이터베이스를 나타내는 database object와 그 아래 페이지들을 질의하는 방법을 제공해요. 이 페이지는 공식 문서 기준으로 데이터베이스 구조와 질의 방식을 풀어요.

핵심 개념

데이터베이스가 API에서 어떻게 표현되는가

Database object는 데이터베이스의 제목·부모·속성 스키마 등을 담아요. 공식 문서에 따르면 데이터베이스는 하나 이상의 data source(데이터 소스) 목록을 갖고, 각 data source는 그 아래 페이지(행)들의 부모로 동작해요. 즉 데이터베이스 → 데이터 소스 → 페이지(행)로 이어지는 구조예요.

{
  "object": "database",
  "id": "248104cd-477e-80fd-b757-e945d38000bd",
  "title": [ { "type": "text", "text": { "content": "Grocery DB" } } ],
  "parent": { "type": "page_id", "page_id": "..." },
  "is_inline": false,
  "in_trash": false
}

데이터베이스에 항목 추가하기

데이터베이스의 각 행은 페이지로 표현되며, 각 컬럼은 그 페이지의 속성(property) 이에요. API로 데이터베이스에 항목을 추가하려면 새 페이지를 만들고 그 속성들을 채워요. 노션의 다양한 컬럼 유형(텍스트·숫자·선택·관계 등)이 각각에 대응하는 속성 값으로 들어가요.

데이터베이스에서 항목 찾기

데이터베이스 안에서 원하는 항목을 찾는 건 질의(query) 로 해요. 조건으로 필터(filter) 를 걸고 정렬(sort) 을 지정해서 원하는 페이지 목록을 가져와요. 예를 들어 "상태가 '발행'인 포스트만 최신순으로" 같은 질의를 API로 표현할 수 있어요. 질의 결과는 페이지 목록으로 돌아오고, 각 페이지의 속성으로 원하는 값을 읽어요.

링크/위키 데이터베이스

공식 문서는 두 가지 특수한 데이터베이스 유형을 언급하면서 공개 API가 지원하지 않는다고 분명히 해요. 하나는 연결 데이터베이스(linked database) 로, 같은 데이터를 여러 곳에 보여주는 것이고(원본 데이터 소스가 공유되어야 함), 다른 하나는 위키 데이터베이스로, 워크스페이스 오너가 자식 페이지·DB를 정리할 수 있는 카테고리예요. 이 둘은 공개 API로 지원되지 않으니, 연결을 공유할 땐 반드시 원본 데이터 소스가 공유되도록 해야 해요.

실제 적용 (데이터스케쳐스)

웹빌더에서 노션 데이터베이스는 웹사이트의 구조화된 콘텐츠 원천이에요. 예를 들어 고객이 노션 DB에 "글 제목, 본문, 발행 상태" 같은 속성으로 콘텐츠를 정리해 두면, API로 그 DB를 질의해 발행 상태인 항목만 골라 웹 페이지로 변환해요. 필터·정렬로 "어떤 항목을 보여줄지"를 결정하는 게 곧 사이트 구성이 되죠.

여기서 놓치기 쉬운 점은 DB의 각 행이 곧 페이지라는 구조예요. 그래서 항목을 "추가·수정"하는 것도 페이지의 속성을 다루는 일이고, 블록기반 본문을 읽는 건 페이지에 속한 블록을 가져오는 일이에요. 변환 시 속성 스키마가 바뀌면 깨질 수 있으니, 데이터 소스를 명확히 공유하고 속성 스키마를 관리해야 해요. 인증을 어떻게 받는지는 인증, 변경을 실시간으로 받는 방법은 웹훅에서 이어져요.

더 알아보기