開始
加載和管理數據
處理數據
政府
參考資料及資源
2023年4月19日更新
給我們反饋
的用於Python的Databricks SQL連接器是一個Python庫，允許您使用Python代碼在Databricks集群和Databricks SQL倉庫上運行SQL命令。用於Python的Databricks SQL連接器比類似的Python庫(如pyodbc．這個庫如下Python數據庫API規範v2.0．
運行Python >=3.7和<=3.11的開發機器。
現有的集群或SQL倉庫．
為要使用的集群或SQL倉庫收集以下信息:
集群的服務器主機名。你可以從服務器主機名的值高級選項> JDBC/ODBC選項卡。
集群的HTTP路徑。你可以從HTTP路徑的值高級選項> JDBC/ODBC選項卡。
一個磚個人訪問令牌用於工作空間。
請注意
作為安全最佳實踐，您不應該將此信息硬編碼到代碼中。相反，您應該從安全位置檢索此信息。例如，本文後麵的代碼示例使用環境變量。
SQL倉庫的服務器主機名。你可以從服務器主機名的值連接細節選項卡用於SQL倉庫。
SQL倉庫的HTTP路徑。你可以從HTTP路徑的值連接細節選項卡用於SQL倉庫。
在您的開發機器上運行Databricks SQL Connector for Python庫皮普安裝databricks-sql-connector．
皮普安裝databricks-sql-connector
下麵的代碼示例演示了如何使用Databricks SQL Connector for Python查詢和插入數據、查詢元數據、管理遊標和連接，以及配置日誌。
這些代碼示例檢索它們server_hostname，http_path,access_token來自這些環境變量的連接變量值:
server_hostname
http_path
access_token
DATABRICKS_SERVER_HOSTNAME，代表服務器主機名來自需求的價值。
DATABRICKS_SERVER_HOSTNAME
DATABRICKS_HTTP_PATH，代表HTTP路徑來自需求的價值。
DATABRICKS_HTTP_PATH
DATABRICKS_TOKEN，它表示來自需求的訪問令牌。
DATABRICKS_TOKEN
您可以使用其他方法來檢索這些連接變量值。使用環境變量隻是眾多方法中的一種。
查詢數據
插入數據
查詢元數據
管理遊標和連接
配置日誌記錄
下麵的代碼示例演示了如何調用Databricks SQL Connector for Python來在集群或SQL倉庫上運行基本的SQL命令。的前兩行鑽石表格
鑽石
的鑽石表格包含在樣本數據集．這張桌子也有特色教程:用筆記本查詢數據．
從磚進口sql進口操作係統與sql．連接（server_hostname=操作係統．采用（“DATABRICKS_SERVER_HOSTNAME”)，http_path=操作係統．采用（“DATABRICKS_HTTP_PATH”)，access_token=操作係統．采用（“DATABRICKS_TOKEN”））作為連接：與連接．光標（）作為光標：光標．執行（"選擇*從默認。鑽石限2"）結果=光標．fetchall（）為行在結果：打印（行）
下麵的例子演示了如何插入少量數據(數千行):
從磚進口sql進口操作係統與sql．連接（server_hostname=操作係統．采用（“DATABRICKS_SERVER_HOSTNAME”)，http_path=操作係統．采用（“DATABRICKS_HTTP_PATH”)，access_token=操作係統．采用（“DATABRICKS_TOKEN”））作為連接：與連接．光標（）作為光標：光標．執行（"創建表如果不存在(x int, x_squared int)"）廣場=((我，我*我）為我在範圍（One hundred.)]值="，"．加入([f"（{x}，{y})”為（x，y）在廣場]）光標．執行（f"插入方框值{值}”）光標．執行（"SELECT * FROM squares LIMIT 10"）結果=光標．fetchall（）為行在結果：打印（行）
對於大量數據，應先將數據上傳到雲存儲，然後再執行複製到命令。
有用於檢索元數據的專用方法。下麵的示例檢索關於樣例表中列的元數據:
從磚進口sql進口操作係統與sql．連接（server_hostname=操作係統．采用（“DATABRICKS_SERVER_HOSTNAME”)，http_path=操作係統．采用（“DATABRICKS_HTTP_PATH”)，access_token=操作係統．采用（“DATABRICKS_TOKEN”））作為連接：與連接．光標（）作為光標：光標．列（schema_name=“默認”，table_name=“廣場”）打印（光標．fetchall（））
最好的做法是關閉所有已完成的連接和遊標。這將釋放Databricks集群上的資源。
您可以使用上下文管理器與的語法)來管理資源，或顯式調用關閉：
與
關閉
從磚進口sql進口操作係統連接=sql．連接（server_hostname=操作係統．采用（“DATABRICKS_SERVER_HOSTNAME”)，http_path=操作係統．采用（“DATABRICKS_HTTP_PATH”)，access_token=操作係統．采用（“DATABRICKS_TOKEN”））光標=連接．光標（）光標．執行（“SELECT * from range(10)”）打印（光標．fetchall（））光標．關閉（）連接．關閉（）
Databricks 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 range(10)”）結果=光標．fetchall（）為行在結果：日誌記錄．調試（行）光標．關閉（）連接．關閉（）
包
模塊
方法
連接方法
連接
類
連接類
關閉方法
光標方法
光標
光標類
屬性
arraysize屬性
arraysize
描述屬性
描述
取消方法
取消
執行方法
執行
executemany方法
executemany
目錄方法
目錄
模式方法
模式
表方法
表
列方法
列
fetchall方法
fetchall
fetchmany方法
fetchmany
fetchone方法
fetchone
fetchall_arrow方法
fetchall_arrow
fetchmany_arrow方法
fetchmany_arrow
行類
行
asDict方法
asDict
類型轉換
databricks-sql-connector
用法:皮普安裝databricks-sql-connector
另請參閱databricks-sql-connectorPython包索引(PyPI)。
databricks.sql
用法:從磚進口sql
從磚進口sql
創建到數據庫的連接。
返回一個連接對象。
參數
類型:str
str
集群的服務器主機名。要獲取服務器主機名，請參閱本文前麵的說明。
必選參數。
例子:1234567890123456.7.gcp.www.eheci.com
1234567890123456.7.gcp.www.eheci.com
集群的HTTP路徑。要獲取HTTP路徑，請參閱本文前麵的說明。
例子:sql / protocolv1 / o / 1234567890123456/1234 - 567890 test123
sql / protocolv1 / o / 1234567890123456/1234 - 567890 test123
您的Databricks個人訪問令牌，用於集群的工作空間。要創建令牌，請參見本文前麵的說明。
例子:dapi…< the-remaining-portion-of-your-token >
dapi…< the-remaining-portion-of-your-token >
session_configuration
類型:dict [str,任何)
dict [str,任何)
Spark會話配置參數字典。設置配置相當於使用集關鍵=瓦爾SQL命令。運行SQL命令集- v獲取可用配置的完整列表。
集關鍵=瓦爾
集- v
默認為沒有一個．
沒有一個
可選參數。
例子:{“spark.sql.variable.substitute”:真正的}
{“spark.sql.variable.substitute”:真正的}
http_headers
類型:列表(元組(str,str]]]
列表(元組(str,str]]]
在客戶端發出的每個RPC請求的HTTP標頭中設置額外的(鍵、值)對。典型的用法不會設置任何額外的HTTP頭。默認為沒有一個．
從2.0版本開始
用於連接的初始編目。默認為沒有一個(在這種情況下，通常是默認目錄hive_metastore將被使用)。
hive_metastore
用於連接的初始模式。默認為沒有一個(在這種情況下，默認模式默認的將被使用)。
默認的
表示到數據庫的連接。
關閉與數據庫的連接，並釋放服務器上的所有相關資源。對此連接的任何其他調用都將拋出錯誤．
錯誤
沒有參數。
沒有返回值。
返回一種機製，該機製允許遍曆數據庫中的記錄。
返回一個光標對象。
與the連用fetchmany方法指定內部緩衝區大小，這也是一次實際從服務器獲取的行數。默認值為10000．對於窄結果(每行不包含大量數據的結果)，您應該增加此值以獲得更好的性能。
10000
讀寫訪問。
包含一個Python列表的元組對象。每一個元組對象包含7個值，每個值的前2項元組對象，其中包含描述單個結果列的信息，如下所示:
列表
元組
名字:列的名稱。
名字
type_code:表示列類型的字符串。例如，整數列的類型代碼為int．
type_code
int
每7項剩下的5項元組對象沒有被實現，它們的值也沒有被定義。它們通常返回為4沒有一個值後跟一個真正的價值。
真正的
隻讀訪問。
中斷遊標已啟動的任何數據庫查詢或命令的運行。方法釋放服務器上的關聯資源關閉方法調用取消方法。
關閉遊標並釋放服務器上的相關資源。關閉已關閉的遊標可能會拋出錯誤。
準備並運行數據庫查詢或命令。
操作
準備然後運行的查詢或命令。
沒有的例子參數參數:
光標．執行（SELECT * FROM default。鑽石在哪裏切割=”Ideal" LIMIT 2'）
的例子參數參數:
光標．執行（SELECT * FROM default。鑽石在哪裏切割=% (cut_type)限製2》，{“cut_type”：“理想”}）
類型:字典
的參數序列操作參數。
可選參數。默認值為沒有一個．
方法中的所有參數序列準備並運行數據庫查詢或命令seq_of_parameters論點。隻保留最終結果集。
seq_of_parameters
類型:列表的dict
dict
控件中使用的多組參數值的序列操作參數。
執行關於目錄的元數據查詢。實際結果應該使用fetchmany或fetchall．結果集中的重要字段包括:
字段名:TABLE_CAT．類型:str．目錄的名稱。
TABLE_CAT
從1.0版本開始
執行關於模式的元數據查詢。實際結果應該使用fetchmany或fetchall．結果集中的重要字段包括:
字段名:TABLE_SCHEM．類型:str．模式的名稱。
TABLE_SCHEM
字段名:TABLE_CATALOG．類型:str．模式所屬的目錄。
TABLE_CATALOG
catalog_name
要檢索有關信息的目錄名稱。的％字符被解釋為通配符。
％
schema_name
要檢索有關信息的架構名稱。的％字符被解釋為通配符。
執行關於表和視圖的元數據查詢。實際結果應該使用fetchmany或fetchall．結果集中的重要字段包括:
字段名:TABLE_CAT．類型:str．表所屬的目錄。
字段名:TABLE_SCHEM．類型:str．表所屬的模式。
字段名:TABLE_NAME．類型:str．表的名稱。
TABLE_NAME
字段名:TABLE_TYPE．類型:str．比如這種關係視圖或表格(適用於Databricks Runtime 10.2及以上版本;以前版本的Databricks運行時返回一個空字符串)。
TABLE_TYPE
視圖
表格
table_name
要檢索有關信息的表名。的％字符被解釋為通配符。
table_types
類型:列表(str)
列表(str)
例如，要匹配的表類型列表表格或視圖．
執行關於列的元數據查詢。實際結果應該使用fetchmany或fetchall．結果集中的重要字段包括:
字段名:TABLE_CAT．類型:str．列所屬的目錄。
字段名:TABLE_SCHEM．類型:str．列所屬的模式。
字段名:TABLE_NAME．類型:str．該列所屬的表的名稱。
字段名:COLUMN_NAME．類型:str．列的名稱。
COLUMN_NAME
column_name
要檢索有關信息的列名。的％字符被解釋為通配符。
獲取查詢的所有(或所有剩餘)行。
返回查詢的所有(或所有剩餘)行作為Python列表的行對象。
拋出一個錯誤如果之前調用到執行方法未返回任何數據或沒有執行尚未作出決定。
獲取查詢的下一行。
返回到大小(或arraysize如果屬性大小未指定)查詢的下一行作為Python列表的行對象。如果小於大小剩下的行將被獲取，所有剩下的行將被返回。
大小
類型:int
接下來要得到的行數。
可選參數。的值arraysize屬性。
例子:cursor.fetchmany (10)
cursor.fetchmany (10)
獲取數據集的下一行。
將數據集的下一行作為單個序列作為Python返回元組對象，否則返回沒有一個如果沒有更多可用的數據。
獲取查詢的所有(或所有剩餘)行，如PyArrow表格對象。返回大量數據的查詢應該使用fetchmany_arrow而是減少內存消耗。
將查詢的所有(或所有剩餘)行返回為PyArrow表。
獲取查詢的下一行作為PyArrow表格對象。
返回到大小參數(或arraysize如果屬性大小未指定)查詢的下一行作為Python PyArrow表格對象。
例子:cursor.fetchmany_arrow (10)
cursor.fetchmany_arrow (10)
row類是一個類似元組的數據結構，表示單個結果行。如果該行包含具有名稱的列“my_column”，您可以訪問“my_column”領域的行通過row.my_column．例如，您還可以使用數字索引來訪問字段行[0]．如果不允許列名作為屬性方法名(例如，以數字開頭)，則可以以行(“1 _my_column”)．
“my_column”
row.my_column
行[0]
行(“1 _my_column”)
返回按字段名索引的行的字典表示形式。如果有重複的字段名，將在字典中返回其中一個重複字段(但隻有一個)。沒有定義返回哪個重複字段。
返回一個dict的字段。
下表將Apache Spark SQL數據類型映射為對應的Python數據類型。
Apache Spark SQL數據類型
Python數據類型
數組
numpy.ndarray
長整型數字
二進製
中bytearray
布爾
保齡球
日期
datetime.date
小數
小數。小數
雙
浮動
地圖
零
NoneType
短整型
字符串
結構體
時間戳
datetime.datetime
非常小的整數
tokenAuthWrapperInvalidAccessToken:無效的訪問令牌
問題:當您運行代碼時，您會看到類似於的消息錯誤在請求來服務器:tokenAuthWrapperInvalidAccessToken:無效的訪問令牌．
錯誤在請求來服務器:tokenAuthWrapperInvalidAccessToken:無效的訪問令牌
可能的原因:傳遞給的值access_token不是有效的Databricks個人訪問令牌。
建議修複:檢查傳遞給的值access_token是正確的，再試一次。
gaierror (8,的節點名也不servname提供,或不知道”)
問題:當您運行代碼時，您會看到類似於的消息錯誤在請求來服務器:gaierror (8,的節點名也不servname提供,或不知道”)．
錯誤在請求來服務器:gaierror (8,的節點名也不servname提供,或不知道”)
可能的原因:傳遞給的值server_hostname不是正確的主機名。
建議修複:檢查傳遞給的值server_hostname是正確的，再試一次。
有關查找服務器主機名的更多信息，請參見檢索連接詳細信息．
IpAclError
問題當你運行你的代碼時，你會看到這個消息錯誤在請求來服務器:IpAclValidation當您嚐試在Databricks筆記本上使用連接器時。
錯誤在請求來服務器:IpAclValidation
可能的原因:您可以為Databricks工作區啟用IP允許列表。在IP allow列表中，默認不允許Spark集群連接回控製平麵。
建議修複:請聯係管理員將數據平麵子網添加到允許IP列表中。
有關更多信息，請參見:
的用於Python的Databricks SQL連接器GitHub上的存儲庫
數據類型
內置類型(保齡球，中bytearray，浮動，int,str)在Python網站上
datetime(datetime.date和datatime.datetime)在Python網站上
datatime.datetime
小數(小數。小數)在Python網站上
內置的常量(NoneType)在Python網站上