Tovább a tartalomhoz
Tudástár

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.

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 }


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.


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.


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ő.


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éke false, ami a set_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őtt error állapotban végződik, a processing_error pedig weighting_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.


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).

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 compute sor name é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ított name é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 alias sorát a rendszer elutasítja: ha egy oszlopot csak egyetlen új néven szeretne kiszolgálni, használja a rename műveletet.
  • Új nevek. A recept által létrehozott név (egy rename célja, egy álnév vagy egy számított name) 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 a score ü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 és reorder sorok egymás között bármilyen sorrendben állhatnak. A sorrend a compute sorok között számít, az alias sorok 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.


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.

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

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 }


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."}
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