Python的磚SQL的連接器

的Python的磚SQL的連接器是一個Python庫,它允許您使用Python代碼上運行SQL命令磚集群和磚SQL的倉庫。Python的磚SQL的連接器是比類似的Python庫更容易設置和使用等pyodbc。這個庫是PEP 249 - Python數據庫API規範v2.0。

需求

  • 開發機器運行Python > = 3.7和< = 3.11。

  • 現有的集群或SQL倉庫。

開始

  • 為集群或SQL收集以下信息倉庫,您想要使用:

    請注意

    作為一個安全最佳實踐,您不應該硬編碼這些信息到你的代碼。相反,你應該檢索這些信息從一個安全的位置。例如,在本文後麵的代碼示例使用環境變量。

    • SQL服務器主機名的倉庫。你可以得到這個的服務器主機名的價值連接細節為你的SQL選項卡倉庫。

    • SQL的HTTP路徑倉庫。你可以得到這個的HTTP路徑的價值連接細節為你的SQL選項卡倉庫。

    • 一個磚個人訪問令牌的工作空間。

    請注意

    作為一個安全最佳實踐,您不應該硬編碼這些信息到你的代碼。相反,你應該檢索這些信息從一個安全的位置。例如,在本文後麵的代碼示例使用環境變量。

  • 安裝Python庫的磚SQL連接器的開發機器上運行皮普安裝databricks-sql-connector。

例子

下麵的代碼示例演示如何使用Python的磚SQL連接器的查詢和插入數據,查詢元數據,管理遊標和連接,並配置日誌記錄。

這些代碼示例檢索它們server_hostname,http_path,access_token從這些環境變量連接變量值:

  • DATABRICKS_SERVER_HOSTNAME,代表了服務器主機名價值的需求。

  • DATABRICKS_HTTP_PATH,代表了HTTP路徑價值的需求。

  • DATABRICKS_TOKEN代表您的訪問令牌的需求。

您可以使用其他方法來檢索這些連接變量值。使用環境變量隻是眾多方法之一。

查詢數據

下麵的代碼示例演示了如何調用Python的磚SQL的連接器在集群上運行一個基本的SQL命令或SQL倉庫。這個命令返回的前兩行鑽石表。

的鑽石表是包含在樣本數據集。這個表也在與筆記本電腦教程:查詢數據。

從磚進口sql進口操作係統與sql。連接(server_hostname=操作係統。采用(“DATABRICKS_SERVER_HOSTNAME”),http_path=操作係統。采用(“DATABRICKS_HTTP_PATH”),access_token=操作係統。采用(“DATABRICKS_TOKEN”))作為連接:與連接。光標()作為光標:光標。執行(“SELECT *從違約。鑽石限製2”)結果=光標。fetchall()為行在結果:打印(行)

插入數據

下麵的示例演示如何插入少量的數據(成千上萬行):

從磚進口sql進口操作係統與sql。連接(server_hostname=操作係統。采用(“DATABRICKS_SERVER_HOSTNAME”),http_path=操作係統。采用(“DATABRICKS_HTTP_PATH”),access_token=操作係統。采用(“DATABRICKS_TOKEN”))作為連接:與連接。光標()作為光標:光標。執行(如果不存在“創建表廣場(x int, int x_squared)”)廣場=((我,我*我)為我在範圍(One hundred.)]值=”、“。加入([f”({x},{y})”為(x,y)在廣場])光標。執行(f“插入平方值{值}”)光標。執行(“SELECT * FROM廣場限製10”)結果=光標。fetchall()為行在結果:打印(行)

對於大量數據,您應該首先將數據上傳到雲存儲,然後執行複製到命令。

查詢元數據

有專用的方法檢索元數據。下麵的示例檢索元數據列在一個示例表:

從磚進口sql進口操作係統與sql。連接(server_hostname=操作係統。采用(“DATABRICKS_SERVER_HOSTNAME”),http_path=操作係統。采用(“DATABRICKS_HTTP_PATH”),access_token=操作係統。采用(“DATABRICKS_TOKEN”))作為連接:與連接。光標()作為光標:光標。列(schema_name=“默認”,table_name=“廣場”)打印(光標。fetchall())

管理遊標和連接

最佳實踐是關閉所有連接和遊標已經完成。這使集群資源數據磚和磚SQL倉庫。

您可以使用一個上下文管理器(與語法中使用以前的例子)來管理資源,或者顯式地調用關閉:

從磚進口sql進口操作係統連接=sql。連接(server_hostname=操作係統。采用(“DATABRICKS_SERVER_HOSTNAME”),http_path=操作係統。采用(“DATABRICKS_HTTP_PATH”),access_token=操作係統。采用(“DATABRICKS_TOKEN”))光標=連接。光標()光標。執行(“SELECT * from範圍(10)”)打印(光標。fetchall())光標。關閉()連接。關閉()

配置日誌記錄

磚的SQL連接器使用Python的標準的日誌模塊。您可以配置日誌級別類似如下:

從磚進口sql進口操作係統,日誌記錄日誌記錄。getlog(“databricks.sql”)。setLevel(日誌記錄。調試)日誌記錄。basicConfig(文件名=“results.log”,水平=日誌記錄。調試)連接=sql。連接(server_hostname=操作係統。采用(“DATABRICKS_SERVER_HOSTNAME”),http_path=操作係統。采用(“DATABRICKS_HTTP_PATH”),access_token=操作係統。采用(“DATABRICKS_TOKEN”))光標=連接。光標()光標。執行(“SELECT * from範圍(10)”)結果=光標。fetchall()為行在結果:日誌記錄。調試(行)光標。關閉()連接。關閉()

API參考

包

databricks-sql-connector

用法:皮普安裝databricks-sql-connector

另請參閱databricks-sql-connector在Python包指數(PyPI)。

模塊

databricks.sql

用法:從磚進口sql

方法

連接方法

創建一個連接到一個數據庫。

返回一個連接對象。

參數

server_hostname

類型:str

集群的服務器主機名或SQL倉庫。服務器主機名,見本文前麵的指令。

這個參數是必需的。

例子:dbc-a1b2345c-d6e7.cloud.m.eheci.com

http_path

類型:str

集群的HTTP路徑或SQL倉庫。HTTP路徑,本文前麵看到的指令。

這個參數是必需的。

例子:sql / protocolv1 / o / 1234567890123456/1234 - 567890 test123一個集群。/ sql / 1.0 /倉庫/ a1b234c567d8e9fa對於SQL倉庫。

access_token

類型:str

你的磚個人工作空間的訪問令牌集群或SQL倉庫。要創建一個令牌,見本文前麵的指令。

這個參數是必需的。

例子:dapi…< the-remaining-portion-of-your-token >

session_configuration

類型:dict [str,任何)

字典的火花會話配置參數。設置一個配置相當於使用集關鍵=瓦爾SQL命令。運行SQL命令集- v可用配置的完整列表。

默認為沒有一個。

這個參數是可選的。

例子:{“spark.sql.variable.substitute”:真正的}

http_headers

類型:列表(元組(str,str]]]

附加的(關鍵字,值)對設置HTTP頭在每個RPC請求客戶機。典型用法不會設置任何額外的HTTP標頭。默認為沒有一個。

這個參數是可選的。

自2.0版

目錄

類型:str

數據庫連接使用。默認為沒有一個(在這種情況下,默認目錄,通常hive_metastore將使用)。

這個參數是可選的。

自2.0版

模式

類型:str

初始模式用於連接。默認為沒有一個(在這種情況下,默認模式默認的將使用)。

這個參數是可選的。

自2.0版

類

連接類

代表一個連接到一個數據庫。

方法
關閉方法

關閉數據庫連接和釋放所有相關的資源在服務器上。任何額外的調用這個連接將拋出錯誤。

沒有參數。

沒有返回值。

光標方法

返回一個機製,允許在遍曆記錄在數據庫中。

沒有參數。

返回一個光標對象。

光標類

屬性
arraysize屬性

使用的fetchmany方法,指定內部緩衝區大小,也多少行實際上是一次從服務器獲取。默認值是10000年。狹窄的結果(結果的每一行不包含大量的數據),你應該增加這個值獲得更好的性能。

讀寫訪問。

描述屬性

包含一個Python列表的元組對象。每一個元組對象包含7個值,與前兩項元組對象包含信息描述一個結果列如下:

  • 的名字:列的名稱。

  • type_code:一個字符串代表列的類型。例如,一個整數列類型的代碼int。

剩下的每個7-item的5項元組對象都沒有實現,他們的值沒有定義。他們通常會被返回為4沒有一個緊隨其後的是一個值真正的價值。

隻讀訪問。

方法
取消方法

中斷正在運行的任何數據庫查詢或命令的光標已經開始。發布服務器上的相關資源,調用關閉方法調用後取消方法。

沒有參數。

沒有返回值。

關閉方法

關閉遊標和釋放相關資源在服務器上。關閉一個已經關閉遊標可能會拋出一個錯誤。

沒有參數。

沒有返回值。

執行方法

準備,然後運行一個數據庫查詢或命令。

沒有返回值。

參數

操作

類型:str

查詢或命令,然後運行做準備。

這個參數是必需的。

沒有例子參數參數:

光標。執行(“從默認選擇*。鑽石切割=”Ideal" LIMIT 2')

的例子參數參數:

光標。執行(“從默認選擇*。鑽石切割=% (cut_type)限製2》,{“cut_type”:“理想”})

參數

類型:字典

一係列的參數來使用操作參數。

這個參數是可選的。默認值是沒有一個。
executemany方法

準備,然後運行一個數據庫查詢或命令使用中的所有參數序列seq_of_parameters論點。隻保留最終的結果集。

沒有返回值。

參數

操作

類型:str

查詢或命令,然後運行做準備。

這個參數是必需的。

seq_of_parameters

類型:列表的dict

許多序列集的參數值來使用操作參數。

這個參數是必需的。
目錄方法

執行一個元數據查詢的目錄。實際結果然後應該拿來使用fetchmany或fetchall。重要的結果集字段包括:

  • 字段名:TABLE_CAT。類型:str。目錄的名稱。

沒有參數。

沒有返回值。

自1.0版

模式方法

執行一個元數據查詢模式。實際結果然後應該拿來使用fetchmany或fetchall。重要的結果集字段包括:

  • 字段名:TABLE_SCHEM。類型:str。模式的名稱。

  • 字段名:TABLE_CATALOG。類型:str。目錄模式所屬。

沒有返回值。

自1.0版

參數

catalog_name

類型:str

目錄名稱來檢索信息。的%性格是解釋為一個通配符。

這個參數是可選的。

schema_name

類型:str

一個模式名稱來檢索信息。的%性格是解釋為一個通配符。

這個參數是可選的。
表方法

執行一個查詢元數據表和視圖。實際結果然後應該拿來使用fetchmany或fetchall。重要的結果集字段包括:

  • 字段名:TABLE_CAT。類型:str。目錄表所屬。

  • 字段名:TABLE_SCHEM。類型:str。表所屬的模式。

  • 字段名:TABLE_NAME。類型:str。表的名稱。

  • 字段名:TABLE_TYPE。類型:str。例如,什麼樣的關係視圖或表(適用於磚運行時10.2及以上以及磚SQL;之前版本的磚運行時返回一個空字符串)。

沒有返回值。

自1.0版

參數

catalog_name

類型:str

目錄名稱來檢索信息。的%性格是解釋為一個通配符。

這個參數是可選的。

schema_name

類型:str

一個模式名稱來檢索信息。的%性格是解釋為一個通配符。

這個參數是可選的。

table_name

類型:str

表的名稱來檢索信息。的%性格是解釋為一個通配符。

這個參數是可選的。

table_types

類型:列表(str)

表類型匹配的列表,例如表或視圖。

這個參數是可選的。
列方法

執行一個元數據查詢的列。實際結果然後應該拿來使用fetchmany或fetchall。重要的結果集字段包括:

  • 字段名:TABLE_CAT。類型:str。目錄列所屬。

  • 字段名:TABLE_SCHEM。類型:str。列所屬的模式。

  • 字段名:TABLE_NAME。類型:str。該列所屬的表的名稱。

  • 字段名:COLUMN_NAME。類型:str。列的名稱。

沒有返回值。

自1.0版

參數

catalog_name

類型:str

目錄名稱來檢索信息。的%性格是解釋為一個通配符。

這個參數是可選的。

schema_name

類型:str

一個模式名稱來檢索信息。的%性格是解釋為一個通配符。

這個參數是可選的。

table_name

類型:str

表的名稱來檢索信息。的%性格是解釋為一個通配符。

這個參數是可選的。

column_name

類型:str

列的名稱來檢索信息。的%性格是解釋為一個通配符。

這個參數是可選的。
fetchall方法

得到所有(或所有剩餘)行查詢。

沒有參數。

返回查詢的所有(或所有剩餘)行Python列表的行對象。

拋出一個錯誤如果前一個調用執行方法沒有返回任何數據執行電話還沒有。

fetchmany方法

被查詢的下一行。

返回到大小(或arraysize如果屬性大小沒有指定)的下一行作為一個Python查詢列表的行對象。如果有不足大小行左取出,將返回所有剩餘的行。

拋出一個錯誤如果前一個調用執行方法沒有返回任何數據執行電話還沒有。

參數

大小

類型:int

下一行的數量。

這個參數是可選的。如果沒有指定,的值arraysize使用屬性。

例子:cursor.fetchmany (10)
fetchone方法

數據集的下一行。

沒有參數。

返回數據集的下一行作為一個序列作為一個Python元組對象,或返回沒有一個如果沒有更多的可用數據。

拋出一個錯誤如果前一個調用執行方法沒有返回任何數據執行電話還沒有。

fetchall_arrow方法

被查詢的所有(或所有剩餘)行,PyArrow表對象。查詢返回非常大量的數據應該使用fetchmany_arrow而不是減少內存消耗。

沒有參數。

返回所有(或所有剩餘)行PyArrow表的查詢。

拋出一個錯誤如果前一個調用執行方法沒有返回任何數據執行電話還沒有。

自2.0版

fetchmany_arrow方法

被作為PyArrow查詢的下一行表對象。

返回到大小論點(或arraysize如果屬性大小沒有指定)的下一行作為一個Python PyArrow查詢表對象。

拋出一個錯誤如果前一個調用執行方法沒有返回任何數據執行電話還沒有。

自2.0版

參數

大小

類型:int

下一行的數量。

這個參數是可選的。如果沒有指定,的值arraysize使用屬性。

例子:cursor.fetchmany_arrow (10)

行類

行類是一個tuple-like數據結構,代表一個單獨的結果行。如果行包含一個列的名稱“my_column”,你可以訪問“my_column”領域的行通過row.my_column。您還可以使用數字indicies訪問字段,例如行[0]。如果列作為屬性名稱是不允許方法名稱(例如,它始於一個數字),然後你可以訪問字段行(“1 _my_column”)。

自1.0版

方法
asDict方法

返回的字典表示一行,這是索引字段名稱。如果有重複的字段名稱,一個重複的字段(但隻有一個)將返回的字典。這重複的字段是沒有定義返回。

沒有參數。

返回一個dict的字段。

類型轉換

下表將Apache火花SQL數據類型映射到他們的Python數據類型的等價物。

Apache火花SQL數據類型

Python數據類型

數組

numpy.ndarray

長整型數字

int

二進製

中bytearray

布爾

bool

日期

datetime.date

小數

decimal.Decimal

雙

浮動

int

int

地圖

str

零

NoneType

短整型

int

字符串

str

結構體

str

時間戳

datetime.datetime

非常小的整數

int

故障排除

tokenAuthWrapperInvalidAccessToken:無效的訪問令牌消息

問題:當您運行您的代碼,您將看到一條消息類似錯誤在請求來服務器:tokenAuthWrapperInvalidAccessToken:無效的訪問令牌。

可能的原因:價值傳遞access_token不是一個有效的磚個人訪問令牌。

建議修複:檢查值傳遞給access_token是正確的,再試一次。

gaierror (8,的節點名也不servname提供,或不知道”)消息

問題:當您運行您的代碼,您將看到一條消息類似錯誤在請求來服務器:gaierror (8,的節點名也不servname提供,或不知道”)。

可能的原因:價值傳遞server_hostname不是正確的主機名。

建議修複:檢查值傳遞給server_hostname是正確的,再試一次。

尋找服務器主機名的更多信息,見檢索連接細節。

IpAclError消息

問題:當您運行您的代碼,您會看到信息錯誤在請求來服務器:IpAclValidation當你嚐試使用磚筆記本連接器。

可能的原因:你可能IP允許清單為磚啟用工作區。與IP允許清單,從火花集群連接回控製飛機在默認情況下是不允許的。

建議修複:要求管理員添加數據平麵子網IP允許列表。

額外的資源

有關更多信息,請參見: