chDB para Go - ClickHouse Documentation

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

Instalación

Instalar libchdb

Primero, instala la biblioteca chDB:

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

Instalar chdb-go

Instala el paquete para Go:

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

O 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 realizar consultas rápidas:

# Simple query
./chdb-go "SELECT 123"

# Interactive mode
./chdb-go

# Interactive mode with persistent storage
./chdb-go --path /tmp/chdb

Librería de Go - inicio rápido

Consultas sin estado

Para consultas sencillas y puntuales:

package main

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

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

Consultas con estado mediante una sesión

Para consultas complejas con estado persistente:

package main

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

func main() {
    // Create a session with persistent storage
    session, err := chdb.NewSession("/tmp/chdb-data")
    if err != nil {
        panic(err)
    }
    defer session.Cleanup()

    // Create database and table
    _, 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)
    }

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

    // Query data
    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() {
    // Open database connection
    db, err := sql.Open("chdb", "")
    if err != nil {
        panic(err)
    }
    defer db.Close()

    // Query with standard database/sql interface
    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() {
    // Create a session for streaming queries
    session, err := chdb.NewSession("/tmp/chdb-stream")
    if err != nil {
        log.Fatal(err)
    }
    defer session.Cleanup()

    // Execute a streaming query for large dataset
    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
    
    // Process data in chunks
    for {
        chunk := streamResult.GetNext()
        if chunk == nil {
            // No more data
            break
        }
        
        // Check for streaming errors
        if err := streamResult.Error(); err != nil {
            log.Printf("Streaming error: %v", err)
            break
        }
        
        rowsRead := chunk.RowsRead()
        // You can process the chunk data here
        // For example, write to file, send over network, 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:

Uso eficiente de la memoria - Permite procesar grandes conjuntos de datos sin cargarlo todo en memoria
Procesamiento en tiempo real - Permite empezar a procesar los datos en cuanto llega el primer fragmento
Soporte para cancelación - Permite cancelar consultas de larga duración con Cancel()
Gestión de errores - Permite comprobar si hay errores durante el streaming con Error()

Documentación de la API

chDB-go proporciona APIs de alto nivel y de 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 detallado

Requisitos del sistema

Go 1.21 o posterior
Compatible con Linux y macOS

​Instalación

​Uso

​Interfaz de línea de comandos

​Librería de Go - inicio rápido

​Consultas sin estado

​Consultas con estado mediante una sesión

​Interfaz del driver SQL

​Consultas en streaming para grandes conjuntos de datos

​Documentación de la API

​Requisitos del sistema