Spinta
Kad būtų paprasčiau atverti duomenis, rekomenduojame naudoti įrankį pavadinimu Spinta, kuris sukurtas duomenų atvėrimo automatizavimui. Spinta leidžia automatizuotai generuoti duomenų struktūros aprašus, juos patikrinti ar nėra klaidų, perduoti duomenis į saugyklą ir publikuoti atvertus duomenis aukščiausiu brandos lygiu ir laikantis geriausių atvirų duomenų publikavimo praktikų.
Jei naudodamiesi Spinta radote kokių nors klaidų ar turite kitų pastabų, galite pranešti apie klaidą, kad galėtume ją pataisyti.
Diegimas
Techniniai reikalavimai
Techniniai reikalavimai gali skirtis, priklausomai nuo to, kokiu tikslu naudojama Spinta priemonė. Jei naudojama tik duomenų atvėrimui, o ne publikavimui tuomet užtenka:
- CPU
1 CPU, šiuo metu perduodant duomenis nėra naudojamas lygiagretinimas, todėl bus naudojamas tik vienas CPU, ateityje tai gali keistis.
- RAM
512Mb, duomenys skaitomi srautiniu būdu, todėl nepriklausomai nuo šaltinio dydžio, naudojamas fiksuotas RAM kiekis.
Vienas Spinta procesas naudoja apie 100Mb RAM.
- HDD
Priklauso nuo duomenų kiekio.
Duomenų perdavimui iš šaltinio į saugyklą, saugomi papildomi duomenys:
Vidinių ir publikuojamų pirminių raktų sąsaja, saugoma
~/.local/share/spinta/keymap.db
Sqlite duomenų bazėje. Duomenys atrodo taip:bb969358-ce9e-4255-b596-c748f6885332|bf8b4530d8d246dd74ac53a13471bba17941dff7|BINDATA... 522a3615-8527-4eb7-8327-977fe4383dcd|c4ea21bb365bbeeaf5f2c654883e56d11e43c44e|BINDATA... 9be3e60b-d557-4596-a370-660f3c337772|9842926af7ca0a8cca12604f945414f07b01e13d|BINDATA... 60c2f4da-c32a-4fba-a39a-8e85252a77ad|a42c6cf1de3abfdea9b95f34687cbbe92b9a7383|BINDATA... ab2baaa6-508d-4069-9a45-53bce46676ca|8dc00598417d4eb788a77ac6ccef3cb484905d8b|BINDATA...
Saugomas išorinis raktas, vidinio rakto sha1 ir vidinio rakto reikšmė MsgPack formatu.
Šios lentelės dydis tiesiogiai proporcingas šaltinio įrašų skaičiui ir šaltinio lentelių pirminių raktų dydžiui.
Vidutiniškai, 10^6 įrašų telpa į 200Mb.
Perduodamų duomenų būsenos lentelė, kuri saugoma
~/.local/share/spinta/push
kataloge. Kiekvienai saugyklai į kurią perduodami duomenys sukuriama atskira būsenos lentelė, Sqlite formatu. Būsenos duomenys atrodo taip:bb969358-ce9e-4255-b596-c748f6885332|5d28bd0ccad38701a5fcc775259b91e53bf3b1b3|2022-02-10 13:26:39.255110 522a3615-8527-4eb7-8327-977fe4383dcd|0711b352478dda05732c4448e689aa9246986911|2022-02-10 13:26:39.255602 9be3e60b-d557-4596-a370-660f3c337772|ea85925a127b84a30d7be40daa150236954a39f6|2022-02-10 13:26:39.255976 60c2f4da-c32a-4fba-a39a-8e85252a77ad|7d5d3486ff456a2419476c4d7e6b2a73ae7bca22|2022-02-10 13:26:39.256167 ab2baaa6-508d-4069-9a45-53bce46676ca|fe5e2696e1768bc40ecce6b7418723d06e62a53a|2022-02-10 13:26:39.256342
Saugomas išorinis pirminis raktas, visų perduodamų duomenų sha1 ir data, kad buvo perduoti duomenys paskutinį kartą.
Vidutiniškai, 10^6 įrašų talpa į 200Mb.
Apytiksliai, vienam milijonui įrašų reikėtų turėti bend 0.5G laisvos disko vietos.
Duomenų atvėrimo priemonė Spinta yra sukurta naudojant Python technologiją. Todėl prieš diegiant, jūsų naudojamoje aplinkoje turi būti įdiegta Python 3.9 arba naujesnė versija.
Debian/Ubuntu
Pirmiausia, prieš atliekant diegimą, reikėtų pasirinkti kokiame failų
sistemos kataloge diegsite priemones. Rekomenduojame diegti į /opt/spinta
katalogą.
Jei diegimą atliekate serveryje, tuomet verta sukurti atskirą naudotoją, kurio teisėmis bus leidžiamos priemonės, tai padaryti galite taip:
$ sudo useradd --system --create-home --home-dir /opt/spinta spinta
$ sudo -u spinta -s --set-home
$ cd
Toliau visus veiksmus atliksime /opt/spinta
kataloge.
Pirmiausia reikėtų įsitikinti ar jūsų naudojama distribucijos versija turi reikalinga Python versiją, tai galite pažiūrėti taip:
$ python3 --version
Jei turite 3.9 ar naujesnę versiją, tuomet galite pereiti prie Python paketų diegimas žingsnio.
Naujesnę Python versiją galite įsidiegti pasirinkdami vieną iš dviejų galimų variantų:
Variantas 1: naudojant pyenv, kuris atsisiūs Python išeities kodą ir sukompiliuos reikiamą Python versiją. Šis variantas yra universalesnis, tačiau sudėtingesnis ir reikalaujantis daugiau laiko.
Variantas 2 Naudojant PPA repozitoriumus, kurie veiks tik Ubuntu aplinkoje, tačiau reikiamą Python versiją gausite žymiai paprasčiau.
Naujesnės Python versijos diegimas naudojant pyenv
Pirmiausia mums reikia įdiegti pyenv ir visus šiai priemones ir Python kompiliavimui reikalingus paketus:
$ sudo apt update
$ sudo apt upgrade
$ sudo apt install -y \
git make build-essential libssl-dev zlib1g-dev \
libbz2-dev libreadline-dev libsqlite3-dev wget \
curl llvm libncurses5-dev libncursesw5-dev \
xz-utils tk-dev libffi-dev liblzma-dev \
python-openssl
$ curl https://pyenv.run | bash
Naujausios Python versijos diegimas naudojant pyenv daromas taip:
$ .pyenv/bin/pyenv install 3.10.7
Jei diegiate Spintą kitoje Linux distribucijoje, reikalingų paketų sąrašą galite rasti pyenv dokumentacijoje.
Atlikus naujos Python versijos diegimo veiksmus susikuriame izoliuotą aplinką, kurioje diegsime reikalingus Python paketus:
$ .pyenv/versions/3.10.7/bin/python -m venv venv
Naujesnės Python versijos diegimas naudojant PPA
Naujausios Python versijos diegimas naudojant PPA daromas taip:
Pirmiausiai mums reikia įdiegti PPA repozitoriumų valdymo priemones:
$ sudo apt update
$ sudo apt install software-properties-common
$ sudo add-apt-repository ppa:deadsnakes/ppa
Ir galiausiai įdiegiame pageidaujamą Python versiją:
$ sudo apt update
$ sudo apt install python3.10 python3.10-venv
Atlikus naujos Python versijos diegimo veiksmus susikuriame izoliuotą aplinką, kurioje diegsime reikalingus Python paketus:
$ python3.10 -m venv venv
Python paketų diegimas
Kai jau turite tinkamą Python versiją ir esate susikūrė izoliuotą Python aplinką, Spinta galima įdiegti taip:
$ venv/bin/pip install spinta
Galiausiai, įdiegus Spinta paketą, reikia aktyvuoti izoliuotą aplinką, kad
galėtumėte toliau dirbti su Spinta paketo teikiama komanda spinta
:
$ source venv/bin/activate
Tai padarius, galite patikrinti ar komanda spinta
veikia:
$ spinta --version
0.1.9
Ši komanda turi išvesti, Spinta priemonės versijos numerį.
Pastaba
Atkreipkite dėmesį, kad spinta
komanda yra pasiekiama tik tada, kai yra
aktyvuota Python virtuali aplinka:
$ source venv/bin/activate
Python virtualios aplinkos aktyvavimas galioja tol, kol yra aktyvi terminalo sesija.
Windows
Tiesioginio Windows palaikymo nėra, tačiau Spinta galima įdiegti ir naudoti per Windows Subsystem for Linux (WSL). Informaciją apie tai, kaip įsidiegti WSL galite rasti Microsoft Windows dokumentacijoje.
Renkantis Linux distribuciją iš Microsoft Store rekomenduojame rinktis Ubuntu.
Įsidiegus ir pasileidus Ubuntu per WSL, toliau sekite Debian/Ubuntu instrukcijas.
Jei įvykdžius sekančią komandą:
$ curl https://pyenv.run | bash
Gaunate tokią klaidą:
% Total % Received % Xferd Average Speed Time Time Time Current
Dload Upload Total Spent Left Speed
100 285 100 285 0 0 396 0 --:--:-- --:--:-- --:--:-- 395
curl: (60) SSL certificate problem: self signed certificate in certificate chain
More details here: https://curl.haxx.se/docs/sslcerts.html
curl failed to verify the legitimacy of the server and therefore could not
establish a secure connection to it. To learn more about this situation and
how to fix it, please visit the web page mentioned above.
Tuomet įsitikinkite, kad jūsų ugniasienė neblokuoja prieigos prie išorinių resursų. Taip pat galite laikinai sustabdyti antivirusinė, kuri taip pat gali blokuoti tokio pobūdžio komandų vykdymą.
Kitas variantas, curl
komandą galite vykdyti su -k
argumentu.
Panaši situacija gali pasitaikyti ir vykdant:
.pyenv/bin/pyenv install $PYVER
Šios komandos vykdymo metu galite gauti tokią klaidą:
Downloading Python-3.9.5.tar.xz...
-> https://www.python.org/ftp/python/3.9.5/Python-3.9.5.tar.xz
error: failed to download Python-3.9.5.tar.xz
BUILD FAILED (Ubuntu 20.04 using python-build 2.0.0)
Tokių atveju įsitikinkite ar ugniasienė leidžia kreiptis į išore ir pabandykite laikinai sustabdyti antivirusinę programą.
Atnaujinimas
Norint atnaujinti Spinta paketą, reikia atlikti tokius žingsnius:
Komandų eilutėje pakeisti aktyvų kelią, kur yra įdiegta Spinta:
cd /kelias/iki/spinta
Atnaujinti Spinta paketą:
venv/bin/pip install --upgrade spinta
Konfigūravimas
Įdiegus Spinta jokia papildoma konfigūracija nereikalinga, kadangi visus reikalingus parametrus galima perduoti per komandinės eilutės argumentus, pavyzdžiui:
$ spinta inspect -r sql sqlite:///sqlite.db -o sdsa.xlsx
Tačiau, norint išvengti jautrių duomenų perdavimo per komandinę eilutę ir pageidaujant, kad duomenų bazės prisijugnimo parametrai nebūtų įrašomi į struktūros aprašą, dalį parametrų galima iškelti į konfigūracijos failą:
backends:
mydb:
type: sql
dsn: sqlite://sqlite.db
Iškėlus duomenų bazės konfigūracijos parametrus į konfigūracinį failą, komandų
eilutėje -o config=config.yml
nurodoma configūracinio failo vieta, -r sql
mydb
nurodo pavadinimą iš backends
sąrašo:
$ spinta -o config=config.yml inspect -r sql mydb -o sdsa.xlsx
ŠDSA generavimas
Spinta leidžia automatiškai generuoti DSA lentelę iš duomenų šaltinio.
Tarkime, jei turime SQLite duomenų bazę su viena lentele:
$ sqlite3 sqlite.db <<EOF
CREATE TABLE COUNTRY (
NAME TEXT
);
EOF
Tada iš tokio duomenų šaltinio, DSA lentelę galima sugeneruoti taip:
$ spinta inspect -r sql sqlite:///sqlite.db
d | r | b | m | property | type | ref | source
dataset | | |
| sql | sql | | sqlite:///sqlite.db
| | |
| | | Country | | | COUNTRY
| | | | name | string | | NAME
Šiuo atveju, kadangi nenurodėme kur saugoti sugeneruotą DSA lentelę, ji buvo tiesiog išvesta į ekraną.
-r
argumentui perduoti du argumentai sql
ir sqlite:///sqlite.db
, kurie
atitinka resource.type
ir resource.source
.
Jei norima DSA lentelę išsaugoti į Excel lentelę, tada argumento -o
pagalba galima nurodyti kelią iki failo, kuriame reikia išsaugoti DSA
lentelę XLSX formatu:
$ spinta inspect -r sql sqlite:///sqlite.db -o sdsa.xlsx
DSA lentelę, išsaugotą XLSX formatu galima atsidaryti ir redaguoti naudojant LibreOffice Calc, Excel ar kitomis skaičiuoklės programomis. Tačiau taip pat lentelės turinį galima peržiūrėti ir Spintos pagalba:
$ spinta show manifest.csv
d | r | b | m | property | type | ref | source
dataset | | |
| sql | sql | | sqlite:///sqlite.db
| | |
| | | Country | | | COUNTRY
| | | | name | string | | NAME
Jei turite daug duomenų šaltinių, galima juos visus surašyti į DSA
lentelę, ir tada paleisti inspect
komandą, kuri nuskaitys visus lentelėje
esančius duomenų šaltinius ir kiekvienam iš jų sugeneruos duomenų struktūros
aprašus.
Naują DSA lentelę galite pradėti kurti taip:
$ spinta init sdsa.xlsx
Ši komanda sugeneruos tuščią DSA lentelę:
$ spinta show sdsa.xlsx
d | r | b | m | property | type | ref | source
Tada, šią lentelę galite atsidaryti su jūsų mėgiama skaičiuoklės programa ir užpildyti turimus duomenų šaltinius, pavyzdžiui, tokia užpildyta lentelė galėtų atrodyti taip:
$ spinta show resources.xlsx
d | r | b | m | property | type | ref | source
dataset | | |
| sql | sql | | sqlite:///sqlite.db
Struktūros generavimas daromas panašiai, kaip ir nurodant resursus -r
argumentų pagalba, tik šį karta reikia nurodyti kelia iki DSA lentelės:
$ spinta inspect resources.xlsx -o sdsa.xlsx
$ spinta show sdsa.xlsx
d | r | b | m | property | type | ref | source
dataset | | |
| sql | sql | | sqlite:///sqlite.db
| | |
| | | Country | | | COUNTRY
| | | | name | string | | NAME
Analogiškai DSA lentelės generuojamos ir visiems kitiems
resource.type
formatams.
CSV
Pastaba
Kol kas Spinta neturi įmontuoto CSV formato palaikymo, todėl ši rekomendacija yra laikinas trūkstamo CSV palaikymo apėjimas. Ateityje planuojama integruoti Dask karkasą, kurio dėka atsiras CSV ir daugelio kitų formatų palaikymas.
Norint gauti pradinė ŠDSA variantą iš CSV failų, pirmiausiai CSV failus reikėtų importuoti į SQLite duomenų bazę:
$ sqlite3 data.db -csv ".import table1.csv table1"
$ sqlite3 data.db -csv ".import table2.csv table2"
$ sqlite3 data.db -csv ".import table3.csv table3"
Tokiu būdu importavus duomenis į SQLite, duomenų struktūros aprašas generuojamas taip:
$ spinta inspect -r sql sqlite:///data.db -o sdsa.xlsx
Jei pageidaujate, trūkstamus metaduomenis, tokius kaip duomenų laukus, pirminius raktus ar ryšius galite pateikti naudodami DB Browser for SQLite programą. Tačiau tą patį galite padaryti ir skaičiuoklės pagalba, redaguodami ŠDSA lentelę.
SQL DDL dump
Įspėjimas
Kol kas šis funkcionalumas nėra pilnai įgyvendintas. Spinta gali sugeneruoti DSA tik lentelėms.
Jei tam tikras resursas reikalauja formulių panaudojimo, tada formulę galite
nurodyti -f
argumento pagalba. Pavyzdžiui, jei neturite prieigos prie
pačios duomenų bazės, bet turite prieigą, prie duomenų bazės SQL DDL skripto,
o skriptas yra užkoduotas UTF-16
koduote. Tada DSA lentelė bus
generuojama taip:
$ spinta inspect -r sqldump dump.sql -f 'file(encoding: "utf-16")'
d | r | b | m | property | type | ref | source | prepare
dataset | | | |
| sql | sql | | sqlite:///sqlite.db | file(encoding: "utf-16")
| | | |
| | | Country | | | COUNTRY |
| | | | name | string | | NAME |
Šiuo atveju, dump.sql
failas atrodytų taip:
CREATE TABLE COUNTRY (
NAME TEXT
);
SQLite
Generuojant DSA iš SQLite duomenų bazės, jokių papildomų paketų
diegti nereikia. inspect
komanda atrodys taip:
$ spinta inspect -r sql sqlite:///data.db -o sdsa.xlsx
Atkreipkite dėmesį, kad absoliutus kelias atrodo taip:
sqlite:////data.db
O reliatyvus atrodo taip:
sqlite:///data.db
PostgreSQL
Generuojant DSA iš PostgreSQL duomenų bazės, jums papildomai reikia įdiegti tokį Python paketą:
$ pip install psycopg2-binary
O inspect
komanda atrodys taip:
$ spinta inspect -r sql postgresql+psycopg2://user:pass@host:port/db -o sdsa.xlsx
MySQL
Generuojant DSA iš MySQL duomenų bazės, jums papildomai reikia įdiegti tokį Python paketą:
$ pip install pymysql
O inspect
komanda atrodys taip:
$ spinta inspect -r sql mysql+pymysql://user:pass@host:port/db -o sdsa.xlsx
MySQL (<5.6)
pymysql
biblioteka palaiko MySQL >= 5.6 ir MariaDB >= 10 versijas. Jei
naudojate labai seną MySQL versiją, tuomet, vietoj pymysql
reikėtų naudoti
senesnę mysqlclient biblioteką, kuri palaiko MySQL >= 3.23.32. mysqlclient
diegimui pirmiausia reikės įsidiegti tokius sisteminius paketus:
$ sudo apt install build-essential python3-dev default-libmysqlclient-dev
O data ir pačią mysqlclient
biblioteką:
pip install mysqlclient
inspect
komanda atrodys taip:
spinta inspect -r sql mysql+mysqldb://user:pass@host:port/db -o sdsa.xlsx
p.s. jei vis dar naudojate tokią seną MySQL versiją, laikas atsinaujinti!
Microsoft SQL Server
Generuojant DSA iš Microsoft SQL Server duomenų bazės, jums papildomai reikia įdiegti FreeTDS paketą:
$ sudo apt install freetds-bin
Ir pymssql Python paketą:
$ pip install pymssql
Toliau reikia sukonfigūruoti FreeTDS, rekomenduojame naudoti tokį konfigūracijos failą:
[global]
tds version = 7.4
port = 1433
client charset = utf-8
inspect
komanda atrodys taip:
$ spinta inspect -r sql mssql+pymssql://user:pass@host:port/db -o sdsa.xlsx
Oracle
Generuojant DSA iš Oracle duomenų bazės, jums papildomai reikia įdiegti cx_Oracle paketą:
$ pip install cx_Oracle
Dėl papildomos informacijos apie Oracle jungtį, skaitykite cx_Oracle dokumentacijoje.
inspect
komanda atrodys taip:
$ spinta inspect -r sql oracle+cx_oracle://user:pass@host:port/db -o sdsa.xlsx
ŠDSA atnaujinimas
Po to, kai yra sugeneruojamas pradinis ŠDSA ir papildomas trūkstamais duomenimis, dažniausiai po tam tikro laiko, šaltinio duomenų struktūra keičiasi ir karts nuo karto reikia atnaujinti esamą ŠDSA ir šaltinio, įtraukiant naujausius pakeitimus šaltinyje.
Tai galima padaryti tokiu būdu:
$ spinta inspect sdsa.xlsx -o sdsa_updated.xlsx
sdsa_updated.xlsx
faile išliks visi metaduomenys, kuris buvo pradiniame sdsa
.xlsx
, papildant juos naujais metaduomenimis iš šaltinio.
ŠDSA testavimas prieš publikuojant
Kai jau yra parengtas ŠDSA variantas iš kurio galima atverti duomenis pirmiausia reikia patikrinti are ŠDSA yra be klaidų. Tai galima padaryti šios komandos pagalba:
$ spinta check sdsa.xlsx
Jei klaidų nėra, tuomet papildomai, galima paleisti duomenų publikavimo priemonę, kuri duomenis publikuos tiesiai iš pirminio duomenų šaltinio. Duomenų publikavimas iš pirminio šaltinio turi tam tikrų apribojimų, tačiau ši galimybė leidžia peržiūrėti, kaip atrodys publikuojami duomenys, prie juos publikuojan viešai.
Kaip atrodys publikuojami duomenys, galite peržiūrėti taip:
$ spinta run --mode external sdsa.xlsx
Ši komanda paleis HTTP serverį 127.0.0.1:8000 adresu, atsidarę šį adresą naršyklėje galėsite peržiūrėti kaip atrodo duomenys.
ŠDSA vertimas į ADSA
ŠDSA yra toks duomenų struktūros aprašas, kuris yra susietas su duomenų
šaltiniu, yra užpildytas source
stulpelis.
Verčiant ŠDSA į ADSA, iš esmės pašalinami source
ir prepare
stulpelių duomenys, o taip pat pašalinamos visos eilutės, kurių
access
yra mažesnis, nei open
.
ŠDSA vertimą į ADSA galima daryti automatiškai taip:
$ spinta copy sdsa.xlsx --no-source --access open -o adsa.csv