开始
加载和管理数据
处理数据
政府
参考和资源
2023年1月19日更新
给我们反馈
的Databricks SQL连接器for Python是一个Python库，允许您使用Python代码在Databricks集群和Databricks SQL仓库上运行SQL命令。Databricks SQL Connector for Python比类似的Python库更容易设置和使用pyodbc．下面是这个库Python数据库API规范v2.0．
运行Python >=3.7和<=3.11的开发机器。
现有的集群或SQL仓库．
收集您想要使用的集群或SQL仓库的以下信息:
集群的服务器主机名。你可以从服务器主机名的价值高级选项> JDBC/ODBCTAB为您的集群。
集群的HTTP路径。你可以从HTTP路径的价值高级选项> JDBC/ODBCTAB为您的集群。
一个砖个人访问令牌对于工作空间。
请注意
作为安全最佳实践，您不应该将此信息硬编码到代码中。相反，您应该从安全的位置检索此信息。例如，本文后面的代码示例使用环境变量。
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连接器for Python在集群或SQL仓库上运行基本SQL命令。的前两行钻石表格
钻石
的钻石表包含在样本数据集．这张表也是在教程:使用笔记本查询数据．
从砖进口sql进口操作系统与sql．连接（server_hostname＝操作系统．采用（“DATABRICKS_SERVER_HOSTNAME”)，http_path＝操作系统．采用（“DATABRICKS_HTTP_PATH”)，access_token＝操作系统．采用（“DATABRICKS_TOKEN”）)作为连接：与连接．光标（）作为光标：光标．执行（“SELECT * FROM default.”钻石限量2"）结果＝光标．fetchall（）为行在结果：打印（行）
下面的例子演示了如何插入少量数据(数千行):
从砖进口sql进口操作系统与sql．连接（server_hostname＝操作系统．采用（“DATABRICKS_SERVER_HOSTNAME”)，http_path＝操作系统．采用（“DATABRICKS_HTTP_PATH”)，access_token＝操作系统．采用（“DATABRICKS_TOKEN”）)作为连接：与连接．光标（）作为光标：光标．执行（“CREATE TABLE IF NOT EXISTS squares (x int, x_squared int)”）广场＝((我，我＊我）为我在范围（One hundred.）]值＝”、“．加入（[f"（｛x｝，｛y｝)”为（x，y）在广场]）光标．执行（f“INSERT INTO squares VALUES”｛值｝＂）光标．执行（“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集群和Databricks SQL仓库上的资源。
您可以使用上下文管理器与前面示例中使用的语法)来管理资源，或显式调用关闭：
与
关闭
从砖进口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
集群或SQL仓库的服务器主机名。要获得服务器主机名，请参阅本文前面的说明。
必选参数。
例子:dbc-a1b2345c-d6e7.cloud.www.neidfyre.com
dbc-a1b2345c-d6e7.cloud.www.neidfyre.com
集群或SQL仓库的HTTP路径。要获得HTTP路径，请参阅本文前面的说明。
例子:sql / protocolv1 / o / 1234567890123456/1234 - 567890 test123对于集群。/ sql / 1.0 /仓库/ a1b234c567d8e9faSQL仓库。
sql / protocolv1 / o / 1234567890123456/1234 - 567890 test123
/ sql / 1.0 /仓库/ a1b234c567d8e9fa
您的Databricks个人访问令牌用于集群或SQL仓库的工作空间。要创建令牌，请参阅本文前面的说明。
例子: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 SQL;以前版本的Databricks Runtime返回空字符串)。
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)
行类是一种类似元组的数据结构，表示单个结果行。如果该行包含具有此名称的列“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允许列表中。
有关更多信息，请参见:
的Databricks SQL连接器for PythonGitHub上的存储库
数据类型
内置类型(保龄球，中bytearray，浮动，int,str)
datetime(datetime.date而且datatime.datetime)
datatime.datetime
小数(小数。小数)
内置的常量(NoneType)