Adatkészlet-eszközök – MCP-eszközreferencia
Az adatkészlet-eszközök a csomaghoz kötött medallion adatfolyamot valósítják meg: a csomag egy projektet, egy kérdőívet és a kampányok egy részhalmazát kapcsolja össze egyetlen lineáris Bronz → Ezüst → Arany lánccal (az életciklus-műveleteket lásd a Csomageszközök oldalon). Ezek az eszközök a kitöltések válaszaiból előállítják a csomag Bronz adatkészletét, származtatják az Ezüst adatkészletet (a nyitott válaszok kódolása, majd utólagos rétegzés szerinti súlyozás a kódolt eseteken), Arany adatkészletté finomítják, és több formátumban exportálják. A minőség a csomag ügye, nem az adatkészleté – lásd a minőségi eszközöket a Csomageszközök referenciájában.
list_datasets
Szekció neve “list_datasets”Adatkészletek listázása opcionális szűrőkkel.
| Paraméter | Típus | Kötelező | Alapértelmezés | Leírás |
|---|---|---|---|---|
stage |
string |
Nem | — | Szűrés szakasz szerint: "bronze", "silver" vagy "gold" |
source_type |
string |
Nem | — | Szűrés: "campaign", "project", "upload", "weighted" vagy "refined" |
campaign_id |
string |
Nem | — | Szűrés kampányazonosító szerint |
limit |
integer |
Nem | 100 |
A visszaadott találatok legnagyobb száma |
Visszatérési érték: { items: [...], count, limit }
get_dataset
Szekció neve “get_dataset”Egy adatkészlet azonosító adatainak, leszármazásának, mutatóinak és állapotának lekérdezése. Ez az az eszköz, amelynek lekérdezését minden adatfolyam-lépés javasolja, ezért korlátos méretű – a válasz nem nő a kérdőívvel.
| Paraméter | Típus | Kötelező | Alapértelmezés | Leírás |
|---|---|---|---|---|
dataset_id |
string |
Igen | — | Az adatkészlet UUID-ja |
Visszatérési érték: 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.
A processing_error annak oka, hogy egy szakasz error állapotban végződött – például a származtatás saját coding_produced_no_columns: elutasítása. Minden más állapotban null. Olvassa ki, valahányszor a processing_status értéke error: enélkül egy lekérdezés azt látja, hogy egy szakasz sikertelen volt, de azt nem, hogy miért.
A processing_error a kettőspont előtt mindig a hiba fajtáját tartalmazza. A csak azonosítókat, egységeket, oszlopokat vagy küszöböt megnevező ok teljes egészében visszaérkezik. A súlyozási elutasítás megtartja az általa megnevezett tényezőt és oszlopot, de az idézett oszlopértékeket nem, mert azok válaszadói adatok lehetnek. Az ok teljes szövegét a Balansor Ezüst szakaszoldala mutatja meg. A get_bundle_quality ugyanígy jelenti egy sikertelen szakasz okát, és ugyanígy tesz a get_task_status is egy Ezüst adatkészletnél leállt run_bundle_pipeline futtatás esetén.
A weighting_config a származtatás feljegyzése arról, amit tett:
- a tényezők, amelyekre súlyozott, a célértékeikkel és az igazításaikkal;
- a konvergencia számai;
- hány sort távolított el a teljességi küszöb és az önkéntesek kizárása;
- mely nyitott szöveges egységeket próbált meg kódolni, melyeket kódolt és melyeket veszített el, minden veszteség fajtájával.
Az oszlopséma nem itt található – a get_dataset_schema eszközzel olvashatja ki. Ez az egyetlen korlátlan méretű mező, amelyet egy adatkészlet hordoz (egy 192 oszlopos Ezüst adatkészletnél a 90 KB-os válaszból 89 KB), így egy lekérdezés több tízezer tokent költött el egy változatlan séma újraolvasására, csak hogy egy 7 bájtos állapotszöveget lásson.
Az invalid_cells egy {column: count} leképezés azokról a cellákról, amelyeket az előállítás nem tudott az oszlopuk által tárolt típusként beolvasni, ezért üresként tárolta őket – például egy szöveget tartalmazó Radio elem. A {} azt jelenti, hogy az előállítás ellenőrizte és nem talált ilyet; a null azt, hogy az adatkészlet régebbi az ellenőrzésnél. Az így írt üres érték egyébként megkülönböztethetetlen attól, hogy a válaszadó kihagyta a kérdést, ezért olvassa ki, mielőtt a hiányzó adatokról következtetéseket vonna le.
get_dataset_schema
Szekció neve “get_dataset_schema”Egy adatkészlet oszlopsémájának lekérdezése: oszloponként a dtype, az item_id, az item_title és a control_type, amelyből származik, a labels leképezése (kód → felirat), valamint a roster-, illetve indikátoreredete.
| Paraméter | Típus | Kötelező | Alapértelmezés | Leírás |
|---|---|---|---|---|
dataset_id |
string |
Igen | — | Az adatkészlet UUID-ja |
columns |
string[] |
Nem | — | A visszaadandó oszlopnevek; hagyja el, ha minden oszlopra szüksége van |
detail |
boolean |
Nem | true |
A false a column_schema helyett a column_index mezőt adja vissza – minden oszlop nevét és control_type értékét |
Visszatérési érték: { dataset_id, stage, column_count, column_schema, returned, unknown_columns }; ha a detail értéke false, a column_schema helyén a column_index áll ({ name: control_type }, sormetaadatnál null).
Két sormetaadat-oszlop írja le, meddig jutottak az egyes kitöltések: a _reached azoknak az elemeknek a száma, amelyeket a válaszadónak megjelenítettek (a képernyőn lévőt is beleértve), a _completeness pedig ezek közül a megválaszoltak aránya (megválaszolt ÷ elért). A csomag teljességi küszöbe a _completeness értéket olvassa.
A Bronz adatkészlet a custom_attribute_keys mezőt is visszaadja: azokat a válaszadói egyéni attribútumokat, amelyekkel előállították, és amelyek mindegyike az adatkészlet egy oszlopa (_custom_<key>). Csak azokat az attribútumokat állítja elő a rendszer, amelyekre a csomag egy mintavételistratégia-tényezője vagy kalibrációs célértéke hivatkozik, ezért olvassa ki ezt a listát, mielőtt egy attribútumot célozna: a listán kívüli kulcs egy újbóli előállításig (create_bronze_dataset) nincs az adatkészletben. Az üres lista azt jelenti, hogy semmire sem hivatkoztak. Ezüst és Arany adatkészlet esetén, valamint olyan Bronz adatkészletnél, amelyet a kulcsok rögzítése előtt állítottak elő, a mező hiányzik; az utóbbit állítsa elő újra, mielőtt egy attribútumra súlyozna.
A column_count az adatkészlet saját értéke, így columns szűrővel nagyobb a returned értéknél, és a különbség megmutatja, a séma mekkora részét nem látta még. Az átadott, de az adatkészletben nem létező név az unknown_columns mezőben tér vissza, nem hagyja el a rendszer, így az elgépelés megkülönböztethető attól az oszloptól, amely a szakaszból valóban hiányzik.
Valódi mérőeszköznél két lépésben olvassa ki. Egy 293 oszlopos séma kb. 134 KB, ami a legtöbb ügynök eszközválasz-keretét meghaladja. Először detail: false értékkel hívja meg – ugyanaz a 293 oszlop kb. 7 KB-os indexként érkezik vissza –, majd adja át columns paraméterként azt a néhány nevet, amelynek a teljes bejegyzésére szüksége van. Két helyzetben kell egyáltalán ez az eszköz: a kalibrációs célértékek kiválasztásakor (melyik oszlop, és a labels leképezése hogyan nevezi az egyes kódokat), valamint egy Arany műveletkatalógus összeállításakor (milyen oszlopok léteznek, amelyeket át lehet nevezni, el lehet távolítani vagy át lehet rendezni). A másik út a GET /api/v1/datasets/<id>, amely a teljes sémát hordozza – a nagy eredmények csatornája a REST.
create_bronze_dataset
Szekció neve “create_bronze_dataset”Egy csomag Bronz adatkészletének előállítása. A csomag már tartalmazza a kérdőívet és a kampányok részhalmazát – ennél az eszköznél nincs szabadon megadható kérdőív- vagy kampányválasztás. Az előnézeteket a rendszer feltétel nélkül elutasítja, így semmilyen argumentummal nem kerülhet be egy tervezés közbeni próbakitöltés a mérési alapba. Az újrafuttatás az új Bronz adatkészletet a csomag láncához csatolja, és láncszerűen érvényteleníti az utána következő Ezüst/Arany adatkészletet (ezek elavulnak, de nem törlődnek – a receptjeik megmaradnak egy egykattintásos újraszármaztatáshoz).
| Paraméter | Típus | Kötelező | Alapértelmezés | Leírás |
|---|---|---|---|---|
bundle_id |
string |
Igen | — | Az a csomag, amelynek Bronz adatkészletét (újra) elő kell állítani |
include_demographics |
boolean |
Nem | true |
A válaszadók demográfiai oszlopainak és a csomag által megnevezett egyéni attribútumoknak a felvétele |
Visszatérési érték: { dataset_id, bundle_id, stage: "bronze", ... } az előállítási jelentéssel, amely tartalmazza az invalid_cells mezőt (lásd a get_dataset eszközt, ahol ezt bármely későbbi körben kiolvashatja), a custom_attribute_keys mezőt (az oszlopként kiírt egyéni attribútumok) és az empty_custom_attribute_keys mezőt (ezek közül azok, amelyekkel egyetlen megkérdezett válaszadó sem rendelkezik – így derül ki egy elgépelt jellemzőnév).
Mely válaszadói jellemzőket állítja elő a rendszer. Az életkort, a nemet és a lakóhelyet minden sorhoz kiírja a rendszer. Egyéni attribútumot csak akkor ír ki, ha a csomag egy mintavételistratégia-tényezője vagy kalibrációs célértéke hivatkozik rá; a válaszadói rekord minden más kulcsa kimarad az adatkészletből. Az a megnevezett attribútum, amellyel egyetlen válaszadó sem rendelkezik, szintén kap egy üresen hagyott oszlopot. Ezért ha egy előállítás után nevez meg új attribútumot, újabb create_bronze_dataset hívásra van szükség, mielőtt egy származtatás súlyozhatna rá.
Az include_demographics: false értéket a rendszer elutasítja, ha a csomag egyéni attribútumot nevez meg, az attribútumokat megnevező {"error": "named_attributes_require_enrichment", "detail": "..."} válasszal. A megnevezett attribútumot a rendszer csak a demográfiai oszlopokkal együtt írja ki, és egy nélküle előállított Bronz adatkészlet soha nem lenne súlyozható rá. Ehelyett az alapértelmezett értékkel állítsa elő.
code_open_ends (álnév: derive_silver)
Szekció neve “code_open_ends (álnév: derive_silver)”Egy csomag Ezüst adatkészletének származtatása: a nyitott szöveges válaszok kódolása kiválasztott dimenziónként egy-egy címkézett kategoriális oszlopba, majd rake-súlyozás (utólagos rétegzés szerinti súlyozás) a kódolt eseteken. Ez az egyetlen eszköz, amely Ezüst adatkészletet hoz létre, és mindig a csomag saját, kész Bronz adatkészletéből indul – bármely más adatkészlet súlyozását egyetlen eszköz sem kínálja.
| Paraméter | Típus | Kötelező | Alapértelmezés | Leírás |
|---|---|---|---|---|
bundle_id |
string |
Igen | — | Az a csomag, amelynek Bronz adatkészletéből Ezüst adatkészletet kell származtatni |
Visszatérési érték: { silver_dataset_id, status: "processing", job_id } – a származtatás a háttérben fut. Kérdezze le a get_dataset(dataset_id=silver_dataset_id) hívással, amíg a processing_status értéke ready vagy error nem lesz.
A kódolás azokon az egységeken fut, amelyeket a csomag kódolási kiválasztása megnevez – ezt a set_coding_selection eszközzel állíthatja be (lásd a Csomageszközöket) –, és ezeken belül azokon a dimenziókon, amelyeket egy kutató a Balansorban kiválasztott; az elemző által nominal típusúnak besorolt egységet a rendszer ehelyett pontos érték szerint kódolja, modellhívás és dimenzió-áttekintés nélkül. A besorolatlan vagy identifier típusúnak besorolt kiválasztott egység az azt megnevező coding_selection_unresolvable hibával leállítja a származtatást. Ha semmi sincs kiválasztva, a kódolás kimarad, és a súlyozás közvetlenül a Bronz adatokon fut; ez szokványos kimenetel, nem hiba. Az a kiválasztott egység, amelynek dimenzióit senki sem tekintette át, nem hoz létre kódolt oszlopot, a származtatás mégis sikeres – mielőtt az eredményt teljesnek tekintené, ellenőrizze a get_bundle_coding awaiting_review mezőjét. A rendszer elutasítja a származtatást, ha egy kalibrációs célérték olyan kódolt oszlopot nevez meg, amelynek dimenzióját (weighting_factor_dimension_deselected) vagy teljes egységét (weighting_factor_deselected) a csomag már nem választja ki – válassza ki újra, vagy hagyja el a tényezőt. A származtatást weighting_attributes_not_extracted hibával is elutasítja, ha olyan válaszadói egyéni attribútumra súlyozna, amellyel a Bronz adatkészletet nem állították elő (lásd alább). A derive_silver ugyanennek a műveletnek a második eszközneveként van regisztrálva – a „derive silver” és a „code open ends” megfogalmazású ügynöki szöveg is erre oldódik fel.
Az a származtatás, amely semmit sem kódol, error, nem pedig ready állapotban végződik. Egy nem kódolható egység kódolatlan marad, a többit pedig a rendszer továbbra is kódolja, de ha a származtatás által megkísérelt egyik egység sem hozott létre oszlopot, az Ezüst adatkészlet processing_status: "error" állapotba kerül, a processing_error pedig coding_produced_no_columns: szöveggel kezdődik, majd felsorolja az egyes egységkulcsokat és azt, hogy miért nem adtak semmit. Kezelje végleges állapotként – egy újrafuttatás ugyanazokkal az egységekkel találkozik, és ugyanúgy semmit sem hoz létre, ezért az újbóli származtatás előtt szüntesse meg az okot (állítsa elő újra azt a Bronz adatkészletet, amelyből hiányoznak a szöveges oszlopok, vagy javítsa ki a kódkönyvet a Balansorban). Ez különbözik az elérhetetlen beágyazási háttérszolgáltatástól, amelyet a feladat magától újrapróbál, mielőtt bármilyen hibát kiírna.
Ha a Bronz adatkészletben nem szereplő egyéni attribútumra súlyozna, a rendszer a súlyozást név szerint elutasítja. A kód weighting_attributes_not_extracted, a részletek pedig megnevezik az egyes attribútumokat és az oszlopukat. A kalibrációs célértékektől függően kétféleképpen érkezik:
- Ha a célértékek alkotják a teljes súlyozási halmazt (a
use_strategy_factorsértékefalse, ami aset_calibration_targets(factors=[...])hívás után, illetve azután áll fenn, hogy egy kutató megnyitotta az Ezüst oldalt), maga az eszköz válaszol{"error": "weighting_attributes_not_extracted", "detail": "..."}értékkel, és nem indul feladat. - Ha a célértékek még a mintavételi stratégiát követik, az eszköz
processingértéket ad vissza, az Ezüst adatkészlet még bármilyen kódolás előtterrorállapotban végződik, aprocessing_errorpedigweighting_attributes_not_extracted:szöveggel kezdődik.
A javítás mindkét esetben ugyanaz: futtassa újra a create_bronze_dataset eszközt, majd származtasson. Ha a csomag egyetlen válaszadója sem rendelkezik ilyen nevű attribútummal, a név hibás; javítsa ki a kalibrációs célértékekben vagy a mintavételi stratégiában, mivel egy újbóli előállítás csak egy üres oszlopot adna hozzá. Ha előre látni szeretné ezt, vesse össze a Bronz adatkészlet custom_attribute_keys mezőjét (get_dataset_schema) azokkal az attribútumokkal, amelyekre súlyozni kíván. Az az attribútum, amelyet a stratégia súlyozás nélkül nevez meg, soha nem akadályozza a származtatást; a tényezője egy újbóli előállításig nem mérhetőként jelenik meg a get_bundle_quality eredményében.
create_gold_dataset
Szekció neve “create_gold_dataset”Egy csomag kész Ezüst adatkészletének finomítása a csomag Arany adatkészletévé. Mindig a csomag saját Ezüst adatkészletéből indul; a láncban lévő korábbi Arany adatkészletet lecseréli.
| Paraméter | Típus | Kötelező | Alapértelmezés | Leírás |
|---|---|---|---|---|
bundle_id |
string |
Igen | — | Az a csomag, amelynek Ezüst adatkészletét finomítani kell |
name |
string |
Nem | — | Az Arany adatkészlet neve. Alapértelmezés: "{bundle_name} — Gold" |
operations |
object[] |
Nem | — | Az ehhez a híváshoz tartozó Arany recept. Ha elhagyja, a csomag tárolt receptjéből épül fel (az Arany oldalon mentett elrendezés; a get_bundle eszközzel olvashatja ki). Ha megadja, csak erre a hívásra írja felül a tárolt receptet; a rendszer semmit sem tárol |
Műveletek nélkül (ha sem átadott, sem tárolt művelet nincs) az Arany adatkészlet az Ezüst adatkészlet másolata. Műveletekkel az Arany adatkészlet csak abban tér el az Ezüst adatkészlettől, amit azok előírnak: minden el nem távolított oszlop megmarad, az Ezüst fájl sorrendjében, a teljes sémabejegyzésével (kérdésszöveg, értékcímkék).
Az operations recept
Szekció neve “Az operations recept”Sorok rendezett listája. Egy sor az Ezüst fájl oszlopait nevezi meg – soha nem egy rename által bevezetett nevet. Az egyetlen kivétel a reorder bejegyzés, amely a recept által hozzáadott oszlopot is megnevezhet. A get_dataset_schema azokat az oszlopokat sorolja fel, amelyeket az Ezüst adatkészlet sémája megnevez: válaszokat, kódolt dimenziókat és súlyokat. Az Ezüst fájl olyan oszlopokat is tartalmaz, amelyeket nem sorol fel: sormetaadat-oszlopokat (például _survey_id és _response_timing) és kiegészítő oszlopokat, vagyis az előállítás által hozzáadott válaszadói jellemzőket (_demographic_*, _custom_*). Ezek bármely más oszlophoz hasonlóan megmaradnak az Arany adatkészletben, és a recept név szerint ezekre is hivatkozhat.
op |
Mezők | Hatás |
|---|---|---|
rename |
column, to |
A column kiszolgálása to néven. Egy oszlopnál az utolsó rename érvényes |
remove |
column |
A column kihagyása az Arany adatkészletből |
alias |
column, to |
A column még egyszeri kiszolgálása to néven. További nevenként egy sor; egy oszlopnak több is lehet. Magát a column oszlopot is ki kell szolgálni |
reorder |
order (nevek listája) |
A megnevezett oszlopok kerülnek előre, ebben a sorrendben; minden oszlop, amelyet az order kihagy, az alapértelmezett helyén követi őket. Egy bejegyzés Ezüst-oszlop, egy álnév to értéke vagy egy számított name lehet, mindegyik legfeljebb egyszer. Soha nem hagy el oszlopot. Csak az utolsó reorder sor lép érvénybe |
compute |
name, kind, valamint a fajta saját mezői |
Egy name nevű oszlop hozzáadása |
Alapértelmezett helyek minden olyan oszlopnál, amelyet az order nem nevez meg: az Ezüst-oszlopok az Ezüst fájl sorrendjében, majd az álnevek a recept sorrendjében, végül a számított oszlopok a recept sorrendjében. Ha egy álnevet vagy számított oszlopot két Ezüst-oszlop közé szeretne tenni, nevezze meg az order listában az előtte álló oszlopokkal együtt.
A compute fajtái:
kind |
Mezők | Hatás |
|---|---|---|
arithmetic |
left, operator ("+", "-", "*", "/"), right |
Művelet két oszlop között, minden cellát számként olvasva. A nem szám értékű cella és a nullával való osztás üres értéket ad |
recode |
column, buckets ([min, max, label] elemek listája) |
Minden sáv a min és max közötti értékeket – a határokat is beleértve – a label címkéhez rendeli; minden cellát számként olvas. A nem szám értékű cella, illetve az, amelyet egyik sáv sem fed le, üres értéket ad. A min és a max véges szám, és a min nem lehet nagyobb a max értékénél; a label nem üres szöveg |
concat |
columns (lista), separator (szöveg) |
Az oszlopok összefűzése sorrendben |
A formula egy jövőbeli kiadásnak van fenntartva, és a rendszer név szerint elutasítja, op és kind értékként egyaránt.
A receptnek az alábbi szabályokat kell teljesítenie:
- Mit olvas egy számítás. A számítások a teljes Ezüst adatkészleten futnak, mielőtt bármely oszlopot átneveznének vagy eltávolítanának. A bemenet egy Ezüst-oszlop (akár kiszolgált, akár átnevezett, akár eltávolított) vagy egy a listában korábbi
computesornameértéke, soha nem álnév. Az, hogy egy számított oszlop hol áll a fájlban, nem változtat azon, mit olvashat. - Álnevek és számított nevek. Egy álnév
toértékének és egy számítottnameértéknek minden Ezüst-oszlopnévtől különböznie kell, az eltávolítottakat is beleértve. - Az álnévhez kell az oszlopa. A recept által eltávolított oszlop
aliassorát a rendszer elutasítja: ha egy oszlopot csak egyetlen új néven szeretne kiszolgálni, használja arenameműveletet. - Új nevek. A recept által létrehozott név (egy
renamecélja, egy álnév vagy egy számítottname) nem lehet üres, és nem kezdődhet, illetve nem végződhet szóközzel. - Kimeneti nevek. Az Arany adatkészlet végső nevei: minden kiszolgált oszlop a végső nevén, valamint minden álnév és minden számított név. A recept által létrehozott névnek a kis- és nagybetűktől eltekintve is különböznie kell minden más kimeneti névtől: a
Scoreés ascoreütközik. Két olyan Ezüst-oszlopot, amelyet a recept a saját nevén hagy, a rendszer soha nem utasít el, akkor sem, ha csak a kis- és nagybetűkben különböznek; ez az Ezüst adatkészlet saját elnevezése. - Legalább egy oszlop. Azt a receptet, amely minden Ezüst-oszlopot eltávolít, és egyet sem számít ki, a rendszer elutasítja.
- A súlyoszlop. Az Arany adatkészlet súlyai az Ezüst adatkészlet súlyoszlopából származnak: átnevezve az új nevén is súlyoszlop marad; eltávolítva az Arany adatkészlet nem hordoz súlyokat, akkor sem, ha egy másik oszlopot a régi nevére neveznek át. A súlyoszlop álneve az értékeinek második másolata, és soha nem az Arany adatkészlet súlyoszlopa.
- A
rename,remove,aliasésreordersorok egymás között bármilyen sorrendben állhatnak. A sorrend acomputesorok között számít, azaliassorok között pedig csak az alapértelmezett helyük szempontjából.
[ {"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+"]]}]Visszatérési érték: { gold_dataset_id, name, stage: "gold", bundle_id, row_count, column_count, skipped }
A skipped felsorolja azokat a receptbejegyzéseket, amelyeket az összeállítás félretett, mert az Ezüst adatkészletben nincs meg az oszlopuk, mindegyiket { "op": "remove" | "reorder", "column": "<name>" } alakban. Egy recept túlélheti azt az Ezüst adatkészletet, amelyhez írták: az a remove vagy reorder bejegyzés, amely az Ezüst adatkészletben már nem létező oszlopot nevez meg, kimarad, és itt jelenik meg; a rendszer nem utasítja el. Üres lista, ha semmi sem maradt ki.
Elutasítások (mindegyik { "error": "<code>", "detail": "..." } alakú; nem jelenik meg Arany adatkészlet):
error |
Mikor |
|---|---|
silver_not_ready |
A csomagnak nincs kész Ezüst adatkészlete, a fájlja nem olvasható, vagy az Ezüst adatkészlet megváltozott, miközben az Arany adatkészlet épült. Származtassa az Ezüst adatkészletet, majd hívja újra |
bronze_schema_stale |
A csomag Bronz adatkészletét egy régebbi oszlopkészlettel állították elő. Állítsa elő újra a Bronz adatkészletet, származtassa az Ezüst adatkészletet, majd hívja újra |
invalid_operations |
A recept megsért egy fenti szabályt, amelyet a rendszer bármilyen összeállítás előtt ellenőriz: ismeretlen vagy fenntartott op vagy kind, hiányzó mező, üres vagy szóközökkel körülvett új név, hibás sáv (olyan határ, amely nem véges szám, vagy a max értékénél nagyobb min), egy reorder sorban kétszer szereplő név, az Ezüst adatkészletből hiányzó oszlop rename vagy alias sora, eltávolított oszlop alias sora, olyan számítási bemenet, amely sem Ezüst-oszlop, sem korábbi számított név, Ezüst-oszloppal egyező álnév vagy számított név, a recept által létrehozott olyan név, amely egy másik kimeneti névtől csak kis- és nagybetűkben tér el, vagy olyan recept, amely egyetlen oszlopot sem hagy meg. A detail megnevezi az összes érintett oszlopot |
build_failed |
A recept átment az ellenőrzéseken, de egy számítást nem lehetett elvégezni az adatokon. A detail tartalmazza az okot |
layout_changed |
Csak tárolt receptből történő összeállításkor: a receptet (az Arany oldalon) újra mentették, miközben ez az Arany adatkészlet épült. A rendszer elveti az elkészült Arany adatkészletet, és a csomag korábbi, a mentés előtti receptből épült Arany adatkészlete már nem ready állapotú; hívja újra |
gold_superseded |
Egy párhuzamos összeállítás lecserélte ezt az Arany adatkészletet; hívja újra |
Szakaszvalidáció: A csomag Ezüst adatkészletének ready állapotúnak kell lennie; a hiányzó vagy nem kész Ezüst adatkészlet hibát ad vissza, ahelyett hogy a rendszer a Bronz adatkészletre térne vissza.
export_dataset
Szekció neve “export_dataset”Adatkészlet exportálása a megadott formátumban.
| Paraméter | Típus | Kötelező | Alapértelmezés | Leírás |
|---|---|---|---|---|
dataset_id |
string |
Igen | — | Az adatkészlet UUID-ja |
format |
string |
Nem | "csv" |
Exportformátum: "csv", "csv_semicolon" (; elválasztó és , tizedesjel magyar, német, francia vagy spanyol Excelhez), "xlsx", "spss", "parquet", "rds" vagy "json" |
Visszatérési érték: { dataset_id, format, download_url, rows, columns, file_size_bytes }. Az exportált fájlt a rendszer soha nem adja vissza közvetlenül a válaszban – a download_url egy rövid életű link (a létrehozása után néhány perccel lejár), amellyel a fájl további hitelesítés nélkül, közvetlenül HTTPS-en tölthető le; a lejáratáig tetszőleges számú alkalommal újra felhasználható. Ha a link lejárt, kérjen új exportot.
Exportformátumok
Szekció neve “Exportformátumok”| Formátum | Kiterjesztés | Leírás |
|---|---|---|
csv |
.csv |
Univerzális formátum a legtöbb eszközhöz |
xlsx |
.xlsx |
Excel összesítő- és sémamunkalappal |
spss |
.sav |
SPSS változó- és értékcímkékkel |
parquet |
.parquet |
Oszlopos formátum teljes metaadattal (Snappy tömörítés) |
rds |
.rds |
R – a kategoriális változók faktorként, az értékcímkék faktorszintként érkeznek |
json |
.json |
Egyetlen dokumentum: {dataset, column_schema, rows}. A sorok megtartják a tárolt válaszkódokat; az egyes oszlopok értékcímkéi a column_schema mezőben találhatók. A hiányzó értékek null értékűek |
delete_dataset
Szekció neve “delete_dataset”Adatkészlet és opcionálisan az adatfájljának törlése.
| Paraméter | Típus | Kötelező | Alapértelmezés | Leírás |
|---|---|---|---|---|
dataset_id |
string |
Igen | — | Az adatkészlet UUID-ja |
delete_file |
boolean |
Nem | false |
A Parquet adatfájl törlése is |
Visszatérési érték: { deleted: true, dataset_id, dataset_info: { name, stage, row_count, data_path }, file_deleted }
Hibakezelés
Szekció neve “Hibakezelés”Szakaszvalidáció
Szekció neve “Szakaszvalidáció”A csomag adatfolyama megköveteli a szakaszok sorrendjét és készenlétét – egy szakasz nem ugorható át, és elavult állapotban nem exportálható:
| Művelet | Követelmény | Hiba |
|---|---|---|
code_open_ends / derive_silver |
A csomag Bronz adatkészletének ready állapotúnak kell lennie |
{"error": "bronze_not_ready", "detail": "Extract a ready Bronze first"} |
code_open_ends / derive_silver |
A Bronz adatkészletnek az aktuális előállítási sémaverzióval kell készülnie | {"error": "bronze_schema_stale", "detail": "..."}. Állítsa elő újra a Bronz adatkészletet (create_bronze_dataset), majd származtasson |
code_open_ends / derive_silver |
Minden egyéni attribútumnak, amelyre a származtatás súlyoz, szerepelnie kell a Bronz adatkészletben | {"error": "weighting_attributes_not_extracted", "detail": "..."}, az attribútumok megnevezésével. Állítsa elő újra a Bronz adatkészletet, majd származtasson |
create_bronze_dataset |
Az include_demographics értékének true-nak kell maradnia, ha a csomag egyéni attribútumot nevez meg |
{"error": "named_attributes_require_enrichment", "detail": "..."}, az attribútumok megnevezésével |
create_gold_dataset |
A csomag Ezüst adatkészletének ready állapotúnak kell lennie |
{"error": "silver_not_ready", "detail": "Derive a ready Silver first"} |
create_gold_dataset |
A csomag Bronz adatkészletének az aktuális előállítási sémaverzióval kell készülnie | {"error": "bronze_schema_stale", "detail": "..."}, megnevezve, mit nem rögzít az a Bronz adatkészlet. Állítsa elő újra a Bronz adatkészletet, származtassa az Ezüst adatkészletet, majd építse fel az Arany adatkészletet |
create_gold_dataset |
A receptnek érvényesnek kell lennie az Ezüst oszlopaira | {"error": "invalid_operations", "detail": "..."}, a sorok és oszlopok megnevezésével. Lásd: create_gold_dataset |
export_dataset |
Az adatkészletnek ready állapotúnak kell lennie (nem processing/invalidated/error) |
{"error": "not_ready", "detail": "Dataset is '{status}', not ready — re-derive the stage before exporting."} |
export_dataset |
Az érintett Bronz adatkészletnek (magának az adatkészletnek, illetve Ezüst vagy Arany adatkészlet esetén a csomagja Bronz adatkészletének) az aktuális előállítási sémaverzióval kell készülnie | {"error": "bronze_schema_stale", "detail": "..."}, megnevezve, mit nem rögzít az a Bronz adatkészlet. Állítsa elő újra a Bronz adatkészletet, származtasson újra, majd exportáljon |
export_dataset |
Egy Ezüst adatkészlet minden kódolt kérdését át kell tekinteni: a dimenzió-áttekintésre váró kérdésnek még nincs kódolt oszlopa | {"error": "coding_awaiting_review", "detail": "..."}, a kérdések megnevezésével. Tekintse át a dimenziókat a Balansorban, származtasson újra, majd exportáljon |
export_dataset |
Az adatkészlet adatfájljának léteznie kell | {"error": "file_missing", "detail": "The dataset's data file is missing — re-derive the stage."} |
Gyakori hibák
Szekció neve “Gyakori hibák”| Helyzet | Válasz |
|---|---|
| Az adatkészlet nem található | {"error": "Dataset {id} not found"} |
| A csomag nem található | {"error": "not_found", "detail": "Bundle {id} not found"} |
| A stratégia nem található | {"error": "Sampling strategy {id} not found"} |
| Nincs adatfájl | {"error": "Dataset {id} has no data file"} |
| Érvénytelen exportformátum | {"error": "Invalid format. Allowed: csv, csv_semicolon, xlsx, spss, parquet, rds, json"} |
| Nincs befejezett kitöltés | {"error": "no_completed_surveys", "detail": "..."} – bővítse a kampányválasztást, vagy várjon további befejezett kitöltésekre |
| A csomag egyetlen kampányt sem választ ki | {"error": "no_campaigns_selected", "detail": "..."} – a csomag mérési alapja az általa kiválasztott kampányok kitöltései; rendeljen hozzá legalább egyet |
| Az előállítás nem tudta kiírni az adatkészletet | {"error": "extraction_failed", "column": "q_x", "detail": "..."} – egy oszlop olyan értékeket tartalmaz, amelyek nem egyesíthetők egyetlen típusba. A hibát okozó értéket a rendszer szándékosan kihagyja (az egy válaszadó válasza); vizsgálja meg az oszlop nyers értékeit, javítsa ki a forrásválaszokat, és állítsa elő újra |