Explorando dados com notebooks do Marimo e chDB

Este guia explica como configurar e usar o chDB para explorar dados do ClickHouse Cloud ou de arquivos locais em notebooks do Marimo

Neste guia, você aprenderá a explorar, em um notebook do Marimo, um conjunto de dados do ClickHouse Cloud com a ajuda do chDB — um mecanismo SQL OLAP rápido executado no próprio processo, baseado em ClickHouse.

Pré-requisitos:

• Python 3.8 ou superior
• um ambiente virtual
• um serviço do ClickHouse Cloud em funcionamento e seus detalhes de conexão

Se você ainda não tem uma conta no ClickHouse Cloud, pode se inscrever para um teste e receber US$ 300 em créditos gratuitos para começar.

O que você aprenderá:

• Conectar-se ao ClickHouse Cloud a partir de notebooks do Marimo usando chDB
• Consultar conjuntos de dados remotos e converter os resultados em DataFrames do Pandas
• Visualizar dados usando Plotly no Marimo
• Aproveitar o modelo de execução reativa do Marimo para explorar dados de forma interativa

Usaremos o conjunto de dados UK Property Price, disponível no ClickHouse Cloud como um dos conjuntos de dados iniciais. Ele contém dados sobre os preços pelos quais casas foram vendidas no Reino Unido de 1995 a 2024.

​

Configuração

​

Carregamento do conjunto de dados

Para adicionar este conjunto de dados a um serviço existente do ClickHouse Cloud, faça login em console.clickhouse.cloud com os dados da sua conta.

No menu à esquerda, clique em Data sources. Em seguida, clique em Predefined sample data:

Selecione Get started no cartão de dados de preços pagos de imóveis do Reino Unido (4GB):

Em seguida, clique em Import dataset:

O ClickHouse criará automaticamente a tabela pp_complete no banco de dados default e a preencherá com 28,92 milhões de linhas de dados de preços.

Para reduzir a probabilidade de expor suas credenciais, recomendamos que você adicione seu nome de usuário e senha do ClickHouse Cloud como variáveis de ambiente na sua máquina local. Em um terminal, execute o comando a seguir para adicionar seu nome de usuário e senha como variáveis de ambiente:

​

Configurando as credenciais

export CLICKHOUSE_CLOUD_HOSTNAME=<HOSTNAME>
export CLICKHOUSE_CLOUD_USER=default
export CLICKHOUSE_CLOUD_PASSWORD=your_actual_password

As variáveis de ambiente acima persistem apenas durante a sessão do terminal. Para defini-las permanentemente, adicione-as ao arquivo de configuração do shell.

​

Instalando o Marimo

Agora, ative o ambiente virtual. No ambiente virtual, instale os seguintes pacotes que serão usados neste guia:

pip install chdb pandas plotly marimo

Crie um novo notebook do Marimo com o seguinte comando:

marimo edit clickhouse_exploration.py

Uma nova janela do navegador deve abrir com a interface do Marimo em localhost:2718:

Os notebooks do Marimo são armazenados como arquivos Python puros, o que facilita o controle de versão e o compartilhamento com outras pessoas.

​

Instalação de dependências

Em uma nova célula, importe os pacotes necessários:

import marimo as mo
import chdb
import pandas as pd
import os
import plotly.express as px
import plotly.graph_objects as go

Ao passar o mouse sobre a célula, você verá aparecer dois círculos com o símbolo ”+”. Você pode clicar neles para adicionar novas células.

Adicione uma nova célula e execute uma consulta simples para verificar se tudo está configurado corretamente:

result = chdb.query("SELECT 'Hello ClickHouse from Marimo!'", "DataFrame")
result

Você deve ver o resultado exibido abaixo da célula que você acabou de executar:

​

Explorando os dados

Com o conjunto de dados UK price paid configurado e o chDB em execução em um notebook do Marimo, agora já podemos começar a explorar os dados. Vamos imaginar que queremos verificar como o preço mudou ao longo do tempo em uma área específica do Reino Unido, como a capital, Londres. A função remoteSecure do ClickHouse permite recuperar facilmente os dados do ClickHouse Cloud. Você pode instruir o chDB a retornar esses dados em processo como um DataFrame do Pandas, que é uma forma prática e familiar de trabalhar com dados.

​

Consultando dados do ClickHouse Cloud

Crie uma nova célula com a consulta a seguir para obter os dados de preços pagos do Reino Unido no seu serviço do ClickHouse Cloud e convertê-los em um pandas.DataFrame:

query = f"""
SELECT
    toYear(date) AS year,
    round(avg(price)) AS price,
    bar(price, 0, 1000000, 80)
FROM remoteSecure(
    '{os.environ.get("CLICKHOUSE_CLOUD_HOSTNAME")}',
    'default.pp_complete',
    '{os.environ.get("CLICKHOUSE_CLOUD_USER")}',
    '{os.environ.get("CLICKHOUSE_CLOUD_PASSWORD")}'
)
WHERE town = 'LONDON'
GROUP BY year
ORDER BY year
"""

df = chdb.query(query, "DataFrame")
df.head()

No trecho acima, chdb.query(query, "DataFrame") executa a consulta especificada e retorna o resultado como um Pandas DataFrame.

Na consulta, estamos usando a função remoteSecure para nos conectar ao ClickHouse Cloud.

A função remoteSecure recebe como parâmetros:

• uma string de conexão
• o nome do banco de dados e da tabela a serem usados
• seu nome de usuário
• sua senha

Como prática recomendada de segurança, prefira usar variáveis de ambiente para os parâmetros de nome de usuário e senha, em vez de especificá-los diretamente na função, embora isso seja possível, se você quiser.

A função remoteSecure se conecta ao serviço remoto do ClickHouse Cloud, executa a consulta e retorna o resultado. Dependendo do volume dos seus dados, isso pode levar alguns segundos.

Neste caso, retornamos o preço médio por ano e filtramos por town='LONDON'. O resultado é então armazenado como um DataFrame em uma variável chamada df.

​

Visualizando os dados

Com os dados agora disponíveis em um formato familiar, vamos explorar como os preços dos imóveis em Londres mudaram ao longo do tempo.

O Marimo funciona particularmente bem com bibliotecas de visualização interativas, como o Plotly. Em uma nova célula, crie um gráfico interativo:

fig = px.line(
    df, 
    x='year', 
    y='price',
    title='Average Property Prices in London Over Time',
    labels={'price': 'Average Price (£)', 'year': 'Year'}
)

fig.update_traces(mode='lines+markers')
fig.update_layout(hovermode='x unified')
fig

Talvez não seja surpresa que os preços dos imóveis em Londres tenham aumentado substancialmente ao longo do tempo.

Um dos pontos fortes do Marimo é seu modelo de execução reativa. Vamos criar um widget interativo para selecionar diferentes cidades dinamicamente.

​

Seleção interativa de cidades

Em uma nova célula, crie uma lista suspensa para selecionar diferentes cidades:

town_selector = mo.ui.dropdown(
    options=['LONDON', 'MANCHESTER', 'BIRMINGHAM', 'LEEDS', 'LIVERPOOL'],
    value='LONDON',
    label='Select a town:'
)
town_selector

Em outra célula, crie uma consulta que responda à seleção da cidade. Quando você alterar a lista suspensa, essa célula será executada novamente automaticamente:

query_reactive = f"""
SELECT
    toYear(date) AS year,
    round(avg(price)) AS price
FROM remoteSecure(
    '{os.environ.get("CLICKHOUSE_CLOUD_HOSTNAME")}',
    'default.pp_complete',
    '{os.environ.get("CLICKHOUSE_CLOUD_USER")}',
    '{os.environ.get("CLICKHOUSE_CLOUD_PASSWORD")}'
)
WHERE town = '{town_selector.value}'
GROUP BY year
ORDER BY year
"""

df_reactive = chdb.query(query_reactive, "DataFrame")
df_reactive

Agora crie um gráfico que seja atualizado automaticamente quando você alterar a cidade. Você pode mover o gráfico para cima do DataFrame dinâmico para que ele apareça abaixo da célula com a lista suspensa.

fig_reactive = px.line(
    df_reactive,
    x='year',
    y='price',
    title=f'Average Property Prices in {town_selector.value} Over Time',
    labels={'price': 'Average Price (£)', 'year': 'Year'}
)

fig_reactive.update_traces(mode='lines+markers')
fig_reactive.update_layout(hovermode='x unified')
fig_reactive

Agora, ao selecionar uma cidade na lista suspensa, o gráfico é atualizado dinamicamente:

​

Explorando distribuições de preços com box plots interativos

Vamos nos aprofundar nos dados examinando a distribuição dos preços dos imóveis em Londres ao longo de diferentes anos. Um box plot mostrará a mediana, os quartis e os valores atípicos, oferecendo uma compreensão muito melhor do que apenas o preço médio. Primeiro, vamos criar um seletor de ano que nos permitirá explorar diferentes anos de forma interativa:

Em uma nova célula, adicione o seguinte:

year_slider = mo.ui.slider(
    start=1995,
    stop=2024,
    value=2020,
    step=1,
    label='Select Year:',
    show_value=True
)
year_slider

Agora, vamos consultar os preços individuais dos imóveis para o ano selecionado. Observe que não estamos fazendo uma agregação aqui - queremos todas as transações individuais para construir nossa distribuição:

query_distribution = f"""
SELECT
    price,
    toYear(date) AS year
FROM remoteSecure(
    '{os.environ.get("CLICKHOUSE_CLOUD_HOSTNAME")}',
    'default.pp_complete',
    '{os.environ.get("CLICKHOUSE_CLOUD_USER")}',
    '{os.environ.get("CLICKHOUSE_CLOUD_PASSWORD")}'
)
WHERE town = 'LONDON'
  AND toYear(date) = {year_slider.value}
  AND price > 0
  AND price < 5000000
"""

df_distribution = chdb.query(query_distribution, "DataFrame")

# create an interactive box plot.
fig_box = go.Figure()

fig_box.add_trace(
    go.Box(
        y=df_distribution['price'],
        name=f'London {year_slider.value}',
        boxmean='sd',  # Show mean and standard deviation
        marker_color='lightblue',
        boxpoints='outliers'  # Show outlier points
    )
)

fig_box.update_layout(
    title=f'Distribution of Property Prices in London ({year_slider.value})',
    yaxis=dict(
        title='Price (£)',
        tickformat=',.0f'
    ),
    showlegend=False,
    height=600
)

fig_box

Se você selecionar o botão de opções no canto superior direito da célula, poderá ocultar o código. Ao mover o controle deslizante, o gráfico será atualizado automaticamente graças à execução reativa do Marimo:

​

Resumo

Este guia demonstrou como usar o chDB para explorar seus dados no ClickHouse Cloud com notebooks do Marimo. Usando o conjunto de dados UK Property Price, mostramos como consultar dados remotos no ClickHouse Cloud com a função remoteSecure() e converter os resultados diretamente em DataFrames do Pandas para análise e visualização. Com o chDB e o modelo de execução reativa do Marimo, cientistas de dados podem aproveitar os poderosos recursos de SQL do ClickHouse junto com ferramentas Python conhecidas, como Pandas e Plotly, além de contar com widgets interativos e rastreamento automático de dependências, que tornam a análise exploratória mais eficiente e reproduzível.