برنامج تشغيل Databricks SQL ل Go

برنامج تشغيل Databricks SQL ل Go هو مكتبة Go تسمح لك باستخدام التعليمات البرمجية Go لتشغيل أوامر SQL على موارد حساب Azure Databricks. تكمل هذه المقالة برنامج تشغيل Databricks SQL ل Go README ومرجع واجهة برمجة التطبيقات والأمثلة.

المتطلبات

• جهاز تطوير يعمل بنظام التشغيل Go، الإصدار 1.20 أو أعلى. لطباعة الإصدار المثبت من Go، قم بتشغيل الأمر go version. قم بتنزيل Go وتثبيته.
• نظام مجموعة موجود أو مستودع SQL.
• قيم اسم مضيف الخادم والمنفذ ومسار HTTP للمجموعة الموجودة أو مستودع SQL.
  • احصل على هذه القيم لنظام مجموعة.
  • احصل على هذه القيم لمستودع SQL.

بدء استخدام برنامج تشغيل Databricks SQL ل Go

1. على جهاز التطوير الخاص بك مع تثبيت Go 1.20 أو أعلى بالفعل وإنشاء مشروع تعليمة برمجية Go موجود بالفعل، قم بإنشاء go.mod ملف لتعقب تبعيات التعليمات البرمجية Go الخاصة بك عن طريق تشغيل go mod init الأمر، على سبيل المثال:

   go mod init sample
   

2. خذ تبعية على حزمة Databricks SQL Driver for Go عن طريق تشغيل go mod edit -require الأمر، واستبدال v1.5.2 بأحدث إصدار من حزمة Databricks SQL Driver for Go كما هو موضح في الإصدارات:

   go mod edit -require github.com/databricks/databricks-sql-go@v1.5.2
   

   go.mod يجب أن يبدو الملف الآن كما يلي:

   module sample
   
   go 1.20
   
   require github.com/databricks/databricks-sql-go v1.5.2
   

3. في مشروعك، قم بإنشاء ملف التعليمات البرمجية Go الذي يستورد برنامج تشغيل Databricks SQL ل Go. المثال التالي، في ملف يسمى main.go بالمحتويات التالية، يسرد جميع المجموعات في مساحة عمل Azure Databricks:

   package main
   
   import (
     "database/sql"
     "os"
     _ "github.com/databricks/databricks-sql-go"
   )
   
   func main() {
     dsn := os.Getenv("DATABRICKS_DSN")
   
     if dsn == "" {
       panic("No connection string found. " +
        "Set the DATABRICKS_DSN environment variable, and try again.")
     }
   
     db, err := sql.Open("databricks", dsn)
     if err != nil {
       panic(err)
     }
     defer db.Close()
   
     if err := db.Ping(); err != nil {
       panic(err)
     }
   }
   

4. أضف أي تبعيات وحدة مفقودة go mod tidy عن طريق تشغيل الأمر :

   go mod tidy
   

   إشعار

   إذا تلقيت الخطأ go: warning: "all" matched no packages، نسيت إضافة ملف التعليمات البرمجية Go الذي يستورد برنامج تشغيل Databricks SQL ل Go.

5. قم بعمل نسخ من جميع الحزم اللازمة لدعم بنيات واختبارات الحزم في الوحدة النمطية go mod vendor الخاصة بكmain، عن طريق تشغيل الأمر :

   go mod vendor
   

6. تعديل التعليمات البرمجية DATABRICKS_DSN الخاصة بك حسب الحاجة لتعيين متغير البيئة لمصادقة Azure Databricks. راجع أيضا الاتصال سلسلة الاتصال DSN.

7. قم بتشغيل ملف التعليمات البرمجية Go الخاص بك، بافتراض ملف يسمى main.go، عن طريق تشغيل go run الأمر :

   go run main.go
   

8. إذا لم يتم إرجاع أي أخطاء، فقد نجحت في مصادقة برنامج تشغيل Databricks SQL ل Go مع مساحة عمل Azure Databricks وتوصيلها بمجموعة Azure Databricks قيد التشغيل أو مستودع SQL في مساحة العمل هذه.

الاتصال سلسلة الاتصال DSN

للوصول إلى المجموعات ومستودعات SQL، استخدم sql.Open() لإنشاء مقبض قاعدة بيانات من خلال اسم مصدر بيانات (DSN) سلسلة الاتصال. يسترد مثال التعليمات البرمجية هذا سلسلة الاتصال DSN من متغير بيئة يسمى DATABRICKS_DSN:

package main

import (
  "database/sql"
  "os"
  _ "github.com/databricks/databricks-sql-go"
)

func main() {
  dsn := os.Getenv("DATABRICKS_DSN")

  if dsn == "" {
    panic("No connection string found. " +
          "Set the DATABRICKS_DSN environment variable, and try again.")
  }

  db, err := sql.Open("databricks", dsn)
  if err != nil {
    panic(err)
  }
  defer db.Close()

  if err := db.Ping(); err != nil {
    panic(err)
  }
}

لتحديد سلسلة الاتصال DSN بالتنسيق الصحيح، راجع أمثلة سلسلة الاتصال DSN في المصادقة. على سبيل المثال، بالنسبة لمصادقة الرمز المميز للوصول الشخصي ل Azure Databricks، استخدم بناء الجملة التالي، حيث:

• <personal-access-token> هو رمز الوصول الشخصي Azure Databricks الخاص بك من المتطلبات.
• <server-hostname>هو قيمة Server Hostname من المتطلبات.
• <port-number>هي قيمة المنفذ من المتطلبات، والتي عادة ما 443تكون .
• <http-path>هي قيمة مسار HTTP من المتطلبات.
• <paramX=valueX> هي معلمة اختيارية واحدة أو أكثر مدرجة لاحقا في هذه المقالة.

token:<personal-access-token>@<server-hostname>:<port-number>/<http-path>?<param1=value1>&<param2=value2>

على سبيل المثال، بالنسبة لنظام مجموعة:

token:dapi12345678901234567890123456789012@adb-1234567890123456.7.azuredatabricks.net:443/sql/protocolv1/o/1234567890123456/1234-567890-abcdefgh

على سبيل المثال، لمستودع SQL:

token:dapi12345678901234567890123456789012@adb-1234567890123456.7.azuredatabricks.net:443/sql/1.0/endpoints/a1b234c5678901d2

تتمثل المعلمات الاختيارية في الآتي

• يمكن تحديد معلمات الاتصال الاختيارية المدعومة في <param=value>. تتضمن بعض تلك الأكثر استخداما ما يلي:
  • catalog: تعيين اسم الكتالوج الأولي في جلسة العمل.
  • schema: تعيين اسم المخطط الأولي في جلسة العمل.
  • maxRows: إعداد الحد الأقصى لعدد الصفوف التي تم جلبها لكل طلب. الافتراضي هو 10000.
  • timeout: يضيف المهلة (بالثوان) لتنفيذ استعلام الخادم. الإعداد الافتراضي ليس مهلة.
  • userAgentEntry: يستخدم لتحديد الشركاء. لمزيد من المعلومات، راجع وثائق شريكك.
• يمكن تحديد معلمات جلسة العمل الاختيارية المدعومة في param=value. تتضمن بعض تلك الأكثر استخداما ما يلي:
  • ansi_mode: سلسلة منطقية. true لعبارات الجلسة للالتزام بالقواعد المحددة بواسطة مواصفات ANSI SQL. الإعداد الافتراضي للنظام خطأ.
  • timezone: سلسلة، على سبيل المثال America/Los_Angeles. تعيين المنطقة الزمنية لجلسة العمل. الإعداد الافتراضي للنظام هو UTC.

على سبيل المثال، لمستودع SQL:

token:dapi12345678901234567890123456789012@adb-1234567890123456.7.azuredatabricks.net:443/sql/1.0/endpoints/a1b234c5678901d2?catalog=hive_metastore&schema=example&maxRows=100&timeout=60&timezone=America/Sao_Paulo&ansi_mode=true

الاتصال بالدالة NewConnector

بدلا من ذلك، يتطلب استخدام sql.OpenDB() لإنشاء مقبض قاعدة بيانات من خلال كائن موصل جديد تم إنشاؤه باستخدام dbsql.NewConnector() (الاتصال بم مجموعات Azure Databricks ومستودعات SQL باستخدام كائن موصل جديد إصدار 1.0.0 أو أعلى من Databricks SQL Driver for Go). على سبيل المثال:

package main

import (
  "database/sql"
  "os"
  dbsql "github.com/databricks/databricks-sql-go"
)

func main() {
  connector, err := dbsql.NewConnector(
    dbsql.WithAccessToken(os.Getenv("DATABRICKS_ACCESS_TOKEN")),
    dbsql.WithServerHostname(os.Getenv("DATABRICKS_HOST")),
    dbsql.WithPort(443),
    dbsql.WithHTTPPath(os.Getenv("DATABRICKS_HTTP_PATH")),
  )
  if err != nil {
    panic(err)
  }

  db := sql.OpenDB(connector)
  defer db.Close()

  if err := db.Ping(); err != nil {
    panic(err)
  }
}

لتحديد مجموعة NewConnector الإعدادات الصحيحة، راجع الأمثلة في المصادقة.

تتضمن بعض الخيارات الوظيفية الأكثر استخداما ما يلي:

• WithAccessToken(<access-token>): رمز الوصول الشخصي Azure Databricks الخاص بك من المتطلبات. مطلوب string.
• WithServerHostname(<server-hostname>): قيمة Server Hostname من المتطلبات. مطلوب string.
• WithPort(<port>): رقم منفذ الخادم، عادة 443. مطلوب int.
• WithHTTPPath(<http-path>): قيمة مسار HTTP من المتطلبات. مطلوب string.
• WithInitialNamespace(<catalog>, <schema>):اسم الكتالوج والمخطط في جلسة العمل. اختياري string, string.
• WithMaxRows(<max-rows>): الحد الأقصى لعدد الصفوف التي تم جلبها لكل طلب. الافتراضي هو 10000. اختياري int.
• WithSessionParams(<params-map>): معلمات الجلسة بما في ذلك "المنطقة الزمنية" و"ansi_mode". اختياري map[string]string.
• WithTimeout(<timeout>). المهلة (في time.Duration) لتنفيذ استعلام الخادم. الإعداد الافتراضي ليس مهلة. اختياري.
• WithUserAgentEntry(<isv-name-plus-product-name>). يستخدم لتحديد الشركاء. لمزيد من المعلومات، راجع وثائق شريكك. اختياري string.

على سبيل المثال:

connector, err := dbsql.NewConnector(
  dbsql.WithAccessToken(os.Getenv("DATABRICKS_ACCESS_TOKEN")),
  dbsql.WithServerHostname(os.Getenv("DATABRICKS_HOST")),
  dbsql.WithPort(443),
  dbsql.WithHTTPPath(os.Getenv("DATABRICKS_HTTP_PATH")),
  dbsql.WithInitialNamespace("samples", "nyctaxi"),
  dbsql.WithMaxRows(100),
  dbsql.SessionParams(map[string]string{"timezone": "America/Sao_Paulo", "ansi_mode": "true"}),
  dbsql.WithTimeout(time.Minute),
  dbsql.WithUserAgentEntry("example-user"),
)

المصادقة

يدعم برنامج تشغيل Databricks SQL ل Go أنواع مصادقة Azure Databricks التالية:

• مصادقة رمز الوصول الشخصي ل Databricks
• مصادقة الرمز المميز لمعرف Microsoft Entra
• مصادقة OAuth من مستخدم إلى جهاز (U2M)
• مصادقة OAuth من جهاز إلى جهاز (M2M)

لا يدعم برنامج تشغيل Databricks SQL ل Go بعد أنواع مصادقة Azure Databricks التالية:

• مصادقة الهويات المدارة من Azure
• المصادقة الأساسية لخدمة MS Entra
• مصادقة Azure CLI

مصادقة رمز الوصول الشخصي ل Databricks

لاستخدام برنامج تشغيل Databricks SQL ل Go مع مصادقة رمز الوصول الشخصي Azure Databricks، يجب أولا إنشاء رمز مميز للوصول الشخصي ل Azure Databricks. للحصول على تفاصيل حول هذه الخطوة، راجع الرموز المميزة للوصول الشخصي إلى Azure Databricks لمستخدمي مساحة العمل.

لمصادقة برنامج تشغيل Databricks SQL ل Go مع سلسلة الاتصال DSN ومثال التعليمات البرمجية في الاتصال سلسلة الاتصال DSN، استخدم بناء جملة DSN سلسلة الاتصال التالي، حيث:

• <personal-access-token> هو رمز الوصول الشخصي Azure Databricks الخاص بك من المتطلبات.
• <server-hostname>هو قيمة Server Hostname من المتطلبات.
• <port-number>هي قيمة المنفذ من المتطلبات، والتي عادة ما 443تكون .
• <http-path>هي قيمة مسار HTTP من المتطلبات.

يمكنك أيضا إلحاق معلمة اختيارية واحدة أو أكثر مدرجة سابقا في هذه المقالة.

token:<personal-access-token>@<server-hostname>:<port-number>/<http-path>

لمصادقة برنامج تشغيل Databricks SQL ل Go مع NewConnector الدالة ، استخدم القصاصة البرمجية التالية ومثال التعليمات البرمجية في الاتصال بوظيفة NewConnector، والتي تفترض أنك قمت بتعيين متغيرات البيئة التالية:

• DATABRICKS_SERVER_HOSTNAMEتعيين إلى قيمة Server Hostname لنظام المجموعة أو مستودع SQL.
• DATABRICKS_HTTP_PATH، قم بتعيين إلى قيمة مسار HTTP لنظام المجموعة أو مستودع SQL.
• DATABRICKS_TOKEN، قم بتعيين إلى رمز الوصول الشخصي Azure Databricks.

لتعيين متغيرات البيئة، راجع وثائق نظام التشغيل الخاص بك.

connector, err := dbsql.NewConnector(
  dbsql.WithServerHostname(os.Getenv("DATABRICKS_SERVER_HOSTNAME")),
  dbsql.WithHTTPPath(os.Getenv("DATABRICKS_HTTP_PATH")),
  dbsql.WithPort(443),
  dbsql.WithAccessToken(os.Getenv("DATABRICKS_TOKEN")),
)

مصادقة الرمز المميز لمعرف Microsoft Entra

يدعم برنامج تشغيل Databricks SQL ل Go الرموز المميزة لمعرف Microsoft Entra لمستخدم Azure Databricks أو كيان خدمة معرف Microsoft Entra.

لإنشاء رمز مميز للوصول إلى معرف Microsoft Entra، قم بما يلي:

• بالنسبة لمستخدم Azure Databricks، يمكنك استخدام Azure CLI. راجع الحصول على الرموز المميزة لمعرف Microsoft Entra للمستخدمين باستخدام Azure CLI.

  • للحصول على أساس خدمة معرف Microsoft Entra، راجع الحصول على رمز مميز للوصول إلى معرف Microsoft Entra باستخدام Azure CLI. لإنشاء كيان خدمة مدار من Microsoft Entra ID، راجع إدارة كيانات الخدمة.

  الرموز المميزة لمعرف Microsoft Entra لها عمر افتراضي يبلغ حوالي ساعة واحدة. لإنشاء رمز مميز جديد لمعرف Microsoft Entra، كرر هذه العملية.

  لمصادقة برنامج تشغيل Databricks SQL ل Go مع سلسلة الاتصال DSN ومثال التعليمات البرمجية في الاتصال سلسلة الاتصال DSN، استخدم بناء جملة DSN سلسلة الاتصال التالي، حيث:

  • <microsoft-entra-id-token> هو الرمز المميز لمعرف Microsoft Entra.
  • <server-hostname>هو قيمة Server Hostname من المتطلبات.
  • <port-number>هي قيمة المنفذ من المتطلبات، والتي عادة ما 443تكون .
  • <http-path>هي قيمة مسار HTTP من المتطلبات.

  يمكنك أيضا إلحاق معلمة اختيارية واحدة أو أكثر مدرجة سابقا في هذه المقالة.

  token:<microsoft-entra-id-token>@<server-hostname>:<port-number>/<http-path>
  

  لمصادقة برنامج تشغيل Databricks SQL ل Go مع NewConnector الدالة ، استخدم القصاصة البرمجية التالية ومثال التعليمات البرمجية في الاتصال بوظيفة NewConnector، والتي تفترض أنك قمت بتعيين متغيرات البيئة التالية:

  • DATABRICKS_SERVER_HOSTNAMEتعيين إلى قيمة Server Hostname لنظام المجموعة أو مستودع SQL.
  • DATABRICKS_HTTP_PATH، قم بتعيين إلى قيمة مسار HTTP لنظام المجموعة أو مستودع SQL.
  • DATABRICKS_TOKEN، قم بتعيين إلى الرمز المميز لمعرف Microsoft Entra.

  لتعيين متغيرات البيئة، راجع وثائق نظام التشغيل الخاص بك.

  connector, err := dbsql.NewConnector(
    dbsql.WithServerHostname(os.Getenv("DATABRICKS_SERVER_HOSTNAME")),
    dbsql.WithHTTPPath(os.Getenv("DATABRICKS_HTTP_PATH")),
    dbsql.WithPort(443),
    dbsql.WithAccessToken(os.Getenv("DATABRICKS_TOKEN")),
  )
  

مصادقة OAuth من مستخدم إلى جهاز (U2M)

يدعم Databricks SQL Driver للإصدارات Go 1.5.0 والإصدارات الأحدث مصادقة OAuth من مستخدم إلى جهاز (U2M).

لاستخدام برنامج تشغيل Databricks SQL ل Go مع سلسلة الاتصال DSN ومثال التعليمات البرمجية في الاتصال سلسلة الاتصال DSN، استخدم بناء جملة سلسلة الاتصال DSN التالي، حيث:

• <server-hostname>هو قيمة Server Hostname من المتطلبات.
• <port-number>هي قيمة المنفذ من المتطلبات، والتي عادة ما 443تكون .
• <http-path>هي قيمة مسار HTTP من المتطلبات.

يمكنك أيضا إلحاق معلمة اختيارية واحدة أو أكثر مدرجة سابقا في هذه المقالة.

<server-hostname>:<port-number>/<http-path>?authType=OauthU2M

لمصادقة برنامج تشغيل Databricks SQL ل Go مع الدالة NewConnector ، يجب أولا إضافة ما يلي إلى إعلانك import :

"github.com/databricks/databricks-sql-go/auth/oauth/u2m"

ثم استخدم القصاصة البرمجية التالية ومثال التعليمات البرمجية في الاتصال بوظيفة NewConnector، والتي تفترض أنك قمت بتعيين متغيرات البيئة التالية:

• DATABRICKS_SERVER_HOSTNAMEتعيين إلى قيمة Server Hostname لنظام المجموعة أو مستودع SQL.
• DATABRICKS_HTTP_PATH، قم بتعيين إلى قيمة مسار HTTP لنظام المجموعة أو مستودع SQL.

لتعيين متغيرات البيئة، راجع وثائق نظام التشغيل الخاص بك.

authenticator, err := u2m.NewAuthenticator(os.Getenv("DATABRICKS_SERVER_HOSTNAME"), 1*time.Minute)
if err != nil {
  panic(err)
}

connector, err := dbsql.NewConnector(
  dbsql.WithServerHostname(os.Getenv("DATABRICKS_SERVER_HOSTNAME")),
  dbsql.WithHTTPPath(os.Getenv("DATABRICKS_HTTP_PATH")),
  dbsql.WithPort(443),
  dbsql.WithAuthenticator(authenticator),
)

مصادقة OAuth من جهاز إلى جهاز (M2M)

يدعم Databricks SQL Driver للإصدارات Go 1.5.2 والإصدارات الأحدث مصادقة OAuth من جهاز إلى جهاز (M2M).

لاستخدام برنامج تشغيل Databricks SQL ل Go مع مصادقة OAuth M2M، يجب عليك القيام بما يلي:

1. إنشاء كيان خدمة Azure Databricks في مساحة عمل Azure Databricks، وإنشاء سر OAuth لكيان الخدمة هذا.

   لإنشاء كيان الخدمة وسر OAuth الخاص به، راجع مصادقة الوصول إلى Azure Databricks باستخدام كيان خدمة باستخدام OAuth (OAuth M2M). دون ملاحظة عن قيمة UUID أو Application ID الخاصة بكيان الخدمة، والقيمة السرية لسر OAuth الخاص بكيان الخدمة.

2. امنح كيان الخدمة هذا حق الوصول إلى نظام المجموعة أو المستودع الخاص بك.

   لمنح كيان الخدمة حق الوصول إلى نظام المجموعة أو المستودع، راجع حساب الأذونات أو إدارة مستودع SQL.

لمصادقة برنامج تشغيل Databricks SQL ل Go مع سلسلة الاتصال DSN ومثال التعليمات البرمجية في الاتصال سلسلة الاتصال DSN، استخدم بناء جملة DSN سلسلة الاتصال التالي، حيث:

• <server-hostname>هو قيمة Server Hostname من المتطلبات.
• <port-number>هي قيمة المنفذ من المتطلبات، والتي عادة ما 443تكون .
• <http-path>هي قيمة مسار HTTP من المتطلبات.
• <client-id>هي قيمة UUID أو معرف التطبيق لمدير الخدمة.
• <client-secret>هي القيمة السرية لسر OAuth الخاص بكيان الخدمة.

يمكنك أيضا إلحاق معلمة اختيارية واحدة أو أكثر مدرجة سابقا في هذه المقالة.

<server-hostname>:<port-number>/<http-path>?authType=OAuthM2M&clientID=<client-id>&clientSecret=<client-secret>

لمصادقة برنامج تشغيل Databricks SQL ل Go مع الدالة NewConnector ، يجب أولا إضافة ما يلي إلى إعلانك import :

"github.com/databricks/databricks-sql-go/auth/oauth/m2m"

ثم استخدم القصاصة البرمجية التالية ومثال التعليمات البرمجية في الاتصال بوظيفة NewConnector، والتي تفترض أنك قمت بتعيين متغيرات البيئة التالية:

• DATABRICKS_SERVER_HOSTNAMEتعيين إلى قيمة Server Hostname لنظام المجموعة أو مستودع SQL.
• DATABRICKS_HTTP_PATH، قم بتعيين إلى قيمة مسار HTTP لنظام المجموعة أو مستودع SQL.
• DATABRICKS_CLIENT_ID، قم بتعيين إلى قيمة UUID أو معرف التطبيق الخاصة بكيان الخدمة.
• DATABRICKS_CLIENT_SECRET، قم بتعيين إلى القيمة السرية لسر OAuth الخاص بكيان الخدمة.

لتعيين متغيرات البيئة، راجع وثائق نظام التشغيل الخاص بك.

authenticator := m2m.NewAuthenticator(
  os.Getenv("DATABRICKS_CLIENT_ID"),
  os.Getenv("DATABRICKS_CLIENT_SECRET"),
  os.Getenv("DATABRICKS_SERVER_HOSTNAME"),
)

connector, err := dbsql.NewConnector(
  dbsql.WithServerHostname(os.Getenv("DATABRICKS_SERVER_HOSTNAME")),
  dbsql.WithHTTPPath(os.Getenv("DATABRICKS_HTTP_PATH")),
  dbsql.WithPort(443),
  dbsql.WithAuthenticator(authenticator),
)

بيانات الاستعلام

يوضح مثال التعليمات البرمجية التالي كيفية استدعاء برنامج تشغيل Databricks SQL ل Go لتشغيل استعلام SQL أساسي على مورد حساب Azure Databricks. يقوم هذا الأمر بإرجاع أول صفين من trips الجدول في مخطط الكتالوج nyctaxi samples.

يسترد مثال التعليمات البرمجية هذا سلسلة الاتصال DSN من متغير بيئة يسمى DATABRICKS_DSN.

package main

import (
  "database/sql"
  "fmt"
  "os"
  "time"

  _ "github.com/databricks/databricks-sql-go"
)

func main() {
  dsn := os.Getenv("DATABRICKS_DSN")

  if dsn == "" {
    panic("No connection string found." +
          "Set the DATABRICKS_DSN environment variable, and try again.")
  }

  db, err := sql.Open("databricks", dsn)
  if err != nil {
    panic(err)
  }

  defer db.Close()

  var (
    tpep_pickup_datetime  time.Time
    tpep_dropoff_datetime time.Time
    trip_distance         float64
    fare_amount           float64
    pickup_zip            int
    dropoff_zip           int
  )

  rows, err := db.Query("SELECT * FROM samples.nyctaxi.trips LIMIT 2")
  if err != nil {
    panic(err)
  }

  defer rows.Close()

  fmt.Print("tpep_pickup_datetime,",
    "tpep_dropoff_datetime,",
    "trip_distance,",
    "fare_amount,",
    "pickup_zip,",
    "dropoff_zip\n")

  for rows.Next() {
    err := rows.Scan(&tpep_pickup_datetime,
      &tpep_dropoff_datetime,
      &trip_distance,
      &fare_amount,
      &pickup_zip,
      &dropoff_zip)
    if err != nil {
      panic(err)
    }

    fmt.Print(tpep_pickup_datetime, ",",
      tpep_dropoff_datetime, ",",
      trip_distance, ",",
      fare_amount, ",",
      pickup_zip, ",",
      dropoff_zip, "\n")
  }

  err = rows.Err()
  if err != nil {
    panic(err)
  }
}

إدارة الملفات في وحدات تخزين كتالوج Unity

يمكنك برنامج تشغيل Databricks SQL من كتابة الملفات المحلية إلى وحدات تخزين كتالوج Unity، وتنزيل الملفات من وحدات التخزين، وحذف الملفات من وحدات التخزين، كما هو موضح في المثال التالي:

package main

import (
  "context"
  "database/sql"
  "os"

  _ "github.com/databricks/databricks-sql-go"
  "github.com/databricks/databricks-sql-go/driverctx"
)

func main() {
  dsn := os.Getenv("DATABRICKS_DSN")

  if dsn == "" {
    panic("No connection string found." +
      "Set the DATABRICKS_DSN environment variable, and try again.")
  }

  db, err := sql.Open("databricks", dsn)
  if err != nil {
    panic(err)
  }
  defer db.Close()

  // For writing local files to volumes and downloading files from volumes,
  // you must first specify the path to the local folder that contains the
  // files to be written or downloaded.
  // For multiple folders, add their paths to the following string array.
  // For deleting files in volumes, this string array is ignored but must
  // still be provided, so in that case its value can be set for example
  // to an empty string.
  ctx := driverctx.NewContextWithStagingInfo(
    context.Background(),
    []string{"/tmp/"},
  )

  // Write a local file to the path in the specified volume.
  // Specify OVERWRITE to overwrite any existing file in that path.
  db.ExecContext(ctx, "PUT '/tmp/my-data.csv' INTO '/Volumes/main/default/my-volume/my-data.csv' OVERWRITE")

  // Download a file from the path in the specified volume.
  db.ExecContext(ctx, "GET '/Volumes/main/default/my-volume/my-data.csv' TO '/tmp/my-downloaded-data.csv'")

  // Delete a file from the path in the specified volume.
  db.ExecContext(ctx, "REMOVE '/Volumes/main/default/my-volume/my-data.csv'")

  db.Close()
}

تسجيل الدخول

استخدم github.com/databricks/databricks-sql-go/logger لتسجيل الرسائل التي يصدرها برنامج تشغيل Databricks SQL ل Go. يستخدم sql.Open() مثال التعليمات البرمجية التالي لإنشاء مقبض قاعدة بيانات من خلال سلسلة الاتصال DSN. يسترد مثال التعليمات البرمجية هذا سلسلة الاتصال DSN من متغير بيئة يسمى DATABRICKS_DSN. تتم كتابة جميع رسائل السجل التي يتم إرسالها على debug المستوى وما يلي إلى results.log الملف.

package main

import (
  "database/sql"
  "io"
  "log"
  "os"

  _ "github.com/databricks/databricks-sql-go"
  dbsqllog "github.com/databricks/databricks-sql-go/logger"
)

func main() {
  dsn := os.Getenv("DATABRICKS_DSN")

  // Use the specified file for logging messages to.
  file, err := os.Create("results.log")
  if err != nil {
    log.Fatal(err)
  }
  defer file.Close()

  writer := io.Writer(file)

  // Log messages at the debug level and below.
  if err := dbsqllog.SetLogLevel("debug"); err != nil {
    log.Fatal(err)
  }

  // Log messages to the file.
  dbsqllog.SetLogOutput(writer)

  if dsn == "" {
    panic("Error: Cannot connect. No connection string found. " +
      "Set the DATABRICKS_DSN environment variable, and try again.")
  }

  db, err := sql.Open("databricks", dsn)
  if err != nil {
    panic(err)
  }
  defer db.Close()

  if err := db.Ping(); err != nil {
    panic(err)
  }
}

الاختبار

لاختبار التعليمات البرمجية الخاصة بك، استخدم أطر عمل اختبار Go مثل مكتبة اختبار القياسية. لاختبار التعليمات البرمجية الخاصة بك في ظل ظروف محاكاة دون استدعاء نقاط نهاية Azure Databricks REST API أو تغيير حالة حسابات Azure Databricks أو مساحات العمل الخاصة بك، استخدم Go وهمية المكتبات مثل testfify.

على سبيل المثال، بالنظر إلى الملف التالي المسمى helpers.go الذي يحتوي على دالة GetDBWithDSNPAT ترجع اتصال مساحة عمل Azure Databricks، ودالة GetNYCTaxiTrips تقوم بإرجاع البيانات من trips الجدول في مخطط الكتالوج samples nyctaxi ، و PrintNYCTaxiTrips التي تطبع البيانات التي تم إرجاعها:

package main

import (
  "database/sql"
  "fmt"
  "strconv"
  "time"
)

func GetDBWithDSNPAT(dsn string) (*sql.DB, error) {
  db, err := sql.Open("databricks", dsn)
  if err != nil {
    return nil, err
  }
  return db, nil
}

func GetNYCTaxiTrips(db *sql.DB, numRows int) (*sql.Rows, error) {
  rows, err := db.Query("SELECT * FROM samples.nyctaxi.trips LIMIT " + strconv.Itoa(numRows))
  if err != nil {
    return nil, err
  }
  return rows, nil
}

func PrintNYCTaxiTrips(rows *sql.Rows) {
  var (
    tpep_pickup_datetime  time.Time
    tpep_dropoff_datetime time.Time
    trip_distance         float64
    fare_amount           float64
    pickup_zip            int
    dropoff_zip           int
  )

  fmt.Print(
    "tpep_pickup_datetime,",
    "tpep_dropoff_datetime,",
    "trip_distance,",
    "fare_amount,",
    "pickup_zip,",
    "dropoff_zip\n",
  )

  for rows.Next() {
    err := rows.Scan(
      &tpep_pickup_datetime,
      &tpep_dropoff_datetime,
      &trip_distance,
      &fare_amount,
      &pickup_zip,
      &dropoff_zip,
    )
    if err != nil {
      panic(err)
    }

    fmt.Print(
      tpep_pickup_datetime, ",",
      tpep_dropoff_datetime, ",",
      trip_distance, ",",
      fare_amount, ",",
      pickup_zip, ",",
      dropoff_zip, "\n",
    )
  }

  err := rows.Err()
  if err != nil {
    panic(err)
  }
}

وبالنظر إلى الملف التالي المسمى main.go الذي يستدعي هذه الدالات:

package main

import (
  "os"
)

func main() {
  db, err := GetDBWithDSNPAT(os.Getenv("DATABRICKS_DSN"))
  if err != nil {
    panic(err)
  }

  rows, err := GetNYCTaxiTrips(db, 2)
  if err != nil {
    panic(err)
  }

  PrintNYCTaxiTrips(rows)
}

يختبر الملف التالي المسمى helpers_test.go ما إذا كانت الدالة GetNYCTaxiTrips ترجع الاستجابة المتوقعة. بدلا من إنشاء اتصال حقيقي بمساحة العمل الهدف، يقوم هذا الاختبار بالسخرية من كائن sql.DB . كما يسخر الاختبار من بعض البيانات التي تتوافق مع المخطط والقيم الموجودة في البيانات الحقيقية. يقوم الاختبار بإرجاع البيانات المقلدة من خلال الاتصال الوهمي ثم يتحقق مما إذا كانت إحدى قيم صفوف البيانات المقلدة تطابق القيمة المتوقعة.

package main

import (
  "database/sql"
  "testing"

  "github.com/stretchr/testify/assert"
  "github.com/stretchr/testify/mock"
)

// Define an interface that contains a method with the same signature
// as the real GetNYCTaxiTrips function that you want to test.
type MockGetNYCTaxiTrips interface {
  GetNYCTaxiTrips(db *sql.DB, numRows int) (*sql.Rows, error)
}

// Define a struct that represents the receiver of the interface's method
// that you want to test.
type MockGetNYCTaxiTripsObj struct {
  mock.Mock
}

// Define the behavior of the interface's method that you want to test.
func (m *MockGetNYCTaxiTripsObj) GetNYCTaxiTrips(db *sql.DB, numRows int) (*sql.Rows, error) {
  args := m.Called(db, numRows)
  return args.Get(0).(*sql.Rows), args.Error(1)
}

func TestGetNYCTaxiTrips(t *testing.T) {
  // Instantiate the receiver.
  mockGetNYCTaxiTripsObj := new(MockGetNYCTaxiTripsObj)

  // Define how the mock function should be called and what it should return.
  // We're not concerned with whether the actual database is connected to--just
  // what is returned.
  mockGetNYCTaxiTripsObj.On("GetNYCTaxiTrips", mock.Anything, mock.AnythingOfType("int")).Return(&sql.Rows{}, nil)

  // Call the mock function that you want to test.
  rows, err := mockGetNYCTaxiTripsObj.GetNYCTaxiTrips(nil, 2)

  // Assert that the mock function was called as expected.
  mockGetNYCTaxiTripsObj.AssertExpectations(t)

  // Assert that the mock function returned what you expected.
  assert.NotNil(t, rows)
  assert.Nil(t, err)
}

نظرا لأن الدالة GetNYCTaxiTrips تحتوي على عبارة SELECT وبالتالي لا تغير حالة trips الجدول، فإن الاستنساخ غير مطلوب مطلقا في هذا المثال. ومع ذلك، يمكنك الاستنساخ من تشغيل الاختبارات بسرعة دون انتظار إجراء اتصال فعلي بمساحة العمل. كما يمكنك الاستنساخ من إجراء اختبارات محاكاة عدة مرات للوظائف التي قد تغير حالة الجدول، مثل INSERT INTOو UPDATEو DELETE FROM.

الموارد الإضافية

• مستودع Databricks SQL Driver for Go على GitHub
• الصفحة الرئيسية لحزمة قاعدة البيانات/sql
• أمثلة على برنامج تشغيل Databricks SQL ل Go على GitHub