> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# chDB para Go

> Cómo instalar y usar chDB con Go

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.

<div id="installation">
  ## Instalación
</div>

<Steps>
  <Step title="Instalar libchdb" id="install-libchdb">
    Primero, instala la biblioteca chDB:

    ```bash theme={null}
    curl -sL https://lib.chdb.io | bash
    ```
  </Step>

  <Step title="Instalar chdb-go" id="install-chdb-go">
    Instala el paquete para Go:

    ```bash theme={null}
    go install github.com/chdb-io/chdb-go@latest
    ```

    O añádelo a tu `go.mod`:

    ```bash theme={null}
    go get github.com/chdb-io/chdb-go
    ```
  </Step>
</Steps>

<div id="usage">
  ## Uso
</div>

<div id="cli">
  ### Interfaz de línea de comandos
</div>

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

```bash theme={null}
# Simple query
./chdb-go "SELECT 123"

# Interactive mode
./chdb-go

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

<div id="quick-start">
  ### Librería de Go - inicio rápido
</div>

<div id="stateless-queries">
  #### Consultas sin estado
</div>

Para consultas sencillas y puntuales:

```go theme={null}
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)
}
```

<div id="stateful-queries">
  #### Consultas con estado mediante una sesión
</div>

Para consultas complejas con estado persistente:

```go theme={null}
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)
}
```

<div id="sql-driver">
  #### Interfaz del driver SQL
</div>

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

```go theme={null}
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)
    }
}
```

<div id="query-streaming">
  #### Consultas en streaming para grandes conjuntos de datos
</div>

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

```go theme={null}
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()`

<div id="api-documentation">
  ## Documentación de la API
</div>

chDB-go proporciona APIs de alto nivel y de bajo nivel:

* **[Documentación de la API de alto nivel](https://github.com/chdb-io/chdb-go/blob/main/chdb.md)** - Recomendada para la mayoría de los casos de uso
* **[Documentación de la API de bajo nivel](https://github.com/chdb-io/chdb-go/blob/main/lowApi.md)** - Para casos de uso avanzados que requieren un control detallado

<div id="requirements">
  ## Requisitos del sistema
</div>

* Go 1.21 o posterior
* Compatible con Linux y macOS