Pular para o conteúdo principal

Conectar ao Lakebase

Use o Structured Streaming para gravar no Lakebase ou em um banco de dados PostgreSQL externo com processamento em lotes integrado, novas tentativas automáticas e autenticação gerenciada pelo workspace.

Quando usar o destino do Lakebase​

Use o coletor do Lakebase para gravações em transmissão de baixa latência no Lakebase ou em um banco de dados PostgreSQL externo. Este coletor não exige que você implemente funções customizadas foreach para gerenciar processamento em lote, gerenciamento de conexões e tratamento de erros.

Casos de uso comuns incluem:

  • Atualize bancos de dados de aplicativos em tempo real para painéis operacionais ou recursos voltados para o cliente.
  • Sincronizar dados em constante alteração, como resultados de transmissão agregados ou filtrados, em um banco de dados transacional.
  • Escreva a saída de uma query do Structured Streaming em uma tabela Lakebase com latência de dezenas de milissegundos usando o modo em tempo real no compute clássico.

Para sincronizar dados do Lakebase com as tabelas do Delta Lake no Lakehouse, no sentido inverso, consulte Lakebase Change Data Feed.

Requisitos​

  • Databricks Runtime 18 LTS ou acima.

  • Compute clássico com modos de acesso dedicados ou padrão, ou compute serverless para notebooks ou jobs. Em compute serverless, use Trigger.AvailableNow(). Consulte Transmissão em compute serverless.

  • Um banco de dados Lakebase ou uma conexão do Unity Catalog com um banco de dados PostgreSQL externo.

Requisitos de identificador​

Para todos os destinos, o Databricks recomenda o uso de nomes de esquema, tabela, coluna e coluna de chave primária que comecem com uma letra ou underscore e contenham apenas letras, números e underscores. O coletor impõe esses requisitos quando cria automaticamente uma tabela Lakebase. Para usar identificadores que não atendem a esses requisitos, crie a tabela de destino antes de começar a query.

Conecte-se a um banco de dados​

O coletor do Lakebase oferece suporte aos seguintes métodos de conexão:

Tabelas do Lakebase não registradas no Unity Catalog​

Para tabelas Lakebase não registradas no Unity Catalog, o conector gerencia automaticamente as credenciais e usa a identidade do usuário ou da entidade de serviço Databricks que está executando a consulta. Se a tabela não existe, o conector cria a tabela.

Para gravar em uma tabela do Lakebase, use as opções endpoint e dbtable:

Python
(df.writeStream
.format("postgresql")
.outputMode("update")
.option("endpoint", "<project-id>.<branch-id>.<endpoint-id>")
.option("database", "<database>") # Optional. Defaults to databricks_postgres.
.option("dbtable", "<schema>.<table>")
.option("upsertkey", "<primary-key-columns>") # Optional
.option("checkpointLocation", "/Volumes/<catalog>/<schema>/<volume>/<checkpoint-name>")
.start()
)

Substitua os seguintes espaços reservados:

  • <project-id>.<branch-id>.<endpoint-id>: Seu endpoint Lakebase. Encontre todos os três valores no nome do recurso no menu Obter ID da tab Computes , que tem o formato projects/<project-id>/branches/<branch-id>/endpoints/<endpoint-id>. Consulte Identificadores de Compute.
  • <database>: Opcional. O nome do banco de dados PostgreSQL de destino. O default é databricks_postgres. Consulte Gerenciar bancos de dados.
  • <schema>.<table>: A tabela de destino no formato schema.table. Se você omitir o esquema, o sink usará o esquema public. Para a criação automática de tabelas, use identificadores que comecem com uma letra ou underscore e contenham apenas letras, números e underscores.
  • <primary-key-columns>: Opcional. Uma lista separada por vírgulas de todas as colunas na chave principal da tabela de destino, por exemplo, id ou user_id,event_type. Consulte Comportamento de upsert.
  • /Volumes/<catalog>/<schema>/<volume>/<checkpoint-name>: Um caminho de volume do Unity Catalog onde a consulta armazena seu ponto de verificação. Você também pode usar um URI de armazenamento de objeto em cloud. O local deve ser um armazenamento onde você pode gravar, não um disco local, e deve ser exclusivo para cada consulta de transmissão. Isso é independente da tabela de destino. Consulte pontos de verificação de transmissão estructurada.

Para configurações opcionais, como batchsize e batchinterval, consulte as opções de coletor do PostgreSQL.

External PostgreSQL with Unity Catalog credentials​

info

Visualização

Esse recurso está em Prévia Pública. Os administradores do workspace podem controlar o acesso ao Custom JDBC on UC Compute na página Pré-visualizações . Consulte Gerenciar prévias do Databricks.

Use uma conexão do Unity Catalog para se autenticar em um banco de dados PostgreSQL externo sem armazenar credenciais em seu código. A tabela de destino já deve existir.

Criar uma conexão do tipo POSTGRESQL. Consulte Criar uma conexão. O usuário ou service principal do Databricks que executa a query deve ter USE CONNECTION na conexão.

To write to the PostgreSQL table, use the databricks.connection, database, and dbtable options:

Python
(df.writeStream
.format("postgresql")
.outputMode("update")
.option("databricks.connection", "<connection-name>")
.option("database", "<database>")
.option("dbtable", "<schema>.<table>")
.option("upsertkey", "<primary-key-columns>") # Optional
.option("checkpointLocation", "/Volumes/<catalog>/<schema>/<volume>/<checkpoint-name>")
.start()
)

Substitua os seguintes espaços reservados:

  • <connection-name>: O nome da conexão do Unity Catalog.
  • <database>: O nome do banco de dados PostgreSQL de destino.
  • <schema>.<table>: A tabela de destino existente no formato schema.table. Se você omitir o esquema, o sink usará o esquema public.
  • <primary-key-columns>: Opcional. Uma lista separada por vírgulas de todas as colunas na chave principal da tabela de destino, por exemplo, id ou user_id,event_type. Consulte Comportamento de upsert.
  • /Volumes/<catalog>/<schema>/<volume>/<checkpoint-name>: Um caminho de volume do Unity Catalog onde a consulta armazena seu ponto de verificação. Você também pode usar um URI de armazenamento de objeto em cloud. O local deve ser um armazenamento onde você pode gravar, não um disco local, e deve ser exclusivo para cada consulta de transmissão. Isso é independente da tabela de destino. Consulte pontos de verificação de transmissão estructurada.

As conexões PostgreSQL usam TLS. A verificação de certificado segue as configurações na conexão do Unity Catalog, que você escolhe ao criar a conexão:

  • Certificado de servidor confiável : quando selecionada, a conexão usa sslmode=require, que criptografa a conexão sem verificar o certificado do servidor.
  • Certificado de servidor fornecido pelo usuário : forneça um certificado de servidor codificado em PEM para usar sslmode=verify-full quando a opção Certificado de servidor confiável não estiver selecionada. Se você não fornecer um certificado, a conexão usará sslmode=verify-full com o armazenamento de confiança default da JVM.

Opções de configuração​

O sink gera um erro para opções não reconhecidas, JDBC_STREAMING_SINK_INVALID_OPTIONS.

Para as opções de configuração do coletor, incluindo as opções comuns e as opções para cada método de conexão, consulte as opções do coletor PostgreSQL.

Evolução do esquema aditivo​

No Databricks Runtime 19 e acima, defina .option("mergeSchema", "true") em seu gravador de transmissão antes de .start() ou .toTable() para adicionar colunas do DataFrame que estão faltando em uma tabela Lakebase existente ou uma tabela PostgreSQL externa. A opção é default para false. Sem ele, um DataFrame com novas colunas fará com que a query falhe.

O sink verifica novas colunas quando a query inicializa, antes de gravar os dados. Reinicie a query com o esquema do DataFrame atualizado e mergeSchema habilitado para adicionar novas colunas. O sink não verifica mudanças de esquema em cada limite de lote.

As novas colunas permitem nulos e usam os mapeamentos de tipo de dados para tabelas do Lakebase criadas automaticamente. As linhas existentes têm valores nulos nas colunas adicionadas. A identidade do banco de dados usada pelo sink deve ter permissão para alterar a tabela de destino. Para PostgreSQL externo, a tabela de destino já deve existir.

A evolução do esquema adiciona apenas colunas de nível superior. Ela não renomeia nem descarta colunas, não altera os tipos de coluna existentes nem amplia os tipos. Para fazer essas alterações, pare a query, altere a tabela de destino você mesmo e reinicie a query com um esquema de DataFrame compatível.

Mapeamentos de tipos de dados​

O coletor verifica se cada coluna do DataFrame é compatível com sua coluna de destino correspondente antes de gravar em um Lakebase existente ou em um banco de dados PostgreSQL externo.

A tabela a seguir contém os tipos com suporte no Databricks Runtime 18 LTS e acima:

Tipo Spark

Automatically created Lakebase table type

Compatible types in existing PostgreSQL tables

ByteType, ShortType

smallint

smallint

IntegerType

integer

integer

LongType

bigint

bigint

FloatType

real

real

DoubleType

double precision

double precision

DecimalType

numeric

numeric

StringType

text

varchar, text

VarcharType(n)

varchar(n)

varchar, text

CharType(n)

char(n)

char

BinaryType

bytea

bytea

BooleanType

boolean

boolean

TimestampType

timestamptz

timestamptz

TimestampNTZType

timestamp

timestamp

DateType

date

date

ArrayType, MapType, StructType, VariantType, NullType

jsonb

json, jsonb

Tipo Spark

Automatically created Lakebase table type

Compatible types in existing PostgreSQL tables

ByteType, ShortType

smallint

smallint

IntegerType

integer

integer

LongType

bigint

bigint

FloatType

real

real

DoubleType

double precision

double precision

DecimalType

numeric

numeric

StringType

text

varchar, text

VarcharType(n)

varchar(n)

varchar, text

CharType(n)

char(n)

char

BinaryType

bytea

bytea

BooleanType

boolean

boolean

TimestampType

timestamptz

timestamptz

TimestampNTZType

timestamp

timestamp

DateType

date

date

ArrayType, MapType, StructType, VariantType, NullType

jsonb

json, jsonb

A tabela a seguir contém os tipos com suporte no Databricks Runtime 19 e acima:

Tipo Spark

Automatically created Lakebase table type

Compatible types in existing PostgreSQL tables

DayTimeIntervalType, YearMonthIntervalType

interval

interval

Tipo Spark

Automatically created Lakebase table type

Compatible types in existing PostgreSQL tables

DayTimeIntervalType, YearMonthIntervalType

interval

interval

Comportamento de upsert​

A opção upsertkey identifica as colunas da chave principal da tabela de destino. Para uma tabela existente, as colunas em upsertkey devem corresponder exatamente à chave principal da tabela. Se você omitir a opção, o coletor (sink) lerá a chave principal da tabela. Para uma tabela Lakebase criada pelo coletor, upsertkey define a chave principal. Se você omitir a opção, o coletor cria a tabela sem uma chave principal.

Quando a tabela de destino tem uma chave primária, o coletor realiza upsert com a sintaxe INSERT INTO ... ON CONFLICT (<primary_key_columns>) DO UPDATE SET ... do PostgreSQL. Quando a tabela de destino não tem uma chave primária, o coletor executa inserções. O modo de saída de uma query não tem efeito sobre esse comportamento.

Todas as colunas de primary key devem estar presentes no DataFrame e usar tipos comparáveis, como tipos numéricos ou de strings.

Para controlar como os upserts atualizam colunas que não são chaves primárias, consulte Estratégias de merge para upserts.

Estratégias de merge para upserts​

No Databricks Runtime 19 acima, você pode usar estratégias de merge para controlar como o sink atualiza colunas que não são chaves key quando linhas têm a mesma chave key. Por exemplo, você pode manter o maior timestamp ou atualizar uma coluna somente quando um evento de entrada tiver um valor de ordenação mais novo.

As estratégias de merge aplicam-se apenas a upserts. Se a tabela de destino não tiver uma key primária, definir upsert.mergeStrategies ou upsert.defaultMergeStrategy causará um erro. Você pode atribuir estratégias apenas a colunas que não são key primária. Defina upsert.mergeStrategies como uma lista separada por vírgulas em formato column:strategy. Defina upsert.defaultMergeStrategy para configurar um default para colunas sem estratégias explícitas. Por default, o sink usa a estratégia latest.

Estratégias de merge suportadas​

Estratégia

Comportamento

latest

Use o valor mais recente por ordem de chegada. Este é o default.

earliest

Use o primeiro valor por ordem de chegada.

latestNonNull

Use o último valor não nulo por ordem de chegada.

earliestNonNull

Use o valor não nulo mais antigo por ordem de chegada.

greatest

Use o maior dos valores existentes e recebidos. Os valores nulos são ignorados, portanto um valor nulo recebido não substituirá um valor existente.

least

Use o menor dos valores existentes e de entrada. Valores nulos são ignorados, portanto, um valor de entrada nulo não substitui um valor existente.

latestBy(column)

Use o valor da linha com o maior valor na coluna de ordenação especificada. Veja Como latestBy e earliestBy lidam com empates e nulos.

earliestBy(column)

Use o valor da linha com o menor valor na coluna de ordenação especificada. Veja Como latestBy e earliestBy tratam empates e nulos.

Estratégia

Comportamento

latest

Use o valor mais recente por ordem de chegada. Este é o default.

earliest

Use o primeiro valor por ordem de chegada.

latestNonNull

Use o último valor não nulo por ordem de chegada.

earliestNonNull

Use o valor não nulo mais antigo por ordem de chegada.

greatest

Use o maior dos valores existentes e recebidos. Os valores nulos são ignorados, portanto um valor nulo recebido não substituirá um valor existente.

least

Use o menor dos valores existentes e de entrada. Valores nulos são ignorados, portanto, um valor de entrada nulo não substitui um valor existente.

latestBy(column)

Use o valor da linha com o maior valor na coluna de ordenação especificada. Veja Como latestBy e earliestBy lidam com empates e nulos.

earliestBy(column)

Use o valor da linha com o menor valor na coluna de ordenação especificada. Veja Como latestBy e earliestBy tratam empates e nulos.

Como latestBy e earliestBy lidam com empates e nulos​

latestBy(column) e earliestBy(column) escolher um valor comparando o valor de ordenação de entrada com aquele já armazenado na tabela. Para manter esse valor armazenado preciso, a coluna de ordenação deve usar a estratégia de correspondência, seja em upsert.mergeStrategies ou através de upsert.defaultMergeStrategy:

  • Para latestBy(column), a coluna de ordenação deve usar greatest.
  • Para earliestBy(column), a coluna de ordenação deve usar least.

Por exemplo, is_success:latestBy(last_updated_at) requer last_updated_at:greatest.

Quando ambos os valores de ordenação não são nulos, o latestBy(column) atualiza uma coluna apenas quando o valor de ordenação de entrada é estritamente maior (>) que o valor de ordenação existente. Para earliestBy(column), ele deve ser estritamente menor (<). Para ambas as estratégias, quando os valores de ordenação são iguais, o sink mantém o valor existente na coluna. Em um único lote, se várias linhas têm a mesma key primária e o mesmo valor de ordenação, o sink mantém a primeira linha que recebe.

Por exemplo, se is_success usa latestBy(last_updated_at) e uma linha de entrada tem o mesmo last_updated_at que a linha existente, o sink retém is_success existente, mesmo se o valor de entrada for diferente.

Para ambas as estratégias, os valores de ordenação não nulos têm precedência sobre os valores de ordenação nulos. Uma linha recebida com um valor de ordenação não nulo substitui um valor existente cujo valor de ordenação é nulo. Uma linha recebida com um valor de ordenação nulo não substitui um valor existente, inclusive quando o valor de ordenação existente também é nulo.

Exemplo: Lógica personalizada de upsert de modelo​

Considere uma tabela com as colunas id, last_updated_at, creation_date e is_success. Você pode querer expressar a seguinte lógica:

SQL
INSERT INTO events ...
ON CONFLICT (id) DO UPDATE
SET
-- Keep the most recent timestamp.
last_updated_at = GREATEST(events.last_updated_at, EXCLUDED.last_updated_at),

-- Keep the earliest non-null creation date.
creation_date = COALESCE(events.creation_date, EXCLUDED.creation_date),

-- Keep the value of is_success from the event with the most recent last_updated_at.
is_success = CASE
WHEN EXCLUDED.last_updated_at IS NOT NULL
AND (events.last_updated_at IS NULL
OR EXCLUDED.last_updated_at > events.last_updated_at)
THEN EXCLUDED.is_success
ELSE events.is_success
END;

Para modelar esta lógica, use as seguintes estratégias de merge:

Python
(df.writeStream
.format("postgresql")
.outputMode("update")
.option("databricks.connection", "<connection-name>")
.option("database", "<database>")
.option("dbtable", "<schema>.<table>")
.option("upsertkey", "id")
.option("upsert.mergeStrategies", "last_updated_at:greatest,creation_date:earliestNonNull,is_success:latestBy(last_updated_at)")
.option("checkpointLocation", "/Volumes/<catalog>/<schema>/<volume>/<checkpoint-name>")
.start()
)

Estratégias de merge default parametrizadas​

No Databricks Runtime 19 e acima, upsert.defaultMergeStrategy também aceita latestBy(column) e earliestBy(column). Use esses valores default para aplicar a mesma regra de ordenação a colunas que não são primary-key sem listar cada coluna em upsert.mergeStrategies. As estratégias explícitas por coluna substituem o default, exceto para a coluna de ordenação, como descrito abaixo.

Quando o default é latestBy(column), o sink aplica automaticamente greatest à coluna de ordenação. Quando o default é earliestBy(column), ele aplica automaticamente least. Se você atribuir explicitamente uma estratégia à coluna de ordenação, ela deverá corresponder à estratégia greatest ou least necessária.

O exemplo a seguir usa last_updated_at para selecionar valores para todas as outras colunas que não sejam key primária:

Python
(df.writeStream
.format("postgresql")
.outputMode("update")
.option("databricks.connection", "<connection-name>")
.option("database", "<database>")
.option("dbtable", "<schema>.<table>")
.option("upsertkey", "id")
.option("upsert.defaultMergeStrategy", "latestBy(last_updated_at)")
.option("checkpointLocation", "/Volumes/<catalog>/<schema>/<volume>/<checkpoint-name>")
.start()
)

Desempenho tuning​

Processamento em lote e contrapressão​

Um flush é acionado quando uma das condições é atendida:

  • O buffer atinge batchsize linhas, cujo padrão é 1000.
  • A idade do buffer excede batchinterval, que por default é 100 milliseconds.

Quando o banco de dados não consegue acompanhar a taxa de dados de entrada, o destino propaga contrapressão a montante para a fonte.

Latência e Taxa de transferência: Orientações

  • Para cargas de trabalho de baixa latência com modo em tempo real, diminua batchinterval para garantir um tempo máximo menor antes da liberação. Consulte Conceitos do modo em tempo real para obter conceitos e Exemplos do modo em tempo real para obter um exemplo de código.
  • Para cargas de trabalho de alta taxa de transferência, aumente batchsize para reduzir a sobrecarga de cada transação.

Comportamento da conexão​

O sink usa pooling de conexão em executors. Por padrão, cada tarefa usa uma conexão de banco de dados.

O Databricks recomenda que você use o valor default de 1 tarefa para cada conexão. Ao aumentar o número de tarefas para cada conexão, poderá causar contenções de conexão e aumentar as latências para conexões de alta taxa de transferência.

Para configurar a proporção de tarefas para conexões, defina a configuração do Spark spark.databricks.sql.streaming.jdbc.tasksPerConnection. Se o banco de dados de destino tiver um limite de conexão baixo, reduza o número de partições em ordem aleatória ou aumente spark.databricks.sql.streaming.jdbc.tasksPerConnection.

O sink tenta novamente, de forma automática, erros transitórios de JDBC, incluindo falhas de conexão, deadlocks e limitação de taxa. Se o coletor esgotar todas as tentativas, a consulta falhará.

Gatilhos e modos de saída compatíveis​

Gatilhos​

Esta tabela mostra o suporte para tipos de Trigger do Structured Streaming em compute classic e serverless:

Trigger

Compute clássico

Compute serverless (notebooks e jobs)

RealTime

Sim

Não

ProcessingTime

Sim

Não

AvailableNow

Sim

Sim

Once

Sim. Descontinuado. Use AvailableNow.

Sim. Descontinuado. Use AvailableNow.

Trigger

Compute clássico

Compute serverless (notebooks e jobs)

RealTime

Sim

Não

ProcessingTime

Sim

Não

AvailableNow

Sim

Sim

Once

Sim. Descontinuado. Use AvailableNow.

Sim. Descontinuado. Use AvailableNow.

Modos de saída​

Esta tabela mostra suporte para modos de saída de transmissão estructurada.

Modo de saída

Suportado

update

Sim

append

Sim. O comportamento é idêntico ao de update. A query faz um upsert quando a tabela de destino tem uma chave primária; caso contrário, a query insere. Consulte Comportamento de upsert.

complete

Não

Modo de saída

Suportado

update

Sim

append

Sim. O comportamento é idêntico ao de update. A query faz um upsert quando a tabela de destino tem uma chave primária; caso contrário, a query insere. Consulte Comportamento de upsert.

complete

Não

Limitações​

  • Para um banco de dados PostgreSQL externo conectado por meio de uma conexão do Unity Catalog, a tabela de destino já deve existir. O coletor cria automaticamente tabelas ausentes apenas no Lakebase.
  • Lakeflow pipelines are not supported.