Important
Pour accéder aux API REST Databricks, vous devez vous authentifier.
Pour configurer des entrepôts SQL individuels, utilisez l’API Entrepôts SQL. Pour configurer tous les entrepôts SQL, utilisez l’API Entrepôts SQL globale.
Spécifications
- Pour créer des entrepôts SQL, vous devez avoir l’autorisation Créer un cluster, qui est activée dans l’espace de travail Science & Ingénierie des données.
- Pour gérer un entrepôt SQL, vous devez avoir l’autorisation Peut gérer dans Databricks SQL pour l’entrepôt.
Utilisation de l’API Warehouses avec des entrepôts SQL serverless
Vous pouvez utiliser l’API SQL Warehouse pour gérer les entrepôts SQL serverless. Avant de pouvoir créer des entrepôts SQL serverless, vous devez activer la fonctionnalité de l’espace de travail. Pour plus d’informations sur le calcul Serverless, consultez Calcul Serverless.
- Si vous utilisez des API Databricks pour créer un entrepôt SQL, elles seront serverless par défaut si la fonctionnalité serverless est activée pour votre espace de travail. Pour créer un entrepôt SQL pro ou classique, ajoutez le paramètre
enable_serverless_compute dans la demande d’API et définissez-le sur false. Vous pouvez ajouter ce paramètre à la fois à la demande Créer l’API et Modifier l’API.
- Pour passer d’un entrepôt SQL serverless à un entrepôt SQL pro ou classique, modifiez l’entrepôt et définissez
enable_serverless_compute sur false.
- Pour les entrepôts SQL serverless, les stratégies d’instance spot (
spot_instance_policy) ne sont pas prises en charge et ignorées.
Notez que pour le champ Arrêt automatique (auto_stop_mins), les valeurs par défaut et minimales sont différentes pour les entrepôts SQL serverless, pro et classiques.
API Entrepôts SQL
Utilisez cette API pour créer, modifier, lister et obtenir des entrepôt SQL.
Dans cette section :
Créer
| Point de terminaison |
Méthode HTTP |
2.0/sql/warehouses/ |
POST |
2.0/sql/endpoints/ (déconseillé) |
POST |
Créer un entrepôt SQL.
| Nom du champ |
Type |
Description |
name |
STRING |
Nom de l’entrepôt SQL. Elle doit être unique. Ce champ doit obligatoirement être renseigné. |
cluster_size |
STRING |
Taille des clusters alloués à l’entrepôt : "2X-Small", "X-Small", "Small", "Medium", "Large", "X-Large", "2X-Large", "3X-Large", "4X-Large". Pour la mise en correspondance entre la taille du cluster et celle de l’instance, consultez Taille du cluster. Ce champ doit obligatoirement être renseigné. |
min_num_clusters |
INT32 |
Nombre minimal de clusters disponibles quand un entrepôt SQL est en cours d’exécution. La valeur par défaut est 1. |
max_num_clusters |
INT32 |
Nombre maximal de clusters disponibles quand un entrepôt SQL est en cours d’exécution. Ce champ doit obligatoirement être renseigné. Si l’équilibrage de charge sur plusieurs clusters n’est pas activé, cela se limite à 1. |
auto_stop_mins |
INT32 |
Délai en minutes jusqu’à ce qu’un entrepôt SQL inactif arrête tous les clusters et s’arrête lui-même. Ce champ est facultatif. La définition de cette valeur sur 0 désactive l’arrêt automatique. Pour les entrepôts SQL pro et classiques, la valeur par défaut est de 15 et la valeur minimale est de 10. Pour les entrepôts SQL serverless, la valeur par défaut est de 10 et la valeur minimale est de 1. Databricks recommande de définir ce paramètre sur 10 minutes pour une utilisation classique. Des valeurs inférieures (comme 1) entraînent le redémarrage plus fréquent de Databricks de l’entrepôt, ce qui n’est pas recommandé. Notez que le minimum est de 5 minutes lors de la création de l’entrepôt dans l’interface utilisateur. Cela s’applique uniquement aux entrepôts inactifs dans l’état EN COURS D’EXÉCUTION. Si un entrepôt n’est pas en mesure d’acquérir des ressources de calcul sous-jacentes et qu’il reste dans l’état DÉMARRAGE, il est arrêté automatiquement après 75 minutes. |
tags |
WarehouseTags |
Paires clé-valeur qui décrivent l’entrepôt. Azure Databricks marque toutes les ressources d’entrepôt avec ces étiquettes. Ce champ est facultatif. |
| enable_photon |
BOOLEAN |
Si les requêtes sont exécutées sur un moteur vectoriel natif qui accélère l’exécution des requêtes. Ce champ est facultatif. Par défaut, il s’agit de true. |
enable_serverless_compute |
BOOLEAN |
Indique si cet entrepôt SQL est un entrepôt SQL serverless. Pour utiliser un entrepôt SQL Serverless, vous devez activer les entrepôts SQL serverless pour l’espace de travail. Ce champ est facultatif. Si les entrepôts SQL serverless sont désactivés pour l’espace de travail, la valeur par défaut est false. Si les entrepôts SQL serverless sont désactivés pour l’espace de travail, la valeur par défaut est true. |
warehouse_type |
WarehouseType |
Type d’entrepôt SQL de l’entrepôt. Ce champ est facultatif. Pour un entrepôt SQL non serverless, les types d’entrepôts classique et pro sont des options viables, et le type d’entrepôt par défaut est classique. Pour un entrepôt serverless, ce champ ne peut être que pro. Pour obtenir une liste des valeurs valides, consultez la section "WarehouseType" plus loin dans cet article. |
channel |
Channel |
S’il faut utiliser la version actuelle de la capacité de calcul de l’entrepôt SQL ou la préversion. Les versions préliminaires vous permettent d’essayer des fonctionnalités avant qu’elles ne deviennent la norme pour Databricks SQL. En général, les versions préliminaires sont promues à la version actuelle deux semaines après la mise en production de la version préliminaire initiale, mais certaines versions préliminaires peuvent durer plus longtemps. Pour en savoir plus sur les fonctionnalités de la version préliminaire la plus récente, consultez les notes de publication. Databricks ne recommande pas l’utilisation de versions préliminaires pour les charges de travail de production. Ce champ est facultatif. Par défaut, il s’agit de CHANNEL_NAME_CURRENT. |
spot_instance_policy |
WarehouseSpotInstancePolicy |
Stratégie de spot à utiliser pour allouer les instances aux clusters. Ce champ est facultatif. Ce champ n’est pas utilisé si l’entrepôt SQL est un entrepôt SQL serverless. |
Exemple de requête
{
"name": "My SQL Warehouse",
"cluster_size": "Medium",
"min_num_clusters": 1,
"max_num_clusters": 10,
"tags": {
"custom_tags": [
{
"key": "mykey",
"value": "myvalue"
}
]
},
"spot_instance_policy":"COST_OPTIMIZED",
"enable_photon": "true",
"enable_serverless_compute": "true",
"warehouse_type": "PRO",
"channel": {
"name": "CHANNEL_NAME_CURRENT"
}
}
Exemple de réponse
{
"id": "0123456789abcdef"
}
DELETE
| Point de terminaison |
Méthode HTTP |
2.0/sql/warehouses/{id} |
DELETE |
2.0/sql/endpoints/{id} (déconseillé) |
DELETE |
Supprimer un entrepôt SQL.
Modifier
| Point de terminaison |
Méthode HTTP |
2.0/sql/warehouses/{id}/edit |
POST |
2.0/sql/endpoints/{id}/edit (déconseillé) |
POST |
Modifier un entrepôt SQL. Tous les champs sont facultatifs. Les champs manquants ont pour valeur par défaut les valeurs actuelles.
| Nom du champ |
Type |
Description |
id |
STRING |
ID de l’entrepôt SQL. |
name |
STRING |
Nom de l’entrepôt SQL. |
cluster_size |
STRING |
Taille des clusters alloués à l’entrepôt : "2X-Small", "X-Small", "Small", "Medium", "Large", "X-Large", "2X-Large", "3X-Large", "4X-Large". Pour la mise en correspondance entre la taille du cluster et celle de l’instance, consultez Taille du cluster. |
min_num_clusters |
INT32 |
Nombre minimal de clusters disponibles quand un entrepôt SQL est en cours d’exécution. |
max_num_clusters |
INT32 |
Nombre maximal de clusters disponibles quand un entrepôt SQL est en cours d’exécution. Ce champ doit obligatoirement être renseigné. Si l’équilibrage de charge sur plusieurs clusters n’est pas activé, limité à 1. |
auto_stop_mins |
INT32 |
Délai en minutes jusqu’à ce qu’un entrepôt SQL inactif arrête tous les clusters et s’arrête lui-même. La définition de cette valeur sur 0 désactive l’arrêt automatique. Pour les entrepôts SQL pro et classiques, la valeur par défaut est de 15 et la valeur minimale est de 10. Pour les entrepôts SQL serverless, la valeur par défaut est de 10 et la valeur minimale est de 1. Databricks recommande de définir ce paramètre sur 10 minutes pour une utilisation classique. Des valeurs inférieures (comme 1) entraînent le redémarrage plus fréquent de Databricks de l’entrepôt, ce qui n’est pas recommandé. Notez que le minimum est de 5 minutes lors de la création de l’entrepôt dans l’interface utilisateur. Cela s’applique uniquement aux entrepôts inactifs dans l’état EN COURS D’EXÉCUTION. Si un entrepôt n’est pas en mesure d’acquérir des ressources de calcul sous-jacentes et qu’il reste dans l’état DÉMARRAGE, il est arrêté automatiquement après 75 minutes. |
tags |
WarehouseTags |
Paires clé-valeur qui décrivent l’entrepôt. |
spot_instance_policy |
WarehouseSpotInstancePolicy |
Stratégie de spot à utiliser pour allouer les instances aux clusters. |
enable_photon |
BOOLEAN |
Si les requêtes sont exécutées sur un moteur vectoriel natif qui accélère l’exécution des requêtes. |
enable_serverless_compute |
BOOLEAN |
Indique si cet entrepôt SQL est un entrepôt SQL serverless. Pour utiliser un entrepôt SQL Serverless, vous devez activer les entrepôts SQL serverless pour l’espace de travail. |
warehouse_type |
WarehouseType |
Type d’entrepôt SQL de l’entrepôt. Ce champ est facultatif. Pour un entrepôt SQL non serverless, les types d’entrepôts classique et pro sont des options viables, et le type d’entrepôt par défaut est classique. Pour un entrepôt serverless, ce champ ne peut être que pro. Pour obtenir une liste des valeurs valides, consultez la section "WarehouseType" plus loin dans cet article. |
channel |
Channel |
S’il faut utiliser la version actuelle de la capacité de calcul de l’entrepôt SQL ou la préversion. Les versions préliminaires vous permettent d’essayer des fonctionnalités avant qu’elles ne deviennent la norme pour Databricks SQL. En général, les versions préliminaires sont promues à la version actuelle deux semaines après la mise en production de la version préliminaire initiale, mais certaines versions préliminaires peuvent durer plus longtemps. Pour en savoir plus sur les fonctionnalités de la version préliminaire la plus récente, consultez les notes de publication. Databricks ne recommande pas l’utilisation de versions préliminaires pour les charges de travail de production. Ce champ est facultatif. Par défaut, il s’agit de CHANNEL_NAME_CURRENT. |
Exemple de requête
{
"name": "My Edited SQL warehouse",
"cluster_size": "Large",
"auto_stop_mins": 60
}
Obtenir
| Point de terminaison |
Méthode HTTP |
2.0/sql/warehouses/{id} |
GET |
2.0/sql/endpoints/{id} (déconseillé) |
GET |
Récupérer les informations pour un entrepôt SQL.
| Nom du champ |
Type |
Description |
id |
STRING |
ID d’entrepôt SQL. |
name |
STRING |
Nom de l’entrepôt SQL. |
cluster_size |
STRING |
Taille des clusters alloués à l’entrepôt : "2X-Small", "X-Small", "Small", "Medium", "Large", "X-Large", "2X-Large", "3X-Large", "4X-Large". Pour la mise en correspondance entre la taille du cluster et celle de l’instance, consultez Taille du cluster. |
auto_stop_mins |
INT32 |
Le nombre de minutes jusqu’à ce qu’un entrepôt SQL inactif arrête tous les clusters et s’arrête lui-même. |
spot_instance_policy |
WarehouseSpotInstancePolicy |
Stratégie de spot à utiliser pour allouer les instances aux clusters. |
num_clusters |
INT32 |
Nombre de clusters alloués à l’entrepôt. |
min_num_clusters |
INT32 |
Nombre minimal de clusters disponibles quand un entrepôt SQL est en cours d’exécution. |
max_num_clusters |
INT32 |
Nombre maximal de clusters disponibles quand un entrepôt SQL est en cours d’exécution. |
num_active_sessions |
INT32 |
Nombre de sessions JDBC et ODBC actives en cours d’exécution sur l’entrepôt SQL. |
state |
WarehouseState |
État de l’entrepôt SQL. |
creator_name |
STRING |
Adresse e-mail de l’utilisateur qui a créé l’entrepôt. |
creator_id |
STRING |
ID Azure Databricks de l’utilisateur qui a créé l’entrepôt. |
jdbc_url |
STRING |
URL utilisée pour envoyer des commandes SQL à l’entrepôt SQL en utilisant JDBC. |
odbc_params |
ODBCParams |
Informations relatives à l’hôte, au chemin, au protocole et au port nécessaires pour envoyer des commandes SQL à l’entrepôt SQL en utilisant ODBC. |
tags |
WarehouseTags |
Paires clé-valeur qui décrivent l’entrepôt. |
health |
WarehouseHealth |
Intégrité de l’entrepôt. |
enable_photon |
BOOLEAN |
Si les requêtes sont exécutées sur un moteur vectoriel natif qui accélère l’exécution des requêtes. |
enable_serverless_compute |
BOOLEAN |
Indique si cet entrepôt SQL est un entrepôt SQL serverless. Pour utiliser un entrepôt SQL Serverless, vous devez activer les entrepôts SQL serverless pour l’espace de travail. Ce champ est facultatif. Si les entrepôts SQL serverless sont désactivés pour l’espace de travail, la valeur par défaut est false. Si les entrepôts SQL serverless sont désactivés pour l’espace de travail, la valeur par défaut est true. |
warehouse_type |
WarehouseType |
Type d’entrepôt SQL de l’entrepôt. Ce champ est facultatif. Pour un entrepôt SQL non serverless, les types d’entrepôts classique et pro sont des options viables, et le type d’entrepôt par défaut est classique. Pour un entrepôt serverless, ce champ ne peut être que pro. Pour obtenir une liste des valeurs valides, consultez la section "WarehouseType" plus loin dans cet article. |
channel |
Channel |
Si l’entrepôt SQL utilise la version actuelle de la capacité de calcul de l’entrepôt SQL ou la préversion. Les versions préliminaires vous permettent d’essayer des fonctionnalités avant qu’elles ne deviennent la norme pour Databricks SQL. En général, les versions préliminaires sont promues à la version actuelle deux semaines après la mise en production de la version préliminaire initiale, mais certaines versions préliminaires peuvent durer plus longtemps. Pour en savoir plus sur les fonctionnalités de la version préliminaire la plus récente, consultez les notes de publication. Databricks ne recommande pas l’utilisation de versions préliminaires pour les charges de travail de production. Ce champ est facultatif. Par défaut, il s’agit de CHANNEL_NAME_CURRENT. |
Exemple de réponse
{
"id": "7f2629a529869126",
"name": "MyWarehouse",
"cluster_size": "Small",
"min_num_clusters": 1,
"max_num_clusters": 1,
"auto_stop_mins": 0,
"auto_resume": true,
"num_clusters": 0,
"num_active_sessions": 0,
"state": "STOPPED",
"creator_name": "user@example.com",
"jdbc_url": "jdbc:spark://hostname.staging.cloud.databricks.com:443/default;transportMode=http;ssl=1;AuthMech=3;httpPath=/sql/1.0/warehouses/7f2629a529869126;",
"odbc_params": {
"hostname": "hostname.cloud.databricks.com",
"path": "/sql/1.0/warehouses/7f2629a529869126",
"protocol": "https",
"port": 443
},
"tags": {
"custom_tags": [
{
"key": "mykey",
"value": "myvalue"
}
]
},
"spot_instance_policy": "COST_OPTIMIZED",
"enable_photon": true,
"cluster_size": "Small",
"enable_serverless_compute": true,
"warehouse_type": "PRO",
"channel": {
"name": "CHANNEL_NAME_CURRENT"
}
}
List
| Point de terminaison |
Méthode HTTP |
2.0/sql/warehouses/ |
GET |
2.0/sql/endpoints/ (déconseillé) |
GET |
Lister tous les entrepôts SQL de l’espace de travail.
Exemple de réponse
{
"warehouses": [
{ "id": "123456790abcdef", "name": "My SQL warehouse", "cluster_size": "Medium" },
{ "id": "098765321fedcba", "name": "Another SQL warehouse", "cluster_size": "Large" }
]
}
Remarque : Si vous utilisez l’API dépréciée 2.0/sql/endpoints/, le champ de réponse de plus haut niveau sera « points de terminaison » au lieu de « entrepôts ».
Démarrer
| Point de terminaison |
Méthode HTTP |
2.0/sql/warehouses/{id}/start |
POST |
2.0/sql/endpoints/{id}/start (déconseillé) |
POST |
Démarrer un entrepôt SQL.
Arrêter
| Point de terminaison |
Méthode HTTP |
2.0/sql/warehouses/{id}/stop |
POST |
2.0/sql/endpoints/{id}/stop (déconseillé) |
POST |
Arrêter un entrepôt SQL.
API Entrepôts SQL globale
Utilisez cette API pour configurer la stratégie de sécurité, les propriétés d’accès aux données et les paramètres de configuration pour tous les entrepôts SQL.
Dans cette section :
Obtenir
| Point de terminaison |
Méthode HTTP |
/2.0/sql/config/warehouses |
GET |
/2.0/sql/config/endpoints (déconseillé) |
GET |
Obtenir la configuration de tous les entrepôts SQL.
Exemple de réponse
{
"security_policy": "DATA_ACCESS_CONTROL",
"data_access_config": [
{
"key": "spark.sql.hive.metastore.jars",
"value": "/databricks/hive_metastore_jars/*"
}
],
"sql_configuration_parameters": {
"configuration_pairs": [
{
"key" : "legacy_time_parser_policy",
"value": "LEGACY"
}
]
}
}
Modifier
Modifier la configuration de tous les entrepôts SQL.
Important
- Tous les champs sont obligatoires.
- Le fait d’appeler cette méthode redémarre tous les entrepôts SQL en cours d’exécution.
| Point de terminaison |
Méthode HTTP |
/2.0/sql/config/warehouses |
PUT |
/2.0/sql/config/endpoints (déconseillé) |
PUT |
Exemple de requête
{
"data_access_config": [
{
"key": "spark.sql.hive.metastore.jars",
"value": "/databricks/hive_metastore_jars/*"
}
],
"sql_configuration_parameters": {
"configuration_pairs": [
{
"key" : "legacy_time_parser_policy",
"value": "LEGACY"
}
]
}
}
Structures de données
Dans cette section :
WarehouseConfPair
| Nom du champ |
Type |
Description |
key |
STRING |
Nom de la clé de configuration. |
value |
STRING |
Valeur de la clé de configuration. |
WarehouseHealth
| Nom du champ |
Type |
Description |
status |
WarehouseStatus |
État de l’entrepôt. |
message |
STRING |
Message descriptif de l’état d’intégrité. Contient des informations sur les erreurs qui contribuent à l’état d’intégrité actuel. |
WarehouseSecurityPolicy
WarehouseSpotInstancePolicy
| Option |
Description |
COST_OPTIMIZED |
Utilisez une instance à la demande pour le pilote du cluster et des instances de spot pour les Exécuteurs du cluster. Le prix maximum de la machine virtuelle spot est de 100 % du prix à la demande. Il s’agit de la stratégie par défaut. |
RELIABILITY_OPTIMIZED |
Utilisez des instances à la demande pour tous les nœuds du cluster. |
WarehouseState
État d’un entrepôt SQL. Les transitions d’état autorisées sont les suivantes :
STARTING ->STARTING, RUNNING, STOPPING, DELETING
RUNNING ->STOPPING, DELETING
STOPPING ->STOPPED, STARTING
STOPPED ->STARTING, DELETING
DELETING ->DELETED
| State |
Description |
STARTING |
L’entrepôt est en cours de démarrage. |
RUNNING |
Le processus de démarrage est terminé et l’entrepôt est prêt à être utilisé. |
STOPPING |
L’entrepôt est en cours d’arrêt. |
STOPPED |
L’entrepôt est arrêté. Démarrez-le en appelant start ou en envoyant une requête JDBC ou ODBC. |
DELETING |
L’entrepôt est en cours de destruction. |
DELETED |
L’entrepôt a été supprimé et ne peut pas être récupéré. |
WarehouseStatus
| State |
Description |
HEALTHY |
L’entrepôt fonctionne normalement et il n’y a pas de problème connu. |
DEGRADED |
L’entrepôt peut être fonctionnel, mais il existe des problèmes connus. Les performances peuvent être altérées. |
FAILED |
L’entrepôt est gravement compromis et ne sera pas en mesure de répondre aux requêtes. |
| Nom du champ |
Type |
Description |
custom_tags |
Tableau de WarehouseTagPair |
Objet contenant un tableau de paires clé-valeur. |
WarehouseTagPair
| Nom du champ |
Type |
Description |
key |
STRING |
Nom de la clé d’étiquette. |
value |
STRING |
Valeur de la clé d’étiquette. |
ODBCParams
| Nom du champ |
Type |
Description |
host |
STRING |
Nom d’hôte du serveur ODBC. |
path |
STRING |
Chemin d’accès du serveur ODBC. |
protocol |
STRING |
Protocole du serveur ODBC. |
port |
INT32 |
Port du serveur ODBC. |
RepeatedWarehouseConfPairs
| Nom du champ |
Type |
Description |
configuration_pairs |
Tableau de WarehouseConfPair |
Objet contenant un tableau de paires clé-valeur. |
Canal
ChannelName
| Option |
Description |
CHANNEL_NAME_PREVIEW |
L’entrepôt SQL est défini sur le canal en préversion et utilise des fonctionnalités à venir. |
CHANNEL_NAME_CURRENT |
L’entrepôt SQL est défini sur le canal actuel. |
WarehouseType
| Option |
Description |
CLASSIC |
Entrepôts classiques. |
PRO |
Les entrepôts pro non serverless et les entrepôts serverless sont considérés comme PRO. |