chDB para Go

Cómo instalar y usar chDB con Go

chDB-go proporciona bindings de Go para chDB, lo que te permite ejecutar consultas de ClickHouse directamente en tus aplicaciones de Go sin dependencias externas.

​

Instalación

​

Paso 1: Instala libchdb

Primero, instala la biblioteca chDB:

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

​

Paso 2: Instalar chdb-go

Instala el paquete para Go:

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

O bien, añádelo a tu go.mod:

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

​

Uso

​

Interfaz de línea de comandos

chDB-go incluye una CLI para consultas rápidas:

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

# Modo interactivo
./chdb-go

# Modo interactivo con almacenamiento persistente
./chdb-go --path /tmp/chdb

​

Biblioteca de Go - guía de inicio rápido

​

Consultas sin estado

Para consultas simples y aisladas:

package main

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

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

​

Consultas con estado mediante sesión

Para consultas complejas con estado persistente:

package main

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

func main() {
    // Crear una sesión con almacenamiento persistente
    session, err := chdb.NewSession("/tmp/chdb-data")
    if err != nil {
        panic(err)
    }
    defer session.Cleanup()

    // Crear base de datos y tabla
    _, 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)
    }

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

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

​

Interfaz del driver SQL

chDB-go implementa la interfaz database/sql de Go:

package main

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

func main() {
    // Abrir conexión a la base de datos
    db, err := sql.Open("chdb", "")
    if err != nil {
        panic(err)
    }
    defer db.Close()

    // Consulta con la interfaz estándar 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 en streaming para grandes conjuntos de datos

Para procesar grandes conjuntos de datos que no caben en memoria, use consultas en streaming:

package main

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

func main() {
    // Crear una sesión para consultas de streaming
    session, err := chdb.NewSession("/tmp/chdb-stream")
    if err != nil {
        log.Fatal(err)
    }
    defer session.Cleanup()

    // Ejecutar una consulta de streaming para un conjunto de datos 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
    
    // Procesar datos en fragmentos
    for {
        chunk := streamResult.GetNext()
        if chunk == nil {
            // No hay más datos
            break
        }
        
        // Comprobar errores de streaming
        if err := streamResult.Error(); err != nil {
            log.Printf("Streaming error: %v", err)
            break
        }
        
        rowsRead := chunk.RowsRead()
        // Aquí se pueden procesar los datos del fragmento
        // Por ejemplo, escribir en un archivo, enviar por red, 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)
}

Beneficios del streaming de consultas:

• Eficiencia de memoria - Procesa grandes conjuntos de datos sin cargarlo todo en memoria
• Procesamiento en tiempo real - Empieza a procesar los datos en cuanto llega el primer fragmento
• Compatibilidad con cancelación - Permite cancelar consultas de larga duración con Cancel()
• Gestión de errores - Comprueba si hay errores durante el streaming con Error()

​

Documentación de la API

chDB-go ofrece APIs de alto y bajo nivel:

• Documentación de la API de alto nivel - Recomendada para la mayoría de los casos de uso
• Documentación de la API de bajo nivel - Para casos de uso avanzados que requieren un control más preciso

​

Requisitos del sistema

• Go 1.21 o posterior
• Compatible con Linux y macOS