Outils de jeu de données — référence des outils MCP
Les outils de jeu de données mettent en œuvre le pipeline de données médaillon propre au lot : un lot associe un projet, un questionnaire et un sous-ensemble de campagnes à une seule chaîne linéaire Bronze → Silver → Gold (voir Outils de lot pour les opérations de cycle de vie). Ces outils extraient les réponses aux enquêtes dans le Bronze d’un lot, dérivent son Silver (codage des questions ouvertes, puis pondération par post-stratification sur la base de cas codée), l’affinent en Gold et l’exportent dans plusieurs formats. La qualité relève du lot, et non du jeu de données — voir les outils de qualité dans la Référence des outils de lot.
list_datasets
Section intitulée « list_datasets »Liste les jeux de données, avec des filtres facultatifs.
| Paramètre | Type | Obligatoire | Par défaut | Description |
|---|---|---|---|---|
stage |
string |
Non | — | Filtre par étape : "bronze", "silver" ou "gold" |
source_type |
string |
Non | — | Filtre : "campaign", "project", "upload", "weighted" ou "refined" |
campaign_id |
string |
Non | — | Filtre par identifiant de campagne |
limit |
integer |
Non | 100 |
Nombre maximal de résultats renvoyés |
Renvoie : { items: [...], count, limit }
get_dataset
Section intitulée « get_dataset »Récupère l’identité, la filiation, les métriques et l’état d’un jeu de données. C’est l’outil que chaque étape du pipeline demande d’interroger : sa réponse est donc bornée et ne grossit pas avec le questionnaire.
| Paramètre | Type | Obligatoire | Par défaut | Description |
|---|---|---|---|---|
dataset_id |
string |
Oui | — | UUID du jeu de données |
Renvoie : id, name, description, stage, source_type, source_dataset_ids, bundle_id, campaign_id, questionnaire_id, strategy_id, row_count, column_count, has_weights, weight_column, weighted_at, weighting_method, weighting_config, quality_score, processing_status, processing_error, data_path, created_at, invalid_cells.
processing_error est la raison pour laquelle une étape s’est terminée en error — par exemple le refus coding_produced_no_columns: propre à la dérivation. Il vaut null pour tous les autres états. Lisez-le chaque fois que processing_status vaut error : sans lui, une interrogation peut constater qu’une étape a échoué sans savoir pourquoi.
processing_error indique toujours le type d’échec avant les deux-points. Une raison qui ne nomme que des identifiants, des unités, des colonnes ou un seuil est renvoyée en entier. Un refus de pondération conserve le facteur et la colonne qu’il nomme, mais pas les valeurs de colonne qu’il cite, car elles peuvent être des données de répondants. La page de l’étape Silver dans Balansor affiche cette raison en entier. get_bundle_quality rapporte de la même manière la raison d’une étape en échec, tout comme get_task_status pour une exécution de run_bundle_pipeline arrêtée au Silver.
weighting_config est la trace de ce qu’a fait la dérivation :
- les facteurs sur lesquels elle a pondéré, avec leurs cibles et leurs ajustements ;
- les indicateurs de convergence ;
- le nombre de lignes écartées par le seuil de complétude et par l’exclusion des volontaires ;
- les unités ouvertes qu’elle a tentées, codées et perdues, avec le type de chaque perte.
Le schéma des colonnes ne figure pas ici — lisez-le avec get_dataset_schema. C’est le seul champ non borné d’un jeu de données (89 Ko d’une réponse de 90 Ko pour un Silver de 192 colonnes) : une interrogation dépensait ainsi des dizaines de milliers de jetons à relire un schéma inchangé pour lire une chaîne d’état de 7 octets.
invalid_cells vaut {column: count} pour les cellules que l’extraction n’a pas pu lire dans le type que stocke leur colonne et qu’elle a donc enregistrées vides — un item Radio contenant du texte rédigé, par exemple. {} signifie que l’extraction a vérifié et n’en a trouvé aucune ; null signifie que le jeu de données est antérieur à ce contrôle. Une valeur vide écrite ainsi est par ailleurs impossible à distinguer d’une question sautée par le répondant : lisez donc ce champ avant de tirer des conclusions sur les données manquantes.
get_dataset_schema
Section intitulée « get_dataset_schema »Récupère le schéma des colonnes d’un jeu de données : pour chaque colonne, son dtype, l’item_id, l’item_title et le control_type dont elle provient, sa table labels (code → libellé) et sa provenance roster/indicateur.
| Paramètre | Type | Obligatoire | Par défaut | Description |
|---|---|---|---|---|
dataset_id |
string |
Oui | — | UUID du jeu de données |
columns |
string[] |
Non | — | Noms des colonnes à renvoyer ; omettez-le pour obtenir toutes les colonnes |
detail |
boolean |
Non | true |
false renvoie column_index — le nom et le control_type de chaque colonne — au lieu de column_schema |
Renvoie : { dataset_id, stage, column_count, column_schema, returned, unknown_columns }, avec column_index ({ name: control_type }, null pour les métadonnées de ligne) à la place de column_schema lorsque detail vaut false.
Deux colonnes de métadonnées de ligne décrivent jusqu’où chaque enquête est allée : _reached compte les items présentés au répondant (y compris celui affiché à l’écran), et _completeness est la part de ceux auxquels il a répondu (réponses ÷ items atteints). Le seuil de complétude du lot s’appuie sur _completeness.
Un Bronze renvoie aussi custom_attribute_keys : les attributs personnalisés de répondant avec lesquels il a été extrait, chacun formant une colonne du jeu de données (_custom_<key>). Seuls les attributs nommés par un facteur de stratégie d’échantillonnage ou par une cible de calage du lot sont extraits : lisez donc cette liste avant de cibler un attribut, car une clé qui n’y figure pas n’est pas dans le jeu de données tant qu’une nouvelle extraction (create_bronze_dataset) n’a pas eu lieu. Une liste vide signifie que rien n’a été nommé. Le champ est absent pour le Silver et le Gold, ainsi que pour un Bronze extrait avant l’enregistrement des clés ; réextrayez ce dernier avant de pondérer sur un attribut.
column_count est celui du jeu de données : avec un filtre columns, il est donc supérieur à returned, et l’écart vous indique la part du schéma que vous n’avez pas vue. Un nom transmis que le jeu de données ne possède pas est renvoyé dans unknown_columns au lieu d’être ignoré : une faute de frappe se distingue ainsi d’une colonne réellement absente de l’étape.
Sur un instrument réel, lisez-le en deux temps. Un schéma de 293 colonnes pèse environ 134 Ko, plus que le budget de résultat d’outil de la plupart des agents. Appelez d’abord avec detail: false — les mêmes 293 colonnes reviennent sous la forme d’un index d’environ 7 Ko — puis transmettez dans columns les quelques noms dont vous avez besoin pour obtenir leurs entrées complètes. Cet outil n’est nécessaire qu’à deux moments : le choix des cibles de calage (quelle colonne, et comment sa table labels nomme chaque code) et la composition d’un catalogue d’opérations Gold (quelles colonnes existent pour être renommées, supprimées ou réordonnées). GET /api/v1/datasets/<id> est l’autre accès et renvoie le schéma complet — REST est le canal des résultats volumineux.
create_bronze_dataset
Section intitulée « create_bronze_dataset »Extrait le jeu de données Bronze d’un lot. Le lot porte déjà le questionnaire et son sous-ensemble de campagnes : cet outil n’offre aucune sélection libre de questionnaire ou de campagnes. Les aperçus sont refusés sans condition, de sorte qu’aucun argument ne peut faire entrer dans la base un parcours de test réalisé pendant la conception. Une nouvelle exécution rattache le Bronze frais à la chaîne du lot et invalide en cascade le Silver et le Gold en aval (ils deviennent obsolètes, sans être supprimés — leurs recettes subsistent pour une redérivation en un clic).
| Paramètre | Type | Obligatoire | Par défaut | Description |
|---|---|---|---|---|
bundle_id |
string |
Oui | — | Lot dont le Bronze doit être (ré)extrait |
include_demographics |
boolean |
Non | true |
Inclut les colonnes démographiques des répondants et les attributs personnalisés que nomme le lot |
Renvoie : { dataset_id, bundle_id, stage: "bronze", ... } avec le rapport d’extraction, dont invalid_cells (voir get_dataset, où le relire lors d’un tour ultérieur), custom_attribute_keys (les attributs personnalisés écrits en colonnes) et empty_custom_attribute_keys (ceux d’entre eux qu’aucun répondant interrogé ne porte — c’est ainsi qu’apparaît un nom d’attribut mal orthographié).
Quels attributs de répondant sont extraits. L’âge, le sexe et la localisation sont écrits pour chaque ligne. Un attribut personnalisé n’est écrit que si un facteur de stratégie d’échantillonnage ou une cible de calage du lot le nomme ; toute autre clé de l’enregistrement du répondant reste hors du jeu de données. Un attribut nommé qu’aucun répondant ne porte obtient tout de même une colonne, laissée vide. Nommer un nouvel attribut après une extraction exige donc un nouvel appel à create_bronze_dataset avant qu’une dérivation puisse pondérer sur cet attribut.
include_demographics: false est refusé lorsque le lot nomme un attribut personnalisé, avec {"error": "named_attributes_require_enrichment", "detail": "..."} qui nomme les attributs. Un attribut nommé n’est écrit qu’avec les colonnes démographiques, et un Bronze qui en serait dépourvu ne pourrait jamais être pondéré sur cet attribut. Lancez plutôt l’extraction avec la valeur par défaut.
code_open_ends (alias : derive_silver)
Section intitulée « code_open_ends (alias : derive_silver) »Dérive le Silver d’un lot : code le texte des questions ouvertes en une colonne catégorielle étiquetée par dimension sélectionnée, puis effectue le calage (pondération par post-stratification) sur la base de cas codée. C’est le seul outil qui produit un jeu de données Silver, et il part toujours du Bronze prêt du lot lui-même — aucun outil ne permet de pondérer un autre jeu de données.
| Paramètre | Type | Obligatoire | Par défaut | Description |
|---|---|---|---|---|
bundle_id |
string |
Oui | — | Lot dont le Bronze doit être dérivé en Silver |
Renvoie : { silver_dataset_id, status: "processing", job_id } — la dérivation s’exécute en arrière-plan. Interrogez get_dataset(dataset_id=silver_dataset_id) jusqu’à ce que processing_status vaille ready ou error.
Le codage porte sur les unités que nomme la sélection de codage du lot — définissez-la avec set_coding_selection (voir Outils de lot) — et, au sein de chacune, sur les dimensions qu’un chercheur a sélectionnées dans Balansor ; une unité que l’analyste a classée nominal est codée sur la valeur exacte, sans appel à un modèle ni revue des dimensions. Une unité sélectionnée non classée ou classée identifier interrompt la dérivation avec coding_selection_unresolvable, qui la nomme. Lorsque rien n’est sélectionné, le codage est ignoré et la pondération s’exécute directement sur les données Bronze ; c’est un résultat normal, pas une erreur. Une unité sélectionnée dont personne n’a revu les dimensions ne produit aucune colonne codée, et la dérivation réussit quand même — vérifiez awaiting_review dans get_bundle_coding avant de considérer le résultat comme complet. Une dérivation est refusée lorsqu’une cible de calage nomme une colonne codée dont la dimension (weighting_factor_dimension_deselected) ou l’unité entière (weighting_factor_deselected) n’est plus sélectionnée par le lot — resélectionnez-la ou supprimez le facteur. Une dérivation est aussi refusée avec weighting_attributes_not_extracted lorsqu’elle pondérerait sur un attribut personnalisé de répondant avec lequel le Bronze n’a pas été extrait (voir ci-dessous). derive_silver est enregistré comme second nom d’outil pour la même opération : un texte d’agent qui parle de « dériver le Silver » et un autre qui parle de « coder les questions ouvertes » y mènent tous deux.
Une dérivation qui ne code rien se termine en error, et non en ready. Une unité impossible à coder reste non codée et les autres sont tout de même codées ; mais si aucune des unités tentées par la dérivation n’a produit de colonne, le Silver atteint processing_status: "error" avec un processing_error qui commence par coding_produced_no_columns:, suivi de chaque clé d’unité et de la raison pour laquelle elle n’a rien donné. Considérez cet état comme définitif : une nouvelle exécution retrouve les mêmes unités et n’obtient pas davantage de colonne ; corrigez donc la cause (réextrayez un Bronze dont les colonnes de texte manquent, ou réparez le livre de codes dans Balansor) avant de dériver à nouveau. Ce cas est distinct d’un service d’embeddings injoignable, que la tâche réessaie d’elle-même avant d’écrire la moindre erreur.
Pondérer sur un attribut personnalisé absent du Bronze est refusé, avec son nom. Le code est weighting_attributes_not_extracted et le détail nomme chaque attribut et sa colonne. Il se présente de deux manières, selon les cibles de calage :
- Lorsque les cibles constituent tout l’ensemble de pondération (
use_strategy_factorsvautfalse, ce qui est le cas aprèsset_calibration_targets(factors=[...])ou dès qu’un chercheur a ouvert la page Silver), l’outil répond lui-même{"error": "weighting_attributes_not_extracted", "detail": "..."}et aucune tâche ne démarre. - Lorsque les cibles suivent encore la stratégie d’échantillonnage, l’outil renvoie
processinget le Silver se termine enerroravant tout codage, avec unprocessing_errorqui commence parweighting_attributes_not_extracted:.
Dans les deux cas, la solution est la même : relancez create_bronze_dataset, puis dérivez. Si aucun répondant du lot ne porte d’attribut de ce nom, c’est le nom qui est erroné ; corrigez-le dans les cibles de calage ou dans la stratégie d’échantillonnage, car une nouvelle extraction ne ferait qu’ajouter une colonne vide. Comparez les custom_attribute_keys du Bronze (get_dataset_schema) avec les attributs sur lesquels vous comptez pondérer pour anticiper ce cas. Un attribut que nomme la stratégie sans qu’on pondère dessus ne bloque jamais une dérivation ; son facteur apparaît comme non mesurable dans get_bundle_quality jusqu’à une nouvelle extraction.
create_gold_dataset
Section intitulée « create_gold_dataset »Affine le Silver prêt d’un lot pour en faire son Gold. Part toujours du Silver du lot lui-même ; remplace tout Gold antérieur de la chaîne.
| Paramètre | Type | Obligatoire | Par défaut | Description |
|---|---|---|---|---|
bundle_id |
string |
Oui | — | Lot dont le Silver doit être affiné |
name |
string |
Non | — | Nom du jeu de données Gold. Par défaut "{bundle_name} — Gold" |
operations |
object[] |
Non | — | La recette Gold de cet appel. Omettez-la pour construire à partir de la recette enregistrée du lot (la disposition sauvegardée sur la page Gold ; lisez-la avec get_bundle). La transmettre remplace la recette enregistrée pour cet appel seulement ; rien n’est enregistré |
Sans opérations (aucune transmise et aucune enregistrée), le Gold est une copie du Silver. Avec des opérations, le Gold ne diffère du Silver que par ce qu’elles indiquent : chaque colonne non supprimée est conservée, dans l’ordre du fichier Silver, avec son entrée de schéma complète (texte de la question, libellés des valeurs).
La recette operations
Section intitulée « La recette operations »Une liste ordonnée de lignes. Une ligne nomme des colonnes du fichier Silver — jamais un nom introduit par un rename. La seule exception est une entrée reorder, qui peut aussi nommer une colonne ajoutée par la recette. get_dataset_schema liste les colonnes que nomme le schéma du Silver : réponses, dimensions codées et poids. Le fichier Silver contient aussi des colonnes qu’il ne liste pas : les colonnes de métadonnées de ligne (comme _survey_id et _response_timing) et les colonnes d’enrichissement, c’est-à-dire les attributs de répondant ajoutés par l’extraction (_demographic_*, _custom_*). Elles sont conservées dans le Gold comme toute autre colonne, et une recette peut aussi les désigner par leur nom.
op |
Champs | Effet |
|---|---|---|
rename |
column, to |
Sert column sous le nom to. Le dernier rename d’une même colonne l’emporte |
remove |
column |
Exclut column du Gold |
alias |
column, to |
Sert column une fois de plus, sous le nom to. Une ligne par nom supplémentaire ; une colonne peut en avoir plusieurs. column doit elle-même être servie |
reorder |
order (liste de noms) |
Les colonnes nommées viennent en premier, dans cet ordre ; toute colonne omise par order suit à sa position par défaut. Une entrée est une colonne Silver, le to d’un alias ou le name d’une colonne calculée, chacun au plus une fois. Ne supprime jamais de colonne. Seule la dernière ligne reorder prend effet |
compute |
name, kind, plus les champs propres au type |
Ajoute une colonne nommée name |
Positions par défaut, pour toute colonne que order ne nomme pas : les colonnes Silver dans l’ordre du fichier Silver, puis les alias dans l’ordre de la recette, puis les colonnes calculées dans l’ordre de la recette. Pour placer un alias ou une colonne calculée entre deux colonnes Silver, nommez-le dans order avec les colonnes qui le précèdent.
Types de compute :
kind |
Champs | Effet |
|---|---|---|
arithmetic |
left, operator ("+", "-", "*", "/"), right |
Une opération entre deux colonnes, chaque cellule étant lue comme un nombre. Une cellule qui n’est pas un nombre, ainsi qu’une division par zéro, donnent une valeur vide |
recode |
column, buckets (liste de [min, max, label]) |
Chaque tranche associe les valeurs de min à max, bornes incluses, à label ; chaque cellule est lue comme un nombre. Une cellule qui n’est pas un nombre, ou qu’aucune tranche ne contient, donne une valeur vide. min et max sont des nombres finis, min n’étant pas supérieur à max ; label est un texte non vide |
concat |
columns (liste), separator (texte) |
Concatène les colonnes dans l’ordre |
formula est réservé à une version future et refusé nommément, aussi bien comme op que comme kind.
Règles que la recette doit respecter :
- Ce que lit un calcul. Les calculs s’exécutent sur l’ensemble du Silver, avant tout renommage ou toute suppression de colonne. Une entrée est une colonne Silver (servie, renommée ou supprimée, indifféremment) ou le
named’une lignecomputeantérieure dans la liste, jamais un alias. La position d’une colonne calculée dans le fichier ne change rien à ce qu’elle peut lire. - Noms d’alias et de colonnes calculées. Le
tod’un alias et lenamed’une colonne calculée doivent différer de tous les noms de colonnes Silver, y compris des colonnes supprimées. - Un alias exige sa colonne. Un
aliasd’une colonne que la recette supprime est refusé : pour servir une colonne sous un seul nouveau nom, utilisezrename. - Nouveaux noms. Un nom créé par la recette (cible d’un
rename, alias ounamecalculé) ne peut pas être vide et ne peut ni commencer ni se terminer par une espace. - Noms en sortie. Les noms du Gold final sont ceux de chaque colonne servie sous son nom définitif, plus chaque alias et chaque nom calculé. Un nom créé par la recette doit différer de tous les autres noms en sortie, sans tenir compte de la casse :
Scoreetscoreentrent en collision. Deux colonnes Silver que la recette laisse sous leur propre nom ne sont jamais refusées, même si elles ne diffèrent que par la casse ; c’est le nommage propre au Silver. - Au moins une colonne. Une recette qui supprime toutes les colonnes Silver sans en calculer aucune est refusée.
- La colonne de poids. Les poids du Gold sont la colonne de poids du Silver : renommée, elle reste la colonne de poids sous son nouveau nom ; supprimée, le Gold ne porte aucun poids, même si une autre colonne est renommée sous son ancien nom. Un alias de la colonne de poids est une seconde copie de ses valeurs et n’est jamais la colonne de poids du Gold.
- Les lignes
rename,remove,aliasetreorderpeuvent se succéder dans n’importe quel ordre. L’ordre compte entre lignescompute, et entre lignesaliasuniquement pour leur position par défaut.
[ {"op": "rename", "column": "age", "to": "Age"}, {"op": "remove", "column": "_response_timing"}, {"op": "alias", "column": "age", "to": "age_at_interview"}, {"op": "reorder", "order": ["_survey_id", "age", "age_band"]}, {"op": "compute", "name": "age_band", "kind": "recode", "column": "age", "buckets": [[18, 34, "18-34"], [35, 54, "35-54"], [55, 120, "55+"]]}]Renvoie : { gold_dataset_id, name, stage: "gold", bundle_id, row_count, column_count, skipped }
skipped liste les entrées de la recette que la construction a mises de côté parce que le Silver n’a pas leur colonne, chacune sous la forme { "op": "remove" | "reorder", "column": "<name>" }. Une recette peut survivre au Silver pour lequel elle a été écrite : une entrée remove ou reorder qui nomme une colonne que le Silver n’a plus est ignorée et signalée ici plutôt que refusée. La liste est vide lorsque rien n’a été ignoré.
Refus (chacun sous la forme { "error": "<code>", "detail": "..." } ; aucun Gold n’est publié) :
error |
Quand |
|---|---|
silver_not_ready |
Le lot n’a pas de Silver prêt, son fichier est illisible, ou le Silver a changé pendant la construction du Gold. Dérivez le Silver, puis rappelez l’outil |
bronze_schema_stale |
Le Bronze du lot a été extrait avec un ancien jeu de colonnes. Réextrayez le Bronze, dérivez le Silver, puis rappelez l’outil |
invalid_operations |
La recette enfreint l’une des règles ci-dessus, vérifiées avant toute construction : un op ou un kind inconnu ou réservé, un champ manquant, un nouveau nom vide ou entouré d’espaces, une tranche mal formée (une borne qui n’est pas un nombre fini, ou min supérieur à max), un nom cité deux fois dans un même reorder, un rename ou un alias d’une colonne absente du Silver, un alias d’une colonne supprimée, une entrée de calcul qui n’est ni une colonne Silver ni un nom calculé antérieur, un alias ou un nom calculé identique à une colonne Silver, un nom créé par la recette qui ne diffère d’un autre nom en sortie que par la casse, ou une recette qui ne laisse aucune colonne. detail nomme chaque colonne concernée |
build_failed |
La recette a passé les contrôles, mais un calcul n’a pas pu être effectué sur les données. detail en donne la raison |
layout_changed |
Uniquement lors d’une construction à partir de la recette enregistrée : la recette a été enregistrée de nouveau (sur la page Gold) pendant la construction de ce Gold. Le Gold construit est abandonné et le Gold précédent du lot, construit à partir de la recette d’avant cette sauvegarde, n’est plus ready ; rappelez l’outil |
gold_superseded |
Une construction concurrente a remplacé ce Gold ; rappelez l’outil |
Validation de l’étape : le Silver du lot doit être ready ; un Silver absent ou non prêt renvoie une erreur au lieu de se rabattre sur le Bronze.
export_dataset
Section intitulée « export_dataset »Exporte un jeu de données dans le format indiqué.
| Paramètre | Type | Obligatoire | Par défaut | Description |
|---|---|---|---|---|
dataset_id |
string |
Oui | — | UUID du jeu de données |
format |
string |
Non | "csv" |
Format d’export : "csv", "csv_semicolon" (séparateurs ; et décimales ,, pour un Excel hongrois, allemand, français ou espagnol), "xlsx", "spss", "parquet", "rds" ou "json" |
Renvoie : { dataset_id, format, download_url, rows, columns, file_size_bytes }. Le fichier exporté n’est jamais renvoyé directement dans la réponse : download_url est un lien de courte durée (il expire quelques minutes après sa création) qui permet de récupérer le fichier directement en HTTPS sans autre authentification ; il peut être réutilisé autant de fois que nécessaire jusqu’à son expiration. Demandez un nouvel export si le lien a expiré.
Formats d’export
Section intitulée « Formats d’export »| Format | Extension | Description |
|---|---|---|
csv |
.csv |
Format universel, compatible avec la plupart des outils |
xlsx |
.xlsx |
Excel, avec des feuilles de synthèse et de schéma |
spss |
.sav |
SPSS, avec libellés de variables et de valeurs |
parquet |
.parquet |
Format en colonnes avec métadonnées complètes (compression Snappy) |
rds |
.rds |
R — les variables catégorielles arrivent sous forme de facteurs, les libellés de valeurs sous forme de niveaux de facteur |
json |
.json |
Un seul document : {dataset, column_schema, rows}. Les lignes conservent les codes de réponse enregistrés ; les libellés de valeurs de chaque colonne figurent dans column_schema. Les valeurs manquantes valent null |
delete_dataset
Section intitulée « delete_dataset »Supprime un jeu de données et, facultativement, son fichier de données.
| Paramètre | Type | Obligatoire | Par défaut | Description |
|---|---|---|---|---|
dataset_id |
string |
Oui | — | UUID du jeu de données |
delete_file |
boolean |
Non | false |
Supprime aussi le fichier de données Parquet |
Renvoie : { deleted: true, dataset_id, dataset_info: { name, stage, row_count, data_path }, file_deleted }
Gestion des erreurs
Section intitulée « Gestion des erreurs »Validation des étapes
Section intitulée « Validation des étapes »Le pipeline du lot impose la progression et l’état prêt des étapes : une étape ne peut être ni sautée ni exportée tant qu’elle est obsolète.
| Opération | Exigence | Erreur |
|---|---|---|
code_open_ends / derive_silver |
Le Bronze du lot doit être ready |
{"error": "bronze_not_ready", "detail": "Extract a ready Bronze first"} |
code_open_ends / derive_silver |
Le Bronze doit correspondre à la version actuelle du schéma d’extraction | {"error": "bronze_schema_stale", "detail": "..."}. Réextrayez le Bronze (create_bronze_dataset), puis dérivez |
code_open_ends / derive_silver |
Chaque attribut personnalisé sur lequel pondère la dérivation doit avoir été extrait dans le Bronze | {"error": "weighting_attributes_not_extracted", "detail": "..."}, qui nomme les attributs. Réextrayez le Bronze, puis dérivez |
create_bronze_dataset |
include_demographics doit rester à true lorsque le lot nomme un attribut personnalisé |
{"error": "named_attributes_require_enrichment", "detail": "..."}, qui nomme les attributs |
create_gold_dataset |
Le Silver du lot doit être ready |
{"error": "silver_not_ready", "detail": "Derive a ready Silver first"} |
create_gold_dataset |
Le Bronze du lot doit correspondre à la version actuelle du schéma d’extraction | {"error": "bronze_schema_stale", "detail": "..."}, qui indique ce que ce Bronze n’enregistre pas. Réextrayez le Bronze, dérivez le Silver, puis construisez le Gold |
create_gold_dataset |
La recette doit être valide pour les colonnes du Silver | {"error": "invalid_operations", "detail": "..."}, qui nomme les lignes et les colonnes. Voir create_gold_dataset |
export_dataset |
Le jeu de données doit être ready (et non processing/invalidated/error) |
{"error": "not_ready", "detail": "Dataset is '{status}', not ready — re-derive the stage before exporting."} |
export_dataset |
Le Bronze du jeu de données (lui-même, ou le Bronze de son lot pour un Silver ou un Gold) doit correspondre à la version actuelle du schéma d’extraction | {"error": "bronze_schema_stale", "detail": "..."}, qui indique ce que ce Bronze n’enregistre pas. Réextrayez le Bronze, redérivez, puis exportez |
export_dataset |
Les questions codées d’un Silver doivent toutes avoir été revues : une question en attente de revue des dimensions n’a pas encore de colonne codée | {"error": "coding_awaiting_review", "detail": "..."}, qui nomme les questions. Revoyez les dimensions dans Balansor, redérivez, puis exportez |
export_dataset |
Le fichier de données du jeu de données doit exister | {"error": "file_missing", "detail": "The dataset's data file is missing — re-derive the stage."} |
Erreurs courantes
Section intitulée « Erreurs courantes »| Cas | Réponse |
|---|---|
| Jeu de données introuvable | {"error": "Dataset {id} not found"} |
| Lot introuvable | {"error": "not_found", "detail": "Bundle {id} not found"} |
| Stratégie introuvable | {"error": "Sampling strategy {id} not found"} |
| Aucun fichier de données | {"error": "Dataset {id} has no data file"} |
| Format d’export invalide | {"error": "Invalid format. Allowed: csv, csv_semicolon, xlsx, spss, parquet, rds, json"} |
| Aucune enquête terminée | {"error": "no_completed_surveys", "detail": "..."} — élargissez la sélection de campagnes ou attendez davantage d’enquêtes terminées |
| Le lot ne sélectionne aucune campagne | {"error": "no_campaigns_selected", "detail": "..."} — la base de mesure d’un lot est constituée des enquêtes des campagnes qu’il sélectionne ; affectez-en au moins une |
| L’extraction n’a pas pu écrire le jeu de données | {"error": "extraction_failed", "column": "q_x", "detail": "..."} — une colonne contient des valeurs qui ne peuvent pas être ramenées à un type unique. La valeur fautive est volontairement omise (il s’agit de la réponse d’un répondant) ; examinez les valeurs brutes de cette colonne, corrigez les réponses sources et réextrayez |