marimo 노트북

marimo 노트북 (marimo Notebooks)

marimo는 Python과 SQL을 위한 오픈소스 반응형(reactive) 노트북이에요. DuckDB의 Python 클라이언트와 긴밀하게 통합되어서, 한 개의 git 버전 관리가 가능한 노트북 안에서 Python과 SQL을 자유롭게 섞어 쓸 수 있어요. 전통적인 노트북과 달리 셀을 실행하거나 UI 요소를 조작하면 marimo가 영향받는 셀을 자동(또는 지연) 실행해서 코드와 출력이 항상 일관되게 유지돼요. DuckDB와의 통합 덕분에 데이터를 대화형으로 다루기에 잘 맞고, Python 파일로 저장되기 때문에 노트북을 스크립트처럼 실행하기도 간단해요.

출처: 공식문서

설치

시작하려면 터미널에서 marimo와 DuckDB를 설치해요.

pip install "marimo[sql]" # or uv add "marimo[sql]"

그다음 지원 라이브러리를 설치해요.

pip install "polars[pyarrow]" # or uv add "polars[pyarrow]"

튜토리얼을 실행해 보세요.

marimo tutorial sql

marimo에서 SQL 쓰기

marimo edit notebook.py로 터미널에서 노트북을 만들면, SQL 셀을 세 가지 방법 중 하나로 생성할 수 있어요.

  • + 버튼을 우클릭하고 SQL cell을 선택
  • 셀 메뉴에서 빈 셀을 SQL로 변환
  • 노트북 하단의 SQL 버튼 클릭

여기서 흥미로운 점이 있어요. marimo의 SQL 셀은 SQL을 쓰는 것처럼 보이지만, 실제로는 mo.sql() 함수를 쓰는 표준 Python 코드로 직렬화돼요. 그래서 노트북이 특별한 문법이나 매직 커맨드 없이 순수 Python 코드로 유지돼요.

df = mo.sql(f"SELECT 'Off and flying!' AS a_duckdb_column")

이렇게 하는 이유는 marimo가 노트북을 순수 Python으로 저장하기 때문이에요. 여러 이유가 있지만, 대표적으로 git 친화적인 diff와 Python 스크립트로 실행할 수 있다는 점이 있어요.

SQL 문장 자체는 f-string이라서 {} 안에 Python 값을 넣어 쿼리에 보간할 수 있어요(뒤에서 보여드릴게요). 즉 SQL 쿼리가 UI 요소나 다른 Python 값에 의존할 수 있고, 이 모든 게 marimo의 데이터플로우 그래프의 일부가 돼요.

주의! 사용자가 만든 콘텐츠가 SQL 쿼리에 들어간다면 SQL 인젝션을 막기 위해 입력을 반드시 정제(sanitize)해야 해요.

커스텀 DuckDB 커넥션 연결하기

기본 전역 커넥션 대신 커스텀 DuckDB 커넥션을 쓰고 싶다면, 셀을 만들고 DuckDB 커넥션을 Python 변수로 생성하면 돼요.

import duckdb

# Create a DuckDB connection
conn = duckdb.connect("path/to/my/duckdb.db")

marimo가 커넥션을 자동으로 발견해서, SQL 셀의 커넥션 드롭다운에서 선택할 수 있게 해줘요.

데이터베이스·스키마·테이블 자동 발견

marimo는 커넥션을 내부적으로 들여다보고 데이터베이스, 스키마, 테이블, 컬럼을 Data Sources 패널에 보여줘요. 이 패널로 스키마를 빠르게 탐색해서 테이블과 컬럼을 SQL 쿼리에 끌어다 쓸 수 있어요.

로컬 데이터프레임 참조하기

데이터프레임을 담고 있는 Python 변수 이름을 SQL 셀에서 그대로 쓰면 로컬 데이터프레임을 참조할 수 있어요. 단, 같은 이름의 테이블이 데이터베이스 커넥션에 있으면 데이터베이스 테이블이 우선해요.

import polars as pl
df = pl.DataFrame({"column": [1, 2, 3]})

SELECT * FROM df WHERE column > 2

SQL 셀의 출력 참조하기

SQL 셀에서 비공개(밑줄로 시작하지 않는) 출력 변수를 정의하면, 그 결과 데이터프레임을 다른 Python·SQL 셀에서 참조할 수 있어요.

반응형 SQL 셀

marimo는 의존성이 바뀌면 자동으로 갱신되는 반응형 SQL 셀을 만들 수 있어요. 비싼 쿼리나 대용량 데이터셋을 다룬다면 marimo 런타임을 "lazy"로 설정할 수 있는데, 그러면 의존 셀이 실행 대신 '오래됨(stale)'으로만 표시되고 사용자가 다시 실행할 시점을 정할 수 있어요.

digits = mo.ui.slider(label="Digits", start=100, stop=10000, step=200)
digits

CREATE TABLE random_data AS
    SELECT i AS id, random() AS random_value,
    FROM range({digits.value}) AS t(i);

SELECT * FROM random_data;

이렇게 슬라이더 같은 UI 요소를 조작하면 데이터가 훨씬 손에 잡히는 것처럼 느껴져요.

marimo에서 DuckDB 기반 OLAP 분석

marimo는 분석 워크플로에서 DuckDB와 잘 어울리는 여러 기능을 제공해요.

  • Python과 SQL 사이의 매끄러운 통합
  • 쿼리가 바뀌면 의존 셀을 자동으로 갱신하는 반응형 실행
  • SQL 쿼리를 파라미터화하는 데 쓸 수 있는 대화형 UI 요소
  • 노트북을 독립 실행 앱이나 Python 스크립트로 내보내기, 또는 WebAssembly를 통해 브라우저 안에서 완전히 실행하기

다음 단계

  • marimo 문서 읽어보기.
  • SQL 튜토리얼 시도: marimo tutorial sql.
  • 이 가이드의 코드는 GitHub에서 볼 수 있어요. marimo edit github_url로 실행해 보세요.

더 알아보기 (Learn more)