Commit 82784610 authored by Mantas Zimnickas's avatar Mantas Zimnickas

Update docs

parent e79fda0c
Pipeline #122367750 failed with stage
in 2 minutes and 59 seconds
......@@ -43,83 +43,96 @@ Tokio duomenų šaltinio duomenų struktūros aprašas atrodo taip:
.. code-block:: yaml
name: pavyzdziai/priklausomybes
type: dataset
name: datasets/pavyzdziai/priklausomybes
resources:
salys:
type: json
source: https://example.com/salys/
objects:
geografija/salis:
source: resources
properties:
id:
type: pk
source: code
kodas:
type: string
source: code
pavadinimas:
type: string
source: country
miestai:
type: json
source: https://example.com/salys/{salis.kodas}/miestai/
objects:
geografija/miestas:
source: resources
dependencies:
salis: geografija/salis/:dataset/pavyzdziai/priklausomybes
properties:
id:
type: pk
source: city
salis:
type: ref
object: geografija/salis
dependency: salis.id
pavadinimas:
type: string
source: city
.. code-block:: yaml
type: model
name: datasets/pavyzdziai/priklausomybes/salis
pull:
dataset: datasets/pavyzdziai/priklausomybes
resource: salys
source: resources
pk: kodas
properties:
kodas:
type: string
pull: code
pavadinimas:
type: string
pull: country
.. code-block:: yaml
type: model
name: datasets/pavyzdziai/priklausomybes/miestas
pull:
dataset: datasets/pavyzdziai/priklausomybes
resource: miestai
source: resources
pk: pavadinimas
using:
- salis: query('datasets/pavyzdziai/priklausomybes/salis')
properties:
salis:
type: ref
model: datasets/pavyzdziai/priklausomybes/salis
pull:
source: $salis._id
ref: _id
pavadinimas:
type: string
pull: city
Šioje vietoje, panaudojant priklausomybę:
.. code-block:: yaml
dependencies:
salis: geografija/salis/:dataset/pavyzdziai/priklausomybes
using:
salis: query('datasets/pavyzdziai/priklausomybes/salis')
Prieš kreipiantis į miestų :term:`prieigos tašką <prieigos taškas>` vykdoma
užklausa::
/geografija/salis/:dataset/pavyzdziai/priklausomybes
query('datasets/pavyzdziai/priklausomybes/salis')
Tada kviečiamas miestų :term:`prieigos taškas` tiek kartų, kiek yra kiek
užklausa grąžino eilučių. Miestų :term:`prieigos taško <prieigos taškas>` URL
adrese esantis `{salis.kodas}` pakeičiamas į užklausos eilutėje esančią
reikšme. Tokiu būdu, gauname visus miestus.
Papildomai, `geografija/miestas` savybė `salis`, reikšmę gauna ne iš `source`,
o iš `dependency: salis.id`, tokiu būdu susiejant miestą su šalimi.
Modelio `datasets/pavyzdziai/priklausomybes/miestas` savybė `salis`, reikšmę
gauna iš kintamojo `$salis._id`. Pagal nutylėjimą lauko `pull.source` reikšmė
atitinka siejamo modelio `pull.pk` reikšmę, pagal kurią gaunamas tikrasis
identifikatorius. Tačiau šiuo atveju identifikatorius jau šinomas, todėl
papildomai nurodome, kad šiuo atveju `pull.source` rodo į `_id` lauką.
Galutiniame rezultate gauname tokias dvi lenteles:
**geografija/salis**
**datasets/pavyzdziai/priklausomybes/salis**
========== ===========
id pavadinimas
========== ===========
`552c4c24` Lietuva
========== ===========
==================================== ===========
id pavadinimas
==================================== ===========
cb379696-76f7-43d8-8a72-57ac4e9914d0 Lietuva
==================================== ===========
**geografija/miestas**
**datasets/pavyzdziai/priklausomybes/miestas**
========== ========== ===========
id salis pavadinimas
========== ========== ===========
`8e65fec0` `552c4c24` Vilnius
`4fe80490` `552c4c24` Kaunas
========== ========== ===========
==================================== ==================================== ===========
id salis pavadinimas
==================================== ==================================== ===========
164973fa-7a8f-439b-8b26-cfade23c6bc7 cb379696-76f7-43d8-8a72-57ac4e9914d0 Vilnius
00dd95e6-7c40-43d7-8429-50c9ca0b3c76 cb379696-76f7-43d8-8a72-57ac4e9914d0 Kaunas
==================================== ==================================== ===========
Atkreipkite dėmesį, kad visuose pavyzdžiuose, nepriklausomai nuo duomenų
šaltinio, naudodami vieningą žodyną visą laiką gauname tuose pačius duomenis,
......
......@@ -268,7 +268,6 @@ Turinys
inventorying
sources
pk
norm
dependencies
vocabulary
......
......@@ -1195,7 +1195,7 @@ lentelė atrodytų taip:
+---+---+---+---+-----------------+--------------------------+---------+-----------+-------+---------+--------+-------------+
| | | | | a3code | code | string | | 5 | | | |
+---+---+---+---+-----------------+--------------------------+---------+-----------+-------+---------+--------+-------------+
| | | | | name\@en | country | string | | 5 | | | |
| | | | | name.en | country | text | | 5 | | | |
+---+---+---+---+-----------------+--------------------------+---------+-----------+-------+---------+--------+-------------+
| datasets/gov/dp2/countries | | | | | | | |
+---+---+---+---+-----------------+--------------------------+---------+-----------+-------+---------+--------+-------------+
......@@ -1209,7 +1209,7 @@ lentelė atrodytų taip:
+---+---+---+---+-----------------+--------------------------+---------+-----------+-------+---------+--------+-------------+
| | | | | a2code | kodas | string | | 5 | | | |
+---+---+---+---+-----------------+--------------------------+---------+-----------+-------+---------+--------+-------------+
| | | | | name\@lt | salis | string | | 5 | | | |
| | | | | name.lt | salis | text | | 5 | | | |
+---+---+---+---+-----------------+--------------------------+---------+-----------+-------+---------+--------+-------------+
| datasets/gov/dp3/countries | | | | | | | |
+---+---+---+---+-----------------+--------------------------+---------+-----------+-------+---------+--------+-------------+
......@@ -1236,7 +1236,7 @@ lentelė atrodytų taip:
+---+-----------+--------+-----+-----+-------+-------------+
| | a3code | string | | | | |
+---+-----------+--------+-----+-----+-------+-------------+
| | name | string | | | | |
| | name | text | | | | |
+---+-----------+--------+-----+-----+-------+-------------+
Duomenų atvėrimo metu, visi inventorizuoti duomenų rinkiniai bus siejami su
......@@ -1256,7 +1256,7 @@ taip:
======= ====== ====== =========== ===========
place/country
-------------------------------------------------
id a2code a3code name\@en name\@lt
id a2code a3code name.en name.lt
======= ====== ====== =========== ===========
1 lt ltu Lithuania Lietuva
2 lv lva Latvia Latvija
......
......@@ -86,38 +86,50 @@ Lietuva Klaipėda
Tarkime ši lentelė yra pateikta CSV formatu adresu
`https://example.com/miestai.csv`.
Šiuo lentelės duomenų aprašas turėtų atrodyti taip:
Lentelės duomenų aprašas turėtų atrodyti taip:
.. code-block:: yaml
name: pavyzdziai/normalizavimas
# datasets/pavyzdziai/normalizavimas.dataset.yml
type: dataset
name: datasets/pavyzdziai/normalizavimas
resources:
miestai:
type: csv
objects:
geografija/salis:
source: https://example.com/miestai.csv
properties:
id:
type: pk
source: šalis
pavadinimas:
type: string
source: šalis
geografija/miestas:
source: https://example.com/miestai.csv
properties:
id:
type: pk
source: šalis
salis:
type: ref
object: geografija/salis
source: šalis
pavadinimas:
type: string
source: miestas
.. code-block:: yaml
# datasets/pavyzdziai/normalizavimas/salis.yml
type: model
name: datasets/pavyzdziai/normalizavimas/salis
pull:
dataset: datasets/pavyzdziai/normalizavimas
resource: miestai
source: https://example.com/miestai.csv
pk: pavadinimas
properties:
pavadinimas:
type: string
pull: šalis
.. code-block:: yaml
# datasets/pavyzdziai/normalizavimas/miestas.yml
type: model
name: datasets/pavyzdziai/normalizavimas/miestas
pull:
dataset: datasets/pavyzdziai/normalizavimas
resource: miestai
source: https://example.com/miestai.csv
pk: pavadinimas
properties:
salis:
type: ref
model: datasets/pavyzdziai/normalizavimas/salis
pull: šalis
pavadinimas:
type: string
pull: miestas
Iš šio pavyzdžio matome, kad miestų duomenys skaitomi du kartus ir paskirstomi
dviejose lentelėse. Pirmą kartą skaitome tik šalys, generuojant pirminį raktą
......@@ -126,23 +138,23 @@ panaudojant šalies pirminį raktą. Galutiniame rezultate gauname tokias
lenteles:
**geografija/salis**
**datasets/pavyzdziai/normalizavimas/salis**
========== ===========
id pavadinimas
========== ===========
`098b634e` Lietuva
========== ===========
==================================== ===========
_id pavadinimas
==================================== ===========
210deafe-4fea-4bb2-b5e2-8a27599dabc6 Lietuva
==================================== ===========
**geografija/miestas**
**datasets/pavyzdziai/normalizavimas/miestas**
========== ========== ===========
id salis pavadinimas
========== ========== ===========
`8e65fec0` `098b634e` Vilnius
`4fe80490` `098b634e` Kaunas
`cad19c34` `098b634e` Klaipėda
========== ========== ===========
==================================== ==================================== ===========
_id salis pavadinimas
==================================== ==================================== ===========
42457737-7607-4184-ae35-d24a65cab8a8 210deafe-4fea-4bb2-b5e2-8a27599dabc6 Vilnius
5fac44f5-a640-4480-83d7-a8039f92fada 210deafe-4fea-4bb2-b5e2-8a27599dabc6 Kaunas
a7cda7ba-c1e9-4254-addd-0c9c229b23ed 210deafe-4fea-4bb2-b5e2-8a27599dabc6 Klaipėda
==================================== ==================================== ===========
Sinonimai
......
.. default-role:: literal
.. _pk:
Pirminis raktas
###############
Manifesto duomenų modelis yra :ref:`normalizuotas <norm>`, tai reiškia, kad objektai yra
išskaidyti į plokščius objektus ir objektai tarpusavyje gali būti jungiami
pirminio rakto (lauko `id`) pagalba.
Laukas `id` yra rezervuotas ir visi duomenų aprašai privalo nurodyti šį lauką.
Lauko `id` tipas turi būti `pk`, pavyzdys:
.. code-block:: yaml
id:
type: pk
source: id
Būtina užtikrinti, kad objektas turėtų unikalų pirminį raktą. Jei duomenų
šaltinis teikia duomenis su pirminiu raktu, tada viskas labai paprasta, tačiau
jei pirminio rakto nėra, tada tenka pirminį raktą išgauti jungiant kelias
reikšmes, kurie visi kartu unikaliai identifikuoja objektą.
Kai reikia jungti kelias reikšmes, pirminio rakto aprašas atrodo taip:
.. code-block:: yaml
id:
type: pk
source:
- foo
- bar
- baz
`id` lauko reikšmė gaunama serializuojant `id` lauko reikšmę MsgPack_ formatu
ir rezultatą verčiant į SHA1_ kontrolinę sumą. Jei `id` reikšmė nėra sąrašas,
tada reikšmė verčiama į sąrašą. Pavyzdžiui `[1, 2, 3]` sąrašas būtų verčiamas
į::
78a74af6c06029985f388dfeceb9794100377124
Atkreipkite dėmesį, kad laukų sąrašo tvarka yra svarbi, sukeitus sąrašo
elementus vietomis, pasikeis ir pirminio rakto reikšmė.
Globalūs identifikatoriai
=========================
Jei tik įmanoma, reikėtų naudoti tokius identifikatorius, kurie yra globalūs.
Pavyzdžiui jei turime tokią lentelę:
======= ======== ===========
id code country
======= ======== ===========
1 lt Lietuva
2 lv Latvija
3 ee Estija
======= ======== ===========
Čia pirminiam raktui geriau naudoti `code`, o ne `id`, kadangi `id` yra lokalus
duomenų rinkinio identifikatorius, o šalies kodas yra globalus. Tačiau, jei
šiame duomenų rinkinyje objektai jungiami tik naudojant lokalų pirminį raktą,
tai žinoma, tada `id` laukui geriau naudoti lokalų pirminį raktą, su kuriuo
jungiasi visi kiti duomenų rinkinio objektai.
.. _MsgPack: https://msgpack.org/
.. _SHA1: https://en.wikipedia.org/wiki/SHA-1
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment