Databricks SQL Connector para Python

Artículo
06/05/2024

Databricks SQL Connector para Python es una biblioteca de Python que permite usar código de Python para ejecutar comandos SQL en clústeres de Azure Databricks y almacenes de Databricks SQL. Databricks SQL Connector para Python es más fácil de configurar y usar que las bibliotecas de Python similares, como pyodbc. Esta biblioteca sigue PEP 249: especificación de la API de base de datos de Python v2.0.

Nota:

El conector SQL de Databricks para Python también incluye un dialecto SQLAlchemy para Azure Databricks. Consulte Uso de SQLAlchemy con Azure Databricks.

Requisitos

Una máquina de desarrollo que ejecute Python >=3.8 y <3.11.
Databricks recomienda usar entornos virtuales de Python, como los proporcionados por venv que se incluyen con Python. Los entornos virtuales ayudan a garantizar que usa las versiones correctas de Python y Databricks SQL Connector para Python juntos. La configuración y el uso de entornos virtuales están fuera del ámbito de este artículo. Para más información, consulte Creación de entornos virtuales.
Un clúster o un almacén de SQL existente.

Introducción

Instale la biblioteca Databricks SQL Connector para Python en la máquina de desarrollo mediante la ejecución de pip install databricks-sql-connector o python -m pip install databricks-sql-connector.
Recopile la siguiente información del clúster o el almacén de SQL que desea usar:

Clúster
- Nombre de host del servidor del clúster. Puede obtenerlo del valor del nombre de host del servidor en la pestaña Opciones avanzadas y JDBC/ODBC del clúster.
- Ruta de acceso HTTP del clúster. Puede obtenerlo del valor de la ruta de acceso HTTP en la pestaña Opciones avanzadas y JDBC/ODBC del clúster.
Almacén de SQL
- Nombre de host del servidor del almacén de SQL. Puede obtenerlo del valor del nombre de host del servidor en la pestaña Detalles de conexión del almacén de SQL.
- Ruta de acceso HTTP del almacén de SQL. Puede obtenerlo del valor de la ruta de acceso HTTP en la pestaña Detalles de conexión del almacén de SQL.

Autenticación

Databricks SQL Connector para Python admite los siguientes tipos de autenticación de Azure Databricks:

Autenticación de token de acceso personal de Databricks
Autenticación mediante token de Microsoft Entra ID (anteriormente Azure Active Directory)
autenticación de máquina a máquina (M2M) de OAuth
Autenticación de usuario a máquina (U2M) de OAuth

Databricks SQL Connector para Python aún no admite los siguientes tipos de autenticación de Azure Databricks:

Autenticación de token de acceso personal de Databricks

Para usar Databricks SQL Connector para Python con la autenticación de token de acceso personal de Azure Databricks, primero debe crear un token de acceso personal de Azure Databricks, como se indica a continuación:

En el área de trabajo de Azure Databricks, haga clic en el nombre de usuario en la barra superior y seleccione Configuración en la lista desplegable.
Haga clic en Desarrollador.
Junto a Tokens de acceso, haga clic en Administrar.
Haga clic en Generate new token (Generar nuevo token).
(Opcional) Escriba un comentario que le ayude a identificar este token en el futuro y cambie la duración predeterminada del token de 90 días. Para crear un token sin duración (no recomendado), deje el cuadro Duración (días) vacío (en blanco).
Haga clic en Generar.
Copie el token mostrado en una ubicación segura y, a continuación, haga clic en Listo.

Nota:

Asegúrese de guardar el token copiado en una ubicación segura. No comparta el token copiado con otros usuarios. Si pierde el token copiado, no podrá volver a generar ese mismo token. Debe repetir el procedimiento para crear un nuevo token. Si pierde el token copiado o cree que el token se ha visto comprometido, Databricks recomienda eliminar inmediatamente ese token del área de trabajo haciendo clic en el icono de papelera (Revocar) situado junto al token en la página Tokens de acceso.

Si no puede crear o usar tokens en el área de trabajo, puede deberse a que el administrador del área de trabajo tiene tokens deshabilitados o no le ha concedido permiso para crear o usar tokens. Consulte el administrador del área de trabajo o lo siguiente:

Para autenticar Databricks SQL Connector para Python, use el siguiente fragmento de código. En este fragmento, se da por supuesto que ha establecido las siguientes variables de entorno:

DATABRICKS_SERVER_HOSTNAMEestablecido en el valor de Nombre de host del servidor del clúster o almacén de SQL.
DATABRICKS_HTTP_PATH, establecido en el valor de Ruta de acceso HTTP del clúster o almacén del SQL.
DATABRICKS_TOKEN, establecido en el token de acceso personal de Azure Databricks.

Para establecer las variables de entorno, consulte la documentación del sistema operativo.

from databricks import sql
import os

with sql.connect(server_hostname = os.getenv("DATABRICKS_SERVER_HOSTNAME"),
                 http_path       = os.getenv("DATABRICKS_HTTP_PATH"),
                 access_token    = os.getenv("DATABRICKS_TOKEN")) as connection:
# ...

Autenticación de máquina a máquina (M2M) de OAuth

El conector de Databricks SQL para Python 2.7.0 y versiones posteriores admite la autenticación de máquina a máquina (M2M) de OAuth. También debe instalar el SDK de Databricks para Python 0.18.0 o posterior (por ejemplo, ejecutando pip install databricks-sdk o python -m pip install databricks-sdk).

Para usar el conector de Databricks SQL para Python con la autenticación M2M de OAuth, es necesario hacer lo siguiente:

Cree una entidad de servicio de Azure Databricks en el área de trabajo de Azure Databricks y cree un secreto de OAuth para esa entidad de servicio.

Para crear la entidad de servicio y su secreto de OAuth, vea autenticación de máquina a máquina (M2M) de OAuth. Anote los valores de UUID o Id. de la aplicación de la entidad de servicio, así como el valor de Secreto del secreto de OAuth de la entidad de servicio.
Proporcione a esa entidad de servicio acceso al clúster o al almacenamiento.

Para conceder a la entidad de servicio acceso al clúster o al almacenamiento, consulte Permisos de proceso o Administrar un almacén de SQL.

Para autenticar Databricks SQL Connector para Python, use el siguiente fragmento de código. En este fragmento, se da por supuesto que ha establecido las siguientes variables de entorno:

DATABRICKS_SERVER_HOSTNAME establezca en el valor de nombre de host del servidor para el clúster o SQL warehouse.
DATABRICKS_HTTP_PATH, establecido en el valor de Ruta de acceso HTTP del clúster o almacén del SQL.
DATABRICKS_CLIENT_ID, establecido en el valor del UUID o Id. de aplicación de la entidad de servicio.
DATABRICKS_CLIENT_SECRET, establecido en el Secreto del secreto de OAuth de la entidad de servicio.

Para establecer las variables de entorno, consulte la documentación del sistema operativo.

from databricks.sdk.core import Config, oauth_service_principal
from databricks import sql
import os

server_hostname = os.getenv("DATABRICKS_SERVER_HOSTNAME")

def credential_provider():
  config = Config(
    host          = f"https://{server_hostname}",
    client_id     = os.getenv("DATABRICKS_CLIENT_ID"),
    client_secret = os.getenv("DATABRICKS_CLIENT_SECRET"))
  return oauth_service_principal(config)

with sql.connect(server_hostname      = server_hostname,
                 http_path            = os.getenv("DATABRICKS_HTTP_PATH"),
                 credentials_provider = credential_provider) as connection:
# ...

Autenticación mediante token de Microsoft Entra ID (anteriormente Azure Active Directory)

Para usar el conector de Databricks SQL para Python con la autenticación de tokens de Microsoft Entra ID (anteriormente, Azure Active Directory), es necesario proporcionar el conector de Databricks SQL para Python con el token de Microsoft Entra ID. Para crear un token de acceso de Microsoft Entra ID, haga lo siguiente:

Para un usuario de Azure Databricks, puede usar la CLI de Azure. Vea Obtención de tokens de Microsoft Entra ID (anteriormente Azure Active Directory) para los usuarios mediante la CLI de Azure.
Para obtener una entidad de servicio de Microsoft Entra ID, consulte Obtener un token de acceso de Microsoft Entra ID con la CLI de Azure. Para crear una entidad de servicio administrada de Microsoft Entra ID, vea Administrar entidades de servicio.

Los tokens de Microsoft Entra ID tienen una duración predeterminada de aproximadamente 1 hora. Para crear un nuevo token de Microsoft Entra ID, repita este proceso.

Para autenticar Databricks SQL Connector para Python, use el siguiente fragmento de código. En este fragmento, se da por supuesto que ha establecido las siguientes variables de entorno:

Establezca DATABRICKS_SERVER_HOSTNAME en el valor de Nombre de host del servidor del clúster o almacén de SQL.
Establezca DATABRICKS_HTTP_PATH en el valor de Ruta de acceso HTTP del clúster o almacén del SQL.
Establezca DATABRICKS_TOKEN en el token de Microsoft Entra ID.

Para establecer las variables de entorno, consulte la documentación del sistema operativo.

from databricks import sql
import os

with sql.connect(server_hostname = os.getenv("DATABRICKS_SERVER_HOSTNAME"),
                 http_path       = os.getenv("DATABRICKS_HTTP_PATH"),
                 access_token    = os.getenv("DATABRICKS_TOKEN")) as connection:
# ...

Autenticación de usuario a máquina (U2M) de OAuth

Databricks SQL Connector para Python versiones 2.7.0 y posteriores admiten autenticación de usuario a máquina (U2M) de OAuth. También debe instalar el SDK de Databricks para Python 0.19.0 o posterior (por ejemplo, ejecutando pip install databricks-sdk o python -m pip install databricks-sdk).

Para autenticar Databricks SQL Connector para Python con la autenticación de U2M de OAuth, use el siguiente fragmento de código. La autenticación de U2M de OAuth usa el inicio de sesión humano en tiempo real y el consentimiento para autenticar la cuenta de usuario Azure Databricks de destino. En este fragmento, se da por supuesto que ha establecido las siguientes variables de entorno:

Establezca DATABRICKS_SERVER_HOSTNAME en el valor de Nombre de host del servidor del clúster o almacén de SQL.
Establezca DATABRICKS_HTTP_PATH en el valor de Ruta de acceso HTTP del clúster o almacén del SQL.

Para establecer las variables de entorno, consulte la documentación del sistema operativo.

from databricks import sql
import os

with sql.connect(server_hostname = os.getenv("DATABRICKS_SERVER_HOSTNAME"),
                 http_path       = os.getenv("DATABRICKS_HTTP_PATH"),
                 auth_type       = "databricks-oauth") as connection:
# ...

Ejemplos

En los ejemplos de código siguientes se muestra cómo usar Databricks SQL Connector para Python para consultar e insertar datos, consultar metadatos, administrar cursores y conexiones y configurar el registro.

Nota:

En los ejemplos de código siguientes se muestra cómo usar un token de acceso personal de Azure Databricks para la autenticación. Para usar otros tipos de autenticación disponibles de Azure Databricks, consulte Autenticación.

En este ejemplo de código se recuperan los valores de variable de conexión server_hostname, http_path y access_token de estas variables de entorno:

DATABRICKS_SERVER_HOSTNAME, que representa el valor de Nombre de host del servidor de los requisitos.
DATABRICKS_HTTP_PATH, que representa el valor de Ruta de acceso HTTP de los requisitos.
DATABRICKS_TOKEN, que representa el token de acceso de los requisitos.

Puede usar otros enfoques para recuperar estos valores de variable de conexión. El uso de variables de entorno es solo un enfoque entre muchos.

Consultar datos
Inserción de datos
Metadatos de consulta
Administrar cursores y conexiones
Administración de archivos en volúmenes del Unity Catalog
Configurar registro

Consultar datos

En el ejemplo de código siguiente, se muestra cómo llamar a Databricks SQL Connector para Python para ejecutar un comando SQL básico en un clúster o un almacén de SQL. Este comando devuelve las dos primeras filas de la tabla trips del esquema nyctaxi del catálogo samples.

from databricks import sql
import os

with sql.connect(server_hostname = os.getenv("DATABRICKS_SERVER_HOSTNAME"),
                 http_path       = os.getenv("DATABRICKS_HTTP_PATH"),
                 access_token    = os.getenv("DATABRICKS_TOKEN")) as connection:

  with connection.cursor() as cursor:
    cursor.execute("SELECT * FROM samples.nyctaxi.trips LIMIT 2")
    result = cursor.fetchall()

    for row in result:
      print(row)

Insertar datos

En el ejemplo siguiente, se muestra cómo insertar pequeñas cantidades de datos (miles de filas):

from databricks import sql
import os

with sql.connect(server_hostname = os.getenv("DATABRICKS_SERVER_HOSTNAME"),
                 http_path       = os.getenv("DATABRICKS_HTTP_PATH"),
                 access_token    = os.getenv("DATABRICKS_TOKEN")) as connection:

  with connection.cursor() as cursor:
    cursor.execute("CREATE TABLE IF NOT EXISTS squares (x int, x_squared int)")

    squares = [(i, i * i) for i in range(100)]
    values = ",".join([f"({x}, {y})" for (x, y) in squares])

    cursor.execute(f"INSERT INTO squares VALUES {values}")

    cursor.execute("SELECT * FROM squares LIMIT 10")

    result = cursor.fetchall()

    for row in result:
      print(row)

Para grandes cantidades de datos, primero debe cargar los datos en el almacenamiento en la nube y, a continuación, ejecutar el comando COPY INTO.

Metadatos de consulta

Hay métodos dedicados para recuperar metadatos. En el ejemplo siguiente, se recuperan metadatos sobre las columnas de una tabla de ejemplo:

from databricks import sql
import os

with sql.connect(server_hostname = os.getenv("DATABRICKS_SERVER_HOSTNAME"),
                 http_path       = os.getenv("DATABRICKS_HTTP_PATH"),
                 access_token    = os.getenv("DATABRICKS_TOKEN")) as connection:

  with connection.cursor() as cursor:
    cursor.columns(schema_name="default", table_name="squares")
    print(cursor.fetchall())

Administrar cursores y conexiones

Se recomienda cerrar las conexiones y cursores que ya no están en uso. Esto libera recursos en los clústeres de Azure Databricks y los almacenes de SQL de Databricks.

Puede usar un administrador de contexto (la sintaxis with utilizada en ejemplos anteriores) para administrar los recursos o llamar explícitamente a close:

from databricks import sql
import os

connection = sql.connect(server_hostname = os.getenv("DATABRICKS_SERVER_HOSTNAME"),
                         http_path       = os.getenv("DATABRICKS_HTTP_PATH"),
                         access_token    = os.getenv("DATABRICKS_TOKEN"))

cursor = connection.cursor()

cursor.execute("SELECT * from range(10)")
print(cursor.fetchall())

cursor.close()
connection.close()

Administración de archivos en volúmenes del catálogo de Unity

El conector SQL de Databricks permite escribir archivos locales en los Volúmenes del catálogo de Unity, descargar archivos de volúmenes y eliminar archivos de volúmenes, tal y como se muestra en el ejemplo siguiente:

from databricks import sql
import os

# For writing local files to volumes and downloading files from volumes,
# you must set the staging_allows_local_path argument to the path to the
# local folder that contains the files to be written or downloaded.
# For deleting files in volumes, you must also specify the
# staging_allows_local_path argument, but its value is ignored,
# so in that case its value can be set for example to an empty string.
with sql.connect(server_hostname            = os.getenv("DATABRICKS_SERVER_HOSTNAME"),
                 http_path                  = os.getenv("DATABRICKS_HTTP_PATH"),
                 access_token               = os.getenv("DATABRICKS_TOKEN"),
                 staging_allowed_local_path = "/tmp/") as connection:

  with connection.cursor() as cursor:

    # Write a local file to the specified path in a volume.
    # Specify OVERWRITE to overwrite any existing file in that path.
    cursor.execute(
      "PUT '/temp/my-data.csv' INTO '/Volumes/main/default/my-volume/my-data.csv' OVERWRITE"
    )

    # Download a file from the specified path in a volume.
    cursor.execute(
      "GET '/Volumes/main/default/my-volume/my-data.csv' TO '/tmp/my-downloaded-data.csv'"
    )

    # Delete a file from the specified path in a volume.
    cursor.execute(
      "REMOVE '/Volumes/main/default/my-volume/my-data.csv'"
    )

registro

Databricks SQL Connector usa el módulo de registro estándar de Python. Puede configurar el nivel de registro similar al siguiente:

from databricks import sql
import os, logging

logging.getLogger("databricks.sql").setLevel(logging.DEBUG)
logging.basicConfig(filename = "results.log",
                    level    = logging.DEBUG)

connection = sql.connect(server_hostname = os.getenv("DATABRICKS_SERVER_HOSTNAME"),
                         http_path       = os.getenv("DATABRICKS_HTTP_PATH"),
                         access_token    = os.getenv("DATABRICKS_TOKEN"))

cursor = connection.cursor()

cursor.execute("SELECT * from range(10)")

result = cursor.fetchall()

for row in result:
   logging.debug(row)

cursor.close()
connection.close()

Prueba

Para probar el código, use marcos de pruebas de Python como pytest. Para probar el código en condiciones simuladas sin llamar a los puntos de conexión de la API de REST de Azure Databricks ni cambiar el estado de las cuentas o áreas de trabajo de Azure Databricks, puede usar bibliotecas de simulación de Python como unittest.mock.

Por ejemplo, dado el siguiente archivo denominado helpers.py que contiene una función get_connection_personal_access_token que usa un token de acceso personal de Azure Databricks para devolver una conexión a un área de trabajo de Azure Databricks y una función select_nyctaxi_trips que usa la conexión para obtener el número especificado de filas de datos de la tabla trips en el esquema nyctaxi del catálogo de samples:

# helpers.py

from databricks import sql
from databricks.sql.client import Connection, List, Row, Cursor

def get_connection_personal_access_token(
  server_hostname: str,
  http_path: str,
  access_token: str
) -> Connection:
  return sql.connect(
    server_hostname = server_hostname,
    http_path = http_path,
    access_token = access_token
  )

def select_nyctaxi_trips(
  connection: Connection,
  num_rows: int
) -> List[Row]:
  cursor: Cursor = connection.cursor()
  cursor.execute(f"SELECT * FROM samples.nyctaxi.trips LIMIT {num_rows}")
  result: List[Row] = cursor.fetchall()
  return result

Y dado el siguiente archivo denominado main.py que llama a las funciones get_connection_personal_access_token y select_nyctaxi_trips:

# main.py

from databricks.sql.client import Connection, List, Row
import os
from helpers import get_connection_personal_access_token, select_nyctaxi_trips

connection: Connection = get_connection_personal_access_token(
  server_hostname = os.getenv("DATABRICKS_SERVER_HOSTNAME"),
  http_path = os.getenv("DATABRICKS_HTTP_PATH"),
  access_token = os.getenv("DATABRICKS_TOKEN")
)

rows: List[Row] = select_nyctaxi_trips(
  connection = connection,
  num_rows = 2
)

for row in rows:
  print(row)

El siguiente archivo denominado test_helpers.py comprueba si la función select_nyctaxi_trips devuelve la respuesta esperada. En lugar de crear una conexión real al área de trabajo de destino, esta prueba simula un objeto Connection. La prueba también simula algunos datos que se ajustan al esquema y los valores que se encuentran en los datos reales. La prueba devuelve los datos ficticios a través de la conexión simulada y, a continuación, comprueba si uno de los valores de filas de datos simulados coincide con el valor esperado.

# test_helpers.py

import pytest
from databricks.sql.client import Connection, List, Row
from datetime import datetime
from helpers import select_nyctaxi_trips
from unittest.mock import create_autospec

@pytest.fixture
def mock_data() -> List[Row]:
  return [
    Row(
      tpep_pickup_datetime = datetime(2016, 2, 14, 16, 52, 13),
      tpep_dropoff_datetime = datetime(2016, 2, 14, 17, 16, 4),
      trip_distance = 4.94,
      fare_amount = 19.0,
      pickup_zip = 10282,
      dropoff_zip = 10171
    ),
    Row(
      tpep_pickup_datetime = datetime(2016, 2, 4, 18, 44, 19),
      tpep_dropoff_datetime = datetime(2016, 2, 4, 18, 46),
      trip_distance = 0.28,
      fare_amount = 3.5,
      pickup_zip = 10110,
      dropoff_zip = 10110
    )
  ]

def test_select_nyctaxi_trips(mock_data: List[Row]):
  # Create a mock Connection.
  mock_connection = create_autospec(Connection)

  # Set the mock Connection's cursor().fetchall() to the mock data.
  mock_connection.cursor().fetchall.return_value = mock_data

  # Call the real function with the mock Connection.
  response: List[Row] = select_nyctaxi_trips(
    connection = mock_connection,
    num_rows = 2)

  # Check the value of one of the mocked data row's columns.
  assert response[1].fare_amount == 3.5

Dado que la función select_nyctaxi_trips contiene una instrucción SELECT y por tanto, no cambia el estado de la tabla trips, la simulación no es absolutamente necesaria en este ejemplo. Sin embargo, la simulación le permite ejecutar rápidamente las pruebas sin esperar a que se realice una conexión real con el área de trabajo. Además, la simulación permite ejecutar pruebas simuladas varias veces para las funciones que podrían cambiar el estado de una tabla, como INSERT INTO, UPDATE, y DELETE FROM.

Paquete

databricks-sql-connector

Uso: pip install databricks-sql-connector

Consulte también databricks-sql-connector en el índice de paquetes de Python (PyPI).

módulo

databricks.sql

Uso: from databricks import sql

Clases

Entre las clases seleccionadas se incluyen las siguientes:

Clases
`Connection` Una sesión en un recurso de proceso de Azure Databricks.
`Cursor` Un mecanismo para recorrer los registros de datos.
`Row` Fila de datos en un resultado de consulta SQL.

Clase `Connection`

Para crear un objetoConnection, llame al método databricks.sql.connect con los parámetros siguientes:

Parámetros
`server_hostname` Tipo: `str` Nombre de host del servidor del clúster o el almacén de SQL. Para obtener el nombre de host del servidor, consulte las instrucciones anteriores de este artículo. Este parámetro es obligatorio. Ejemplo: `adb-1234567890123456.7.azuredatabricks.net`
`http_path` Tipo: `str` Ruta de acceso HTTP del clúster o el almacén de SQL. Para obtener la ruta de acceso HTTP, consulte las instrucciones anteriores de este artículo. Este parámetro es obligatorio. Ejemplo: `sql/protocolv1/o/1234567890123456/1234-567890-test123` para un clúster. `/sql/1.0/warehouses/a1b234c567d8e9fa` para un almacén de SQL.
`access_token`, `auth_type` Tipo: `str` Información sobre la configuración de autenticación de Azure Databricks. Para obtener más información, consulte Autenticación.
`session_configuration` Tipo: `dict[str, Any]` Diccionario de parámetros de configuración de sesión de Spark. Establecer una configuración equivale a usar el comando `SET key=val` de SQL. Ejecute el comando `SET -v` de SQL para obtener una lista completa de las configuraciones disponibles. Su valor predeterminado es `None`. Este parámetro es opcional. Ejemplo: `{"spark.sql.variable.substitute": True}`
`http_headers` Tipo: `List[Tuple[str, str]]]` Pares adicionales (clave, valor) para establecer en encabezados HTTP en cada solicitud RPC que realiza el cliente. El uso típico no establecerá ningún encabezado HTTP adicional. Su valor predeterminado es `None`. Este parámetro es opcional. A partir de la versión 2.0
`catalog` Tipo: `str` Catálogo inicial que se va a usar para la conexión. El valor predeterminado es `None` (en cuyo caso se usará el catálogo predeterminado, normalmente `hive_metastore`). Este parámetro es opcional. A partir de la versión 2.0
`schema` Tipo: `str` Esquema inicial que se va a usar para la conexión. El valor predeterminado es `None` (en cuyo caso se usará el esquema predeterminado `default`). Este parámetro es opcional. A partir de la versión 2.0
`use_cloud_fetch` Tipo: `bool` `True` enviar solicitudes de captura directamente al almacén de objetos en la nube para descargar fragmentos de datos. `False` (el valor predeterminado) para enviar solicitudes de obtención directamente a Azure Databricks. Si `use_cloud_fetch` se establece en `True` pero se bloquea el acceso a la red, se producirá un error en las solicitudes de captura. A partir de la versión 2.8

Entre los métodos de Connection seleccionados se incluyen los siguientes:

Métodos
`close` Cierra la conexión a la base de datos y libera todos los recursos asociados en el servidor. Las llamadas adicionales a esta conexión generarán una excepción `Error`. No hay parámetros. No devuelve ningún valor.
`cursor` Devuelve un nuevo objeto `Cursor` que permite recorrer los registros de una base de datos. No hay parámetros.

Clase `Cursor`

Para crear un objeto Cursor, llame al método Connection de la clase cursor.

Entre los atributos seleccionados Cursor se incluyen los siguientes:

Atributos

Atributos
`arraysize` Se usa con el método `fetchmany`, especifica el tamaño del búfer interno, que es también cuántas filas se capturan realmente del servidor a la vez. El valor predeterminado es `10000`. Para resultados estrechos (resultados en los que cada fila no contiene muchos datos), debe aumentar este valor para mejorar el rendimiento. Acceso de lectura y escritura.
`description` Contiene un objeto `list` de Python de objetos `tuple`. Cada uno de estos objetos `tuple` contiene 7 valores, en los que los dos primeros elementos `tuple` de cada objeto contienen información que describe una sola columna de resultados, como se muestra a continuación: * `name`: nombre de la columna. * `type_code`: cadena que representa el tipo de la columna. Por ejemplo, una columna de número entero tendrá el código de tipo `int`. Los 5 elementos restantes de cada objeto `tuple` de 7 elementos no se han implementado y sus valores no están definidos. Normalmente se devolverán como 4 `None` valores seguidos de un valor único `True`. Acceso de solo lectura.

arraysize

Se usa con el método fetchmany, especifica el tamaño del búfer interno, que es también cuántas filas se capturan realmente del servidor a la vez. El valor predeterminado es 10000. Para resultados estrechos (resultados en los que cada fila no contiene muchos datos), debe aumentar este valor para mejorar el rendimiento.

Acceso de lectura y escritura.

description

Contiene un objeto list de Python de objetos tuple. Cada uno de estos objetos tuple contiene 7 valores, en los que los dos primeros elementos tuple de cada objeto contienen información que describe una sola columna de resultados, como se muestra a continuación:

* name: nombre de la columna.
* type_code: cadena que representa el tipo de la columna. Por ejemplo, una columna de número entero tendrá el código de tipo int.

Los 5 elementos restantes de cada objeto tuple de 7 elementos no se han implementado y sus valores no están definidos. Normalmente se devolverán como 4
None valores seguidos de un valor único True.

Acceso de solo lectura.

Entre los métodos seleccionados Cursor se incluyen los siguientes:

Métodos
`cancel` Interrumpe la ejecución de cualquier consulta o comando de base de datos que haya iniciado el cursor. Para liberar los recursos asociados en el servidor, llame a. `close` método después de llamar al método `cancel`. No hay parámetros. No devuelve ningún valor.
`close` Cierra el cursor y libera los recursos asociados en el servidor. El cierre de un cursor ya cerrado podría producir un error. No hay parámetros. No devuelve ningún valor.
`execute` Prepara y, a continuación, ejecuta una consulta o un comando de base de datos. No devuelve ningún valor. Parámetros: `operation` Tipo: `str` Consulta o comando que se va a preparar y ejecutar. Este parámetro es obligatorio. Ejemplo sin el parámetro `parameters`: `cursor.execute(` `'SELECT * FROM samples.nyctaxi.trips WHERE pickup_zip="10019" LIMIT 2'` `)` Ejemplo con el parámetro `parameters`: `cursor.execute(` `'SELECT * FROM samples.nyctaxi.trips WHERE zip=%(pickup_zip)s LIMIT 2',` `{ 'pickup_zip': '10019' }` `)` `parameters` Tipo: diccionario Secuencia de parámetros que se va a usar con el parámetro `operation`. Este parámetro es opcional. El valor predeterminado es `None`.
`executemany` Prepara y, a continuación, ejecuta una consulta o un comando de base de datos con todas las secuencias de parámetros del argumento `seq_of_parameters`. Solo se conserva el conjunto de resultados final. No devuelve ningún valor. Parámetros: `operation` Tipo: `str` Consulta o comando que se va a preparar y ejecutar. Este parámetro es obligatorio. `seq_of_parameters` Tipo: `list` de `dict` Secuencia de muchos conjuntos de valores de parámetros que se usarán con el parámetro `operation`. Este parámetro es obligatorio.
`catalogs` Ejecuta una consulta de metadatos sobre los catálogos. A continuación, los resultados reales se deben capturar mediante `fetchmany` o `fetchall`. Entre los campos importantes del conjunto de resultados, se incluyen: * Nombre del campo: `TABLE_CAT`. Escriba: `str`. Nombre del catálogo. No hay parámetros. No devuelve ningún valor. A partir de la versión 1.0
`schemas` Ejecuta una consulta de metadatos sobre los esquemas. A continuación, los resultados reales se deben capturar mediante `fetchmany` o `fetchall`. Entre los campos importantes del conjunto de resultados, se incluyen: * Nombre del campo: `TABLE_SCHEM`. Escriba: `str`. Nombre del esquema. * Nombre del campo: `TABLE_CATALOG`. Escriba: `str`. Catálogo al que pertenece el esquema. No devuelve ningún valor. A partir de la versión 1.0 Parámetros: `catalog_name` Tipo: `str` Nombre del catálogo sobre el que se va a recuperar información. El carácter `%` se interpreta como un carácter comodín. Este parámetro es opcional. `schema_name` Tipo: `str` Nombre del esquema sobre el que se va a recuperar información. El carácter `%` se interpreta como un carácter comodín. Este parámetro es opcional.
`tables` Ejecuta una consulta de metadatos sobre tablas y vistas. A continuación, los resultados reales se deben capturar mediante `fetchmany` o `fetchall`. Entre los campos importantes del conjunto de resultados, se incluyen: * Nombre del campo: `TABLE_CAT`. Escriba: `str`. Catálogo al que pertenece la tabla. * Nombre del campo: `TABLE_SCHEM`. Escriba: `str`. Esquema al que pertenece la tabla. * Nombre del campo: `TABLE_NAME`. Escriba: `str`. Nombre de la tabla. * Nombre del campo: `TABLE_TYPE`. Escriba: `str`. El tipo de relación, por ejemplo `VIEW` o `TABLE` (se aplica a Databricks Runtime 10.4 LTS y versiones posteriores, así como a Databricks SQL; las versiones anteriores de Databricks Runtime devuelven una cadena vacía). No devuelve ningún valor. A partir de la versión 1.0 Parámetros `catalog_name` Tipo: `str` Nombre del catálogo sobre el que se va a recuperar información. El carácter `%` se interpreta como un carácter comodín. Este parámetro es opcional. `schema_name` Tipo: `str` Nombre del esquema sobre el que se va a recuperar información. El carácter `%` se interpreta como un carácter comodín. Este parámetro es opcional. `table_name` Tipo: `str` Nombre de la tabla sobre la que se va a recuperar información. El carácter `%` se interpreta como un carácter comodín. Este parámetro es opcional. `table_types` Tipo: `List[str]` Lista de tipos de tabla con las que se buscarán coincidencias, por ejemplo, `TABLE` o `VIEW`. Este parámetro es opcional.
`columns` Ejecuta una consulta de metadatos sobre las columnas. A continuación, los resultados reales se deben capturar mediante `fetchmany` o `fetchall`. Entre los campos importantes del conjunto de resultados, se incluyen: * Nombre del campo: `TABLE_CAT`. Escriba: `str`. Catálogo al que pertenece la columna. * Nombre del campo: `TABLE_SCHEM`. Escriba: `str`. Esquema al que pertenece la columna. * Nombre del campo: `TABLE_NAME`. Escriba: `str`. Nombre de la tabla a la que pertenece la columna. * Nombre del campo: `COLUMN_NAME`. Escriba: `str`. Nombre de la columna. No devuelve ningún valor. A partir de la versión 1.0 Parámetros: `catalog_name` Tipo: `str` Nombre del catálogo sobre el que se va a recuperar información. El carácter `%` se interpreta como un carácter comodín. Este parámetro es opcional. `schema_name` Tipo: `str` Nombre del esquema sobre el que se va a recuperar información. El carácter `%` se interpreta como un carácter comodín. Este parámetro es opcional. `table_name` Tipo: `str` Nombre de la tabla sobre la que se va a recuperar información. El carácter `%` se interpreta como un carácter comodín. Este parámetro es opcional. `column_name` Tipo: `str` Nombre de la columna sobre la que se va a recuperar información. El carácter `%` se interpreta como un carácter comodín. Este parámetro es opcional.
`fetchall` Obtiene todas las filas (o todas las restantes) de una consulta. No hay parámetros. Devuelve todas las filas (o todas las restantes) de la consulta como un `list` de Python `Row` objetos. Produce un `Error` si la llamada anterior al método `execute` no ha devuelto ningún dato o aún no se ha realizado ninguna llamada `execute`.
`fetchmany` Obtiene las filas siguientes de una consulta. Devuelve hasta `size` (o el atributo `arraysize` si no se especifica `size`) de las filas siguientes de una consulta como un `list` de Python de objetos `Row`. Si quedan menos filas que `size` para capturar, se devolverán todas las filas restantes. Produce un `Error` si la llamada anterior al método `execute` no ha devuelto ningún dato o aún no se ha realizado ninguna llamada `execute`. Parámetros: `size` Tipo: `int` Número de filas siguientes que se van a obtener. Este parámetro es opcional. Si no se especifica, se usa el valor del atributo `arraysize`. Ejemplo: `cursor.fetchmany(10)`
`fetchone` Obtiene la siguiente fila del conjunto de datos. No hay parámetros. Devuelve la siguiente fila del conjunto de datos como una sola secuencia como Python. `tuple` objeto o devuelve `None` si no hay más datos disponibles. Produce un `Error` si la llamada anterior al método `execute` no ha devuelto ningún dato o aún no se ha realizado ninguna llamada `execute`.
`fetchall_arrow` Obtiene todas las filas (o todas las restantes) de una consulta, como un objeto `Table` de PyArrow. Las consultas que devuelven grandes cantidades de datos deben usar `fetchmany_arrow` en su lugar para reducir el consumo de memoria. No hay parámetros. Devuelve todas las filas (o todas las restantes) de la consulta como una tabla de PyArrow. Produce un `Error` si la llamada anterior al método `execute` no ha devuelto ningún dato o aún no se ha realizado ninguna llamada `execute`. A partir de la versión 2.0
`fetchmany_arrow` Obtiene las filas siguientes de una consulta como un objeto `Table` de PyArrow. Devuelve hasta el argumento `size` (o el atributo `arraysize` si no se especifica `size`) de las filas siguientes de una consulta como PyArrow de Python. Objeto `Table`. Produce un `Error` si la llamada anterior al método `execute` no ha devuelto ningún dato o aún no se ha realizado ninguna llamada `execute`. A partir de la versión 2.0 Parámetros: `size` Tipo: `int` Número de filas siguientes que se van a obtener. Este parámetro es opcional. Si no se especifica, se usa el valor del atributo `arraysize`. Ejemplo: `cursor.fetchmany_arrow(10)`

Clase `Row`

La clase row es una estructura de datos similar a la tupla que representa una fila de resultados individual. Si la fila contiene una columna con el nombre "my_column", puede acceder al campo "my_column" del elemento row mediante row.my_column. También puede usar índices numéricos para acceder a los campos, por ejemplo, row[0]. Si no se permite el nombre de columna como nombre de método de atributo (por ejemplo, si comienza con un dígito), puede acceder al campo como row["1_my_column"].

A partir de la versión 1.0

Entre los métodos de Row seleccionados se incluyen:

| asDict

Devuelve una representación de diccionario de la fila, que se indexa por nombres de campo. Si hay nombres de campo duplicados, se devolverá uno de los campos duplicados (pero solo uno) en el diccionario. No se define qué campo duplicado se devuelve.

No hay parámetros.

Devuelve un objeto dict de campos. |

Conversiones de tipos

En la tabla siguiente, se asignan los tipos de datos de SQL de Apache Spark a sus tipos de datos equivalentes de Python.

Tipo de datos de SQL de Apache Spark	Tipo de datos de Python
`array`	`numpy.ndarray`
`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`

Solución de problemas

Mensaje `tokenAuthWrapperInvalidAccessToken: Invalid access token`

Problema: al ejecutar el código, aparece un mensaje similar a Error during request to server: tokenAuthWrapperInvalidAccessToken: Invalid access token.

Causa posible: el valor que se ha pasado a access_token no es un token de acceso personal de Azure Databricks.

Corrección recomendada: compruebe que el valor que se ha pasado a access_token sea correcto e inténtelo de nuevo.

Mensaje `gaierror(8, 'nodename nor servname provided, or not known')`

Problema: al ejecutar el código, aparece un mensaje similar a Error during request to server: gaierror(8, 'nodename nor servname provided, or not known').

Causa posible: el valor que se ha pasado a server_hostname no es el nombre de host correcto.

Corrección recomendada: compruebe que el valor que se ha pasado a server_hostname sea correcto e inténtelo de nuevo.

Para obtener más información sobre cómo buscar el nombre de host del servidor, consulte Obtener detalles de conexión para un recurso de proceso de Azure Databricks.

Mensaje `IpAclError`

Problema: al ejecutar el código, verá el mensaje Error during request to server: IpAclValidation al intentar usar el conector en un cuaderno de Azure Databricks.

Causa posible: puede tener habilitada la lista de direcciones IP permitidas para el área de trabajo de Azure Databricks. Con la lista de direcciones IP permitidas, no se permiten las conexiones de los clústeres de Spark al plano de control de manera predeterminada.

Corrección recomendada: pida al administrador que agregue la subred del plano de proceso a la lista de direcciones IP permitidas.

Recursos adicionales

Para más información, consulte:

Repositorio de Databricks SQL Connector para Python en GitHub
Tipos de datos
Tipos integrados (para bool, bytearray, float, int y str) en el sitio web de Python
datetime (para datetime.date y datatime.datetime) en el sitio web de Python
decimal (para decimal.Decimal) en el sitio web de Python
Constantes integradas (para NoneType) en el sitio web de Python

Compartir a través de

Databricks SQL Connector para Python

Requisitos

Introducción

Clúster

Almacén de SQL

Autenticación

Autenticación de token de acceso personal de Databricks

Autenticación de máquina a máquina (M2M) de OAuth

Autenticación mediante token de Microsoft Entra ID (anteriormente Azure Active Directory)

Autenticación de usuario a máquina (U2M) de OAuth

Ejemplos

Consultar datos

Insertar datos

Metadatos de consulta

Administrar cursores y conexiones

Administración de archivos en volúmenes del catálogo de Unity

registro

Prueba

Referencia de la API

Paquete

módulo

Clases

Clase `Connection`

Clase `Cursor`

Clase `Row`

Conversiones de tipos

Solución de problemas

Mensaje `tokenAuthWrapperInvalidAccessToken: Invalid access token`

Mensaje `gaierror(8, 'nodename nor servname provided, or not known')`

Mensaje `IpAclError`

Recursos adicionales

Comentarios

Comentarios

Recursos adicionales

Compartir a través de

Databricks SQL Connector para Python

Requisitos

Introducción

Clúster

Almacén de SQL

Autenticación

Autenticación de token de acceso personal de Databricks

Autenticación de máquina a máquina (M2M) de OAuth

Autenticación mediante token de Microsoft Entra ID (anteriormente Azure Active Directory)

Autenticación de usuario a máquina (U2M) de OAuth

Ejemplos

Consultar datos

Insertar datos

Metadatos de consulta

Administrar cursores y conexiones

Administración de archivos en volúmenes del catálogo de Unity

registro

Prueba

Referencia de la API

Paquete

módulo

Clases

Clase Connection

Clase Cursor

Clase Row

Conversiones de tipos

Solución de problemas

Mensaje tokenAuthWrapperInvalidAccessToken: Invalid access token

Mensaje gaierror(8, 'nodename nor servname provided, or not known')

Mensaje IpAclError

Recursos adicionales

Comentarios

Comentarios

Recursos adicionales

Clase `Connection`

Clase `Cursor`

Clase `Row`

Mensaje `tokenAuthWrapperInvalidAccessToken: Invalid access token`

Mensaje `gaierror(8, 'nodename nor servname provided, or not known')`

Mensaje `IpAclError`