컬렉션과 데이터
GetMyBot 안에 문의, 주문, 예약을 표처럼 저장하고 반응에서 활용하는 방법.
이 페이지에서
컬렉션은 표와 비슷합니다. 한 행에 문의 한 건, 주문 한 건 또는 수업 예약 한 건을 담습니다. 봇이 사용자 답변으로 행을 추가할 수 있고, 운영자는 데이터 → 컬렉션에서 직접 보거나 수정할 수 있습니다.
예를 들어 상담 신청을 받으려면 leads 컬렉션에 name, phone, topic 필드를 만듭니다. 질문을 마친 봇이 이름, 전화번호, 주제를 한 행에 저장하면 나중에 찾아 반응에서 사용할 수 있습니다.
컬렉션이란
필드는 ‘전화번호’, ‘주제’ 같은 열을 정의합니다. 레코드에는 한 행의 값이 들어 있습니다. 필드와 각 유형의 목록을 스키마라고 합니다. 내부적으로 레코드는 JSON 문서이므로 새 필드를 추가해도 기존 행을 다시 만들 필요가 없습니다.
컬렉션 이름은 봇 안에서 고유하며, leads, orders, scores처럼 반응 액션에서 식별자로 사용됩니다.
필드 유형
| 유형 | 저장 내용 | 사용 예 |
|---|---|---|
text | 문자열 | 이름, 이메일, 의견 |
number | 숫자 | 금액, 수량, 점수 |
bool | 예/아니요: true / false | 주문 결제 여부 |
datetime | 날짜와 시간 | 수업 예약 시각 |
json | 중첩 객체나 목록 | 주문 상품과 속성 |
유형은 편집 화면과 저장 시 값 변환에 영향을 줍니다. 스키마는 엄격하지 않습니다. 스키마에 없는 필드도 레코드에 들어오면 저장되고 별도 열로 표시됩니다.
컬렉션 만들기
- 데이터 → 컬렉션을 열고 추가를 누릅니다.
- 이름은 공백 없는 영문으로 입력하면 반응에서 참조하기 쉽습니다.
- 필드 버튼으로 열을 추가하고 유형을 선택합니다.
- 필요하면 아래 보관 규칙을 설정하고 저장합니다.
레코드 보기와 편집
컬렉션 카드의 표 아이콘을 누르면 해당 컬렉션의 데이터 창이 열립니다.
- 보기: 최신 행부터 목록으로 표시하며 값마다 셀이 있습니다.
- 레코드 추가: 스키마에 맞는 양식이 열립니다.
bool은 스위치,json은 JSON 입력란처럼 유형에 맞게 편집합니다. - 편집(연필): 기존 행을 수정합니다.
- 삭제(휴지통): 행을 삭제합니다.
반응 액션도 같은 컬렉션에 레코드를 자동으로 추가합니다. 수동 편집과 자동 기록은 동일한 데이터를 사용합니다.
보관 기간(retention)
컬렉션이 계속 커지지 않도록 자동 정리 규칙을 설정할 수 있습니다.
- 최대 레코드 수: 한도를 넘으면 가장 오래된 레코드부터 삭제합니다.
- 최대 보관 일수: 지정한 기간보다 오래된 레코드를 삭제합니다.
예를 들어 임시 로그를 30일간 보관할 수 있습니다. 정리는 주기적으로 실행되므로 만료 시각에 정확히 삭제되지는 않습니다. 두 제한을 함께 켤 수 있습니다. 아직 업무에 필요한 주문에는 보관 기간을 설정하지 마세요.
반응에서 데이터 사용
반응 액션에서 다음 작업을 할 수 있습니다.
- 레코드 생성:
{{user_id}}와{{text}}같은 치환 값으로 행을 추가합니다. 중복 방지 키가 있으면 같은 키로 다시 실행할 때 새 행 대신 기존 행을 갱신합니다. 사용자 ID를 키로 쓰면 사용자당 최신 문의 하나를 유지할 수 있습니다. - 레코드 업데이트: 조건에 맞는 행을 수정합니다.
- 레코드 검색: 행을 배열로 실행 컨텍스트에 읽어 다음 액션에서 처리합니다.
- Read collection page (
record_page): 레코드를 여러 번에 나눠 읽습니다. 예를 들어 카드 두 장과 ‘다음 페이지’ 버튼을 만들 수 있습니다. - Aggregate whole collection (
record_aggregate): 보관 규칙 내의 모든 일치 레코드에 대해 개수와 합계를 계산합니다. 첫 페이지만 불러왔더라도 계산 범위는 제한되지 않습니다. - Atomic collection transaction (
collection_transaction): 조건을 확인하고 여러 변경을 함께 저장합니다. 마지막 자리 예약과 신청 생성처럼 묶어서 처리하며 충돌하면 앞선 변경도 취소됩니다. - 레코드 삭제: 조건에 맞는 행을 지웁니다.
- 목록 반복(for-each): 컨텍스트 배열을 순회하며 각 항목에 대해 행 수정, 합계 계산, 외부 서비스 호출 같은 중첩 액션을 실행합니다.
이렇게 외부 데이터베이스 없이 CRM을 관리하고 문의를 모으고 점수를 적립하며 보고서를 만들 수 있습니다. 실습에서는 카탈로그 이어 보기, 모든 일치 주문의 합계, 마지막 자리 예약을 다룹니다. 불러온 목록의 페이지, 컬렉션 페이지, 컬렉션 전체 합계는 서로 다르며 각 예제에서 다음 액션으로 전달되는 데이터를 보여줍니다.
목록 반복은 일괄 전송 도구가 아닙니다. 한 번에 최대 500개 항목을 처리하지만 이벤트 전체에서 보낼 수 있는 메시지는 최대 50개입니다. 항목마다 메시지를 보내면 앞의 50개만 전달되고 나머지는 실패할 수 있습니다. 컬렉션에 있는 사람들에게 보내려면 고객 세그먼트를 만들고 일괄 전송을 사용하세요. 전송 속도, 일시 중지, 전송 내역을 관리할 수 있습니다. 이벤트 하나의 예산도 참고하세요.
카탈로그: 검색, 선택, 카드
수업 검색 실습부터 시작하세요. 필요한 컬렉션, 액션 순서, 결과 없음·여러 결과·오래된 버튼 클릭의 확인 방법을 설명합니다.
카탈로그 데이터는 반응과 별도로 보관합니다. 예를 들어 products에는 name과 aliases, variants에는 product_id, name, card를 넣습니다. variants.product_id 편집기에서 다른 컬렉션과 연결을 켜고 products, 키 _record_id, 표시 필드 name을 선택합니다. 연결은 필드의 의미만 나타내며 관련 레코드를 연쇄적으로 갱신하거나 삭제하지 않습니다.
- 수신 텍스트 반응에 컬렉션 검색 (
record_search)을 추가합니다.products, 쿼리{{text}}, 검색 필드name, 동의어 필드aliases, 결과 이름search를 선택합니다. 동의어는 문자열이나 JSON 문자열 배열입니다. 검색은 대소문자와 러시아어 е/ё를 구분하지 않고 문장부호를 공백으로 바꿉니다. - 결과
search를 사용하는 다음 단계 선택 (branch_result)을 추가합니다. 첫 번째로 맞는 분기가 실행됩니다. 먼저 불완전한 결과에 대해 검색어를 더 자세히 묻고, 다음으로 결과 없음, 유사 일치, 레코드 하나, 레코드 여러 개를 처리합니다. 유사 일치는 확인을 받으세요. 결과가 없거나 하나뿐이라고 판단하려면 검색 결과가 완전해야 합니다. - 여러 결과를 보여줄 메시지에서 검색된 레코드로 버튼 만들기를 엽니다.
search를 원본으로,name을 버튼 이름으로, 다음 반응을 대상으로 선택합니다. 도우미가buttons_from.over = search.rows, 이름 템플릿,carry.selected_id = {{item._record_id}}를 채웁니다. 버튼 이름 필드가 결과에 포함되어 있어야 합니다. 고급 버튼 편집도 계속 사용할 수 있습니다. - 다음 반응에 관련 레코드 찾기 (
record_related)를 추가합니다. 컬렉션variants, 키product_id, 값{{ctx.selected_id}}, 결과 이름variants를 입력합니다. 선택한 상품 자체를 읽으려면products와 키_record_id를 사용하세요. 비즈니스 키로 관계를 저장했다면 버튼 도우미와 읽기 액션 모두 같은 키를 선택합니다. - 다시 결과로 분기합니다. 한 건은
{{ctx.variants.first.card}}로 카드로 표시하고 여러 변형은 버튼으로 표시합니다. 버튼은 ID만 전달하고 클릭 후 최신 데이터를 다시 읽습니다. 변경될 수 있는 카드 내용은carry에 저장하지 마세요.
읽기 결과
search.rows는 레코드 목록, search.count는 불러온 행 수, search.first는 첫 레코드, search.first.name은 그 필드 값입니다. 각 행에 _record_id, _score, _match_type가 추가되며 이 이름들은 예약되어 있습니다. 결과가 없으면 이전에 남아 있던 첫 레코드와 필드도 지워집니다.
search.total은 검사한 후보 가운데 일치한 수입니다. total_exact = false는 컬렉션 전체를 확인하지 않았다는 뜻이고 truncated = true는 결과가 잘렸다는 뜻입니다. 이런 결과를 완전하다고 보거나 컬렉션 전체에서 최선의 일치를 찾았다고 보장할 수 없습니다. 요청 한 번에 최대 10,000건과 16 MiB 데이터를 검사하며 실제 한도는 응답에 포함됩니다. 기본 반환은 최대 100행, 최대 설정은 10,000행입니다.
테스트와 설명
검색 편집기에서 검색 테스트를 열고 구체적인 테스트 문구 또는 ID를 입력하세요. 읽기만 수행하므로 뒤따르는 반응, 메시지, 액션은 실행되지 않습니다. 추가 필터에 치환 변수가 있다면 미리 실제 값으로 바꾸세요. 결과에는 행, 일치 유형, 검사한 레코드 수, 적용된 제한이 표시됩니다. 프로젝트, 컬렉션, 설정, 접근 권한이 바뀌면 오래된 결과는 숨겨집니다.
실행 기록에는 검색 필드, 일치 유형, 검사 및 반환 건수, 결과 제한, 선택된 분기가 표시됩니다. 반응 그래프에는 한 반응으로 향하는 모든 조건이 표시됩니다. 기록을 다시 볼 때 해당 이벤트를 열면 내용 조회 권한이 있는 경우 검색 설명을 확인할 수 있습니다.
버튼 도우미는 기본적으로 최대 20개를 만듭니다. 최대 버튼 수는 1~100으로 바꿀 수 있지만 페이지 나누기가 아닌 개수 제한입니다. 빈 목록은 버튼을 만들지 않습니다. 더 많은 결과에는 검색어를 좁히는 분기를 넣으세요.
계산 액션의 불러온 목록 연산 도우미는 레코드 수, 첫 레코드, 필드 합계, 이름 목록에 대한 수식을 만듭니다. 불러온 행만 계산하므로 결과가 불완전하면 컬렉션 전체의 합계가 아닙니다.
API와 MCP
같은 작업을 POST /api/bots/{botID}/collections/{name}/search 및 /related, 권한 collections:read를 가진 MCP 도구 search_records와 related_records로도 실행할 수 있습니다. 요청은 현재 프로젝트와 리전으로 제한됩니다. REST 테스트에는 실제 값을 넣고 템플릿 치환은 반응 액션에서 수행합니다.
결과 처리와 조건부 변경
컬렉션 결과를 list_transform에 넘겨 필터링, 정렬, 중복 제거, 페이지 선택을 할 수 있습니다. list_aggregate는 불러온 행의 이름 붙은 합계를 계산하며 필요하면 그룹화합니다. 이 액션들은 컬렉션뿐 아니라 일반 HTTP 응답의 목록에도 사용할 수 있습니다.
동시에 실행된 두 작업이 상태 변경을 중복 적용하지 않게 하려면 record_update_if를 사용하세요. ID, 기대하는 필드 값, 새 값을 지정하면 한 레코드에 대한 확인과 변경이 원자적으로 이루어집니다. 결과 updated, conflict, not_found를 branch_value로 분기할 수 있습니다. 단순히 필터에 맞는 모든 행을 변경하는 것과 다릅니다. 설정과 제한 및 예시를 참고하세요.
예약을 한 번만 확정하는 실습에서는 상태와 소유자를 확인하고 updated, conflict, not_found 각각에 응답합니다.
Mini App에서 접근
봇의 Telegram Mini App에서 이름으로 컬렉션 레코드를 요청하고 필터와 개수 제한을 적용할 수 있습니다. 사용자는 Telegram 안에서 주문, 이용 기록, 순위표를 볼 수 있습니다.
팁
email,total,paid처럼 짧은 영문 필드 이름을 쓰면 반응 템플릿에서 참조하기 쉽습니다.- 같은 액션이 반복되어도 새 행을 만들지 않으려면 중복 방지 키를 쓰세요. 이를 멱등성(idempotency)이라고 합니다.
- 더는 필요하지 않은 임시 데이터와 로그에는 보관 기간(
retention)을 설정하세요. - 값의 구조가 미리 정해져 있지 않으면
json유형이 적합합니다.