Partager via

Azure Cosmos DB v2 (Bêta)

  • Article

Résumé

Élément Description
État de publication Bêta
PRODUITS Power BI (Modèles sémantiques)
Power BI (Dataflows)
Fabric (Dataflow Gen2)
Types d'authentification pris en charge Clé de flux

Prérequis

Fonctionnalités prises en charge

  • Importer
  • DirectQuery (pour les modèles sémantiques Power BI)
  • Options avancées
    • Nombre de nouvelles tentatives
    • Activer la fonction Passdown « AVERAGE »
    • Activer Passdown « SORT » pour plusieurs colonnes

Se connecter à Azure Cosmos DB

Pour vous connecter aux données Azure Cosmos DB :

  1. Démarrez Power BI Desktop.

  2. Dans l’onglet Accueil, sélectionnez Obtenir les données.

  3. Dans la zone de recherche, entrez Cosmos DB v2.

  4. Sélectionnez Azure Cosmos DB v2 (bêta), puis sélectionnez Se connecter.

    Capture d’écran montrant la sélection Sélectionner Azure Cosmos DB v2.

  5. Dans la page de connexion Azure Cosmos DB v2, pour le point de terminaison Cosmos, entrez l'URI du compte Azure Cosmos DB que vous souhaitez utiliser. Pour le mode Connectivité des données, choisissez un mode approprié pour votre cas d’usage, en suivant les instructions générales suivantes :

    • Pour les jeux de données plus petits, choisissez Importer. Lorsque vous utilisez le mode d’importation, Power BI fonctionne avec Cosmos DB pour importer le contenu de l’ensemble du jeu de données afin de l’utiliser dans vos visualisations.

    • Le mode DirectQuery permet l'envoi de requêtes vers le conteneur Cosmos DB pour l’exécution et améliore les performances du connecteur. Pour les conteneurs Cosmos DB partitionnés, une requête SQL avec une fonction d’agrégation est transmise à Cosmos DB si la requête contient également un filtre (clause WHERE) sur la clé de partition. Par exemple, si la clé de partition est définie sur « Product », une requête SQL pouvant être transmise et exécutée sur le serveur Cosmos DB peut être :

      SELECT SUM(ColumnName) FROM TableName where Product = 'SampleValue'

    Remarque

    Utilisez Azure Synapse Link pour Azure Cosmos DB si vous souhaitez exécuter des fonctions d’agrégation entre partitions sur le conteneur Cosmos DB.

    Plus d’informations :

    Capture d’écran de la zone de dialogue connexion montrant l’entrée de point de terminaison Cosmos et le mode de connectivité des données réglé sur DirectQuery.

  6. À l’invite pour configurer l’authentification de source de données, entrez la clé de compte. Sélectionnez Connecter. Votre catalogue de données, vos bases de données et vos tables s’affichent dans la boîte de dialogue Navigateur.

  7. Dans le volet Options d’affichage, activez la case à cocher du jeu de données que vous souhaitez utiliser.

    Capture d’écran du navigateur mettant en évidence les données que vous avez sélectionnées.

  8. La méthode la plus optimale pour spécifier le filtre clé de partition (afin que les fonctions d’agrégation puissent être poussées vers Cosmos DB) consiste à utiliser des paramètres M dynamiques. Pour utiliser des paramètres M dynamiques, vous devez créer un jeu de données avec des valeurs de clé de partition uniques, créer un paramètre, l’ajouter en tant que filtre sur le jeu de données principal, le lier au jeu de données de clé de partition unique et l’utiliser comme segment pour le jeu de données principal. Procédez comme suit pour activer les paramètres M dynamiques pour le filtrage de clé de partition.

    a. Créer un jeu de données avec des valeurs de clé de partition uniques :

    Dans le navigateur, sélectionnez Transformer des données au lieu de Charger pour afficher l’éditeur Power Query. Cliquez avec le bouton droit sur le jeu de données de requêtes, puis sélectionnez Dupliquer pour créer un jeu de données.

    Capture d’écran présentant la manière de sélectionner des duplicata de votre requête existante dans l’éditeur Power Query.

    Renommez le nouveau modèle de clé de partition, puis cliquez avec le bouton droit sur la colonne clé de partition Cosmos DB. Dans cet exemple, Produit est la colonne clé de partition Cosmos DB. Sélectionnez Supprimer d’autres colonnes, puis sélectionnez Supprimer les doublons.

    Capture d’écran présentant les clés de partition uniques dans l’éditeur Power Query.

    b. Créer un paramètre pour le filtrage dynamique :

    Dans l’éditeur Power Query, sélectionnez Gérer les paramètres>Nouveau paramètre. Renommez le nouveau paramètre pour refléter le paramètre de filtre et entrer une valeur valide en tant que Valeur actuelle.

    Capture d’écran présentant la manière de créer un paramètre dans l’éditeur Power Query.

    c. Appliquer un filtre paramétrisé sur le jeu de données principal :

    Sélectionnez l’icône déroulante de la colonne Clé de partition, puis sélectionnez Filtres de texte>Sont égaux à. Remplacez le type de filtre de Texte par Paramètre. Choisissez ensuite le paramètre créé à l’étape b. Sélectionnez Fermer & Appliquer en haut à gauche de l’éditeur Power Query.

    Capture d’écran présentant les étapes à suivre pour appliquer le filtre paramétrisé.

    d. Créer un segment de valeurs de clé de partition avec liaison de paramètres :

    Dans Power BI, sélectionnez l’onglet Modèle. Sélectionnez ensuite le champ Clé de partition. Dans le volet Propriétés, sélectionnez Liaison avancée>au paramètre. Choisissez le paramètre créé à l’étape b.

    Capture d’écran présentant les étapes de la liaison du paramètre.

    Sélectionnez l’onglet Rapport et ajoutez un segment avec la clé de partition unique.

    Capture d’écran du segment.

    e. Ajouter des visualisations et appliquer le filtre clé de partition à partir du segment :

    Étant donné que la valeur de clé de partition choisie sur le segment est liée au paramètre (comme fait à l’étape d) et que le filtre paramétrisé est appliqué sur le jeu de données principal (comme fait à l’étape c), la valeur de clé de partition choisie est appliquée en tant que filtre sur le jeu de données principal et la requête avec le filtre de clé de partition est transmise à Cosmos DB dans toutes les visualisations.

    Capture d’écran de la visualisation après l’application du filtre clé de la partition.

Options avancées

Power Query fournit un ensemble d’options avancées que vous pouvez ajouter à votre requête si nécessaire.

Le tableau suivant répertorie toutes les options avancées que vous pouvez définir dans Power Query.

Option avancée Description
Nombre de nouvelles tentatives Combien de fois pour réessayer s’il y a des codes de retour HTTP de 408 - Request Timeout, 412 - Precondition Failed, ou 429 - Too Many Requests. Le nombre de nouvelles tentatives par défaut est de 5.
Activer la fonction Passdown AVERAGE Spécifie si le connecteur autorise la transmission de la fonction d’agrégation AVG à Cosmos DB. La valeur par défaut est 1 et le connecteur tente de transmettre la fonction d’agrégation AVG à Cosmos DB, par défaut. Si l’argument contient des valeurs chaîne, booléenne ou null pour la fonction d’agrégation AVG, un jeu de résultats non défini est retourné par le serveur Cosmos DB. Lorsqu’elle est définie sur la valeur 0, la fonction d’agrégation AVG n’est pas transmise au serveur Cosmos DB et le connecteur gère l’opération d’agrégation AVG lui-même.
Activer Passdown SORT pour plusieurs colonnes Spécifie si le connecteur autorise la transmission de plusieurs colonnes à Cosmos DB lorsqu’il est spécifié dans la clause ORDER BY de la requête SQL. La valeur par défaut est 0 et si plusieurs colonnes sont spécifiées dans la clause ORDER BY, le connecteur ne transmet pas les colonnes par défaut et gère plutôt l’exécution de l’ordre par lui-même. Lorsqu’il est défini sur la valeur 1, le connecteur tente de transmettre plusieurs colonnes à Cosmos DB lorsqu’il est spécifié dans la clause ORDER BY de la requête SQL. Pour autoriser la transmission de plusieurs colonnes à Cosmos DB, veillez à définir des index composites sur les colonnes des collections respectives. Pour les collections partitionnées, une requête SQL avec ORDER BY est transmise à Cosmos DB uniquement si la requête contient un filtre sur la clé partitionnée. En outre, s’il existe plus de huit colonnes spécifiées dans la clause ORDER BY, le connecteur ne transmet pas la clause ORDER BY et gère plutôt l’exécution de l’ordre lui-même.

Problèmes connus et limitations

  • Pour les conteneurs Cosmos DB partitionnés, une requête SQL avec une fonction d’agrégation est transmise à Cosmos DB si la requête contient également un filtre (clause WHERE) sur la clé de partition. Si la requête d’agrégation ne contient pas de filtre sur la clé de partition, l’agrégation est effectuée par le connecteur.

  • Le connecteur ne transmet pas une fonction d’agrégation si elle est appelée après l’application de TOP ou LIMIT. Cosmos DB traite l’opération TOP à la fin du traitement d’une requête. Par exemple, dans la requête suivante, TOP est appliqué dans la sous-requête, tandis que la fonction d’agrégation est appliquée au-dessus de ce jeu de résultats :

    SELECT COUNT(1) FROM (SELECT TOP 4 * FROM EMP) E

  • Si DISTINCT est fourni dans une fonction d’agrégation, le connecteur ne transmet pas la fonction d’agrégation à Cosmos DB si une clause DISTINCT est fournie dans une fonction d’agrégation. Lorsqu’il est présent dans une fonction d’agrégation, DISTINCT n’est pas pris en charge par l’API SQL Cosmos DB.

  • Pour la fonction d’agrégation SUM, Cosmos DB retourne une valeur non définie comme jeu de résultats si l’un des arguments de SUM est une chaîne, une valeur booléenne ou null. Toutefois, s’il existe des valeurs null, le connecteur transmet la requête à Cosmos DB de telle sorte qu’il demande à la source de données de remplacer une valeur null par zéro dans le cadre du calcul SUM.

  • Pour la fonction d’agrégation AVG, Cosmos DB retourne undefined comme jeu de résultats si l’un des arguments de SUM est une chaîne, une valeur booléenne ou null. Le connecteur expose une propriété de connexion pour désactiver la transmission de la fonction d’agrégation AVG à Cosmos DB au cas où ce comportement Cosmos DB par défaut doit être remplacé. Lorsque la transmission AVG est désactivée, elle n’est pas transmise à Cosmos DB et le connecteur gère l’exécution de l’opération d’agrégation AVG elle-même. Pour plus d’informations, accédez à « Activer la fonction AVERAGE Passdown » dans Options avancées.

  • Les conteneurs Azure Cosmos DB avec grande clé de partition ne sont actuellement pas pris en charge dans le connecteur.

  • La transmission d’agrégation est désactivée pour la syntaxe suivante en raison des limitations du serveur :

    • Lorsque la requête ne filtre pas sur une clé de partition ou lorsque le filtre de clé de partition utilise l’opérateur OR avec un autre prédicat au niveau supérieur de la clause WHERE.

    • Lorsque la requête a une ou plusieurs clés de partition qui apparaissent dans une clause IS NOT NULL dans la clause WHERE.

  • Le connecteur V2 ne prend pas en charge les types de données complexes tels que les tableaux, les objets et les structures hiérarchiques. Pour ces scénarios, il est recommandé d’utiliser la fonctionnalité Mise en miroir de la structure pour Azure Cosmos DB.

  • Le connecteur V2 utilise l’échantillonnage des 1 000 premiers documents pour présenter le schéma déduit. Il n’est pas recommandé pour les scénarios d’évolution de schéma lorsqu’une seule partie des documents est mise à jour. Par exemple, une propriété nouvellement ajoutée à un document dans un conteneur avec des milliers de documents peut ne pas être incluse dans le schéma déduit. Pour ces scénarios, nous recommandons la fonctionnalité Mise en miroir de Microsoft Fabric pour Azure Cosmos DB.

  • Actuellement, le connecteur V2 ne prend pas en charge les valeurs non-chaînes dans les propriétés de l’objet.

  • La transmission de filtre est désactivée pour la syntaxe suivante en raison des limitations du serveur :

    • Lorsque la requête contenant une ou plusieurs colonnes d’agrégation est référencée dans la clause WHERE.