chDB pour Go - ClickHouse Documentation

chDB-go fournit des bindings Go pour chDB, ce qui vous permet d’exécuter des requêtes ClickHouse directement dans vos applications Go, sans aucune dépendance externe.

Installation

Installer libchdb

Commencez par installer la bibliothèque chDB :

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

Installer chdb-go

Installez le paquet Go :

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

Ou ajoutez-le à votre go.mod :

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

Utilisation

Interface en ligne de commande

chDB-go inclut une CLI pour effectuer rapidement des requêtes :

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

# Interactive mode
./chdb-go

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

Bibliothèque Go - prise en main rapide

Requêtes sans état

Pour les requêtes simples et ponctuelles :

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)
}

Requêtes avec état via une session

Pour les requêtes complexes avec état persistant :

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)
}

Interface du pilote SQL

chDB-go implémente l’interface 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)
    }
}

Exécution de requêtes en flux pour les grands jeux de données

Pour traiter de grands jeux de données qui ne tiennent pas en mémoire, utilisez des requêtes en flux :

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)
}

Avantages des requêtes en flux :

Économe en mémoire - Traitez de grands volumes de données sans tout charger en mémoire
Traitement en temps réel - Commencez à traiter les données dès l’arrivée du premier fragment
Prise en charge de l’annulation - Vous pouvez annuler les requêtes longues avec Cancel()
Gestion des erreurs - Détectez les erreurs pendant la diffusion en flux avec Error()

Documentation de l’API

chDB-go propose des API de haut niveau comme de bas niveau :

Documentation de l’API de haut niveau - Recommandée pour la plupart des cas d’utilisation
Documentation de l’API de bas niveau - Pour les cas d’utilisation avancés nécessitant un contrôle fin

Configuration système requise

Go 1.21 ou version ultérieure
Compatible avec Linux, macOS

​Installation

​Utilisation

​Interface en ligne de commande

​Bibliothèque Go - prise en main rapide

​Requêtes sans état

​Requêtes avec état via une session

​Interface du pilote SQL

​Exécution de requêtes en flux pour les grands jeux de données

​Documentation de l’API

​Configuration système requise