[Notion API][OAuth] relation 속성이 비어 보일 때 source database 공유 범위를 어디까지 열어야 하나

IT 리서치 노트

[Notion API][OAuth] relation 속성이 비어 보일 때 source database 공유 범위를 어디까지 열어야 하나

Notion OAuth 앱에서 database는 잘 열리는데 relation 속성만 비어 보이면 많은 팀이 먼저 잘못된 property ID나 capability 부족을 의심한다. 하지만 2026년 7월 3일 기준 Notion 공식 문서를 다시 보면 relation 속성을 읽거나 바꾸려면 related database도 connection에 공유돼 있어야 하고, linked data source는 원본 source database를 따로 공유해야 한다. 이 글은 relation 속성이 비어 보일 때 source database 공유 범위를 어디까지 열어야 하는지 정리한 것이다.

목차

1. 개요
2. 어디서 실제로 막히는가
3. 실무에서 적용하는 순서
4. 공식 문서와 예시 화면으로 확인하기
5. 주의사항과 리스크
6. 결론
7. 참고 링크

1. 개요

결론부터 말하면 relation 속성 누락은 parent page 하나만 공유해서 해결되지 않는 경우가 많다. source database와 related database를 connection에 각각 열어 두어야 relation schema와 값이 온전하게 보인다. linked view가 Notion 화면에 보인다고 해서 API도 같은 범위를 자동으로 따라가는 것은 아니다.

이미 page와 database 공유 범위 글이 설치 토큰의 큰 범위를 다뤘다면, 이번 글은 relation 누락 상황만 별도로 좁혀 보는 후속편이다. 또 403과 404를 응답 기준으로 나누는 글과 같이 보면 relation 속성 누락을 capability 실패와 섞지 않기 쉬워진다.

relation 조회 누락을 넘어서 실제 schema 수정 단계까지 보려면, 이어서 relation 업데이트가 막힐 때 related database 공유와 linked data source 한계를 어떤 순서로 확인하는지 정리한 글을 같이 보는 편이 좋다. 지금 글이 조회 범위를 다뤘다면, 후속 글은 수정 범위를 다룬다.

2. 어디서 실제로 막히는가

실무에서 흔한 실패는 세 가지다. 첫째, parent page와 현재 보이는 linked view만 공유해 두고 relation 속성도 다 올 것이라고 기대한다. 둘째, source database는 공유했지만 related database를 빠뜨려 relation 값이 부분적으로 비어 보인다. 셋째, retrieve 응답에서 relation 속성이 빠진 것을 object_not_found나 restricted_resource와 같은 층위로만 해석한다.

Notion property 문서는 related database를 공유해야 relation 속성을 retrieve/update할 수 있다고 적고, retrieve a data source 문서는 related database가 공유되지 않으면 relation 기반 속성이 응답에 포함되지 않을 수 있다고 적는다. working with databases 가이드는 linked data source를 API가 직접 지원하지 않으니 원본 source database를 공유하라고 다시 강조한다.

실제 진단에서는 page picker 선택 값을 확인하고, source database를 열어 Add connections를 클릭하고, related database도 같은 방식으로 공유한 뒤, retrieve 응답 JSON과 로그를 저장해서 relation 필드가 돌아왔는지 조회해야 한다. 이 절차를 건너뛰면 403, 404, linked view 착각이 한 번에 섞인다.

• 증상: database는 열리는데 relation 컬럼만 비어 보인다.
• 실패: linked view를 공유했으니 source database도 자동으로 열린다고 본다.
• 막힘: related database 공유 누락을 capability 실패로만 본다.
• 누락: source database와 related database를 분리해 기록하지 않는다.

상황	먼저 볼 곳	판단 기준
relation schema가 아예 안 보인다	source database 공유 여부	linked view가 아니라 원본 database를 열었는지 본다
relation 값이 비거나 일부만 보인다	related database 공유 여부	대상 database를 connection에 추가했는지 본다
linked database만 화면에 있다	source database 위치	API는 linked data source를 직접 지원하지 않는다

3. 실무에서 적용하는 순서

가장 실용적인 점검 순서는 다섯 단계다. 먼저 parent page가 공유됐는지 확인한다. 두 번째로 현재 보이는 database가 linked view인지 원본 source database인지 구분한다. 세 번째로 source database를 connection에 추가한다. 네 번째로 relation 대상 database도 같은 방식으로 공유한다. 마지막으로 retrieve database 또는 retrieve data source 응답에서 relation 속성이 다시 포함됐는지 확인한다.

1. parent page 공유 여부를 먼저 확인한다.
2. 현재 view가 linked인지 원본 source인지 조회한다.
3. source database를 connection에 공유하고 설정 값을 저장한다.
4. related database도 connection에 공유하고 응답을 확인한다.
5. retrieve 응답 JSON과 로그 파일에서 relation 속성이 돌아왔는지 다시 본다.

핵심은 설치 토큰 범위를 '페이지 하나'가 아니라 '리소스 목록'으로 보는 것이다. Notion 문서가 source database와 related database를 각각 따로 언급하는 이유도 이 범위들이 서로 대체되지 않기 때문이다. 실제 운영에서는 공유 화면을 열고, source database를 클릭하고, related database를 추가하고, retrieve를 실행하고, 응답 필드와 로그를 확인하는 순서가 고정돼야 한다.

설치 후 점검 예시

1. Share parent page with the connection
2. Open linked database and locate the source database
3. Share source database with the connection
4. Share related database referenced by relation properties
5. Re-run retrieve database and inspect relation properties

이 순서대로 보면 relation 누락을 잘못된 ID, capability 부족, linked view 착각, related database 공유 누락으로 더 빨리 자를 수 있다.

4. 공식 문서와 예시 화면으로 확인하기

첫 자료는 Notion relation 속성 문서의 핵심 문장이다. relation 속성을 읽거나 수정하려면 related database도 connection에 공유돼 있어야 한다.

relation 속성을 다루려면 related database도 connection에 공유돼 있어야 한다.

즉 부모 database만 공유했다고 relation 값까지 자동으로 온다고 보면 안 된다. relation 대상 database 범위가 빠지면 속성이 비어 보이거나 일부만 보일 수 있다.

두 번째 화면은 retrieve a data source 문서의 경고다. related database가 공유되지 않으면 relation 기반 속성이 응답에 포함되지 않을 수 있다고 적고 있다.

related database가 공유되지 않으면 relation 기반 속성이 응답에서 빠질 수 있다.

현장에서 relation 컬럼이 비어 보일 때 404나 capability 문제만 의심하기 쉬운데, 실제로는 공유 범위가 덜 열린 경우가 많다.

세 번째 자료는 working with databases 가이드의 linked data source 주의점이다. Notion API는 linked data source를 직접 지원하지 않으니 원본 source database를 공유하라고 설명한다.

linked data source가 보여도 API에는 원본 source database 공유가 따로 필요하다.

relation 컬럼이 linked view 안에 있는 경우라면 parent page와 표시된 view만 공유해서는 부족하다. 원본 source database까지 열어야 relation 해석이 맞는다.

공유 범위를 표로 나누면 relation 누락을 더 빨리 좁힐 수 있다. parent page, source database, related database를 한 줄로 합치면 어느 범위가 빠졌는지 찾기 어렵다.

Notion relation 진단은 page, source database, related database를 따로 적는 편이 빠르다.

이미 page와 database 공유 범위 글이 큰 틀을 다뤘다면, 이번 표는 relation 누락 상황만 별도로 좁힌 것이다.

마지막 자료는 설치 직후 남길 수 있는 점검 메모다. relation 누락을 403/404와 구분하려면 어떤 리소스를 공유했는지 한 줄로 남기는 편이 좋다.

relation 누락 상황에서 source database와 related database 공유 범위를 같이 기록하는 메모 예시다.

이 메모가 있으면 post 82처럼 403과 404를 실제 응답 기준으로 나눌 때도 relation 공유 누락이라는 세 번째 분기를 같이 둘 수 있다.

5. 주의사항과 리스크

첫 번째 리스크는 linked database가 보이니 source database 공유도 된 것으로 착각하는 것이다. 두 번째 리스크는 source database만 열어 두고 related database를 빠뜨리는 것이다. 세 번째 리스크는 relation 누락을 404 또는 403의 일반 사례로만 처리해 도움말 문구가 틀어지는 것이다.

설치 직후에는 retrieve 응답을 한 번 저장해 relation 속성 이름과 값이 실제로 포함되는지 확인하는 편이 좋다.

• linked view와 source database는 같은 범위가 아니다.
• related database 공유가 빠지면 relation 값이 비어 보일 수 있다.
• relation 누락은 capability 실패와 별도 분기로 남긴다.

6. 결론

Notion relation 속성이 비어 보일 때는 page만 공유됐는지, source database와 related database까지 연결됐는지를 따로 봐야 한다. source database와 relation 대상 database를 connection 범위에 각각 넣어 두면 설치 직후 schema 누락과 값 누락을 훨씬 빨리 줄일 수 있다.

• parent page, source database, related database를 따로 본다.
• linked data source는 원본 database 공유가 필요하다.
• retrieve 응답으로 relation 속성 복구 여부를 바로 확인한다.

7. 참고 링크

1. https://developers.notion.com/reference/property-object
2. https://developers.notion.com/reference/retrieve-a-data-source
3. https://developers.notion.com/reference/retrieve-a-database
4. https://developers.notion.com/guides/data-apis/working-with-databases