适用于 Python 的 Databricks SQL 连接器

重要

此库采用 公共预览

用于 python 的 Databricks SQL 连接器是一个 python 库,允许使用 python 代码在 Azure Databricks 群集和 Databricks SQL 终结点上运行 SQL 命令。 相比类似的 Python 库(如 pyodbc),适用于 Python 的 Databricks SQL 连接器更易于设置和使用。 此库遵循 PEP 249 – Python 数据库 API 规范 v2.0

要求

开始使用

  • 收集想要使用的群集或 SQL 终结点的以下信息:

    群集

    Sql 端点

    • SQL 终结点的服务器主机名。 从 SQL 终结点的“连接详细信息”选项卡的“服务器主机名”值中可以获取此主机名。
    • SQL 终结点的 HTTP 路径。 从 SQL 终结点的“连接详细信息”选项卡的“HTTP 路径”值中可以获取此路径。
    • Azure Databricks 个人访问令牌。 Azure Databricks 个人访问令牌通常以 dapi 开头。
  • 通过运行 pip install databricks-sql-connector,在开发计算机上安装适用于 Python 的 Databricks SQL 连接器库。

示例

以下代码示例演示如何调用适用于 Python 的 Databricks SQL 连接器在群集或 SQL 终结点上运行基本 SQL 命令。 此命令返回指定数据库表中的前两行。 该代码使用之前指定的环境变量。

from databricks import sql

connection = sql.connect(
  server_hostname='<server-hostname>',
  http_path='<http-path>',
  access_token='<personal-access-token>')

cursor = connection.cursor()

cursor.execute('SELECT * FROM <database-name>.<table-name> LIMIT 2')

result = cursor.fetchall()

for row in result:
  print(row)

cursor.close()

将:

  • <server-hostname> 替换为 <server-hostname> 值。
  • <http-path> 包含 <http-path> 值。
  • <personal-access-token> 替换为 Azure Databricks 个人访问令牌。
  • <database-name> 替换为要查询的数据库的名称。
  • <table-name> 替换为要查询的表的名称。

API 参考

databricks-sql-connector

用法:pip install databricks-sql-connector

另请参阅 Python 包索引 (PyPI) 中的 databricks-sql-connector

模块

databricks.sql

用法:from databricks import sql

方法

connect 方法

创建与数据库的连接。

返回一个 Connection 对象。

parameters
server_hostname

类型:str

群集或 SQL 终结点的服务器主机名。 要获取服务器主机名,请参阅本文前面部分的说明。

此参数是必需的。

示例: adb-1234567890123456.7.azuredatabricks.net
http_path

类型:str

群集或 SQL 终结点的 HTTP 路径。 要获取 HTTP 路径,请参阅本文前面部分的说明。

此参数是必需的。

示例:
sql/protocolv1/o/1234567890123456/1234-567890-test123 适用于群集。
/sql/1.0/endpoints/a1b234c567d8e9fa 适用于 SQL 终结点。
access_token

类型:str

适用于群集或 SQL 终结点工作区的 Azure Databricks 个人访问令牌。 要创建令牌,请参阅本文前面部分的说明。

此参数是必需的。

示例: dapi...<the-remaining-portion-of-your-token>

Connection

表示到数据库的连接。

方法
close 方法

关闭与数据库的连接,并释放服务器上所有关联的资源。 对此连接的任何其他调用都将引发 Error

无参数。

没有返回值。

cursor 方法

返回一种机制,该机制允许遍历数据库中的各种记录。

无参数。

返回一个 Cursor 对象。

Cursor

属性
arraysize 特性

fetchmany 方法一起使用,指定内部缓冲区大小,该大小也是一次性从服务器实际提取的行数。 默认值为 10000。 对于窄结果(在结果中每行未包含大量数据),应增大该值以提高性能。

读写访问。

description 特性

包含 tuple 对象的 Python list。 每个 tuple 对象都包含 7 个值,并且每个 tuple 对象的前 2 个项目包含如下所示的描述单个结果列的信息:

  • name:列的名称。
  • type_code:表示列的类型的字符串。 例如,整数列的类型代码为 int

每个 7 项目 tuple 对象的剩余 5 个项目未实现,并且其值未定义。 它们通常返回 4 个 None 值,后跟一个 True 值。

只读访问。

方法
cancel 方法

中断运行游标启动的任何数据库查询或命令。 若要在服务器上释放关联的资源,请在调用方法后调用 close 方法

无参数。

没有返回值。

close 方法

关闭游标并释放服务器上关联的资源。 关闭已关闭的游标可能会引发错误。

无参数。

没有返回值。

execute 方法

准备并运行数据库查询或命令。

没有返回值。

parameters
operation

类型:str

要准备并运行的查询或命令。

此参数是必需的。

不使用 parameters 参数的示例:


cursor.execute(
'SELECT * FROM default.diamonds WHERE cut="Ideal" LIMIT 2'
)

不使用 parameters 参数的示例:


cursor.execute(
'SELECT * FROM default.diamonds WHERE cut=%(cut_type)s LIMIT 2',
{ 'cut_type': 'Ideal' }
)
parameters

类型:字典

要与 operation 参数一起使用的参数序列。

此参数是可选的。 默认值为 None
executemany 方法

使用 seq_of_parameters 实参中的所有形参序列来准备并运行数据库查询或命令。 仅保留最终结果集。

没有返回值。

parameters
operation

类型:str

要准备并运行的查询或命令。

此参数是必需的。
seq_of_parameters

类型:dictlist


operation 参数一起使用的多个参数集的序列。

此参数是必需的。
fetchall 方法

获取查询的所有(或所有剩余)行。

无参数。

tuple 对象的 Python list 形式返回查询的所有(或所有剩余)行。

Error如果先前对Error方法的调用未返回任何数据或尚未进行任何调用,将引发 execute

fetchmany 方法

获取查询的后续行。

size如果未指定查询的下一行) 为对象的 Python,则返回到参数 (或size属性 sizelisttuple

Error如果先前对Error方法的调用未返回任何数据或尚未进行任何调用,将引发 execute

parameters
大小

类型:int

要获取的后续行数。

此参数是可选的。 如果未指定,则使用 arraysize 属性的值。

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

获取数据集的下一行。

无参数。

以 Python tuple 对象的形式返回数据集的下一行,如果没有更多可用数据,则返回 None

Error如果先前对Error方法的调用未返回任何数据或尚未进行任何调用,将引发 execute

类型转换

下表将 Apache Spark SQL 数据类型映射到其 Python 数据类型等效项。

Apache Spark SQL 数据类型 Python 数据类型
array str
bigint int
binary bytearray
boolean bool
date datetime.date
decimal decimal.Decimal
double float
int int
map str
null NoneType
smallint int
string str
struct str
timestamp datetime.datetime
tinyint int

故障排除

引发 EOFError 异常

问题:运行代码时,会收到 类似于下面的异常:

Traceback (most recent call last):
  ...
  File ".../databricks/sql/TCLIService/TCLIService.py", line 187, in OpenSession
    return self.recv_OpenSession()
  File ".../databricks/sql/TCLIService/TCLIService.py", line 199, in recv_OpenSession
    (fname, mtype, rseqid) = iprot.readMessageBegin()
  File ".../thrift/protocol/TBinaryProtocol.py", line 148, in readMessageBegin
    name = self.trans.readAll(sz)
  File ".../thrift/transport/TTransport.py", line 68, in readAll
    raise EOFError()
EOFError

可能的原因:出现此异常的原因可能是个人访问令牌无效或缺少访问指定 Azure Databricks 资源的权限。

建议的修复:检查连接详细信息,然后重试。

其他资源

有关详细信息,请参阅: