Cube에 앱 연결하기

Cube에 앱을 연결해 데이터 팀이 이미 정의한 비즈니스 지표로 대시보드와 리포트를 만드세요.

Cube는 시맨틱 레이어(semantic layer)를 기반으로 하는 분석 플랫폼입니다. 시맨틱 레이어는 대시보드와 리포트가 함께 재사용하는 공유 지표 정의 모음입니다. Cube 커넥터를 사용하면 Lovable 앱이 직접 만든 대시보드, 리포트, 도구에 이 지표를 표시할 수 있습니다. 이 커넥터는 호스팅 서비스인 Cube Cloud와, 직접 호스팅하는 오픈 소스 버전인 Cube Core 모두에서 작동합니다.

Cube는 앱 + 채팅 커넥터로 제공됩니다. 하나의 공유 연결이 빌드 중 프로젝트 채팅과 게시된 앱 모두에서 작동합니다.

Cube를 사용하면 앱에서 다음과 같은 작업이 가능합니다.

• 데이터 모델에 있는 측정값(measure, 매출 같은 지표)과 차원(dimension, 지역이나 월 같은 그룹 기준) 목록 조회하기
• 필터, 정렬 순서, 행 수 제한을 적용해 측정값을 차원별·시간별로 조회하는 구조화된 쿼리 실행하기
• 구조화된 쿼리로 답할 수 없는 질문에 Semantic SQL(데이터 모델에 대한 SQL 쿼리) 사용하기
• 데이터 팀이 Cube에서 설정한 규칙으로 연결을 통한 모든 쿼리를 고객 한 곳이나 역할 하나로 제한하기

데이터 팀이 이미 관리하는 지표 정의가 앱에 필요할 때 Cube를 사용하세요. Cube가 이 정의를 바탕으로 데이터 웨어하우스용 SQL을 작성하므로 앱에서 계산을 다시 만들 필요가 없습니다. 이 커넥터는 읽기 전용입니다.

주요 활용 사례 및 예시 앱

다음 예시는 Cube로 만들 수 있는 앱과 시작할 때 쓸 수 있는 프롬프트를 보여 줍니다.

Cube 연결 작동 방식

데이터 팀은 각 지표를 Cube 데이터 모델이라는 한곳에서 정의합니다. 데이터 모델은 지표를 큐브(cube)와 뷰(view)로 묶습니다. 큐브는 보통 데이터베이스의 테이블에 대응하고, 뷰는 앱과 리포트에서 쓰도록 여러 큐브를 결합합니다.

Lovable은 Cube용 코드를 작성할 때 기본적으로 데이터 모델을 먼저 읽습니다. 데이터 모델에서 찾은 측정값과 차원 이름을 사용하며, 뷰를 우선합니다. Lovable은 대부분의 쿼리를 구조화된 쿼리로 작성합니다. 구조화된 쿼리는 사용할 측정값, 차원, 필터를 나열합니다. 구조화된 쿼리로 답할 수 없는 질문에는 Semantic SQL을 사용합니다.

Lovable은 기본적으로 자신이 작성하는 각 구조화된 쿼리에 행 수 제한을 추가합니다. 쿼리에 행 수 제한이 없으면 Cube는 최대 10,000행을 반환합니다. 쿼리에서 설정할 수 있는 행 수 제한은 최대 50,000행입니다. 데이터 팀은 Cube에서 두 값을 모두 변경할 수 있습니다.

Lovable은 커넥터 게이트웨이를 통해 Cube에 요청을 보냅니다. 게이트웨이는 자격 증명을 보관하고 각 요청에 토큰을 추가합니다. Cube 자격 증명은 게시된 앱에 노출되지 않습니다.

이 토큰은 JWT(JSON Web Token)로, 요청이 허용되었음을 증명하는 짧은 서명된 텍스트입니다. 기본적으로 Cube는 배포의 API 시크릿으로 서명된 토큰만 받아들입니다. API 시크릿은 Cube 구성에 들어 있는 비밀 값입니다. 토큰에는 요청을 설명하는 값도 담깁니다. 예를 들어 고객사 Acme용 토큰에는 "tenant": "acme" 같은 값이 들어갑니다. Cube는 이 값을 보안 컨텍스트(security context)라고 부릅니다. 액세스 정책 같은 Cube 배포의 규칙은 보안 컨텍스트를 사용해 쿼리가 반환할 데이터를 결정합니다.

연결을 통한 모든 쿼리는 프로젝트 채팅에서든 게시된 앱에서든 같은 보안 컨텍스트를 사용합니다. 따라서 앱을 사용하는 모든 사람이 같은 접근 권한을 갖습니다.

프로젝트 채팅에서 Lovable은 승인을 요청하지 않고 데이터 모델을 읽고 구조화된 쿼리를 실행합니다. SELECT나 WITH로 시작하는 Semantic SQL 쿼리도 묻지 않고 실행합니다. 그 밖의 요청에는 데이터를 읽기만 하더라도 Lovable이 먼저 승인을 요청합니다. SQL 문이 둘 이상 들어 있는 Semantic SQL 쿼리가 그 예입니다. 승인 요청을 멈추려면 연결을 열고 Connection settings 아래에서 Ask before making changes를 Always allow로 설정하세요. 이 설정은 본인과 이 연결에만 적용됩니다. 게시된 앱은 승인을 요청하지 않습니다. 프로젝트 채팅에서 커넥터 작업 승인하기를 참고하세요.

Cube 연결 방법

Cube 연결을 만들 수 있는 사람은 플랜과 워크스페이스 설정에 따라 달라집니다. 앱 + 채팅 커넥터는 Free, Pro, Business 플랜에서 기본적으로 사용할 수 있습니다. Enterprise 플랜에서는 처음에 사실상 비활성화되어 있습니다. admin이 Connectors → Admin settings → App + chat connectors에서 변경하기 전까지 연결 및 클라이언트를 만들 수 있는 사용자 설정의 기본값이 No one이기 때문입니다.

서로 다른 배포나 보안 컨텍스트로 Cube 연결을 여러 개 만들 수 있습니다. 환경, 팀, 고객을 분리할 때 유용합니다.

연결이 만들어지면 연결을 사용할 프로젝트에 링크할 수 있습니다. 프로젝트에서 빌드하는 사람은 누구나 프로젝트 채팅에서 Lovable에게 자신의 프로젝트를 이 연결에 링크해 달라고 요청할 수 있습니다.

사전 요구사항

Cube를 연결하기 전에 다음을 준비하세요.

• 큐브나 뷰가 하나 이상 있는 데이터 모델을 갖춘 Cube Cloud 또는 Cube Core 배포
• Cube Core의 경우 유효한 인증서로 HTTPS를 제공하는 공개 호스트 이름
• 네트워크에서 들어오는 트래픽을 제한한다면 Lovable 커넥터 게이트웨이의 IP 범위를 허용하는 규칙
• 배포의 API 시크릿 또는 배포용 API 토큰
• Lovable 워크스페이스에서 연결을 만들 권한(연결 및 클라이언트를 만들 수 있는 사용자 참고)

Cube Core는 기본적으로 일반 HTTP로 제공됩니다. HTTPS로 제공하려면 Cube Core 앞에 리버스 프록시를 두세요. 리버스 프록시는 HTTPS 요청을 받아 Cube로 전달하는 웹 서버입니다.

연결 방식 선택

연결 방식은 두 가지이며, API 시크릿으로 토큰에 서명하는 주체가 서로 다릅니다.

• API 시크릿 방식에서는 배포의 API 시크릿을 Lovable에 제공합니다. Lovable이 매시간 새 토큰에 서명하므로 연결이 만료되지 않습니다. 보안 컨텍스트는 Lovable에서 설정합니다. API 시크릿을 Lovable과 공유할 수 있다면 이 방식을 사용하세요.
• API 토큰 방식에서는 이미 가지고 있는 토큰을 붙여 넣습니다. Lovable은 API 시크릿을 받지 않습니다. 토큰에 담긴 값이 보안 컨텍스트가 됩니다. 토큰이 만료되면 토큰을 교체할 때까지 앱의 쿼리가 실패합니다. API 시크릿을 공유할 수 없다면 이 방식을 사용하세요.

연결되면 프로젝트에서 빌드하는 누구나 프로젝트 채팅에서 Lovable에게 자신의 프로젝트를 Cube에 링크해 달라고 요청할 수 있습니다(구성된 연결 수준 접근 권한에 따라). 그러면 Lovable 앱이 빌드 중에도, 게시한 뒤에도 Cube 데이터 모델의 측정값과 차원을 쿼리할 수 있습니다.

보안 컨텍스트, API 시크릿, 토큰을 변경하려면 연결을 엽니다. Configure connection 아래에 새 값을 입력하고(보안 컨텍스트는 Advanced settings 아래에 있습니다) Update를 클릭합니다.

연결을 삭제해도 Cube에서는 아무것도 바뀌지 않습니다. API 시크릿은 계속 유효하며, 붙여 넣은 토큰도 마찬가지입니다. 이 값들이 더는 작동하지 않게 하려면 Cube에서 API 시크릿을 변경하세요. 배포에서 CUBEJS_API_SECRETS를 사용한다면 그 목록에서 이전 시크릿을 제거하세요.

제한 사항

Cube 커넥터로는 다음 작업을 할 수 없습니다.

• 앱 사용자마다 별도의 보안 컨텍스트 부여하기. 각 연결은 링크된 모든 프로젝트가 공유하는 하나의 보안 컨텍스트를 나타냅니다.
• 공개 HTTPS 호스트 이름이 없는 배포에 연결하기. 사설 네트워크에 있거나 IP 주소로 접근하는 배포가 그 예입니다.
• 다른 키로 토큰을 검증하는 배포용 토큰에 서명하기. ID 제공업체(별도의 로그인 서비스)의 키로 토큰을 검증하는 배포가 그 예입니다. 이 경우에는 해당 제공업체에서 발급한 토큰으로 API 토큰 방식을 사용하세요. Lovable은 만료까지 7일 이상 남은 토큰만 받아들입니다.

문제 해결

Connect를 클릭했을 때 Cube가 자격 증명을 받아들이지 않으면 Lovable에 Cube did not validate your credentials. 메시지가 표시됩니다. 이유를 보려면 Show error를 클릭하세요.

Cube 연결 관리

연결은 Connectors에서 관리합니다. **Cube**를 선택한 다음 연결을 여세요.

• Unlink projects를 사용하면 다른 프로젝트에서는 연결을 계속 사용할 수 있게 두고 특정 프로젝트의 Cube 접근 권한만 제거할 수 있습니다. 단계별 절차는 연결에서 프로젝트 링크 해제를 참고하세요.
• Delete the connection을 사용하면 워크스페이스에서 연결을 완전히 제거합니다. 삭제는 영구적입니다. 링크된 모든 프로젝트에서 자격 증명이 제거되고, Cube를 사용하는 앱 기능은 새 연결을 추가할 때까지 작동하지 않습니다. 단계와 삭제 권한은 연결 삭제를 참고하세요.

관련 주제

• Workday에 앱 연결하기
• Notion에 앱 연결하기
• Neon에 앱 연결하기
• Granola에 앱 연결하기
• Inngest에 앱 연결하기