Fontes de dados do Spark

A API de Fonte de Dados do Spark permite que você leia e escreva em bancos de dados externos diretamente de Azure Databricks. Use-o somente quando precisar da flexibilidade total do mecanismo Spark, quiser executar consultas nativas na origem ou exigir acesso de gravação a sistemas externos. Em geral, o Azure Databricks recomenda acesso controlado e somente para leitura, com delegação automática de consultas Spark ou SQL. Consulte O que é federação de consulta?.

A API da Fonte de Dados do Spark tem comportamentos específicos para conectividade, execução de consulta e detecção de esquema.

• A carga de trabalho primária e as transformações subsequentes do Spark são executadas no cluster Azure Databricks Spark.
• Ao usar a opção query , a instrução SQL especificada é executada inteiramente na fonte de dados externa. O Spark busca os resultados sem fazer o pushdown de transformações na cadeia de caracteres de consulta.
• A conexão requer um conector incluído no Azure Databricks, um driver JDBC fornecido pelo usuário ou uma fonte de dados personalizada do PySpark.
• O Spark lê automaticamente o esquema da tabela externa do banco de dados e mapeia seus tipos para os tipos do Spark SQL.

Use um conector incluído

O Databricks Runtime inclui conectores otimizados para fontes de dados comuns. Consulte conectores empacotados com suporte para a lista completa.

Conectores integrados usam host e port como opções separadas em vez de usar uma string de URL JDBC completa.

Ler dados usando uma consulta pass-through

Usar a opção query garante que a lógica de filtragem e junção seja executada no banco de dados de origem antes que os dados cheguem ao Spark. Para acesso de leitura controlado com pushdown automático de consultas e delegação de permissões do Catálogo do Unity por meio de exibições, considere consultas remotas.

df = (spark.read
  .format("sqlserver")
  .option("host", "<your-sql-server-instance>.database.windows.net")
  .option("user", dbutils.secrets.get(scope="<scope>", key="<user>"))
  .option("password", dbutils.secrets.get(scope="<scope>", key="<password>"))
  .option("database", "<database-name>")
  .option("query", "SELECT id, name FROM users WHERE active = 1")
  .load())

Gravar dados

Especifique um modo de gravação com .mode() para controlar como os dados são gravados. Use append para adicionar linhas a uma tabela existente ou overwrite para substituir seu conteúdo.

(df.write
  .format("sqlserver")
  .mode("overwrite")
  .option("host", "<your-sql-server-instance>.database.windows.net")
  .option("user", dbutils.secrets.get(scope="<scope>", key="<user>"))
  .option("password", dbutils.secrets.get(scope="<scope>", key="<password>"))
  .option("database", "<database-name>")
  .option("dbtable", "<table-name>")
  .save())

Use uma conexão JDBC do Unity Catalog

Se um conector específico da fonte não estiver incluído ou se você quiser usar uma versão específica do driver JDBC, use uma conexão JDBC do Catálogo do Unity. Isso permite centralizar o gerenciamento de credenciais e trazer seu próprio driver JDBC.

Uma conexão JDBC do Catálogo do Unity oferece várias vantagens em comparação com o uso de um conector incluído ou de um driver JDBC puro diretamente. Com uma conexão JDBC com o Unity Catalog, você pode:

• Use seu próprio arquivo JAR do driver JDBC para qualquer banco de dados com suporte a JDBC.
• Crie a conexão uma vez e reutilize-a em computação serverless, padrão e dedicada.
• Utilize o acesso controlado à fonte de dados usando um objeto de conexão do Catálogo do Unity.
• Ocultar credenciais de conexão do usuário que está consultando.
• Ler e gravar em bancos de dados externos por meio da API de Fonte de Dados do Spark.

Para usar uma conexão do Catálogo do JDBC Unity, especifique databricks.connection em suas opções do Spark:

df = (spark.read
  .format("jdbc")
  .option("databricks.connection", "<connection-name>")
  .option("query", "SELECT * FROM external_table")
  .load())

Para obter instruções de configuração, consulte a conexão JDBC.

Use um conector personalizado em computação dedicada

Em computação dedicada (clássica), você pode instalar conectores de fonte de dados Spark de terceiros ou drivers JDBC que não vêm junto com o Databricks Runtime.

Use essa abordagem quando:

• Você precisa de um conector Spark de terceiros para sistemas como MongoDB, Cassandra, Couchbase ou Elasticsearch.
• Você precisa de uma versão específica do driver que não seja agrupada no runtime.
• Você deseja instalar um driver JDBC diretamente no cluster sem configurar uma conexão do Catálogo do Unity.

Instalar um conector ou um driver

Instale a biblioteca no seu cluster por meio de Computação>seu cluster>Bibliotecas>Instalar nova. Você pode usar as coordenadas do Maven diretamente sem baixar ou carregar jars. Reinicie o cluster para que a biblioteca entre em vigor.

Ler dados

Depois de instalar o conector, use o nome de formato do conector e as opções de conexão necessárias para ler os dados.

df = (spark.read
  .format("mongodb")
  .option("connection.uri", "mongodb://<hostname>:27017")
  .option("database", "<database-name>")
  .option("collection", "<collection-name>")
  .load())

Gravar dados

Use o mesmo nome de formato e opções de conexão para gravar dados de volta na origem.

(df.write
  .format("mongodb")
  .mode("overwrite")
  .option("connection.uri", "mongodb://<hostname>:27017")
  .option("database", "<database-name>")
  .option("collection", "<collection-name>")
  .save())

Considerações

Tenha isso em mente ao usar conectores personalizados em computação dedicada.

• O driver ou conector só está disponível no cluster em que ele está instalado.
• JARs Spark personalizados de terceiros não são suportados em computação Databricks SQL, serverless ou no modo de acesso padrão. Para esses tipos de computação, use conectores agrupados ou conexões do Catálogo do JDBC Unity.

Fontes de dados personalizadas do PySpark

A API Python DataSource permite que você crie conectores de dados personalizados inteiramente em Python, sem bibliotecas baseadas em JARs ou JVM. Use isso quando precisar se conectar a APIs REST, aplicativos SaaS ou qualquer sistema sem uma interface JDBC ou quando quiser gerar dados sintéticos programaticamente. A API dá suporte a leituras e gravações em lote e streaming.

Para configuração, exemplos e referência de API, consulte fontes de dados personalizadas do PySpark.

Comparar estratégias de integração

A tabela a seguir compara a API de Fonte de Dados do Spark com a Lakehouse Federation e o Lakeflow Connect para ajudá-lo a escolher a abordagem certa para seu caso de uso.

Conectores agrupados suportados

As fontes de dados a seguir são agrupadas no Databricks Runtime e podem ser chamadas diretamente por meio do Spark. Leituras e gravações são suportadas em computação dedicada e padrão.

Migrar cargas de trabalho BigQuery JDBC para Databricks Runtime 20

A partir do Databricks Runtime 20, o Databricks Runtime não inclui mais o driver JDBC do BigQuery incluído. Databricks Runtime 19 e anteriores continuam a incluir o driver. Essa mudança afeta cargas de trabalho clássicas de computação que usam Spark JDBC com URL jdbc:bigquery: .

Para encontrar workloads afetadas, pesquise em seu código e em sua configuração em busca de uma URL jdbc:bigquery:. Esse caminho JDBC é separado do conector do Google BigQuery incluído no pacote, que usa .format("bigquery") e permanece disponível. Sem um driver JDBC do BigQuery instalado, as cargas de trabalho afetadas falham com um erro de driver não encontrado.

Antes de mover uma carga de trabalho afetada para Databricks Runtime 20 ou posterior, escolha uma das seguintes opções:

• Para cargas de trabalho de somente leitura, use Lakehouse Federation para consultar o BigQuery por meio de um catálogo externo.
• Substitua as leituras e gravações do Spark JDBC pelo conector BigQuery do Google que vem incluído. Veja Usar um conector integrado e Conectores integrados compatíveis.
• Use uma conexão JDBC do Unity Catalog com seu próprio driver JDBC do BigQuery.
• Em um computador clássico dedicado, instale seu próprio driver JDBC do BigQuery.
• Mantenha a carga de trabalho no Databricks Runtime 19 ou anterior até concluir uma dessas mudanças.

Para informações sobre os drivers disponíveis no Google, veja BigQuery ODBC e JDBC drivers.

Limitações

As limitações a seguir se aplicam ao usar a API de Fonte de Dados do Spark no Azure Databricks.

• As opções do Spark para fontes de dados agrupadas são limitadas a query, dbtablee um pequeno conjunto de opções específicas do conector.
• JARs Spark personalizados de terceiros só podem ser instalados em computação dedicada. Para computação serverless ou padrão, use conectores integrados ou conexões JDBC do Unity Catalog.
• As fontes de dados personalizadas do PySpark exigem o Databricks Runtime 15.4 LTS ou superior.