[Notion API][OAuth] relation 업데이트가 막힐 때 related database 공유와 linked data source 한계를 어떤 순서로 확인하나

Sophie_ 2026. 7. 4. 09:15

IT 리서치 노트

[Notion API][OAuth] relation 업데이트가 막힐 때 related database 공유와 linked data source 한계를 어떤 순서로 확인하나

Notion OAuth 앱에서 relation 값을 업데이트하려는데 body 형식은 맞아 보이는데도 변경이 반영되지 않으면 JSON 구조나 capability부터 의심하기 쉽다. 하지만 2026년 7월 4일 기준 Notion 공식 문서를 다시 보면 relation property는 related database 공유를 전제로 하고, linked data source는 원본 source database를 따로 봐야 한다. 이 글은 relation 업데이트가 막힐 때 related database 공유와 linked data source 한계를 어떤 순서로 확인해야 하는지 정리한 것이다.

1. 개요

결론부터 말하면 relation update 실패는 PATCH body만 다시 읽어서는 잘 안 풀린다. source database가 connection에 공유돼 있어야 schema를 제대로 다룰 수 있고, relation 대상인 related database도 따로 공유돼 있어야 update가 가능하다. linked database가 화면에 보인다고 API 수정 범위까지 자동으로 열린 것은 아니다.

이미 relation 속성이 비어 보일 때 source database 공유 범위를 본 글이 조회 단계였다면, 이번 글은 수정 단계다. 또 403과 404를 실제 응답 기준으로 나눈 글과 같이 보면 relation update 실패를 일반 권한 오류와 섞지 않기 쉬워진다.

PATCH가 통과한 뒤 source page retrieve, property item pagination, bidirectional relation 반영까지 어떤 순서로 다시 확인할지 이어서 보려면 relation update 뒤 retrieve 응답과 bidirectional relation 반영을 다시 확인하는 글이 바로 다음 단계다.

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

실무에서 흔한 실패는 네 가지다. 첫째, linked view만 공유해 두고 원본 source database는 connection에 추가하지 않는다. 둘째, source database는 열었지만 relation이 가리키는 related database를 빠뜨린다. 셋째, row update와 schema update를 같은 요청 층위로 생각한다. 넷째, retrieve 응답에서 relation schema가 비정상인데도 body shape만 고친다.

Notion update a data source 문서는 relation property 업데이트에 related database 공유가 필요하다고 적고, property object 문서는 retrieve와 update 모두 related database 공유를 전제로 둔다. working with databases 가이드는 linked data source를 API가 직접 지원하지 않으니 원본 source database를 공유하라고 다시 적는다. 이 세 문서를 같이 읽으면 relation update 실패는 payload보다 리소스 범위 문제일 가능성이 높다는 점이 보인다.

이때 화면에서 보이는 linked database만 열려 있다고 해서 API도 같은 범위를 가진다고 가정하면 원인 진단이 오래 걸린다. Notion UI 범위와 API 범위는 따로 기록해야 한다.

증상: relation schema 또는 값 업데이트가 반영되지 않는다.
실패: source database와 related database 공유를 따로 기록하지 않는다.
막힘: linked view가 보이니 원본 database도 열린 것으로 본다.
누락: retrieve 응답으로 relation 필드 복구 여부를 다시 확인하지 않는다.

상황	먼저 볼 곳	판단 기준
linked view만 보인다	원본 source database 위치	API는 linked data source를 직접 지원하지 않는다
schema update는 가는데 relation만 안 바뀐다	related database 공유 여부	relation 대상 database를 connection에 추가했는지 본다
PATCH 문법은 맞는데 계속 막힌다	retrieve 응답과 schema 범위	relation schema가 정상 복구됐는지 먼저 확인한다

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

점검 순서는 다섯 단계가 가장 짧다. 먼저 현재 보이는 view가 linked인지 원본 source database인지 구분한다. 두 번째로 source database를 connection에 공유한다. 세 번째로 relation 대상 database도 connection에 공유한다. 네 번째로 retrieve data source 응답에서 relation schema가 정상인지 확인한다. 마지막으로 update payload를 다시 보내고 변경 여부를 검증한다.

view가 linked인지 원본 source인지 먼저 구분한다.
source database를 connection에 공유한다.
related database도 같은 connection에 공유한다.
retrieve 응답에서 relation schema를 다시 확인한다.
그다음 relation update payload를 재시도한다.

핵심은 relation update를 capability나 body shape 하나의 문제로 축소하지 않는 것이다. source database, related database, linked view라는 세 리소스가 서로 다른 범위를 가진다고 전제해야 진단이 짧아진다. 이 해석은 Notion data source와 relation 문서를 함께 읽은 운영 기준이다.

공유 범위 메모 예시

linked_view_seen=true
source_database_shared=true
related_database_shared=true
retrieve_data_source.relation_schema_present=true
update_relation_payload_sent=true
relation_update_applied=true

이 메모가 있으면 relation 조회 누락과 수정 누락을 같은 장애 설명으로 뭉개지 않고, 어떤 공유 범위가 빠졌는지 바로 적을 수 있다.

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

첫 자료는 update a data source 문서 첫 구간이다. relation 수정이 data source schema 업데이트라는 층위에서 다뤄진다는 점을 먼저 잡아야 row update와 혼동하지 않는다.

Notion update a data source 문서는 schema 업데이트와 row 업데이트를 분리해 설명한다.

즉 relation 업데이트 실패는 페이지 row 값만 보던 흐름과 다르다. data source schema, source database 위치, 공유 범위를 함께 봐야 한다.

두 번째 자료는 view 변경 한계를 짚는 구간이다. Notion은 linked view 자체를 API가 모두 다루는 구조가 아니라고 분명히 적고 있다.

Notion은 view 조정은 앱에서 하고, API는 data source schema와 리소스 범위를 기준으로 본다고 설명한다.

그래서 화면에 linked database가 보여도 API가 그 범위를 자동으로 따라간다고 보면 안 된다. relation update 문제를 linked view만 보고 해결하려 하면 자주 막힌다.

세 번째 자료는 relation update의 핵심 문장이다. related database를 connection에 공유해야 relation property 업데이트가 가능하다고 문서가 직접 적고 있다.

relation data source property를 업데이트하려면 related database 공유가 필요하다는 Notion 문서 구간이다.

즉 relation 값이 안 바뀌는 문제를 capability나 body shape 탓으로만 돌리기 전에, 대상 database 공유가 빠졌는지 먼저 봐야 한다. 이미 relation 속성이 비어 보일 때 source database 공유 범위를 본 글이 조회 단계라면, 오늘은 수정 단계다.

네 번째 자료는 property object 문서의 relation 설명이다. retrieve와 update 모두 related database 공유를 요구한다는 점을 한 번 더 확인할 수 있다.

Notion property object 문서는 relation retrieve와 update 모두 related database 공유를 전제로 둔다.

이 문장을 보면 relation update 실패는 단순히 PATCH body의 문법보다 리소스 범위를 먼저 봐야 한다는 점이 분명해진다. source database와 related database를 각각 따로 공유해야 한다는 감각도 여기서 생긴다.

다섯 번째 자료는 linked databases 가이드다. Notion은 API가 linked data source를 직접 지원하지 않으니 원본 source database를 공유하라고 경고한다.

working with databases 가이드는 linked data source 대신 원본 source database를 공유하라고 안내한다.

즉 화면에 보이는 linked view만 공유해 두면 relation update가 여전히 막힐 수 있다. 이 경고를 놓치면 설치 토큰이 충분히 열려 있다고 착각하게 된다.

실무에서는 source database와 related database ID를 같이 메모하고 schema 업데이트 payload를 남겨 두는 편이 좋다. 그래야 relation update 실패를 공유 누락과 body shape 문제로 나눠 볼 수 있다.

relation schema 업데이트 payload와 공유 대상 메모 예시다.

이 기록이 있으면 'PATCH는 맞는데 왜 안 되지'라는 질문이 생겼을 때 body 자체보다 공유 범위와 원본 database 위치를 먼저 다시 볼 수 있다. 또 page와 database 공유 범위를 설계한 글과 연결하면 설치 직후 점검표가 더 선명해진다.

마지막 자료는 relation update 장애를 자르는 점검표다. linked view, source database, related database, retrieve 응답을 따로 기록해 두면 원인 분리가 쉬워진다.

relation 업데이트가 막힐 때 source와 related database 범위를 점검하는 체크리스트다.

이 표를 운영 문서에 넣어 두면 relation 조회 누락과 수정 누락을 같은 문구로 답하지 않아도 된다. source와 related 범위를 분리해 기록하는 습관이 핵심이다.

5. 주의사항과 리스크

첫 번째 리스크는 linked view를 원본 source database와 같은 것으로 취급하는 것이다. 두 번째 리스크는 source database만 공유하고 related database는 빠뜨리는 것이다. 세 번째 리스크는 update 실패를 전부 capability 부족으로만 답하는 것이다.

설치 직후에는 source database와 related database ID를 같이 적고, retrieve 응답 JSON을 한 번 저장해 relation schema가 실제로 보이는지 확인하는 편이 좋다. 그래야 update 실패 때도 payload가 아니라 범위부터 다시 점검할 수 있다.

linked view와 원본 source database는 같은 범위가 아니다.
related database 공유 누락은 relation update 실패의 대표 원인이다.
retrieve 응답으로 relation schema 복구 여부를 먼저 본다.

6. 결론

Notion relation 업데이트가 막힐 때는 body 문법보다 source database와 related database 공유 범위를 먼저 확인해야 한다. linked database가 화면에 보여도 API는 원본 source database를 기준으로 보고, relation property 수정은 related database 공유까지 전제로 한다.

linked view, source database, related database를 따로 기록한다.
retrieve 응답에서 relation schema가 정상인지 먼저 본다.
그다음 relation update payload를 다시 보낸다.