Objets Datagraph

Vue d’ensemble

Un Objet Datagraph est une requête SQL nommée sur le modèle du Datagraph, avec des paramètres déclarés et des colonnes de sortie inférées. Ouvrez DataHub → Datagraph → Objets — Gérez les objets datagraph de votre compte. La liste Objets affiche les colonnes Nom, Statut et Dernière mise à jour. La description indique Gérez les objets datagraph de votre compte. Cliquez sur Créer un objet pour ouvrir un nouveau brouillon. L’état vide indique Aucun objet pour le moment.

Avant de commencer

Le Datagraph Schema doit être publié, car les colonnes de sortie sont inférées sur le modèle Live. Voir Datagraph Schema.
Chaque Datasource référencée par le SQL doit avoir une version Live.
Les Datasources protégées par des filtres au niveau des lignes ne peuvent pas être utilisées dans un Objet.

Disposition de l’éditeur

Panneau	Contenu
INPUT / OUTPUT	Les paramètres de l’Objet et les champs de sortie, en lecture seule pour ces derniers.
VERSIONS	Les versions disponibles de l’Objet.

Le fil d’Ariane indique Datagraph > Objets. Le sous-titre est Définissez et gérez la requête SQL et les options de votre objet datagraph.

Champ	Description
Nom de l’objet	L’identifiant de l’Objet. Utilisez le snake_case, par exemple `top_products_bought`.
Objet édité	Le sélecteur de l’Objet à modifier.
Description	Ce à quoi l’Objet répond, en termes métier.

Écrire le SQL

Les tables Datasource sont référencées par l’identifiant de la Datasource, entre guillemets :

SELECT
  products.name,
  products.image_url,
  products.price
FROM "6a1f9c24e0b84f0f9a2d7c31" AS purchases
JOIN "8b53d7f1c2a94e6ea0b41d77" AS products
  ON products.reference_id = purchases.product_reference
WHERE purchases.user_id = $1
ORDER BY purchases.purchased_at DESC
LIMIT 5

La requête doit référencer au moins une table Datasource, sinon elle est rejetée.

Exemples concrets

Les schémas ci-dessous proviennent d’un modèle d’annonces immobilières construit sur cinq Datasources : utilisateurs, annonces, prix au mètre carré par zone, recommandations pré-calculées et contenus éditoriaux.

Objet	Principe	Paramètres	Retourne
`listings_matching_search`	Joindre les utilisateurs aux annonces sur la zone recherchée, puis filtrer sur le budget.	`user_id` (`string`)	Les annonces triées par score de qualité, limitées à 6.
`listings_price_drop`	Filtrer les annonces d’une zone sur une variation de prix minimale, calculée depuis le prix précédent.	`zone_id` (`string`), `min_drop_pct` (`number`)	Les annonces triées par pourcentage de baisse.
`market_prices_area`	Lire la table de marché pour la zone recherchée par un utilisateur, avec la tendance sur 12 mois.	`user_id` (`string`)	Une ligne : prix médian au mètre carré, tendance, délai de vente moyen.
`recommended_listings`	Joindre une table de recommandations pré-calculées aux annonces, en conservant le rang de l’algorithme.	`user_id` (`string`)	Les annonces recommandées triées par rang.
`editorial_content_area`	Filtrer les contenus éditoriaux sur la zone, en ne gardant que ceux dont la fenêtre de publication est ouverte.	`zone_id` (`string`)	Les guides et articles de marché de cette zone.

Ces mêmes principes se transposent à d’autres modèles : derniers articles achetés par un client, stock restant dans le magasin préféré, meilleures ventes d’une catégorie, ou produits complémentaires d’une commande.

Les filtres qui combinent plusieurs préférences utilisateur — fourchette de budget et nombre de pièces minimum, par exemple — peuvent légitimement ne retourner aucune ligne. Prévisualisez chaque Objet avec un identifiant réel avant publication, et assouplissez la condition la moins critique si le résultat est vide.

Paramètres

Les paramètres sont déclarés dans INPUT / OUTPUT et associés aux emplacements SQL. Cliquez sur Ajouter pour en créer un.

Champ	Description
Nom	Le nom du paramètre, par exemple `user_id`.
Description courte	Affichée au-dessus du champ dans le Data Node Objet Datagraph. 100 caractères maximum.
Description complète	Description détaillée facultative.
Type	Le type scalaire accepté à l’exécution.
Optionnel	Une fois activé, le paramètre peut être omis ou laissé vide à l’exécution.
Index du placeholder SQL	Associe le paramètre à `$1`, `$2`, … dans la requête SQL.

Types de paramètres acceptés :

Type	Valeur attendue
`string`	Une valeur textuelle. Un nombre seul est refusé.
`number`	Une valeur numérique.
`boolean`	`true` ou `false`.
`datetime`	Une valeur date-heure.
`datetime_iso`	Une date-heure ISO 8601, par exemple `2024-01-01T00:00:00.000Z`.
`string[]` / `number[]`	Un tableau JSON de chaînes ou de nombres.
`string{}` / `number{}`	Un objet JSON dont les valeurs sont des chaînes ou des nombres.

Un paramètre NULL comparé avec = ou <> ne correspond jamais. L’éditeur le signale et demande d’utiliser IS NULL ou IS NOT NULL dans la requête SQL.

Valeurs suggérées

Chaque paramètre peut porter une valeur suggérée et une liste de valeurs autorisées. Les deux sont des indications de configuration pour le Data Node Objet Datagraph — voir Objet Datagraph. Elles ne changent rien à l’exécution du SQL.

Valeur suggérée

Définie sous SUGGESTED VALUE → Source dans l’éditeur de paramètre :

Source	Ce qu’elle suggère	Disponible pour
Aucune	Pas de suggestion (défaut).	Tous les types
Depuis le contexte	Une variable Context, choisie avec le Variable Picker. La liste correspond au drawer de Workflow pour ce type : `string` et `string[]` → identifiant utilisateur, IP, ISP, type d’appareil, OS, referer, client mail, locale, jour de la semaine ; `number` et `number[]` → index d’entrypoint ; `boolean` → utilisateur identifié ; `datetime` et `datetime_iso` → date courante.	`string`, `number`, `boolean`, `datetime`, `datetime_iso`, `string[]`, `number[]`
Depuis un attribut de Team	Les valeurs d’un attribut de Team. La clé commence par une lettre minuscule, suivie d’au plus 63 lettres minuscules, chiffres ou underscores.	`string`, `string[]`
Valeur fixe	Une valeur statique, selon le type du paramètre.	Types scalaires et listes

Les types dictionnaire (string{}, number{}) ne peuvent pas utiliser Depuis le contexte.

Éditeur d'option d'Objet avec la source de suggestion Depuis le contexte et le Variable Picker Context ouvert

Valeurs autorisées

Pour les paramètres string, number, string[] et number[], Allowed values liste les valeurs que le paramètre peut prendre, sans doublon. Le Data Node Objet Datagraph les affiche sous forme de select ou multi-select plutôt qu’un champ libre.

Une suggestion ou une valeur autorisée invalide est signalée sur le champ correspondant à l’enregistrement. Quand vous changez le type d’un paramètre, une suggestion ou une valeur autorisée qui ne correspond plus est supprimée.

Colonnes de sortie

Le panneau INPUT / OUTPUT liste les colonnes et leurs types, affichés comme Texte, Nombre ou URL d’image. Les colonnes sont calculées à partir du SQL sur le modèle publié du Datagraph et recalculées à chaque enregistrement.

Prévisualiser les résultats

Enregistrez l’Objet avant de lancer un aperçu.
Cliquez sur Exécuter la requête pour ouvrir Paramètres de la requête.
La fenêtre indique Renseignez les paramètres de l’objet avant d’exécuter l’aperçu SQL. Chaque paramètre affiche son type attendu et sa description courte.
Cliquez sur Remplir avec des exemples pour trouver des valeurs, puis sur Exécuter la requête.

Le panneau Preview retourne jusqu’à 10 lignes, avec le nombre de lignes et un Trace ID utile au support.

Message de l’éditeur	Signification
Write a query with FROM “datasource-id” and click run to see a preview	Le SQL ne référence pas encore de Datasource.
Column ”…” does not exist in the datasource	La colonne ne fait pas partie du modèle Live du Datagraph.
Enter a valid ISO 8601 datetime	La valeur d’un paramètre `datetime_iso` est mal formée.
Unable to find sample values from the data	Aucun échantillon n’a pu être déduit ; saisissez les valeurs manuellement.

La page Requêtes — DataHub → Datagraph → Requêtes — exécute les requêtes SQL des Objets Datagraph. Sélectionnez un Objet et lancez la requête pour afficher les résultats.

Publication

Cliquez sur Publier pour ouvrir la fenêtre Publier l’objet. Le brouillon est publié, la version précédente devient inactive et une nouvelle copie brouillon est créée. Seuls les Objets publiés sont sélectionnables dans les Workflows.

Lorsqu’un Objet appartient à une Famille d’objets Datagraph publiée, sa publication échoue avec Entity group contract violated si ses colonnes ne respectent plus le contrat. Un Objet membre d’une famille publiée ne peut pas être supprimé.

La fenêtre Supprimer l’objet avertit que Les workflows qui interrogent cet objet ne pourront plus être résolus. Supprimer un Objet est irréversible.

Partager un contrat entre plusieurs Objets

Plusieurs Objets qui répondent à la même question pour différents segments — par exemple, un algorithme de recommandation par Objet — peuvent être liés à une Famille d’objets Datagraph. Elle déclare les champs que chaque membre doit retourner et vérifie leurs versions publiées. Voir Familles d’objets Datagraph.

Utiliser un Objet dans un Workflow

Ajoutez le Data Node Objet Datagraph — Exécutez une requête d’objet Datagraph et exposez ses résultats dans le workflow.

Réglage	Description
Objet	Choisissez un Objet dans Sélectionner un objet publié.
Paramètres de l’objet	Un champ par paramètre. Sa description courte apparaît au-dessus du champ.

Le sélecteur vide affiche Aucun objet publié n’est disponible pour le moment. Ouvrir l’objet dans Datahub ouvre l’éditeur de l’Objet.

Seuls les administrateurs techniques peuvent configurer les nœuds d’interrogation d’objet Datagraph.

Le champ Limite de résultats est masqué par défaut. Il apparaît uniquement si un administrateur technique active Objet Datagraph : limite de résultats dans les paramètres du Workflow → Fonctionnalités des datasources. Il accepte de 1 à 200 lignes.

Le Data Node est décrit dans Objet Datagraph.

Les valeurs de paramètres issues de variables du Workflow sont converties vers le type déclaré. Une variable non convertible — du texte libre dans un paramètre number, par exemple — fait échouer le Node à l’exécution, et non à la configuration.

Et ensuite ?

Familles d'objets

Liez plusieurs Objets à un même contrat de sortie.

Schema

Ajoutez les colonnes et relations dont votre SQL a besoin.

Onglets Schema

Examinez les onglets Diagram, Relations et Datasources de la page Schema.

Data Node Datasource

Comparez avec l’interrogation d’une seule Datasource dans un Workflow.

API Datagraph Schema

Gérez le modèle par programmation.

Getting Started

DataHub Deep Dive

Advanced Workflows

Email Rendering

Transformations

Advanced Analytics

Vue d’ensemble

Avant de commencer

Disposition de l’éditeur

Écrire le SQL

Exemples concrets

Paramètres

Valeurs suggérées

Valeur suggérée

Valeurs autorisées

Colonnes de sortie

Prévisualiser les résultats

Publication

Partager un contrat entre plusieurs Objets

Utiliser un Objet dans un Workflow

Et ensuite ?

Familles d'objets

Schema

Onglets Schema

Data Node Datasource

API Datagraph Schema

​Vue d’ensemble

​Avant de commencer

​Disposition de l’éditeur

​Écrire le SQL

​Exemples concrets

​Paramètres

​Valeurs suggérées

​Valeur suggérée

​Valeurs autorisées

​Colonnes de sortie

​Prévisualiser les résultats

​Publication

​Partager un contrat entre plusieurs Objets

​Utiliser un Objet dans un Workflow

​Et ensuite ?

Familles d'objets

Schema

Onglets Schema

Data Node Datasource

API Datagraph Schema

Vue d’ensemble

Avant de commencer

Disposition de l’éditeur

Écrire le SQL

Exemples concrets

Paramètres

Valeurs suggérées

Valeur suggérée

Valeurs autorisées

Colonnes de sortie

Prévisualiser les résultats

Publication

Partager un contrat entre plusieurs Objets

Utiliser un Objet dans un Workflow

Et ensuite ?