ClickHouse Go

تتيح لك مكتبات عميل Go الخاصة بـ ClickHouse الاتصال بـ ClickHouse باستخدام واجهة Go القياسية database/sql أو الواجهة الأصلية المحسّنة.

​

البدء السريع

لنبدأ بمثال بسيط. سيؤدي هذا إلى الاتصال بـ ClickHouse وتنفيذ استعلام على قاعدة بيانات النظام. للبدء، ستحتاج إلى تفاصيل الاتصال الخاصة بك.

​

تفاصيل الاتصال

للاتصال بـ ClickHouse باستخدام native TCP، ستحتاج إلى المعلومات التالية:

المعلمات	الوصف
HOST and PORT	يكون المنفذ عادةً 9440 عند استخدام TLS، أو 9000 عند عدم استخدام TLS.
DATABASE NAME	توجد افتراضيًا قاعدة بيانات باسم default؛ استخدم اسم قاعدة البيانات التي تريد الاتصال بها.
USERNAME and PASSWORD	يكون اسم المستخدم افتراضيًا هو default. استخدم اسم المستخدم المناسب لحالة الاستخدام الخاصة بك.

تتوفر تفاصيل خدمة ClickHouse Cloud الخاصة بك في ClickHouse Cloud console. حدّد الخدمة التي ستتصل بها، ثم انقر على Connect:

اختر Native، وستتوفر التفاصيل ضمن مثال لأمر clickhouse-client.

إذا كنت تستخدم ClickHouse مُدارًا ذاتيًا، فسيحدّد مسؤول ClickHouse لديك تفاصيل الاتصال.

​

تهيئة وحدة

mkdir clickhouse-golang-example
cd clickhouse-golang-example
go mod init clickhouse-golang-example

​

انسخ بعض الشيفرة النموذجية

انسخ هذه الشيفرة إلى الدليل clickhouse-golang-example واحفظها باسم main.go.

main.go

package main

import (
    "context"
    "crypto/tls"
    "fmt"
    "log"

    "github.com/ClickHouse/clickhouse-go/v2"
    "github.com/ClickHouse/clickhouse-go/v2/lib/driver"
)

func main() {
    conn, err := connect()
    if err != nil {
        panic(err)
    }

    ctx := context.Background()
    rows, err := conn.Query(ctx, "SELECT name, toString(uuid) as uuid_str FROM system.tables LIMIT 5")
    if err != nil {
        log.Fatal(err)
    }
    defer rows.Close()

    for rows.Next() {
        var name, uuid string
        if err := rows.Scan(&name, &uuid); err != nil {
            log.Fatal(err)
        }
        log.Printf("name: %s, uuid: %s", name, uuid)
    }

    // NOTE: Do not skip rows.Err() check
    if err := rows.Err(); err != nil {
        log.Fatal(err)
    }

}

func connect() (driver.Conn, error) {
    var (
        ctx       = context.Background()
        conn, err = clickhouse.Open(&clickhouse.Options{
            Addr: []string{"<CLICKHOUSE_SECURE_NATIVE_HOSTNAME>:9440"},
            Auth: clickhouse.Auth{
                Database: "default",
                Username: "default",
                Password: "<DEFAULT_USER_PASSWORD>",
            },
            ClientInfo: clickhouse.ClientInfo{
                Products: []struct {
                    Name    string
                    Version string
                }{
                    {Name: "an-example-go-client", Version: "0.1"},
                },
            },
            Debugf: func(format string, v ...interface{}) {
                fmt.Printf(format, v)
            },
            TLS: &tls.Config{
                InsecureSkipVerify: true,
            },
        })
    )

    if err != nil {
        return nil, err
    }

    if err := conn.Ping(ctx); err != nil {
        if exception, ok := err.(*clickhouse.Exception); ok {
            fmt.Printf("Exception [%d] %s \n%s\n", exception.Code, exception.Message, exception.StackTrace)
        }
        return nil, err
    }
    return conn, nil
}

​

نفّذ go mod tidy

go mod tidy

​

عيّن تفاصيل الاتصال الخاصة بك

سبق أن اطّلعت على تفاصيل الاتصال الخاصة بك. عيّنها في main.go داخل الدالة connect():

func connect() (driver.Conn, error) {
  var (
    ctx       = context.Background()
    conn, err = clickhouse.Open(&clickhouse.Options{
      Addr: []string{"<CLICKHOUSE_SECURE_NATIVE_HOSTNAME>:9440"},
      Auth: clickhouse.Auth{
        Database: "default",
        Username: "default",
        Password: "<DEFAULT_USER_PASSWORD>",
      },

​

نفّذ المثال

go run .

2023/03/06 14:18:33 name: COLUMNS, uuid: 00000000-0000-0000-0000-000000000000
2023/03/06 14:18:33 name: SCHEMATA, uuid: 00000000-0000-0000-0000-000000000000
2023/03/06 14:18:33 name: TABLES, uuid: 00000000-0000-0000-0000-000000000000
2023/03/06 14:18:33 name: VIEWS, uuid: 00000000-0000-0000-0000-000000000000
2023/03/06 14:18:33 name: hourly_data, uuid: a4e36bd4-1e82-45b3-be77-74a0fe65c52b

​

تعرّف على المزيد

تغطي بقية الوثائق في هذه الفئة تفاصيل عميل Go الخاص بـ ClickHouse.

​

نظرة عامة

يدعم ClickHouse مكتبتَي عملاء رسميتين للغة Go. وهاتان المكتبتان متكاملتان ومصممتان عمدًا لدعم حالات استخدام مختلفة.

• clickhouse-go - مكتبة عملاء عالية المستوى للغات البرمجة تدعم إما واجهة database/sql القياسية في Go أو واجهة برمجة تطبيقات ClickHouse الأصلية.
• ch-go - عميل منخفض المستوى. يدعم الواجهة الأصلية فقط.

يوفّر clickhouse-go واجهة عالية المستوى تتيح للمستخدمين تنفيذ الاستعلامات وإدراج البيانات باستخدام دلالات موجّهة للصفوف، مع التجميع على دفعات بمرونة فيما يتعلق بأنواع البيانات — إذ تُحوَّل القيم ما دام ذلك لا يترتب عليه احتمال فقدانٍ في الدقة. أمّا ch-go فيوفّر واجهة محسّنة موجّهة للأعمدة تتيح تدفّقًا سريعًا لكتل البيانات مع حمل منخفض على CPU والذاكرة، وذلك على حساب الصرامة في الأنواع وزيادة تعقيد الاستخدام.

اعتبارًا من الإصدار 2.3، يستخدم clickhouse-go مكتبة ch-go للوظائف منخفضة المستوى مثل الترميز وفك الترميز والضغط. ويستخدم كلا العميلين التنسيق الأصلي في الترميز لتوفير أفضل أداء ممكن، كما يمكنهما الاتصال عبر بروتوكول ClickHouse الأصلي. ويدعم clickhouse-go أيضًا HTTP كآلية نقل في الحالات التي يحتاج فيها المستخدمون إلى استخدام proxy أو موازنة الحمل لحركة المرور.

​

أربع طرق للاتصال

يمنحك clickhouse-go خيارين مستقلين: أي واجهة برمجة تطبيقات تستخدم وأي وسيلة نقل تستخدم. ويؤدي الجمع بينهما إلى أربعة أوضاع اتصال:

	TCP (البروتوكول الأصلي، المنفذ 9000/9440)	HTTP (المنفذ 8123/8443)
واجهة برمجة تطبيقات ClickHouse (clickhouse.Open)	الافتراضي — أفضل أداء	عيّن Protocol: clickhouse.HTTP
واجهة برمجة تطبيقات database/sql (OpenDB / sql.Open)	clickhouse://host:9000	http://host:8123

اختيار واجهة برمجة تطبيقات: اختر واجهة برمجة تطبيقات ClickHouse للحصول على أعلى أداء ومجموعة الميزات الكاملة (استدعاءات التقدم، وعمليات insert العمودية، ودعم غني للأنواع). واختر database/sql عندما تحتاج إلى التكامل مع ORMs أو مع أدوات تتوقع واجهة قاعدة بيانات قياسية لـ Go.

اختيار وسيلة النقل: TCP أسرع وهو الخيار الافتراضي. انتقل إلى HTTP عندما تتطلب البنية التحتية لديك ذلك — على سبيل المثال، عند الاتصال عبر موازن تحميل أو proxy خاص بـ HTTP، أو عندما تحتاج إلى ميزات خاصة بـ HTTP مثل الجلسات مع الجداول المؤقتة، أو خوارزميات ضغط إضافية (gzip, deflate, br).

تستخدم كلتا واجهتي برمجة التطبيقات الترميز الثنائي الأصلي بغض النظر عن وسيلة النقل، لذلك لا يضيف HTTP أي عبء serialization.

	التنسيق الأصلي	النقل عبر TCP	النقل عبر HTTP	كتابة مجمّعة	تنظيم struct	الضغط	استدعاءات التقدم
واجهة برمجة تطبيقات ClickHouse	✅	✅	✅	✅	✅	✅	✅
واجهة برمجة تطبيقات database/sql	✅	✅	✅	✅		✅

​

اختيار عميل

يعتمد اختيار مكتبة العميل على أنماط استخدامك وحاجتك إلى أفضل أداء ممكن. في حالات الاستخدام كثيفة insert، حيث يلزم تنفيذ ملايين عمليات الإدراج في الثانية، نوصي باستخدام العميل منخفض المستوى ch-go. يتجنب هذا العميل الكلفة الإضافية المرتبطة بتحويل البيانات من تنسيق موجّه للصفوف إلى تنسيق موجّه للأعمدة، كما يتطلب التنسيق الأصلي لـ ClickHouse. بالإضافة إلى ذلك، فهو يتجنب أي استبطان (reflection) أو استخدام النوع interface{} (any) لتبسيط الاستخدام.

أما بالنسبة إلى أعباء عمل الاستعلام التي تركز على التجميعات، أو أعباء عمل الإدراج ذات معدل النقل الأقل، فإن clickhouse-go يوفّر واجهة database/sql مألوفة ودلالات صفوف أبسط. ويمكنك أيضًا، عند الحاجة، استخدام HTTP كبروتوكول نقل والاستفادة من الدوال المساعدة لتحويل الصفوف من البُنى (structs) وإليها.

	التنسيق الأصلي	البروتوكول الأصلي	بروتوكول HTTP	واجهة برمجة تطبيقات موجّهة للصفوف	واجهة برمجة تطبيقات موجّهة للأعمدة	مرونة الأنواع	الضغط	العناصر النائبة في الاستعلام
clickhouse-go	✅	✅	✅	✅	✅	✅	✅	✅
ch-go	✅	✅			✅		✅

​

التثبيت

تم إهمال الإصدار v1 من برنامج التشغيل، ولن يتلقى تحديثات للميزات أو دعمًا لأنواع ClickHouse الجديدة. ينبغي لك الترحيل إلى v2، إذ يوفّر أداءً أفضل.

لتثبيت الإصدار 2.x من العميل، أضف الحزمة إلى ملف go.mod:

require github.com/ClickHouse/clickhouse-go/v2 main

أو استنسخ المستودع:

git clone --branch v2 https://github.com/clickhouse/clickhouse-go.git $GOPATH/src/github

لتثبيت إصدار آخر، عدّل المسار أو اسم الفرع بما يتناسب مع ذلك.

mkdir my-clickhouse-app && cd my-clickhouse-app

cat > go.mod <<-END
  module my-clickhouse-app

  go 1.21

  require github.com/ClickHouse/clickhouse-go/v2 main
END

cat > main.go <<-END
  package main

  import (
    "fmt"
    "github.com/ClickHouse/clickhouse-go/v2"
  )

  func main() {
   conn, _ := clickhouse.Open(&clickhouse.Options{Addr: []string{"127.0.0.1:9000"}})
    v, _ := conn.ServerVersion()
    fmt.Println(v.String())
  }
END

go mod tidy
go run main.go

​

الإصدارات

يُطرح العميل بإصدارات مستقلة عن ClickHouse. ويمثّل 2.x الإصدار الرئيسي الحالي قيد التطوير. ويجب أن تكون جميع إصدارات 2.x متوافقةً مع بعضها البعض.

​

توافق ClickHouse

يدعم العميل ما يلي:

• جميع إصدارات ClickHouse المدعومة حاليًا كما هو موضح هنا. وعندما تتوقف إصدارات ClickHouse عن تلقي الدعم، تتوقف أيضًا اختبارات توافقها النشطة مع إصدارات العميل.
• جميع إصدارات ClickHouse ضمن فترة سنتين من تاريخ إصدار العميل. لاحظ أن إصدارات LTS فقط هي التي تخضع لاختبارات نشطة.

​

التوافق مع Golang

إصدار العميل	إصدارات Golang
=> 2.0 <= 2.2	1.17, 1.18
>= 2.3, < 2.41	1.18+
>= 2.41	1.21+
>= 2.43	1.24+

​

أفضل الممارسات

• استخدم واجهة برمجة تطبيقات ClickHouse حيثما أمكن، خاصةً مع الأنواع البدائية. فهذا يجنبك قدرًا كبيرًا من الاستبطان وعدم المباشرة.
• إذا كنت تقرأ مجموعات بيانات كبيرة، ففكّر في تعديل BlockBufferSize. سيزيد ذلك من استهلاك الذاكرة، لكنه يتيح فك ترميز المزيد من الكتل بالتوازي أثناء التكرار على الصفوف. القيمة الافتراضية 2 متحفظة وتقلل من الحمل الإضافي على الذاكرة. وتعني القيم الأعلى وجود المزيد من الكتل في الذاكرة. ويتطلب هذا الاختبار، لأن الاستعلامات المختلفة قد تنتج أحجام كتل مختلفة. لذلك يمكن ضبطه على مستوى الاستعلام عبر Context.
• كن دقيقًا في تحديد الأنواع عند إدراج البيانات. فمع أن العميل مصمم ليكون مرنًا، مثل السماح بتحليل السلاسل النصية إلى UUIDs أو عناوين IP، فإن ذلك يتطلب التحقق من صحة البيانات ويترتب عليه تكلفة وقت الإدراج.
• استخدم عمليات الإدراج الموجّهة بالأعمدة حيثما أمكن. ومرة أخرى، ينبغي أن تكون محددة الأنواع بوضوح لتجنب حاجة العميل إلى تحويل قيمك.
• اتبع توصيات ClickHouse المتعلقة بالأداء لتحقيق أفضل أداء عند الإدراج.

​

الخطوات التالية

• الإعداد — إعدادات الاتصال وTLS والمصادقة وتسجيل الأحداث والضغط
• واجهة برمجة تطبيقات ClickHouse — واجهة برمجة تطبيقات Go الأصلية للاستعلامات والإدراج
• واجهة برمجة تطبيقات Database/SQL — واجهة database/sql القياسية
• أنواع البيانات — تعيينات أنواع Go ودعم الأنواع المعقدة