[Notion API][OAuth] relation update 뒤 retrieve 응답과 bidirectional relation 반영을 어떤 순서로 다시 확인하나

IT 리서치 노트

[Notion API][OAuth] relation update 뒤 retrieve 응답과 bidirectional relation 반영을 어떤 순서로 다시 확인하나

Notion relation update를 보낸 뒤 응답이 200인데도 실제 화면과 API 결과가 어긋나면 payload 문법만 다시 보게 되는 경우가 많다. 하지만 2026년 7월 5일 기준 Notion 공식 문서를 다시 보면 bidirectional relation은 dual_property 구조를 가지며, relation 값 검증은 property item retrieve와 pagination, 그리고 관련 데이터소스 쿼리까지 이어져야 더 정확하다. 이 글은 relation update 뒤 retrieve 응답과 bidirectional relation 반영을 어떤 순서로 다시 확인해야 하는지 정리한 것이다.

목차

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

1. 개요

결론부터 말하면 relation update 뒤 검증은 source page 한 번 읽는 것으로 끝나지 않는다. bidirectional relation이라면 source page property item, 관련 database의 reverse relation, 그리고 dual_property가 살아 있는 schema까지 같이 봐야 한다. relation 값이 많을 수 있으므로 next_url 기반 pagination도 검증 루틴에 넣어야 한다.

이미 relation update가 막힐 때 공유 범위를 본 글이 수정 전 조건을 다뤘다면, 이번 글은 수정 후 검증 순서다. 또 relation 속성이 비어 보일 때 source database 공유 범위를 본 글과 같이 보면 조회와 업데이트 검증을 같은 축에서 설명하기 쉬워진다.

relation 개수가 많거나 반대편 relation 반영이 바로 안 보일 때는 retrieve 한 번으로 결론 내리기 어렵다. 그런 경우에는 property item pagination과 bidirectional relation 반영 지연을 재검증하는 글을 이어서 보면 pagination 누락과 반영 지연을 같은 실패로 묶지 않게 된다.

relation 수가 25개를 넘고 formula나 rollup까지 같이 얽히는 경우라면, 이어서 property item pagination과 formula·rollup 결과를 어떤 순서로 구분하는지 다룬 후속 글로 넘어가는 편이 좋다. 지금 글이 update 뒤 양방향 반영 검증을 다뤘다면, 후속 글은 25개 초과 relation과 계산 결과 오판을 분리한다.

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

실무에서 흔한 실패는 네 가지다. 첫째, update 응답이 성공이니 source page retrieve만 보고 끝낸다. 둘째, relation 값이 많아 일부만 가져왔는데 전체가 반영된 것으로 처리한다. 셋째, bidirectional relation인데 반대편 relation 속성 반영 여부를 다시 질의하지 않는다. 넷째, related database 공유가 빠져 reverse verification이 불완전한데 update 실패와 같은 말로 보고한다.

Notion property object 문서는 dual_property가 bidirectional relation에서 대응 속성 정보를 나타낸다고 설명하고, related database 공유가 relation retrieve와 update의 전제라고 적고 있다. retrieve a page property 문서는 relation 속성도 next_url을 따라 paginated list를 끝까지 봐야 할 수 있다고 설명한다. relation filter 문서는 related database를 relation contains 조건으로 다시 query할 수 있는 기준을 제공한다. 이 문서들을 같이 읽으면 relation update 뒤 검증은 한 번의 retrieve가 아니라 source, pagination, reverse query 세 단계라는 점이 보인다.

특히 source page에서 relation 값이 보인다고 해서 bidirectional 반영까지 완료됐다고 결론 내리면 장애가 오래 남는다. 반대편 database query가 빠지면 source만 성공하고 related는 실패한 상태를 놓치기 쉽다.

• 증상: update 200 이후에도 UI나 reverse relation이 기대와 다르다.
• 실패: relation property item pagination을 끝까지 보지 않는다.
• 막힘: bidirectional relation인데 source page 한쪽만 확인한다.
• 누락: reverse query와 shared scope를 같은 검증 루틴에 넣지 않는다.

상황	먼저 볼 곳	판단 기준
source page에는 값이 보인다	property item pagination	전체 relation 목록을 끝까지 읽었는지 본다
reverse relation은 비어 있다	related database contains query	반대편 relation 반영을 직접 질의한다
schema가 예상과 다르다	dual_property와 shared scope	양방향 relation 전제와 관련 DB 공유를 본다

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

점검 순서는 다섯 단계가 가장 실용적이다. 먼저 relation schema에서 dual_property와 shared scope를 확인한다. 두 번째로 source page의 relation property item을 retrieve한다. 세 번째로 next_url이 있으면 끝까지 따라가 전체 relation 목록을 본다. 네 번째로 related database에서 relation contains 조건으로 reverse query를 실행한다. 마지막으로 source와 related 양쪽 결과를 한 줄 메모로 남겨 update 성공과 bidirectional 반영 성공을 분리한다.

1. schema의 dual_property와 공유 범위를 먼저 확인한다.
2. source page relation property item을 retrieve한다.
3. next_url이 있으면 relation 결과를 끝까지 읽는다.
4. related database에서 relation contains query로 역검증한다.
5. source 성공과 reverse 성공을 별도 결과로 기록한다.

핵심은 relation update 성공을 단일 불리언으로 처리하지 않는 것이다. source page 반영, pagination 완료, reverse relation 반영은 각각 다른 확인 단계다. 이 해석은 Notion relation schema, property item, retrieve property, relation filter 문서를 이어 읽은 운영 기준이다.

검증 메모 예시

schema.dual_property=true
source_relation_item_count=2
source_relation_next_url=false
reverse_query.contains_source_page=true
related_database_shared=true
relation_update_verified=true

이 정도만 남겨도 source page에는 붙었는데 reverse relation이 안 보인다, 혹은 전체 relation 중 일부만 봤다는 식의 차이를 다음 장애 때 빠르게 설명할 수 있다.

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

첫 자료는 relation schema의 dual_property 설명이다. Notion은 bidirectional relation일 때 대응 속성 이름과 ID를 dual_property로 응답에 포함한다고 설명한다.

Notion property object 문서는 bidirectional relation에 대응 속성 정보가 dual_property로 나타난다고 설명한다.

즉 relation update 뒤 검증은 source 쪽 relation 값만 보는 것으로 끝나지 않는다. dual_property가 있는 양방향 relation이라면 반대편 속성까지 같이 확인해야 한다.

두 번째 자료는 relation retrieve와 update의 전제 조건이다. related database가 connection에 공유돼 있어야 relation 속성을 retrieve하거나 update할 수 있다고 문서가 다시 적고 있다.

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

이 문장을 놓치면 update 직후 retrieve가 비어 보일 때 body 문제만 다시 보게 된다. 실제로는 반대편 database 공유 누락 때문에 검증 자체가 불완전할 수 있다.

세 번째 자료는 retrieve a page property 문서의 pagination 설명이다. relation, people, rich_text 같은 속성은 property item API에서 next_url을 따라 전체 값을 봐야 할 수 있다고 적혀 있다.

Notion retrieve a page property 문서는 relation 속성도 next_url 기반 pagination으로 끝까지 읽어야 할 수 있다고 설명한다.

즉 relation update 뒤 source page를 retrieve했는데 값이 일부만 보이면 update 실패로 단정할 수 없다. 특히 relation 개수가 많거나 검증 로직이 property item이 아니라 page retrieve에만 묶여 있으면 반쪽짜리 확인이 된다.

네 번째 자료는 property item object 문서의 relation 설명이다. relation 속성 값은 page reference 배열로 반환되며, 개별 item이나 paginated list로 다뤄야 한다는 구조를 다시 확인할 수 있다.

Notion property item 문서는 relation 값이 page reference 배열과 property item 구조로 반환된다고 설명한다.

이 구조를 알고 있어야 source page retrieve와 page property retrieve를 언제 나눌지 판단할 수 있다. relation 반영 검증은 단순한 문자열 비교가 아니라 page reference 목록 확인이다.

다섯 번째 자료는 relation filter 조건 예시다. Notion은 relation 속성에 특정 page id가 포함되는지 contains 조건으로 query할 수 있다고 문서화하고 있다.

Notion relation filter 문서는 relation 속성에 특정 page ID가 들어 있는지 contains 조건으로 다시 질의할 수 있다고 설명한다.

이 예시는 bidirectional relation 반영을 검증할 때 특히 유용하다. source page를 업데이트한 뒤 related database 쪽에서 relation contains source_page_id로 역검증하면 반대편 반영 여부를 한 번 더 자를 수 있다.

실무에서는 update 뒤 검증 순서를 코드 메모로 남겨 두는 편이 좋다. source page property retrieve, related database query, bidirectional 속성 확인이 한 흐름으로 이어져야 재현이 쉽다.

relation update 뒤 source와 related 양쪽을 다시 확인하는 예시다.

이 코드 구조가 있으면 relation update 성공과 bidirectional 반영 성공을 같은 조건으로 묶지 않고 따로 기록할 수 있다. 또 relation update가 막힐 때 공유 범위를 본 글과 연결하면 수정 전 점검과 수정 후 검증이 한 사다리로 이어진다.

마지막 자료는 relation update 후 검증표다. source page, property item pagination, reverse query, dual_property 확인을 같은 표로 두면 어디가 비었는지 빨리 보인다.

relation update 뒤 source와 related 양쪽 반영을 나눠 보는 체크리스트다.

이 표가 있으면 source page 값은 보이는데 reverse relation이 안 보이는지, 아니면 pagination 때문에 일부만 본 것인지, 또는 related database 공유가 빠져 검증이 끊겼는지를 더 짧게 설명할 수 있다.

5. 주의사항과 리스크

첫 번째 리스크는 source page retrieve 하나만 보고 양방향 반영까지 끝났다고 보는 것이다. 두 번째 리스크는 property item pagination을 생략해 일부 결과만 성공 처리하는 것이다. 세 번째 리스크는 related database 공유가 빠진 상태에서 reverse query 실패를 update 실패와 같은 문구로 뭉개는 것이다.

운영 루틴에는 최소한 dual_property 여부, source relation item count, next_url 존재 여부, reverse relation contains query 결과를 같이 남기는 편이 좋다. 그래야 relation update 결과를 한 줄 성공 로그로 뭉개지 않고 실제 반영 범위를 설명할 수 있다.

• source page 확인과 bidirectional 반영 확인을 따로 기록한다.
• relation property item은 pagination까지 끝내고 본다.
• reverse query 실패는 공유 범위와 검증 경로를 함께 본다.

6. 결론

Notion relation update 뒤 검증은 source page 한 번 읽는 것으로 끝나지 않는다. dual_property와 shared scope를 확인하고, relation property item을 끝까지 읽고, related database에서 reverse relation query까지 해야 bidirectional 반영을 더 정확하게 설명할 수 있다.

• source, pagination, reverse query를 따로 확인한다.
• dual_property가 있으면 양방향 반영까지 검증한다.
• update 성공과 bidirectional 성공을 분리해 기록한다.

7. 참고 링크

1. https://developers.notion.com/reference/property-object
2. https://developers.notion.com/reference/retrieve-a-page-property
3. https://developers.notion.com/reference/property-item-object
4. https://developers.notion.com/reference/post-database-query-filter
5. https://developers.notion.com/reference/query-a-data-source