Revisão e documentação do modelo de ingestão implementado

[ppKrauss]

O modelo de dados do schema ingest sofreu modificações e agora está maduro, sua documentação pode ser revisada e consolidada (em /docs) a partir das discussões e requisitos elaborados. Acrescentar neste texto as pendências conforme a documentação e issues forem revisadas, e indicar com x as pendências resolvidas.

Pendências

Novas implementações:

• [ ] funções lib.id_encode(), lib.id_decode() e lib.id_format(), com sobrecarga para diversas opções de input (ex. código de país duas letras ou numérico) e primeiro parâmetro como seletor ("pack", "packvers", etc.). O formatador acrescenta pontuação padronizada.
• [x] Renomearingest.feature_asis.ghs9 para kx_ghs9 e declarar mais explicitamente a sua formação no CREATE com GENERATED ALWAYS AS f(geom) STORED, onde a função f seria padronizada na PubLib.
• [ ] Contagem de elementos em cada geohash de uma distribuição gerada por considerando o número de pontos em cada geometria. Cada célula do mosaico deveria ter (como no publicado) um conjunto key-value de propriedades da célula, não apenas um value.
• [ ] ...

Correções estruturais:

• [ ] colunas id e packvers_id de ingest.donated_packcomponent requerem revisão. A packvers_id é apenas REFERENCE do identificador de packvers, sem acréscimo do id de componente. Usar função lib.id_encode().
  PS: o id é um serial local e temporário da base de ingestão. Depois que migrar para a base DL03 no schema optim é que será definitivo.
• [ ] Usar função lib.id_encode() em todos os triggers.
• [ ] ...

Correções menores:

• [x] coluna variant de codec_type.csv com termos em inglês. (ex. semicolon e não ponto-e-virgula).
• [x] coluna ftname_type de feature_type pode ser renomeada para ftname_class ou ftname_group.
• [ ] ...

Issues consolidadas

Consolidar nas correções desta issue e/ou na documentação:

• https://github.com/digital-guard/preserv/issues/40
• https://github.com/digital-guard/preserv/issues/41
• https://github.com/digital-guard/preserv/issues/51
• https://github.com/digital-guard/preserv/issues/66
• Wiki - Testes reais para garantia de software ...

PS: fechar todas essas issues mantendo só esta aberta até resolvermos.

[0e1]

Sobre:

Correções estruturais:

* [ ]  colunas `id` e `packvers_id` de `ingest.donated_packcomponent` requerem revisão. A packvers_id é apenas REFERENCE do  identificador de packvers, sem acréscimo do id de componente. Usar função lib.id_encode(). PS: o id é um serial local e temporário da base de ingestão. Depois que migrar para a base DL03 no _schema optim_  é que será definitivo.

Verificar os triggers utilizados para geração dos identificadores das tabelas em https://github.com/digital-guard/preserv/blob/main/src/optim-step1-ini.sql#L199. Se triggers estiverem ok (me parece que sim), ver a geração do identificador de layer.

Em ingest.jsonb_mustache_prepare utiliza-se a chave fullPkID para informar ao processo de ingestão o identificador do layer que está sendo ingerido. Ver L1505 e L1507

[ppKrauss]

Verificar os triggers utilizados

Ok, podemos primeiro esboçar as funções aqui depois implementar naqueles locais.

Cabe antes conferir o modelo de dados a utilizar, em algum momento nos esquecemos do template e da diferença entre o file-MD5 e o file-SHA1... No sandbox_path abaixo vemos esse problema:

SELECT isolabel_ext AS escopo, 
       substr(packvers_id::text,3,6)::int::text ||'.'|| substr(packvers_id::text,3+6,2)::int::text AS pack,
       ftid, ftname_type, id as component_id, path AS sandbox_path
FROM ingest.vw08info_packcomponent
ORDER BY 1,2, ftid;

escopo	pack	ftid	ftname_type	component_id	sandbox_path
BR-RJ-Niteroi	16.1	6	cadparcel	4	BR/data/RJ/Niteroi/_pk0016.04/cadparcel
BR-RJ-Niteroi	16.1	31	via	1	BR/data/RJ/Niteroi/_pk0016.02/via
BR-RJ-Niteroi	16.1	62	parcel	3	BR/data/RJ/Niteroi/_pk0016.01/parcel
BR-RJ-Niteroi	16.1	72	nsvia	2	BR/data/RJ/Niteroi/_pk0016.03/nsvia
BR-RS-CaxiasSul	69.1	6	cadparcel	9	BR/data/RS/CaxiasSul/_pk0069.05/cadparcel
BR-RS-CaxiasSul	69.1	31	via	5	BR/data/RS/CaxiasSul/_pk0069.02/via
BR-RS-CaxiasSul	69.1	62	parcel	8	BR/data/RS/CaxiasSul/_pk0069.03/parcel
BR-RS-CaxiasSul	69.1	71	nsvia	7	BR/data/RS/CaxiasSul/_pk0069.01/nsvia
BR-RS-CaxiasSul	69.1	82	block	6	BR/data/RS/CaxiasSul/_pk0069.04/block

Aqui já destacando que o pacote pode ser formatado como "donor.count", com ou sem todos os zeros a esquerda... Para ordernar string precisamos do zero. O formato de 2022 pode ser com apenas um zero, lá para 2025 precisaremos mais um zero.

Sobre a falha na versão corrente do sandbox_path: deveria ser por exemplo RJ/Niteroi/_pk0016.01.01.04 e não RJ/Niteroi/_pk0016.04, pois temos $donor.$count.$vers.$fileSHA256_count. Quem define esse último count é o pack_template.

[0e1]

A tabela donated_PackComponent possui UNIQUE(packvers_id,ftid,lineage_md5):

CREATE TABLE optim.donated_PackComponent(
  id bigserial NOT NULL PRIMARY KEY,  -- layerfile_id
  packvers_id bigint NOT NULL REFERENCES optim.donated_PackFileVers(id),
  ftid smallint NOT NULL REFERENCES optim.feature_type(ftid),
  is_evidence boolean default false,
  proc_step int DEFAULT 1,  -- current status of the "processing steps", 1=started, 2=loaded, ...=finished
  lineage jsonb NOT NULL,
  lineage_md5 jsonb NOT NULL,
  kx_profile jsonb,
  UNIQUE(packvers_id,ftid,lineage_md5)
);

Então, são packvers_id, ftid, lineage_md5 que devem ser passados para ingest.any_load (ou ingest.osm_load) e para a ingest.getmeta_to_file verificar se o respectivo layer já não foi inserido. Após a ingestão do layer, se pode usar o id de donated_PackComponent.

Com isso, entendo que não precisa revisar as colunas

• colunas id e packvers_id de ingest.donated_packcomponent requerem revisão. A packvers_id é apenas REFERENCE do identificador de packvers, sem acréscimo do id de componente. Usar função lib.id_encode(). PS: o id é um serial local e temporário da base de ingestão. Depois que migrar para a base DL03 no schema optim é que será definitivo.

uma vez que packvers_id não é acrescido do id do componente.

Fiz a correção https://github.com/digital-guard/preserv/commit/7bd4dce1739e1a70058592d4c90ad2104d0a89c1 para ingest.getmeta_to_file verificar existência de layer ingerido usando todas as colunas citadas no unique de donated_PackComponent.

Aqui já destacando que o pacote pode ser formatado como "donor.count", com ou sem todos os zeros a esquerda... Para ordernar string precisamos do zero. O formato de 2022 pode ser com apenas um zero, lá para 2025 precisaremos mais um zero.

Sobre a falha na versão corrente do sandbox_path: deveria ser por exemplo RJ/Niteroi/_pk0016.01.01.04 e não RJ/Niteroi/_pk0016.04, pois temos $donor.$count.$vers.$fileSHA256_count. Quem define esse último count é o pack_template. sandbox_path atualmente está sendo utilizado para fonecer o caminho para gravar arquivos de publicação.

O objetivo de sandbox_path é gerar um caminho com estrutura semelhante à utilizada no git de publicação, para receber os arquivos gerados pelo processo de publicação. Corrige a geração para donor.count. Exemplo:

  packvers_id  | id | ftid | ftname_full | ftname_class | geomtype | kx_scope_label |  isolabel_ext   | housenumber_system_type |                  path                  
---------------+----+------+-------------+--------------+----------+----------------+-----------------+-------------------------+----------------------------------------
 7600004201101 |  4 |   61 | parcel_full | parcel       | poly     | BR-AC-RBO      | BR-AC-RioBranco |                         | BR/data/AC/RioBranco/_pk0042.01/parcel
 7600004201201 |  3 |   71 | nsvia_full  | nsvia        | poly     | BR-AC-RBO      | BR-AC-RioBranco |                         | BR/data/AC/RioBranco/_pk0042.01/nsvia
 7600004201201 |  2 |   81 | block_full  | block        | poly     | BR-AC-RBO      | BR-AC-RioBranco |                         | BR/data/AC/RioBranco/_pk0042.01/block
 7600004201301 |  1 |   31 | via_full    | via          | line     | BR-AC-RBO      | BR-AC-RioBranco |                         | BR/data/AC/RioBranco/_pk0042.01/via

[ppKrauss]

A tabela donated_PackComponent possui UNIQUE(packvers_id,ftid,lineage_md5):

Talvez faça mais sentido UNIQUE(packvers_id,ftid), UNIQUE(lineage_md5).

... uma vez que packvers_id não é acrescido do id do componente.

Se for apenas isso então vale mudar de nome, packvers_id teria semântica de packFileVers_id. Mas inda não está claro porque em DL03 a tabela optim.donated_PackFileVers tem um ID daquela forma:

id	hashedfname	pack_id	pack_item	kx_pack_item_version
7600004201101	d96f47270e22336cf4660f742ae4dba5694f15c6833363167c91d9fc9929871b.zip	7600004201	1	1
7600004201201	73d02ba0ae4b0a994a629f7d06f0a027259f5c1d97e53f9b771fecd345c2a02b.zip	7600004201	2	1
7600004201301	29d68e5ce006079b06b710cc2df3aa08d6cb6934f32bc0b29fc46d3e8272ff77.rar	7600004201	3	1
7600000701101	5c7131c32a7411cf7a27022b8ac2989e88f86254ed74b6b3b2e5cf94b44e3acb.zip	7600000701	1	1
..	..	..	..	..

PS: falta uma coluna stop_date e um flag indicando que o hashedfname é corrente (stop_date IS NULL), para saber se um arquivo foi descartado por outro mais recente, ou está fora de uso na versão de YAML mais recente.

As conversões de pack_item e kx_pack_item_version exigem 2 e 3 dígitos respectivamente, então o primeiro ID seria 076.000042.01.01.001 (alfanumérico br000042.01c01.001), ou seja 760000420101001.

Explicando. Poderíamos eventualmente limitar o número de arquivos SHA256 a 9, lembrando inclusive que o zero está reservado ao pacote das evidências de licença. Todavia a decisão (que pode ser revista) foi por flexibilizar — por exemplo o IBGE pode fornecer diversos files (SHA256) num só pacote de doação. As versões, numa perspectiva de 20 anos, podem ser mensais, o que resultaria em 20*12 = 240. Na hipótese de atualizações semanais (OSM talvez demande em alguns meses do ano), seria da ordem de 960 versões.

... Mas não decidimos como lidar com a versão do pacote, por exemplo quando o YAML muda. Esse ramo do versionamento é relativo ao texto de template-YAML. Então as diferentes versões de file (cada SHA256 tem seu packcomponent_id) terão de ser compatibilizadas com as diferentes versões de template-YAML pela data. É suposto que um novo file só funcione a partir do template-YAML de mesma data ou superiores. A coluna stop_date vai permitir também indicar se o YAML novo descartou um file.

[0e1]

Talvez faça mais sentido UNIQUE(packvers_id,ftid), UNIQUE(lineage_md5).

São Paulo tem vários arquivos por layer (mesmo packvers_id e ftid, mas diferentes md5, por isso estão as três juntas.

As conversões de pack_item e kx_pack_item_version exigem 2 e 3 dígitos respectivamente, então o primeiro ID seria 076.000042.01.01.001 (alfanumérico br000042.01c01.001), ou seja 7600004201 01001.

Então, o id é dessa forma id=pack_id*100000+pack_item*1000+kx_pack_item_version?