Although most examples demonstrate the use of a gather map in the context of an object map, a gather map is a regular term map.
As such, it can be used in other types of term maps such as a subject or predicate map.
Term maps generate RDF terms (IRI, blank node, literal) to be used as the terms of RDF triples.
If such a term map generates a collection or container by means of a gather map, the term retained to form an RDF triple is the head node of the collection or container.
In the case of an RDF list, this is the node that is the subject of the first rdf:first predicate.
The examples section demonstrates how a gather map can be used within a subject map.
If a gather map does not contain any rml:template, rml:constant or rml:reference property, then the head node of each generated collection or container is a new blank node.
Conversely, if a gather map contains either a rml:template, rml:constant or rml:reference property, then the gather map yields named collections or containers whose head node is identified as instructed by the rml:template, rml:constant or rml:reference property.
The following mapping:
rml:predicateObjectMap [
rml:predicate ex:with ;
rml:objectMap [
rml:template "seq/{id}" ;
rml:gather ( [ rml:reference "values.*" ; ] ) ;
rml:gatherAs rdf:Seq ;
] ;
] ;
will yield the following output:
:a ex:with :seq/a . :seq/a rdf:_1 "1" ; rdf:_2 "2" , rdf:_3 "3" .
:b ex:with :seq/b . :seq/b rdf:_1 "4" ; rdf:_2 "5" , rdf:_3 "6" .
:c ex:with :seq/c . :seq/c rdf:_1 "7" ; rdf:_2 "8" , rdf:_3 "9" .
When generating a named collection or container, it may happen that the same IRI or blank node identifier be generated several times, either across multiple iterations or because the gather map is multi-valued as exemplified with the rml:cartesianProduct strategy.
In this situation, to avoid generating ill-formed collections or containers, the processor MUST concatenate (i.e. append) the new collection or container to the previous one.
In other words, when a gather map creates a named collection or container, the processor must first check whether a named collection or container with the same head node IRI or blank node identifier already exists, and if so, it must append the terms to the existing one.
Below we exemplify two such situations.
Here we reuse the running example yet with a slight variation: there are two JSON objects with the value "a" for "id".
[
{ "id": "a", "values": [ "1" , "2" , "3" ] },
{ "id": "b", "values": [ "4" , "5" , "6" ] },
{ "id": "a", "values": [ "7" , "8" , "9" ] }
]
Let's consider the following mapping:
rml:predicateObjectMap [
rml:predicate ex:with ;
rml:objectMap [
rml:gather ( [ rml:reference "values.*" ; ] ) ;
rml:gatherAs rdf:List ;
] ;
] ;
The gather map has no rml:template, rml:constant nor rml:reference property. The expected output consists of three lists, two related to :a and one to :b:
:a ex:with ("1" "2" "3"), ("7" "8" "9") .
:b ex:with ("4" "5" "6") .
Now, when an rml:template, rml:constant or rml:reference is provided,
the two collections related to id "a" cannot be generated separately since they would share the same head node IRI or bank node identifier, thus generating an ill-formed collection. Therefore, the processor must concatenate the two collections related to id "a".
With the following predicate mapping:
rml:predicateObjectMap [
rml:predicate ex:with ;
rml:objectMap [
rml:template "list/{id}" ;
rml:gather ( [ rml:reference "values.*" ; ] ) ;
rml:gatherAs rdf:List ;
] ;
] ;
The processor must generate the following output:
:a ex:with :list/a . :list/a rdf:first "1" ; rdf:rest ("2" "3" "7" "8" "9") .
:b ex:with :list/b . :list/b rdf:first "4" ; rdf:rest ("5" "6") .
It is assumed that a processor will concatenate the collections or containers while respecting the order of the iterations as provided by the logical source.
Let's consider the following input document:
{
"id": "myid",
"a": [ "1" , "2" , "3" ],
"b": [ "4" , "5" ]
}
and the following mapping:
rml:subjectMap [ rml:template "{id}" ] ;
rml:predicateObjectMap [
rml:predicate ex:with ;
rml:objectMap [
rml:gather ( [ rml:reference "a.*" ] [ rml:reference "b.*" ]) ;
rml:gatherAs rdf:List ;
rml:strategy rml:cartesianProduct ;
] ;
] ;
The gather map has no rml:template, rml:constant nor rml:reference property.
As already illustrated, the rml:cartesianProduct strategy will generate multiple collections, yielding the output:
:a ex:with ("1" "4"), ("1" "5"), ("2" "4"), ("2" "5"), ("3" "4"), ("3" "5") .
Now, when an rml:template, rml:constant or rml:reference is provided, to avoid generating ill-formed lists that would share the same head node IRI, the processor must concatenate the lists.
If we add an rml:template in the object map:
rml:objectMap [
rml:template "list/{id}" ;
rml:gather ( [ rml:reference "a.*" ] [ rml:reference "b.*" ]) ;
rml:gatherAs rdf:List ;
rml:strategy rml:cartesianProduct ;
] ;
The processor must now generate the following output:
:a ex:with ("1" "4" "1" "5" "2" "4" "2" "5" "3" "4" "3" "5" ).
An even more tricky situation combines the two previous sections, involving at the same time multiple iterations and multi-valued gather maps.
Let's consider the following document and mapping:
[
{ "id": "a", "values1": [ "1" ], "values2": [ "a" , "b" ] },
{ "id": "b", "values1": [ "3" , "4" ], "values2": [ "c" , "d" ] },
{ "id": "a", "values1": [ "5" , "6" ], "values2": [ "e" ] }
]
rml:logicalSource [
...
rml:iterator "$.*" ;
];
rml:subjectMap [ rml:template "{id}" ] ;
rml:predicateObjectMap [
rml:predicate ex:with ;
rml:objectMap [
rml:template "list/{id}" ;
rml:gather ( [ rml:reference "values1.*" ; ] [ rml:reference "values2.*" ; ] ) ;
rml:gatherAs rdf:List ;
] ;
] ;
For each document, the values of values1 and values2 are appended in the same list, as per the default rml:append strategy.
Furthermore, the lists generated for id "a" must be concatenated since they share the same head node IRI, as explained in the multiple iterations case.
The expected output is:
:a ex:with :list/a .
:list/a rdf:first "1" ; rdf:rest ("a" "b" "5" "6" "e") .
:b ex:with :list/b .
:list/b rdf:first "3" ; rdf:rest ("4" "c" "d") .
Now let's change the default strategy to rml:cartesianProduct:
rml:objectMap [
rml:template "list/{id}" ;
rml:gather ( [ rml:reference "values1.*" ; ] [ rml:reference "values2.*" ; ] ) ;
rml:gatherAs rdf:List ;
rml:strategy rml:cartesianProduct ;
] ;
Each iteration will now yield multiple lists by combining the values of values1 and values2.
For the document with id "b", there are ("3" "c") ("3" "d") ("4" "c") ("4" "d").
But since the template generates the same IRI for all of them, they must be concatenated into a single list: ("3" "c" "3" "d" "4" "c" "4" "d"), as explained in the multi-valued gather map case.
Similarly, for the documents with id "a", the result is: ("1" "a" "1" "b") and ("5" "e" "6" "e").
But again, these lists must be concatenated since they share the same head node IRI, as explained in the multiple iterations case.
Therefore, the processor must now generate the following output:
:a ex:with :list/a .
:list/a rdf:first "1" ; rdf:rest ("a" "1" "b" "5" "e" "6" "e") .
:b ex:with :list/b .
:list/b rdf:first "3" ; rdf:rest ("c" "3" "d" "4" "c" "4" "d") .
