Aller au contenu principal

Se connecter à Lakebase

Utilisez Structured Streaming pour écrire dans Lakebase ou dans une base de données PostgreSQL externe avec le traitement par batch intégré, les nouvelles tentatives automatiques et l'authentification gérée par le workspace.

Quand utiliser le puits Lakebase​

Utilisez le récepteur Lakebase pour des écritures en streaming à faible latence vers Lakebase ou une base de données PostgreSQL externe. Ce récepteur ne vous oblige pas à implémenter des fonctions foreach personnalisées pour gérer le traitement par batch, la gestion des connexions et la gestion des erreurs.

Quelques cas d’usage courants :

  • Mettez à jour les bases de données d'applications en temps réel pour les tableaux de bord opérationnels ou les fonctionnalités destinées aux clients.
  • Synchronisez les données qui changent continuellement, telles que les résultats de streaming agrégés ou filtrés, dans une base de données transactionnelle.
  • Écrivez le résultat d'une query Structured Streaming dans une table Lakebase avec une latence inférieure à la seconde en utilisant le mode temps réel.

Pour synchroniser les données de Lakebase vers les tables Delta Lake dans le Lakehouse, dans la direction inverse, consultez Lakebase Change Data Feed.

Exigences​

  • Databricks Runtime 18 LTS et versions supérieures.

    • Les connexions PostgreSQL externes nécessitent l’utilisation de Databricks Runtime 19 ou version supérieure et l’activation de la version préliminaire Custom JDBC on UC Compute .
    • Les types de données d'intervalle vous obligent à utiliser Databricks Runtime 19 et des versions ultérieures.
    • Les stratégies de Merge pour les upserts nécessitent l’utilisation de Databricks Runtime 19 et versions supérieures.
  • Compute classique avec des modes d'accès dédiés ou standard, ou compute serverless pour les notebooks ou les jobs. Sur le compute serverless, utilisez Trigger.AvailableNow(). Voir Streaming sur le compute serverless.

  • Une base de données Lakebase ou une connexion Unity Catalog à une base de données PostgreSQL externe.

Exigences relatives aux identifiants​

Pour toutes les cibles, Databricks recommande d'utiliser des noms de schémas, de tables, de colonnes et de colonnes de clé primaire qui start par une lettre ou un trait de soulignement et ne contiennent que des lettres, des chiffres et des traits de soulignement. Le récepteur applique ces exigences lorsqu'il crée automatiquement une table Lakebase. Pour utiliser des identifiants ne respectant pas ces exigences, créez la table cible avant de start la query.

Se connecter à une base de données​

Le sink Lakebase prend en charge les méthodes de connexion suivantes :

Tables Lakebase non enregistrées dans Unity Catalog​

Pour les tables Lakebase non enregistrées auprès d'Unity Catalog, le connecteur gère automatiquement les identifiants et utilise l'identité de l'utilisateur ou du Service Principal Databricks exécutant la requête. Si la table n'existe pas, le connecteur crée la table.

Pour écrire dans une table Lakebase, utilisez les options endpoint et 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()
)

Remplacez les espaces réservés suivants :

  • <project-id>.<branch-id>.<endpoint-id>: votre Endpoint Lakebase. Trouvez les trois valeurs dans le Nom de la ressource du menu Obtenir l'ID de l'onglet Compute, qui a le projects/<project-id>/branches/<branch-id>/endpoints/<endpoint-id> format. Voir les identifiants compute.
  • <database>: facultatif. Le nom de la base de données PostgreSQL cible. Default to databricks_postgres. Voir Gérer les bases de données.
  • <schema>.<table>: La table cible au format schema.table. Si vous omettez le schéma, le récepteur utilise le schéma public. Pour la création automatique de tables, utilisez des identifiants qui start par une lettre ou un trait de soulignement et ne contiennent que des lettres, des chiffres et des traits de soulignement.
  • <primary-key-columns>: facultatif. Une liste séparée par des virgules de toutes les colonnes de la clé primaire de la table cible, par exemple id ou user_id,event_type. Voir Comportement d’upsert.
  • /Volumes/<catalog>/<schema>/<volume>/<checkpoint-name>: un chemin de volume Unity Catalog où la query stocke son point de contrôle. Vous pouvez également utiliser un URI de stockage d'objets cloud. L'emplacement doit être un stockage sur lequel vous pouvez écrire, pas un disque local, et doit être unique à chaque query de streaming. Ceci est indépendant de la table cible. Consultez la section Points de contrôle Structured Streaming.

Pour les configurations optionnelles, telles que batchsize et batchinterval, consultez les options de récepteur PostgreSQL.

PostgreSQL externe avec des identifiants Unity Catalog​

info

Aperçu

Cette fonctionnalité est en Aperçu public. Les administrateurs du workspace peuvent contrôler l'accès à Custom JDBC on UC Compute à partir de la page Previews . Consultez Gérer les aperçus Databricks.

Utilisez une connexion Unity Catalog pour vous authentifier auprès d'une base de données PostgreSQL externe sans stocker d'identifiants dans votre code. La table cible doit déjà exister.

Créer une connexion de type POSTGRESQL, voir Créer une connexion. L’utilisateur ou le Service Principal Databricks exécutant la query doit disposer de USE CONNECTION sur la connexion.

Pour écrire dans la table PostgreSQL, utilisez les options databricks.connection, database et dbtable :

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()
)

Remplacez les espaces réservés suivants :

  • <connection-name>: le nom de la connexion Unity Catalog.
  • <database>: Le nom de la base de données PostgreSQL cible.
  • <schema>.<table>: La table cible existante au format schema.table. Si vous omettez le schéma, le récepteur utilise le schéma public.
  • <primary-key-columns>: facultatif. Une liste séparée par des virgules de toutes les colonnes de la clé primaire de la table cible, par exemple id ou user_id,event_type. Voir Comportement d’upsert.
  • /Volumes/<catalog>/<schema>/<volume>/<checkpoint-name>: un chemin de volume Unity Catalog où la query stocke son point de contrôle. Vous pouvez également utiliser un URI de stockage d'objets cloud. L'emplacement doit être un stockage sur lequel vous pouvez écrire, pas un disque local, et doit être unique à chaque query de streaming. Ceci est indépendant de la table cible. Consultez la section Points de contrôle Structured Streaming.

Les connexions PostgreSQL utilisent toujours TLS. La vérification du certificat suit les paramètres de la connexion Unity Catalog, que vous choisissez lorsque vous créez la connexion:

  • Certificat de serveur de confiance : lorsque cette option est sélectionnée, la connexion utilise sslmode=require, ce qui chiffre la connexion sans vérifier le certificat du serveur.
  • Certificat de serveur fourni par l’utilisateur : Fournissez un certificat de serveur encodé au format PEM à utiliser avec sslmode=verify-full lorsque Certificat de serveur de confiance n’est pas sélectionné. Si vous ne fournissez pas de certificat, la connexion utilise sslmode=verify-full avec le magasin de confiance par default de la JVM.

Options de configuration​

Le récepteur génère une erreur pour les options non reconnues, JDBC_STREAMING_SINK_INVALID_OPTIONS.

Pour connaître les options de configuration du récepteur, y compris les options courantes et les options pour chaque méthode de connexion, consultez les options du récepteur PostgreSQL.

Mappages de types de données​

Le récepteur vérifie que chaque colonne DataFrame est compatible avec sa colonne cible correspondante avant d’écrire dans une table Lakebase ou PostgreSQL externe existante.

Le tableau suivant contient les types pris en charge dans Databricks Runtime 18 LTS et versions supérieures :

Type Spark

Type de table Lakebase créé automatiquement

Types compatibles dans les tables PostgreSQL existantes

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

Type Spark

Type de table Lakebase créé automatiquement

Types compatibles dans les tables PostgreSQL existantes

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

Le tableau suivant contient les types pris en charge dans Databricks Runtime 19 et versions supérieures :

Type Spark

Type de table Lakebase créé automatiquement

Types compatibles dans les tables PostgreSQL existantes

DayTimeIntervalType, YearMonthIntervalType

interval

interval

Type Spark

Type de table Lakebase créé automatiquement

Types compatibles dans les tables PostgreSQL existantes

DayTimeIntervalType, YearMonthIntervalType

interval

interval

Comportement d’upsert​

L’option upsertkey identifie les colonnes de clé primaire de la table cible. Pour une table existante, les colonnes de upsertkey doivent correspondre exactement à la clé primaire de la table. Si vous omettez l’option, le récepteur lit la clé primaire à partir de la table. Pour une table Lakebase créée par le récepteur, upsertkey définit la clé primaire. Si vous omettez l’option, le récepteur crée la table sans clé primaire.

Lorsque la table cible possède une clé primaire, la destination effectue des upserts avec la syntaxe INSERT INTO ... ON CONFLICT (<primary_key_columns>) DO UPDATE SET ... de PostgreSQL. Lorsque la table cible ne possède aucune clé primaire, la destination effectue des insertions. Le mode de sortie d’une query n’a aucun effet sur ce comportement.

Toutes les colonnes de clé primaire doivent être présentes dans le DataFrame et utiliser des types comparables, tels que des types numériques ou de chaînes de caractères.

Pour contrôler la manière dont les upserts mettent à jour les colonnes sans clé primaire, consultez Stratégies de Merge pour les upserts.

Stratégies de Merge pour les upserts​

Dans Databricks Runtime 19 et versions ultérieures, vous pouvez utiliser des stratégies de Merge pour contrôler la manière dont le récepteur met à jour les colonnes non clés primaires lorsque des lignes ont la même clé primaire. Par exemple, vous pouvez conserver le plus grand timestamp ou mettre à jour une colonne uniquement lorsqu'un événement entrant a une valeur de classement plus récente.

Les stratégies de Merge s’appliquent uniquement aux upserts. Si la table cible n’a pas de clé primaire, définir upsert.mergeStrategies ou upsert.defaultMergeStrategy entraîne une erreur. Vous pouvez uniquement assigner des stratégies aux colonnes ne constituant pas une clé primaire. Définissez upsert.mergeStrategies sur une liste séparée par des virgules au format column:strategy. Définissez upsert.defaultMergeStrategy pour configurer une default pour les colonnes sans stratégies explicites. upsert.defaultMergeStrategy n'accepte pas latestBy ou earliestBy. default, le récepteur utilise la stratégie latest.

Stratégies de Merge prises en charge​

Stratégie

Comportement

latest

Utilisez la valeur la plus récente selon l’ordre d’arrivée. C’est la valeur default.

earliest

Utiliser la première valeur par ordre d’arrivée.

latestNonNull

Utilisez la dernière valeur non nulle par ordre d'arrivée.

earliestNonNull

Utiliser la première valeur non nulle par ordre d'arrivée.

greatest

Utiliser la plus grande des valeurs existantes et entrantes. Les valeurs nulles sont ignorées ; une valeur entrante nulle ne remplace donc pas une valeur existante.

least

Utilisez la plus petite des valeurs existantes et entrantes. Les valeurs nulles sont ignorées. Ainsi, une valeur entrante nulle ne remplace pas une valeur existante.

latestBy(column)

Utilisez la valeur de la ligne ayant la valeur la plus élevée dans la colonne de tri spécifiée. Voir Comment latestBy et earliestBy gèrent les égalités et les valeurs nulles.

earliestBy(column)

Utilisez la valeur de la ligne avec la valeur la plus faible dans la colonne de tri spécifiée. Voir Comment latestBy et earliestBy gèrent les égalités et les valeurs nulles.

Stratégie

Comportement

latest

Utilisez la valeur la plus récente selon l’ordre d’arrivée. C’est la valeur default.

earliest

Utiliser la première valeur par ordre d’arrivée.

latestNonNull

Utilisez la dernière valeur non nulle par ordre d'arrivée.

earliestNonNull

Utiliser la première valeur non nulle par ordre d'arrivée.

greatest

Utiliser la plus grande des valeurs existantes et entrantes. Les valeurs nulles sont ignorées ; une valeur entrante nulle ne remplace donc pas une valeur existante.

least

Utilisez la plus petite des valeurs existantes et entrantes. Les valeurs nulles sont ignorées. Ainsi, une valeur entrante nulle ne remplace pas une valeur existante.

latestBy(column)

Utilisez la valeur de la ligne ayant la valeur la plus élevée dans la colonne de tri spécifiée. Voir Comment latestBy et earliestBy gèrent les égalités et les valeurs nulles.

earliestBy(column)

Utilisez la valeur de la ligne avec la valeur la plus faible dans la colonne de tri spécifiée. Voir Comment latestBy et earliestBy gèrent les égalités et les valeurs nulles.

Comment latestBy et earliestBy gèrent les égalités et les valeurs nulles​

latestBy(column) et earliestBy(column) choisissez une valeur en comparant la valeur de classement entrante à celle déjà stockée dans la table. Pour maintenir cette valeur stockée à jour, la colonne de classement doit utiliser la stratégie correspondante, soit dans upsert.mergeStrategies, soit par le biais de upsert.defaultMergeStrategy:

  • Pour latestBy(column), la colonne de tri doit utiliser greatest.
  • Pour earliestBy(column), la colonne de tri doit utiliser least.

Par exemple, is_success:latestBy(last_updated_at) nécessite last_updated_at:greatest.

Lorsque les deux valeurs de tri ne sont pas nulles, latestBy(column) met à jour une colonne uniquement lorsque la valeur de tri entrante est strictement supérieure (>) à la valeur de tri existante. Pour earliestBy(column), elle doit être strictement inférieure (<). Pour les deux stratégies, lorsque les valeurs de tri sont égales, le récepteur conserve la valeur existante de la colonne. Au sein d'un même batch, si plusieurs lignes ont la même clé primaire et la même valeur de tri, le récepteur conserve la première ligne qu'il reçoit.

Par exemple, si is_success utilise latestBy(last_updated_at) et qu'une ligne entrante a le même last_updated_at qu'une ligne existante, le récepteur conserve le is_success existant, même si la valeur entrante est différente.

Pour les deux stratégies, les valeurs de classement non nulles sont prioritaires sur les valeurs de classement nulles. Une ligne entrante avec une valeur de classement non nulle remplace une valeur existante dont la valeur de classement est nulle. Une ligne entrante avec une valeur de classement nulle ne remplace pas une valeur existante, même lorsque la valeur de classement existante est également nulle.

Exemple : logique d’upsert personnalisée du modèle​

Considérez une table avec les colonnes id, last_updated_at, creation_date et is_success. Vous pourriez vouloir exprimer la logique suivante :

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;

Pour modéliser cette logique, utilisez les stratégies de Merge suivantes :

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()
)

Optimisation des performances​

Traitement par batch et contre-pression​

Un vidage est Trigger lorsque l'une ou l'autre des conditions est remplie :

  • La mémoire tampon atteint batchsize lignes, qui est par default à 1000.
  • L'âge du tampon dépasse batchinterval, qui est 100 milliseconds default.

Lorsque la base de données ne peut pas suivre le débit de données entrant, le récepteur propage une rétropression en amont vers la source.

Conseils sur la latence et le throughput :

  • Pour les charges de travail à faible latence avec le mode temps réel, diminuez batchinterval afin de garantir un temps maximal plus court avant le vidage. Consultez Concepts du mode temps réel pour les concepts et Exemples du mode temps réel pour un exemple de code.
  • Pour les charges de travail à haut throughput, augmentez batchsize afin de réduire la surcharge pour chaque transaction.

Comportement de connexion​

Le récepteur utilise le pool de connexions sur les exécuteurs. By default, chaque tâche utilise une connexion de base de données.

Databricks vous recommande d'utiliser la valeur par default de 1 tâche pour chaque connexion. Si vous augmentez le nombre de tâches pour chaque connexion, vous pourriez provoquer des contentions de connexion et augmenter les latences pour les connexions à haut throughput.

Pour configurer le rapport entre les tâches et les connexions, définissez la configuration Spark spark.databricks.sql.streaming.jdbc.tasksPerConnection. Si la base de données cible a une faible limite de connexions, réduisez le nombre de partitions de brassage ou augmentez spark.databricks.sql.streaming.jdbc.tasksPerConnection.

Le sink réessaie automatiquement les erreurs JDBC transitoires, y compris les échecs de connexion, les interblocages et la limitation du débit. Si le récepteur épuise toutes les tentatives, la query échoue.

Trigger et modes de sortie pris en charge​

Trigger​

Ce tableau indique la prise en charge des types de trigger Structured Streaming sur le compute classique et serverless :

Déclencheur

Classic Compute

Compute Serverless (notebooks et jobs)

RealTime

Oui

Non

ProcessingTime

Oui

Non

AvailableNow

Oui

Oui

Once

Oui. Obsolète. Utilisez AvailableNow.

Oui. Obsolète. Utilisez AvailableNow.

Déclencheur

Classic Compute

Compute Serverless (notebooks et jobs)

RealTime

Oui

Non

ProcessingTime

Oui

Non

AvailableNow

Oui

Oui

Once

Oui. Obsolète. Utilisez AvailableNow.

Oui. Obsolète. Utilisez AvailableNow.

Modes de sortie​

Ce tableau indique la prise en charge des modes de sortie de Structured Streaming :

Mode de résultat

Pris en charge

update

Oui

append

Oui. Le comportement est identique à update. La query effectue un upsert lorsque la table cible possède une clé primaire ; sinon, la query réalise une insertion. Consultez Comportement de l’upsert.

complete

Non

Mode de résultat

Pris en charge

update

Oui

append

Oui. Le comportement est identique à update. La query effectue un upsert lorsque la table cible possède une clé primaire ; sinon, la query réalise une insertion. Consultez Comportement de l’upsert.

complete

Non

Limitations​

  • Pour une base de données PostgreSQL externe connectée via une connexion Unity Catalog, la table cible doit déjà exister. Le récepteur crée automatiquement les tables manquantes uniquement dans Lakebase.
  • Les LakeFlow Pipelines ne sont pas pris en charge.