API Entrepôts SQL 2.0

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.

Nom du champ Type Description
security_policy WarehouseSecurityPolicy Stratégie de contrôle d’accès aux jeux de données.
data_access_config Tableau de WarehouseConfPair Tableau de paires clé-valeur contenant des propriétés pour la configuration de l’accès aux données.
sql_configuration_parameters RepeatedWarehouseConfPairs Paramètres de configuration 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
Nom du champ Type Description
security_policy WarehouseSecurityPolicy Stratégie de contrôle d’accès aux jeux de données.
data_access_config Tableau de WarehouseConfPair Tableau de paires clé-valeur contenant des propriétés pour la configuration de l’accès aux données.
sql_configuration_parameters RepeatedWarehouseConfPairs Paramètres de configuration SQL.

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

Option Description
DATA_ACCESS_CONTROL Utilisez le contrôle d’accès aux données pour contrôler l’accès aux jeux de données.

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.

WarehouseTags

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

Nom du champ Type Description
name WarehouseType Nom du 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.