chDB para Go - ClickHouse Documentation

O chDB-go fornece bindings para Go do chDB, permitindo executar consultas do ClickHouse diretamente nas suas aplicações Go, sem dependências externas.

Instalação

Etapa 1: Instale a libchdb

Primeiro, instale a biblioteca chDB:

curl -sL https://lib.chdb.io | bash

Passo 2: Instale o chdb-go

Instale o pacote do Go:

go install github.com/chdb-io/chdb-go@latest

Ou adicione-o ao seu go.mod:

go get github.com/chdb-io/chdb-go

Uso

Interface de linha de comando

O chDB-go inclui uma CLI para consultas rápidas:

# Consulta simples
./chdb-go "SELECT 123"

# Modo interativo
./chdb-go

# Modo interativo com armazenamento persistente
./chdb-go --path /tmp/chdb

Biblioteca Go - guia rápido

Consultas sem estado

Para consultas simples e pontuais:

package main

import (
    "fmt"
    "github.com/chdb-io/chdb-go/chdb"
)

func main() {
    // Executa uma consulta simples
    result, err := chdb.Query("SELECT version()", "CSV")
    if err != nil {
        panic(err)
    }
    fmt.Println(result)
}

Consultas com estado usando sessão

Para consultas complexas com estado persistente:

package main

import (
    "fmt"
    "github.com/chdb-io/chdb-go/chdb"
)

func main() {
    // Cria uma sessão com armazenamento persistente
    session, err := chdb.NewSession("/tmp/chdb-data")
    if err != nil {
        panic(err)
    }
    defer session.Cleanup()

    // Cria banco de dados e tabela
    _, err = session.Query(`
        CREATE DATABASE IF NOT EXISTS testdb;
        CREATE TABLE IF NOT EXISTS testdb.test_table (
            id UInt32,
            name String
        ) ENGINE = MergeTree() ORDER BY id
    `, "")
    
    if err != nil {
        panic(err)
    }

    // Insere dados
    _, err = session.Query(`
        INSERT INTO testdb.test_table VALUES 
        (1, 'Alice'), (2, 'Bob'), (3, 'Charlie')
    `, "")
    
    if err != nil {
        panic(err)
    }

    // Consulta dados
    result, err := session.Query("SELECT * FROM testdb.test_table ORDER BY id", "Pretty")
    if err != nil {
        panic(err)
    }
    
    fmt.Println(result)
}

Interface do driver SQL

chDB-go implementa a interface database/sql do Go:

package main

import (
    "database/sql"
    "fmt"
    _ "github.com/chdb-io/chdb-go/chdb/driver"
)

func main() {
    // Abrir conexão com o banco de dados
    db, err := sql.Open("chdb", "")
    if err != nil {
        panic(err)
    }
    defer db.Close()

    // Consulta com a interface padrão database/sql
    rows, err := db.Query("SELECT COUNT(*) FROM url('https://datasets.clickhouse.com/hits/hits.parquet')")
    if err != nil {
        panic(err)
    }
    defer rows.Close()

    for rows.Next() {
        var count int
        err := rows.Scan(&count)
        if err != nil {
            panic(err)
        }
        fmt.Printf("Count: %d\n", count)
    }
}

Consultas em streaming para grandes conjuntos de dados

Para processar grandes conjuntos de dados que não cabem na memória, use consultas em streaming:

package main

import (
    "fmt"
    "log"
    "github.com/chdb-io/chdb-go/chdb"
)

func main() {
    // Cria uma sessão para consultas de streaming
    session, err := chdb.NewSession("/tmp/chdb-stream")
    if err != nil {
        log.Fatal(err)
    }
    defer session.Cleanup()

    // Executa uma consulta de streaming para um conjunto de dados grande
    streamResult, err := session.QueryStreaming(
        "SELECT number, number * 2 as double FROM system.numbers LIMIT 1000000", 
        "CSV",
    )
    if err != nil {
        log.Fatal(err)
    }
    defer streamResult.Free()

    rowCount := 0
    
    // Processa os dados em fragmentos
    for {
        chunk := streamResult.GetNext()
        if chunk == nil {
            // Sem mais dados
            break
        }
        
        // Verifica erros de streaming
        if err := streamResult.Error(); err != nil {
            log.Printf("Streaming error: %v", err)
            break
        }
        
        rowsRead := chunk.RowsRead()
        // Você pode processar os dados do fragmento aqui
        // Por exemplo, gravar em arquivo, enviar pela rede, etc.
        fmt.Printf("Processed chunk with %d rows\n", rowsRead)
        rowCount += int(rowsRead)
        if rowCount%100000 == 0 {
            fmt.Printf("Processed %d rows so far...\n", rowCount)
        }
    }
    
    fmt.Printf("Total rows processed: %d\n", rowCount)
}

Benefícios do streaming de consultas:

Uso eficiente de memória - Processe grandes conjuntos de dados sem carregar tudo na memória
Processamento em tempo real - Comece a processar os dados assim que o primeiro fragmento chegar
Suporte a cancelamento - É possível cancelar consultas de longa execução com Cancel()
Tratamento de erros - Verifique se há erros durante o streaming com Error()

Documentação da API

O chDB-go oferece APIs de alto e baixo nível:

Documentação da API de Alto Nível - Recomendada para a maioria dos casos de uso
Documentação da API de Baixo Nível - Para casos de uso avançados que exigem controle detalhado

Requisitos do sistema

Go 1.21 ou superior
Compatível com Linux e macOS

​Instalação

​Etapa 1: Instale a libchdb

​Passo 2: Instale o chdb-go

​Uso

​Interface de linha de comando

​Biblioteca Go - guia rápido

​Consultas sem estado

​Consultas com estado usando sessão

​Interface do driver SQL

​Consultas em streaming para grandes conjuntos de dados

​Documentação da API

​Requisitos do sistema