AI Search가 D1을 읽습니다: 검색에 넣을 행과 동기화 실패를 먼저 정하세요

AI Search에 D1을 연결하기 전에는 검색에 공개할 행과 열, 변하지 않는 ID, 동기화가 실패했을 때 남는 내용을 먼저 정해 보세요. Cloudflare는 2026년 11월 12일 D1 데이터베이스를 AI Search의 데이터 소스로 사용할 수 있는 베타 기능을 발표했습니다. 데이터베이스의 모든 내용을 실시간으로 보여 주는 연결로 이해하기보다, 쿼리가 돌려준 행을 검색용 문서로 만드는 과정으로 읽으면 적용 범위가 분명해져요.

이 글은 D1에 FAQ·게시글·상품 설명 등을 저장하고 검색을 붙이려는 개발자와 운영자를 위한 검토 안내입니다. 11월 13일에 공식 공지와 현재 D1·동기화·요금 문서를 확인했어요. 아래 게시 상태와 데이터 구성은 설명을 위해 만든 예시이며, 실제 고객 데이터나 검색 성능을 측정한 사례는 아닙니다.

먼저 원본 테이블과 검색 문서를 나눠 보세요

공식 안내에 따르면 AI Search는 사용자가 지정한 읽기 전용 쿼리를 실행하고, 결과의 각 행을 별도 문서로 색인합니다. 대시보드, REST API, Workers binding에서 D1 기반 인스턴스를 만들 수 있어요. D1은 기본 제공 저장소와 함께 쓸 수 있는 선택적 데이터 소스이며, 현재 베타라는 적용 상태도 함께 기록해야 합니다.

따라서 도입 질문은 “어느 데이터베이스를 연결할까?”에서 끝나지 않아요. 같은 테이블에 공개 FAQ와 내부 메모가 함께 있다면 무엇을 검색에 넣을지 먼저 나눠야 합니다. 가상의 게시글 테이블이라면 공개 상태인 행만 반환하도록 조건을 검토할 수 있겠죠. 이 예시는 특정 스키마의 안전성을 확인한 결과가 아니라 공개 범위를 명시하자는 제안입니다.

열도 같은 방식으로 고르세요. 관리 화면에서 편리하게 쓰는 작성자 메모, 내부 분류, 임시 값까지 검색 문서에 필요한 것은 아닐 수 있어요. 공식 문서도 필요한 열만 선택하도록 권합니다. 선택한 열의 내용이 최종 문서에서 어떻게 보이는지 확인하고, 그 문서를 읽을 사람과 데이터 소유자가 의도한 범위가 같은지 검토하세요.

읽기 전용이라는 성질과 공개 범위는 서로 다른 질문입니다. 원본을 수정하지 않는 쿼리라도 반환한 정보는 검색용 문서에 들어갈 수 있어요. 검색 결과의 접근 제어까지 쿼리 하나가 대신한다고 가정하지 말고, 대상 앱의 사용자 구분과 실제 검색 경로를 별도로 확인하는 편이 좋겠습니다.

ID와 열 이름은 다음 동기화까지 생각해 정해요

쿼리는 고유하고 비어 있지 않은 id 열을 반환해야 합니다. 문서는 ID의 자료형과 허용 범위도 정하고 있어요. 중요한 점은 같은 문서를 다음 동기화에서도 같은 대상으로 식별할 수 있어야 한다는 것입니다. 제목처럼 자주 고치는 값을 식별자로 삼기 전에는 변경의 의미를 생각해 보세요.

공식 문서에서 행의 ID 변경은 기존 아이템 삭제와 새 아이템 생성으로 설명됩니다. 예를 들어 “환불 안내”의 제목을 고쳤을 뿐인데 제목에서 만든 ID까지 달라진다면, 콘텐츠 수정과 문서 교체가 함께 일어나는 셈이에요. 이 예시는 실제 오류를 재현한 것이 아니며, 안정적인 기본 키를 검토할 이유를 보여 줍니다.

AI Search는 열 이름에 따라 역할을 구분합니다. title은 문서 제목, content는 본문으로 사용할 수 있고, meta_로 시작하는 열은 사용자 지정 메타데이터가 됩니다. 원본 열 이름이 다르면 별칭으로 역할을 지정할 수 있어요. 문서로 보일 텍스트와 검색을 좁히는 속성을 먼저 구분해 두면 설정을 읽기 쉽습니다.

한 행의 내용을 어떤 Markdown 문서로 만들지도 선택합니다. 현재 문서에는 Labelled, Content only, Key-value, JSON 템플릿이 안내돼 있어요. 고객에게 읽힐 설명과 구조화된 상품 속성은 같은 표시 방식이 편하지 않을 수 있습니다. 이름만 보고 결정하기보다 공식 대시보드의 한 행 Test query와 생성 문서를 확인할 항목으로 남겨 두세요.

평범한 SQL과 이 연결이 허용하는 쿼리는 달라요

D1 데이터 소스 쿼리는 SELECT 또는 WITH로 시작하는 단일 읽기 전용 문장이어야 합니다. 쓰기·관리 키워드와 특정 예약 이름, 바인딩 매개변수 등에 제한이 있어요. 일반 SQL 도구에서 실행할 수 있다는 사실만으로 AI Search의 검증도 통과한다고 판단하기 어렵습니다.

특히 세미콜론과 SQL 주석 기호, 차단된 키워드는 문자열 리터럴 안에서도 거절된다고 현재 문서에 적혀 있습니다. 익숙한 쿼리를 복사하고 맨 끝에 세미콜론을 붙이는 작은 습관도 이 입력에서는 확인 대상이에요. 여기서는 실행할 SQL을 제공하거나 직접 시험하지 않았으니, 적용할 쿼리는 공식 요구사항과 실제 스키마를 함께 대조하세요.

현재 D1 문서는 ORDER BY나 LIMIT를 사용하지 말라고 안내합니다. AI Search가 ID 순으로 결과를 나누어 읽기 때문입니다. 테스트용으로 몇 행만 읽으려는 의도와 실제 연결 쿼리의 읽기 방식이 섞이지 않도록 구분해 주세요. 공개 범위를 줄이려면 어떤 행이 대상인지 나타내는 조건부터 검토할 수 있습니다.

상한은 하나만 있는 것도 아닙니다. D1 결과 행 수, 행당 렌더링 문서 크기, ID와 메타데이터의 제한 외에 일반 인스턴스 파일 한도가 함께 적용됩니다. 큰 테이블을 연결할 계획이라면 “DB가 이 행 수를 저장한다”와 “이 검색 인스턴스가 모든 결과를 색인한다”를 각각 확인해야 해요.

동기화가 성공한 경우와 빈 결과를 구분하세요

D1 같은 외부 데이터 소스는 동기화 작업으로 새 행과 수정·삭제를 반영합니다. 현재 동기화 문서의 기본 간격은 24시간이며, 설정할 수 있는 간격과 수동 작업 시작 방법도 따로 안내돼 있어요. 원본 변경 직후 검색 결과가 반드시 바뀐다는 실시간 보장으로 읽지 않는 것이 좋겠습니다.

D1 문서는 전체 쿼리 결과를 다 읽은 뒤, 더 이상 반환되지 않는 행의 아이템을 삭제한다고 설명합니다. 그런데 쿼리가 실패하거나 아무 행도 반환하지 않으면 작업이 오류로 끝나고 기존 색인 아이템은 유지됩니다. “결과가 0개니까 검색에도 0개가 남는다”는 추론과 실제 문서의 동작이 다르다는 점이 핵심이에요.

가상의 공개 FAQ 한 건을 비공개로 바꾸는 상황을 생각해 보세요. 원본의 공개 조건에서 그 행이 빠졌는지, 동기화 작업이 전체 결과를 정상적으로 읽었는지, 검색에서 해당 내용이 회수됐는지를 나눠 볼 수 있습니다. 원본 수정 표시 하나만 보고 검색에서의 회수까지 끝났다고 쓰지 않는 방식입니다.

전체 콘텐츠를 일시적으로 숨기려는 계획이라면 특히 신중해야 해요. 쿼리가 빈 결과를 반환했을 때 기존 아이템이 남는 조건 때문에, 원하는 회수 동작이 실제로 일어났는지 별도 확인이 필요합니다. 이 글은 인스턴스나 데이터베이스 삭제를 제안하지 않으며, 서비스의 접근 제어·콘텐츠 회수 절차를 담당자와 함께 검토하자는 안내입니다.

현재 동기화 문서는 검색 요청이 없는 외부 데이터 소스 인스턴스의 예약 작업이 자동으로 일시중지되는 조건도 설명합니다. 일시중지돼도 검색 자체는 가능하지만 원본 변경을 받지 않을 수 있어요. 내용이 오래돼 보일 때는 원본 작성일뿐 아니라 Jobs의 상태와 최근 정상 완료 시점도 함께 읽어 보세요.

행 수보다 읽기량과 변경 빈도를 함께 보세요

공식 D1 안내에 따르면 각 동기화는 ID를 확인하는 단계와 페이지 단위 읽기 때문에 전체 쿼리 결과를 적어도 두 번 읽습니다. 이 작업은 D1의 rows read에 포함돼요. 결과 문서가 적다는 사실만으로 원본 읽기량도 항상 작다고 가정하기 어려운 이유입니다.

원본에 조회수처럼 자주 바뀌는 열이 있으면 검색 답변에 필요한지 검토해 보세요. 문서는 값이 바뀌면 행을 다시 색인하므로 이런 변동 열을 제외하는 방식을 권합니다. 검색 내용을 바꾸지 않는 운영 값까지 포함할 때 어떤 일이 생기는지 생각하는 것이며, 특정 비용 절감률을 보장하는 제안은 아닙니다.

안정적이고 색인이 있는 ID도 읽기 방식과 관련됩니다. 계산해서 만드는 ID는 페이지마다 전체 결과를 스캔할 수 있다고 문서가 안내해요. 운영자가 쿼리를 검토할 때 원본 기본 키, 결과 ID, 필터 조건을 함께 적어 두면 단순히 검색 화면만 보는 것보다 확인할 대상을 좁힐 수 있습니다.

요금 문서도 같은 기준일로 읽어 두세요. 11월 13일 확인한 현재 안내에는 AI Search 과금 시작일이 2026년 12월 1일로 제시돼 있고, 서비스별 포함 범위가 구분돼 있습니다. 이 글은 예상 청구서를 계산하지 않습니다. D1 읽기량과 생성 모델 사용처럼 별도 조건이 있는 항목까지 실제 계정의 요금 기준으로 확인해 주세요.

작게 시작할 때 남기면 좋은 세 가지 기록

첫 기록은 데이터 범위입니다. 어느 데이터베이스의 어떤 행·열이 대상인지, 공개 조건과 ID가 무엇인지 적으세요. 두 번째는 반영 과정입니다. 원본 수정 시각, 실제 동기화 작업의 상태와 완료 시각, 검색에서 확인한 결과를 같은 문서에 남길 수 있습니다. 세 번째는 변경 복원에 필요한 기존 쿼리·템플릿·필터입니다.

현재 API 안내에는 query나 template을 생략하면 기존 값이 유지되지만, source_params 객체를 보낼 때 포함·제외 목록은 교체되는 조건이 나옵니다. 일부만 바꿀 의도여도 유지할 값이 빠지지 않았는지 확인할 필요가 있어요. 원본 데이터베이스를 나중에 다른 것으로 바꿀 수 있다고 가정하지 않는 것도 현재 제약을 읽는 일입니다.

연결이 됐다는 표시와 유용한 검색 답변은 같은 검사가 아닙니다. 문서가 실제로 생성됐는지 본 뒤, 질문에 필요한 정보가 들어 있는지 읽어 보세요. 가상의 환불 FAQ라면 문의 조건과 예외가 본문에 있는지, 제목만으로는 답하기 어려운 질문을 던졌을 때 원문을 찾는지 확인할 수 있습니다. 직접 시험한 결과처럼 표현하지는 마세요.

자주 묻는 질문도 정리해 볼게요. DB를 연결하면 모든 행이 공개되나요? 지정한 쿼리 결과와 앱의 검색 접근 범위를 각각 확인해야 합니다. 비공개로 바꿨는데 검색 내용이 남으면 실패인가요? 원본 조건, 동기화 성공 여부와 회수 결과를 나눠 읽으세요. 베타를 운영에 바로 붙여도 되나요? 요구사항·제약·담당 절차를 확인하고 독립된 검증 범위를 먼저 정하는 편이 좋겠습니다.

공식 자료 확인일은 2026년 11월 13일입니다. 발행일의 모든 계정·환경에서 같은 상태라고 보장하는 안내가 아니며, 이 글에서는 실제 계정 설정 변경이나 성능 시험을 수행하지 않았어요.

• 11월 12일 공식 발표
• D1 데이터 소스 문서
• 동기화 동작 안내
• 한도와 요금 기준

함께 읽어 볼 글: OpenSearch와 Elastic Cloud Hosted의 검색 운영·비용 비교. 이번 글과 다른 선택 조건을 비교할 때 참고해 보세요.

원본 데이터 행과 검색에 넣을 문서를 나누어 생각하는 개념 이미지입니다. 실제 서비스 화면이나 색인 성공 결과는 아닙니다.