Datensatz-Tools — MCP-Tool-Referenz
Die Datensatz-Tools setzen die Medallion-Datenpipeline auf Bundle-Ebene um: Ein Bundle verbindet ein Projekt, einen Fragebogen und eine Auswahl an Kampagnen mit einer linearen Kette Bronze → Silver → Gold (die Operationen zum Lebenszyklus finden Sie unter Bundle-Tools). Diese Tools extrahieren Umfrageantworten in das Bronze eines Bundles, leiten dessen Silver ab (Codierung offener Antworten, dann Gewichtung per Nachschichtung auf der codierten Fallbasis), verfeinern zu Gold und exportieren in mehreren Formaten. Qualität ist Sache des Bundles, nicht des Datensatzes – siehe die Qualitäts-Tools in der Referenz der Bundle-Tools.
list_datasets
Abschnitt betitelt „list_datasets“Listet Datensätze auf, optional gefiltert.
| Parameter | Typ | Erforderlich | Standard | Beschreibung |
|---|---|---|---|---|
stage |
string |
Nein | — | Nach Stufe filtern: "bronze", "silver" oder "gold" |
source_type |
string |
Nein | — | Filter: "campaign", "project", "upload", "weighted" oder "refined" |
campaign_id |
string |
Nein | — | Nach Kampagnen-ID filtern |
limit |
integer |
Nein | 100 |
Maximale Anzahl an Ergebnissen |
Rückgabe: { items: [...], count, limit }
get_dataset
Abschnitt betitelt „get_dataset“Liefert Identität, Herkunft, Kennzahlen und Status eines Datensatzes. Dies ist das Tool, das jeder Pipeline-Schritt zum Abfragen nennt; deshalb ist die Antwort begrenzt und wächst nicht mit dem Fragebogen.
| Parameter | Typ | Erforderlich | Standard | Beschreibung |
|---|---|---|---|---|
dataset_id |
string |
Ja | — | UUID des Datensatzes |
Rückgabe: 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 ist der Grund, warum eine Stufe mit error endete – zum Beispiel die eigene Ablehnung coding_produced_no_columns: der Ableitung. Bei jedem anderen Status ist der Wert null. Lesen Sie ihn immer, wenn processing_status den Wert error hat: Ohne ihn erkennt eine Abfrage zwar, dass eine Stufe fehlgeschlagen ist, aber nicht, warum.
processing_error nennt vor dem Doppelpunkt stets die Art des Fehlers. Ein Grund, der nur Bezeichner, Einheiten, Spalten oder einen Schwellenwert nennt, kommt vollständig zurück. Eine Ablehnung der Gewichtung behält den Faktor und die Spalte, die sie nennt, aber nicht die zitierten Spaltenwerte, denn diese können Daten von Befragten sein. Die Silver-Seite in Balansor zeigt diesen Grund vollständig. get_bundle_quality meldet den Grund einer fehlgeschlagenen Stufe auf dieselbe Weise, ebenso get_task_status für einen run_bundle_pipeline-Lauf, der bei Silver abgebrochen ist.
weighting_config ist das Protokoll der Ableitung über das, was sie getan hat:
- die Faktoren, auf die sie gewichtet hat, mit ihren Zielen und Anpassungen;
- die Konvergenzwerte;
- wie viele Zeilen der Vollständigkeitsschwellenwert und der Ausschluss von Freiwilligen entfernt haben;
- welche offenen Einheiten sie versucht, codiert und verloren hat, jeweils mit der Art des Verlusts.
Das Spaltenschema ist nicht enthalten – lesen Sie es mit get_dataset_schema. Es ist das einzige unbegrenzte Feld eines Datensatzes (89 KB einer 90-KB-Antwort bei einem Silver mit 192 Spalten); eine Abfrage hat früher Zehntausende Token damit verbraucht, ein unverändertes Schema erneut zu lesen, nur um eine 7 Byte lange Statuszeichenkette zu sehen.
invalid_cells ist {column: count} für die Zellen, die die Extraktion nicht als den Typ ihrer Spalte lesen konnte und daher leer gespeichert hat – etwa ein Radio-Element, das Fließtext enthält. {} bedeutet, dass die Extraktion geprüft und nichts gefunden hat; null bedeutet, dass der Datensatz älter ist als diese Prüfung. Eine so geschriebene Leerstelle ist sonst nicht von einer übersprungenen Antwort zu unterscheiden; lesen Sie das Feld daher, bevor Sie Schlüsse über fehlende Werte ziehen.
get_dataset_schema
Abschnitt betitelt „get_dataset_schema“Liefert das Spaltenschema eines Datensatzes: je Spalte ihren dtype, die item_id, item_title und control_type, aus denen sie stammt, ihre labels-Zuordnung (Code → Beschriftung) und ihre Herkunft aus Roster oder Indikator.
| Parameter | Typ | Erforderlich | Standard | Beschreibung |
|---|---|---|---|---|
dataset_id |
string |
Ja | — | UUID des Datensatzes |
columns |
string[] |
Nein | — | Zurückzugebende Spaltennamen; weglassen für alle Spalten |
detail |
boolean |
Nein | true |
false liefert statt column_schema den column_index – Name und control_type jeder Spalte |
Rückgabe: { dataset_id, stage, column_count, column_schema, returned, unknown_columns }, bei detail gleich false mit column_index ({ name: control_type }, null für Zeilenmetadaten) anstelle von column_schema.
Zwei Spalten mit Zeilenmetadaten beschreiben, wie weit jede Umfrage gekommen ist: _reached zählt die Elemente, die der befragten Person angezeigt wurden (einschließlich des aktuell angezeigten), und _completeness ist der Anteil davon, den sie beantwortet hat (beantwortet ÷ erreicht). Der Vollständigkeitsschwellenwert des Bundles liest _completeness.
Ein Bronze liefert außerdem custom_attribute_keys: die benutzerdefinierten Attribute der Befragten, mit denen es extrahiert wurde, jedes davon eine Spalte des Datensatzes (_custom_<key>). Extrahiert werden nur Attribute, die ein Faktor einer Stichprobenstrategie oder ein Kalibrierungsziel des Bundles nennt. Lesen Sie diese Liste daher, bevor Sie ein Attribut als Ziel verwenden: Ein Schlüssel außerhalb der Liste ist erst nach einer erneuten Extraktion (create_bronze_dataset) im Datensatz. Eine leere Liste bedeutet, dass nichts genannt wurde. Bei Silver und Gold fehlt das Feld, ebenso bei einem Bronze, das extrahiert wurde, bevor Schlüssel aufgezeichnet wurden; extrahieren Sie ein solches neu, bevor Sie auf ein Attribut gewichten.
column_count ist die Spaltenzahl des Datensatzes selbst. Mit einem columns-Filter ist sie daher größer als returned, und die Differenz zeigt Ihnen, wie viel des Schemas Sie nicht gesehen haben. Ein übergebener Name, den der Datensatz nicht hat, kommt in unknown_columns zurück, statt verworfen zu werden – so lässt sich ein Tippfehler von einer Spalte unterscheiden, die der Stufe tatsächlich fehlt.
Bei einem echten Erhebungsinstrument lesen Sie es in zwei Schritten. Ein Schema mit 293 Spalten umfasst rund 134 KB, mehr als die meisten Agenten als Tool-Ergebnis verkraften. Rufen Sie das Tool zuerst mit detail: false auf – dieselben 293 Spalten kommen dann als Index von etwa 7 KB zurück – und übergeben Sie anschließend die wenigen benötigten Namen als columns, um deren vollständige Einträge zu erhalten. Gebraucht wird dieses Tool überhaupt nur in zwei Momenten: bei der Wahl der Kalibrierungsziele (welche Spalte, und wie ihre labels-Zuordnung jeden Code nennt) und beim Zusammenstellen eines Gold-Operationskatalogs (welche Spalten zum Umbenennen, Entfernen oder Umordnen existieren). GET /api/v1/datasets/<id> ist der andere Zugang und liefert das gesamte Schema – REST ist der Weg für große Ergebnisse.
create_bronze_dataset
Abschnitt betitelt „create_bronze_dataset“Extrahiert den Bronze-Datensatz eines Bundles. Das Bundle trägt bereits den Fragebogen und seine Kampagnenauswahl – bei diesem Tool gibt es keine frei wählbare Auswahl von Fragebogen oder Kampagne. Vorschauen werden ausnahmslos abgelehnt, sodass kein Argument einen Testdurchlauf aus der Designphase in die Basis einschleusen kann. Ein erneuter Lauf hängt das frische Bronze an die Kette des Bundles und macht ein nachgelagertes Silver/Gold kaskadierend ungültig (sie gelten dann als veraltet, werden aber nicht gelöscht – ihre Konfigurationen bleiben für eine Neuableitung mit einem Klick erhalten).
| Parameter | Typ | Erforderlich | Standard | Beschreibung |
|---|---|---|---|---|
bundle_id |
string |
Ja | — | Das Bundle, dessen Bronze (erneut) extrahiert wird |
include_demographics |
boolean |
Nein | true |
Demografische Spalten der Befragten und die vom Bundle genannten benutzerdefinierten Attribute einbeziehen |
Rückgabe: { dataset_id, bundle_id, stage: "bronze", ... } mit dem Extraktionsbericht, einschließlich invalid_cells (siehe get_dataset, wo Sie den Wert bei jedem späteren Schritt lesen), custom_attribute_keys (die als Spalten geschriebenen benutzerdefinierten Attribute) und empty_custom_attribute_keys (diejenigen davon, die keine befragte Person trägt – so zeigt sich ein falsch geschriebener Attributname).
Welche Attribute der Befragten extrahiert werden. Alter, Geschlecht und Ort werden für jede Zeile geschrieben. Ein benutzerdefiniertes Attribut wird nur geschrieben, wenn ein Faktor einer Stichprobenstrategie oder ein Kalibrierungsziel des Bundles es nennt; jeder andere Schlüssel im Eintrag der befragten Person gelangt nicht in den Datensatz. Ein genanntes Attribut, das keine befragte Person trägt, erhält trotzdem eine Spalte, die leer bleibt. Wird ein neues Attribut nach einer Extraktion genannt, ist daher ein weiterer Aufruf von create_bronze_dataset nötig, bevor eine Ableitung darauf gewichten kann.
include_demographics: false wird abgelehnt, wenn das Bundle ein benutzerdefiniertes Attribut nennt, mit {"error": "named_attributes_require_enrichment", "detail": "..."} unter Nennung der Attribute. Ein genanntes Attribut wird nur zusammen mit den demografischen Spalten geschrieben, und ein Bronze ohne es ließe sich nie darauf gewichten. Extrahieren Sie stattdessen mit dem Standardwert.
code_open_ends (Alias: derive_silver)
Abschnitt betitelt „code_open_ends (Alias: derive_silver)“Leitet das Silver eines Bundles ab: codiert offenen Text in eine beschriftete kategoriale Spalte je ausgewählter Dimension und führt dann ein Raking (Gewichtung per Nachschichtung) über die codierte Fallbasis durch. Dies ist das einzige Tool, das einen Silver-Datensatz erzeugt, und es verwendet stets das eigene fertige Bronze des Bundles – einen anderen Datensatz zu gewichten, bietet kein Tool an.
| Parameter | Typ | Erforderlich | Standard | Beschreibung |
|---|---|---|---|---|
bundle_id |
string |
Ja | — | Das Bundle, dessen Bronze zu Silver abgeleitet wird |
Rückgabe: { silver_dataset_id, status: "processing", job_id } – die Ableitung läuft im Hintergrund. Fragen Sie get_dataset(dataset_id=silver_dataset_id) ab, bis processing_status den Wert ready oder error hat.
Die Codierung läuft über die Einheiten, die die Codierungsauswahl des Bundles nennt – festgelegt mit set_coding_selection (siehe Bundle-Tools) – und innerhalb jeder Einheit über die Dimensionen, die Forschende in Balansor ausgewählt haben. Eine als nominal klassifizierte Einheit wird stattdessen nach exaktem Wert codiert, ohne Modellaufruf und ohne Prüfung der Dimensionen. Eine ausgewählte Einheit, die nicht klassifiziert oder als identifier klassifiziert ist, stoppt die Ableitung mit coding_selection_unresolvable unter Nennung der Einheit. Ist nichts ausgewählt, wird die Codierung übersprungen und die Gewichtung läuft direkt auf den Bronze-Daten; das ist ein gewöhnliches Ergebnis, kein Fehler. Eine ausgewählte Einheit, deren Dimensionen niemand geprüft hat, erzeugt keine codierte Spalte, und die Ableitung ist trotzdem erfolgreich – prüfen Sie awaiting_review bei get_bundle_coding, bevor Sie das Ergebnis als vollständig behandeln. Eine Ableitung wird abgelehnt, wenn ein Kalibrierungsziel eine codierte Spalte nennt, deren Dimension (weighting_factor_dimension_deselected) oder deren gesamte Einheit (weighting_factor_deselected) das Bundle nicht mehr auswählt – wählen Sie sie erneut aus oder entfernen Sie den Faktor. Abgelehnt wird eine Ableitung außerdem mit weighting_attributes_not_extracted, wenn sie auf ein benutzerdefiniertes Attribut der Befragten gewichten würde, mit dem das Bronze nicht extrahiert wurde (siehe unten). derive_silver ist als zweiter Tool-Name für dieselbe Operation registriert – Agententext, der „derive silver“ sagt, und Text, der „code open ends“ sagt, führen beide hierher.
Eine Ableitung, die nichts codiert, endet mit error, nicht mit ready. Eine einzelne nicht codierbare Einheit bleibt uncodiert, während die übrigen weiterhin codiert werden. Hat aber jede Einheit, die die Ableitung versucht hat, keine Spalte ergeben, erreicht das Silver processing_status: "error", und processing_error lautet coding_produced_no_columns:, gefolgt von jedem Einheitsschlüssel und dem Grund, warum er nichts ergeben hat. Behandeln Sie das als endgültig – ein erneuter Lauf trifft auf dieselben Einheiten und ergibt dasselbe Nichts. Beheben Sie daher die Ursache (extrahieren Sie ein Bronze neu, dem die Textspalten fehlen, oder reparieren Sie das Codebuch in Balansor), bevor Sie erneut ableiten. Davon zu unterscheiden ist ein nicht erreichbares Embedding-Backend: In diesem Fall wiederholt der Job selbstständig, bevor ein Fehler geschrieben wird.
Eine Gewichtung auf ein benutzerdefiniertes Attribut, das das Bronze nicht enthält, wird unter Nennung des Attributs abgelehnt. Der Code lautet weighting_attributes_not_extracted, und das Detail nennt jedes Attribut und seine Spalte. Je nach Kalibrierungszielen kommt die Ablehnung auf einem von zwei Wegen:
- Bilden die Ziele den gesamten Gewichtungssatz (
use_strategy_factorsistfalse, was nachset_calibration_targets(factors=[...])der Fall ist oder sobald Forschende die Silver-Seite geöffnet haben), antwortet das Tool selbst mit{"error": "weighting_attributes_not_extracted", "detail": "..."}, und es startet kein Job. - Folgen die Ziele weiterhin der Stichprobenstrategie, gibt das Tool
processingzurück, und das Silver endet vor jeder Codierung miterror, wobeiprocessing_errormitweighting_attributes_not_extracted:beginnt.
In beiden Fällen ist die Lösung dieselbe: Führen Sie create_bronze_dataset erneut aus und leiten Sie dann ab. Trägt keine befragte Person des Bundles ein Attribut dieses Namens, ist der Name falsch; korrigieren Sie ihn in den Kalibrierungszielen oder der Stichprobenstrategie, denn eine erneute Extraktion würde nur eine leere Spalte hinzufügen. Vergleichen Sie die custom_attribute_keys des Bronze (get_dataset_schema) mit den Attributen, auf die Sie gewichten wollen, um das vorab zu erkennen. Ein Attribut, das die Strategie nennt, ohne darauf zu gewichten, blockiert nie eine Ableitung; sein Faktor erscheint in get_bundle_quality bis zu einer erneuten Extraktion als nicht messbar.
create_gold_dataset
Abschnitt betitelt „create_gold_dataset“Verfeinert das fertige Silver eines Bundles zu seinem Gold. Verwendet stets das eigene Silver des Bundles und ersetzt ein früheres Gold in der Kette.
| Parameter | Typ | Erforderlich | Standard | Beschreibung |
|---|---|---|---|---|
bundle_id |
string |
Ja | — | Das Bundle, dessen Silver verfeinert wird |
name |
string |
Nein | — | Name des Gold-Datensatzes. Standard ist "{bundle_name} — Gold" |
operations |
object[] |
Nein | — | Die Gold-Konfiguration für diesen Aufruf. Weglassen, um aus der gespeicherten Konfiguration des Bundles zu bauen (dem auf der Gold-Seite gespeicherten Layout; lesen Sie es mit get_bundle). Eine Angabe überschreibt die gespeicherte Konfiguration nur für diesen Aufruf; gespeichert wird nichts |
Ohne Operationen (weder übergeben noch gespeichert) ist das Gold eine Kopie des Silver. Mit Operationen unterscheidet sich das Gold vom Silver nur durch das, was sie angeben: Jede nicht entfernte Spalte bleibt erhalten, in der Reihenfolge der Silver-Datei und mit ihrem vollständigen Schemaeintrag (Fragetext, Wertebeschriftungen).
Die operations-Konfiguration
Abschnitt betitelt „Die operations-Konfiguration“Eine geordnete Liste von Zeilen. Eine Zeile nennt Spalten der Silver-Datei – nie einen Namen, den ein rename einführt. Die einzige Ausnahme ist ein reorder-Eintrag, der auch eine Spalte nennen darf, die die Konfiguration hinzufügt. get_dataset_schema listet die Spalten, die das Schema des Silver nennt: Antworten, codierte Dimensionen und Gewichte. Die Silver-Datei enthält außerdem Spalten, die dort nicht aufgeführt sind: Spalten mit Zeilenmetadaten (etwa _survey_id und _response_timing) und Anreicherungsspalten, also die Attribute der Befragten, die die Extraktion hinzugefügt hat (_demographic_*, _custom_*). Sie bleiben im Gold wie jede andere Spalte erhalten, und auch eine Konfiguration kann sie namentlich ansprechen.
op |
Felder | Wirkung |
|---|---|---|
rename |
column, to |
column unter dem Namen to ausgeben. Das letzte rename einer Spalte gilt |
remove |
column |
column aus dem Gold weglassen |
alias |
column, to |
column zusätzlich unter dem Namen to ausgeben. Eine Zeile pro weiterem Namen; eine Spalte kann mehrere haben. column muss selbst ausgegeben werden |
reorder |
order (Liste von Namen) |
Die genannten Spalten kommen zuerst, in dieser Reihenfolge; jede Spalte, die order auslässt, folgt an ihrer Standardposition. Ein Eintrag ist eine Silver-Spalte, das to eines Alias oder ein berechneter name, jeweils höchstens einmal. Eine Spalte wird dadurch nie entfernt. Nur die letzte reorder-Zeile wirkt |
compute |
name, kind sowie die Felder der jeweiligen Art |
Eine Spalte namens name hinzufügen |
Standardpositionen für jede Spalte, die order nicht nennt: zuerst die Silver-Spalten in der Reihenfolge der Silver-Datei, dann die Aliase in der Reihenfolge der Konfiguration, dann die berechneten Spalten in der Reihenfolge der Konfiguration. Um einen Alias oder eine berechnete Spalte zwischen zwei Silver-Spalten zu platzieren, nennen Sie sie in order zusammen mit den Spalten davor.
Arten von compute:
kind |
Felder | Wirkung |
|---|---|---|
arithmetic |
left, operator ("+", "-", "*", "/"), right |
Eine Rechenoperation zwischen zwei Spalten, jede Zelle als Zahl gelesen. Eine Zelle, die keine Zahl ist, sowie eine Division durch null ergeben einen leeren Wert |
recode |
column, buckets (Liste von [min, max, label]) |
Jede Klasse ordnet die Werte von min bis max einschließlich dem label zu; jede Zelle wird als Zahl gelesen. Eine Zelle, die keine Zahl ist oder in keine Klasse fällt, ergibt einen leeren Wert. min und max sind endliche Zahlen, wobei min nicht über max liegt; label ist nicht leerer Text |
concat |
columns (Liste), separator (Text) |
Die Spalten in Reihenfolge verketten |
formula ist für eine künftige Version reserviert und wird namentlich abgelehnt, sowohl als op als auch als kind.
Regeln, die die Konfiguration erfüllen muss:
- Was eine Berechnung liest. Berechnungen laufen auf dem gesamten Silver, bevor eine Spalte umbenannt oder entfernt wird. Eine Eingabe ist eine Silver-Spalte (ausgegeben, umbenannt oder entfernt gleichermaßen) oder der
nameeinercompute-Zeile weiter oben in der Liste, nie ein Alias. Wo eine berechnete Spalte in der Datei steht, ändert nichts daran, was sie lesen darf. - Alias- und berechnete Namen. Das
toeines Alias und ein berechneternamemüssen sich von jedem Silver-Spaltennamen unterscheiden, entfernte eingeschlossen. - Ein Alias braucht seine Spalte. Ein
aliaseiner Spalte, die die Konfiguration entfernt, wird abgelehnt: Um eine Spalte nur unter einem neuen Namen auszugeben, verwenden Sierename. - Neue Namen. Ein Name, den die Konfiguration erzeugt (ein
rename-Ziel, ein Alias oder ein berechnetername), darf nicht leer sein und nicht mit Leerraum beginnen oder enden. - Ausgabenamen. Die Namen, die das Gold am Ende trägt, sind jede ausgegebene Spalte unter ihrem endgültigen Namen sowie jeder Alias und jeder berechnete Name. Ein von der Konfiguration erzeugter Name muss sich ohne Berücksichtigung der Groß- und Kleinschreibung von jedem anderen Ausgabenamen unterscheiden:
Scoreundscorekollidieren. Zwei Silver-Spalten, die die Konfiguration unter ihren eigenen Namen belässt, werden nie abgelehnt, selbst wenn sie sich nur in der Groß- und Kleinschreibung unterscheiden; das ist die eigene Benennung des Silver. - Mindestens eine Spalte. Eine Konfiguration, die jede Silver-Spalte entfernt und keine berechnet, wird abgelehnt.
- Die Gewichtsspalte. Die Gewichte des Gold sind die Gewichtsspalte des Silver: Umbenannt bleibt sie unter ihrem neuen Namen die Gewichtsspalte; wird sie entfernt, trägt das Gold keine Gewichte, selbst wenn eine andere Spalte auf ihren alten Namen umbenannt wird. Ein Alias der Gewichtsspalte ist eine zweite Kopie ihrer Werte und nie die Gewichtsspalte des Gold.
rename-,remove-,alias- undreorder-Zeilen dürfen untereinander in beliebiger Reihenfolge stehen. Die Reihenfolge zählt beicompute-Zeilen untereinander; beialias-Zeilen zählt sie nur für deren Standardposition.
[ {"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+"]]}]Rückgabe: { gold_dataset_id, name, stage: "gold", bundle_id, row_count, column_count, skipped }
skipped listet die Konfigurationseinträge, die der Build übergangen hat, weil das Silver ihre Spalte nicht hat, jeweils als { "op": "remove" | "reorder", "column": "<name>" }. Eine Konfiguration kann das Silver überdauern, für das sie geschrieben wurde: Ein remove- oder reorder-Eintrag, der eine Spalte nennt, die das Silver nicht mehr hat, wird übersprungen und hier gemeldet statt abgelehnt. Die Liste ist leer, wenn nichts übersprungen wurde.
Ablehnungen (jeweils { "error": "<code>", "detail": "..." }; es wird kein Gold veröffentlicht):
error |
Wann |
|---|---|
silver_not_ready |
Das Bundle hat kein fertiges Silver, seine Datei lässt sich nicht lesen, oder das Silver hat sich geändert, während das Gold gebaut wurde. Leiten Sie das Silver ab und rufen Sie erneut auf |
bronze_schema_stale |
Das Bronze des Bundles wurde mit einem älteren Spaltensatz extrahiert. Extrahieren Sie das Bronze neu, leiten Sie das Silver ab und rufen Sie erneut auf |
invalid_operations |
Die Konfiguration verletzt eine der obigen Regeln, geprüft vor jedem Build: ein unbekanntes oder reserviertes op oder kind, ein fehlendes Feld, ein leerer oder mit Leerraum beginnender oder endender neuer Name, eine fehlerhafte Klasse (eine Grenze, die keine endliche Zahl ist, oder min über max), ein Name, der zweimal in einem reorder steht, ein rename oder alias einer Spalte, die dem Silver fehlt, ein alias einer entfernten Spalte, eine Berechnungseingabe, die weder eine Silver-Spalte noch ein früherer berechneter Name ist, ein Alias oder berechneter Name, der einer Silver-Spalte gleicht, ein von der Konfiguration erzeugter Name, der sich von einem anderen Ausgabenamen nur in der Groß- und Kleinschreibung unterscheidet, oder eine Konfiguration, die keine Spalte übrig lässt. detail nennt jede betroffene Spalte |
build_failed |
Die Konfiguration hat die Prüfungen bestanden, aber eine Berechnung ließ sich auf den Daten nicht durchführen. detail enthält den Grund |
layout_changed |
Nur beim Bau aus der gespeicherten Konfiguration: Die Konfiguration wurde (auf der Gold-Seite) erneut gespeichert, während dieses Gold gebaut wurde. Das gebaute Gold wird verworfen, und das frühere Gold des Bundles, das aus der Konfiguration vor diesem Speichern gebaut wurde, ist nicht mehr ready; rufen Sie erneut auf |
gold_superseded |
Ein gleichzeitiger Build hat dieses Gold ersetzt; rufen Sie erneut auf |
Stufenprüfung: Das Silver des Bundles muss ready sein; ein fehlendes oder nicht fertiges Silver liefert einen Fehler, statt auf Bronze auszuweichen.
export_dataset
Abschnitt betitelt „export_dataset“Exportiert einen Datensatz im angegebenen Format.
| Parameter | Typ | Erforderlich | Standard | Beschreibung |
|---|---|---|---|---|
dataset_id |
string |
Ja | — | UUID des Datensatzes |
format |
string |
Nein | "csv" |
Exportformat: "csv", "csv_semicolon" (Trennzeichen ; und Dezimalzeichen ,, für ein ungarisches, deutsches, französisches oder spanisches Excel), "xlsx", "spss", "parquet", "rds" oder "json" |
Rückgabe: { dataset_id, format, download_url, rows, columns, file_size_bytes }. Die exportierte Datei wird nie direkt zurückgegeben – download_url ist ein kurzlebiger Link (er läuft wenige Minuten nach seiner Erzeugung ab), über den Sie die Datei ohne weitere Authentifizierung direkt per HTTPS abrufen. Bis zum Ablauf lässt er sich beliebig oft verwenden. Fordern Sie einen neuen Export an, wenn der Link abgelaufen ist.
Exportformate
Abschnitt betitelt „Exportformate“| Format | Dateiendung | Beschreibung |
|---|---|---|
csv |
.csv |
Universelles Format für die meisten Werkzeuge |
xlsx |
.xlsx |
Excel mit Übersichts- und Schemablatt |
spss |
.sav |
SPSS mit Variablen- und Wertebeschriftungen |
parquet |
.parquet |
Spaltenorientiertes Format mit vollständigen Metadaten (Snappy-Komprimierung) |
rds |
.rds |
R – kategoriale Variablen kommen als Faktoren an, Wertebeschriftungen als Faktorstufen |
json |
.json |
Ein Dokument: {dataset, column_schema, rows}. Die Zeilen behalten die gespeicherten Antwortcodes; die Wertebeschriftungen jeder Spalte stehen in column_schema. Fehlende Werte sind null |
delete_dataset
Abschnitt betitelt „delete_dataset“Löscht einen Datensatz und optional seine Datendatei.
| Parameter | Typ | Erforderlich | Standard | Beschreibung |
|---|---|---|---|---|
dataset_id |
string |
Ja | — | UUID des Datensatzes |
delete_file |
boolean |
Nein | false |
Auch die Parquet-Datendatei löschen |
Rückgabe: { deleted: true, dataset_id, dataset_info: { name, stage, row_count, data_path }, file_deleted }
Fehlerbehandlung
Abschnitt betitelt „Fehlerbehandlung“Stufenprüfung
Abschnitt betitelt „Stufenprüfung“Die Bundle-Pipeline erzwingt Reihenfolge und Bereitschaft der Stufen – eine Stufe lässt sich nicht überspringen und im veralteten Zustand nicht exportieren:
| Operation | Voraussetzung | Fehler |
|---|---|---|
code_open_ends / derive_silver |
Das Bronze des Bundles muss ready sein |
{"error": "bronze_not_ready", "detail": "Extract a ready Bronze first"} |
code_open_ends / derive_silver |
Das Bronze muss der aktuellen Version des Extraktionsschemas entsprechen | {"error": "bronze_schema_stale", "detail": "..."}. Bronze neu extrahieren (create_bronze_dataset), dann ableiten |
code_open_ends / derive_silver |
Jedes benutzerdefinierte Attribut, auf das die Ableitung gewichtet, muss in das Bronze extrahiert worden sein | {"error": "weighting_attributes_not_extracted", "detail": "..."}, mit Nennung der Attribute. Bronze neu extrahieren, dann ableiten |
create_bronze_dataset |
include_demographics muss true bleiben, wenn das Bundle ein benutzerdefiniertes Attribut nennt |
{"error": "named_attributes_require_enrichment", "detail": "..."}, mit Nennung der Attribute |
create_gold_dataset |
Das Silver des Bundles muss ready sein |
{"error": "silver_not_ready", "detail": "Derive a ready Silver first"} |
create_gold_dataset |
Das Bronze des Bundles muss der aktuellen Version des Extraktionsschemas entsprechen | {"error": "bronze_schema_stale", "detail": "..."}, mit Nennung dessen, was dieses Bronze nicht aufzeichnet. Bronze neu extrahieren, Silver ableiten, dann Gold bauen |
create_gold_dataset |
Die Konfiguration muss für die Spalten des Silver gültig sein | {"error": "invalid_operations", "detail": "..."}, mit Nennung der Zeilen und Spalten. Siehe create_gold_dataset |
export_dataset |
Der Datensatz muss ready sein (nicht processing/invalidated/error) |
{"error": "not_ready", "detail": "Dataset is '{status}', not ready — re-derive the stage before exporting."} |
export_dataset |
Das Bronze des Datensatzes (er selbst oder bei einem Silver oder Gold das Bronze seines Bundles) muss der aktuellen Version des Extraktionsschemas entsprechen | {"error": "bronze_schema_stale", "detail": "..."}, mit Nennung dessen, was dieses Bronze nicht aufzeichnet. Bronze neu extrahieren, neu ableiten, dann exportieren |
export_dataset |
Die codierten Fragen eines Silver müssen alle geprüft sein: Eine Frage, deren Dimensionen noch geprüft werden müssen, hat noch keine codierte Spalte | {"error": "coding_awaiting_review", "detail": "..."}, mit Nennung der Fragen. Dimensionen in Balansor prüfen, neu ableiten, dann exportieren |
export_dataset |
Die Datendatei des Datensatzes muss existieren | {"error": "file_missing", "detail": "The dataset's data file is missing — re-derive the stage."} |
Häufige Fehler
Abschnitt betitelt „Häufige Fehler“| Situation | Antwort |
|---|---|
| Datensatz nicht gefunden | {"error": "Dataset {id} not found"} |
| Bundle nicht gefunden | {"error": "not_found", "detail": "Bundle {id} not found"} |
| Strategie nicht gefunden | {"error": "Sampling strategy {id} not found"} |
| Keine Datendatei | {"error": "Dataset {id} has no data file"} |
| Ungültiges Exportformat | {"error": "Invalid format. Allowed: csv, csv_semicolon, xlsx, spss, parquet, rds, json"} |
| Keine abgeschlossenen Umfragen | {"error": "no_completed_surveys", "detail": "..."} – erweitern Sie die Kampagnenauswahl oder warten Sie auf weitere Abschlüsse |
| Bundle wählt keine Kampagne aus | {"error": "no_campaigns_selected", "detail": "..."} – die Messbasis eines Bundles sind die Umfragen der ausgewählten Kampagnen; weisen Sie mindestens eine zu |
| Extraktion konnte den Datensatz nicht schreiben | {"error": "extraction_failed", "column": "q_x", "detail": "..."} – eine Spalte enthält Werte, die sich nicht zu einem einheitlichen Typ zusammenführen lassen. Der betroffene Wert wird bewusst weggelassen (er ist die Antwort einer befragten Person); prüfen Sie die Rohwerte dieser Spalte, korrigieren Sie die Quellantworten und extrahieren Sie neu |