결과 처리

결과 처리 (Handle Results, Go)

개요 (Overview)

DuckDB는 열 지향이고, database/sql을 통해 결과 집합을 [행 단위로]({% link docs/current/clients/go/querying.md %}#scanning-results) 읽는 것 외에도, Go 클라이언트는 전체 결과를 Apache Arrow로 record batch 스트림으로 교환하고, Arrow 스트림을 쿼리 가능한 뷰로 등록할 수 있어요. 둘 다 아래에 설명할게요.

출처: 문서

본문

Arrow 인터페이스 활성화

DuckDB Arrow 인터페이스는 무거운 의존성이므로 v2부터 옵트인이에요. duckdb_arrow [빌드 태그]({% link docs/current/clients/go/overview.md %}#build-tags)로 활성화해요:

go build -tags=duckdb_arrow

태그가 없으면 여기 설명된 Arrow 타입과 함수는 컴파일되지 않아요. 이 인터페이스는 apache/arrow-go를 기반으로 하므로, 그 array와 arrow 패키지가 record와 schema 타입을 제공해요.

결과를 Arrow로 읽기

원시 DuckDB 연결을 duckdb.NewArrowFromConn()으로 감싼 다음 QueryContext()를 호출해 쿼리를 실행하고 array.RecordReader를 받아요. Next()로 반복하며 한 번에 하나의 arrow.RecordBatch를 읽고, 끝나면 해제해요:

connector, err := duckdb.NewConnector("", nil)
if err != nil {
    log.Fatal(err)
}
defer connector.Close()

conn, err := connector.Connect(context.Background())
if err != nil {
    log.Fatal(err)
}
defer conn.Close()

ar, err := duckdb.NewArrowFromConn(conn)
if err != nil {
    log.Fatal(err)
}

reader, err := ar.QueryContext(context.Background(), "SELECT * FROM generate_series(1, 10)")
if err != nil {
    log.Fatal(err)
}
defer reader.Release()

for reader.Next() {
    record := reader.RecordBatch()
    // 한 번에 하나의 record batch 처리.
    log.Printf("%d rows", record.NumRows())
}
if err := reader.Err(); err != nil {
    log.Fatal(err)
}

QueryContext()는 [database/sql 쿼리]({% link docs/current/clients/go/querying.md %}#binding-parameters)와 마찬가지로 바인딩된 파라미터를 후행 인자로 받아요.

Arrow 스트림을 뷰로 등록

프로그램의 다른 곳에서 만든 Arrow 스트림, 즉 array.RecordReader는 DuckDB 뷰로 등록해 SQL에서 쿼리할 수 있어요. RegisterView()는 리더와 뷰 이름을 받고, 뷰를 등록 해제하는 release 함수를 반환해요. 뷰가 더 이상 필요 없을 때 호출해요:

release, err := ar.RegisterView(reader, "my_arrow_view")
if err != nil {
    log.Fatal(err)
}
defer release()

result, err := ar.QueryContext(context.Background(),
    "SELECT count(*) FROM my_arrow_view")

DuckDB는 등록된 뷰를 다른 테이블처럼 스캔하므로, SQL에서 필터링·조인·집계할 수 있어요.

경고: Arrow 연결은 동시 사용에 안전하지 않으며 database/sql 연결 풀링의 이점도 받지 못해요. 연결당 Arrow 핸들 하나를 사용하고 goroutine 간에 공유하지 마세요.

더 알아보기 (Learn more)

  • [Run Queries]({% link docs/current/clients/go/querying.md %}) — 이 페이지가 읽는 결과를 내는 쿼리 전송 및 행 단위 읽기.
  • [Build Tags]({% link docs/current/clients/go/overview.md %}#build-tags) — Arrow 인터페이스를 활성화하는 duckdb_arrow 태그와 기타 빌드 태그.
  • [Write User Defined Functions]({% link docs/current/clients/go/functions.md %}) — 외부 데이터를 SQL에 노출하는 또 다른 방법인 replacement scans.