Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

LOAD RDF document clarification (description section and definition section) #46

Merged
merged 4 commits into from
Dec 12, 2024
Merged

LOAD RDF document clarification (description section and definition section) #46

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
176d718
LOAD description section
afs Nov 26, 2024
e567e1b
Load Operation section
afs Nov 26, 2024
e87320c
Add note for LOAD in Changes section
afs Nov 30, 2024
a136ddd
Updates from review
afs Dec 4, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
103 changes: 83 additions & 20 deletions spec/index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1164,23 +1164,63 @@ <h5>DELETE WHERE</h5>
&lt;http://example/william&gt; foaf:mbox &lt;mailto:bill@example&gt; .</pre>
</section>
</section>

<section id="load">
<h4>LOAD</h4>
<p>The <code>LOAD</code> operation reads an RDF document from a IRI and inserts its triples into the specified graph in the Graph Store.
The specified destination graph SHOULD be created if required; again, implementations providing an update service over a fixed set of
graphs MUST return with failure for a request that would create a disallowed graph. If the destination graph already exists, then no data in that graph will be
removed.</p>
<pre class="defn nohighlight"><strong>LOAD</strong> ( <strong>SILENT</strong> )? <em><a data-cite=
"SPARQL12-QUERY#rIRIREF">IRIref_from</a></em> ( <strong>INTO GRAPH</strong> <em><a data-cite="SPARQL12-QUERY#rIRIREF">IRIref_to</a></em> )?</pre>
<p><em>IRIref_from</em> specifies the IRI of a document such that a store will be able to identify, locate and read the document. The most common form will be URLs with the <em>http</em>
IRI schemes. Once the document has been read, the resulting triples will be inserted into the destination graph named by the IRI referred to by <em>IRIref_to</em>.</p>
<p>If no destination graph IRI (<em>IRIref_to</em>) is provided to load the triples into, then the data will be loaded into the default graph.</p>
<p>In case no RDF data can be retrieved (as opposed to the empty graph being retrieved) from the IRI denoted by <em>IRIref_from</em>, or in case the retrieval method returns an error (such
as, for instance an HTTP error code), the SPARQL 1.2 Update service SHOULD return failure and the status of the Graph Store
SHOULD remain in the same status as prior to the request; in case the keyword SILENT is present, however, the operation will
still return success and the status of the Graph Store is not specified by the present document: implementations may create the destination graph or not and partially load data, in case of
a transmission error where partial data has been received (which itself may be legal RDF).</p>
<p>
The `LOAD` operation reads an RDF document from an IRI and inserts triples
from the document into the <a href="#defn_graphStore">Graph Store</a>.
</p>

<pre class="defn nohighlight"><strong>LOAD</strong> ( <strong>SILENT</strong> )? <em><a
data-cite="SPARQL12-QUERY#rIRIREF">IRIref_from</a></em> ( <strong>INTO GRAPH</strong> <em><a
data-cite="SPARQL12-QUERY#rIRIREF">IRIref_to</a></em> )?</pre>

<p><em>IRIref_from</em> specifies the IRI of a document, such that a store will be able to
identify, locate, and read the document. The most common IRIs will be URLs in
the `https` and `http` IRI schemes.
</p>

<p>If a destination graph (<i>IRIref_to</i>) is specified by `INTO GRAPH`, then the
specified destination graph SHOULD be created if required; again, implementations
providing an update service over a fixed set of graphs MUST return with failure for a
request that would create a disallowed graph. If the destination graph already exists,
then no data in that graph will be removed.
The RDF document is retrieved and parsed to produce an
<a data-cite="RDF12-CONCEPTS#dfn-rdf-graph">RDF Graph</a>.
This graph is
<a data-cite="RDF12-SEMANTICS#dfn-merging">merged</a> into the destination
graph in the graph store.
</p>
<p>
If no destination graph IRI is specified by `INTO`, then the RDF document is retrieved
and parsed into an <a data-cite="RDF12-CONCEPTS#dfn-rdf-dataset">RDF Dataset</a>.
This dataset is <a data-cite="RDF12-SEMANTICS#dfn-rdf-dataset-merge">merged</a> into the
<a href="#defn_graphStore">graph store</a> viewed as a mutable
<a data-cite="SPARQL12-QUERY#sparqlDataset">RDF Dataset</a>.
</p>

<p>
If no RDF data can be retrieved (as opposed to an empty graph being retrieved) from the
IRI denoted by <em>IRIref_from</em>, or in case the retrieval method returns an error
(such as, for instance an HTTP error code), the SPARQL 1.2 Update service SHOULD return
failure and the status of the Graph Store SHOULD remain in the same status as prior to
the request. However, if the the keyword `SILENT` is present, operation will return
success, rather than failure, and the status of the Graph Store is is not specified.
</p>

<div class="note" id="context-triples">
<p>
Some RDF syntaxes, such as [[[JSON-LD11]]], are often used to serialize
a single graph with no graph name.
[[[RDF12-N-QUADS]]] may be used as a
database dump format for a triple store with the data only in the default graph.
When the `LOAD` operation has an `INTO GRAPH` clause, it is an error if
named graphs are encountered when parsing the RDF document.
</p>
</div>
</section>

<section id="clear">
<h4>CLEAR</h4>
<p>The <code>CLEAR</code> operation removes all the triples in the specified graph(s) in the Graph Store.</p>
Expand Down Expand Up @@ -1564,12 +1604,34 @@ <h4>Delete Insert Operation</h4>
<h4>Load Operation</h4>
<div class="defn">
<p><strong><span class="doc-ref" id="defn_loadOperation">Definition: Load Operation</span></strong></p>
<p>A <a href="#load">Load Operation</a> OpLoad is an Update Operation in which new triples (from a remote graph) are added in the Graph Store, either in the default slot or in a named
slot, if specified.</p>
<p>OpLoad ( GS, <em>documentIRI</em>) = Dataset-UNION ( GS, { graph ( <em>documentIRI</em> ) } )</p>
<p>OpLoad ( GS, <em>documentIRI</em>, <em>iri</em> ) = Dataset-UNION(GS, { {}, ( <em>iri</em>, graph ( <em>documentIRI</em> ) ) } )</p>
<p>where graph(<em>documentIRI</em>) is a function returning the RDF graph serialized by the RDF document retrieved from IRI <em>documentIRI</em>, where blank nodes present in the
retrieved graph are supposed to be "standardized apart"; i.e., blank nodes from a loaded graph need to be disjoint with the blank nodes already present in the Graph Store GS.</p>
<p>
A <a href="#load">Load Operation</a> `OpLoad` is an Update Operation in which new
triples (from a remote graph or dataset) are added to the Graph Store, either in the
default slot or in a named slot, if specified.
Comment on lines +1609 to +1610
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What is a "slot"? These seem to be stand-ins for "(named) graph". If "(named) graph" can't be used yet, then this should be changed to --

Suggested change
triples (from a remote graph or dataset) are added to the Graph Store, either in the
default slot or in a named slot, if specified.
triples (from a remote graph or dataset) are added to the Graph Store.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If "(named) graph" can be used, then this should be changed to --

Suggested change
triples (from a remote graph or dataset) are added to the Graph Store, either in the
default slot or in a named slot, if specified.
triples (from a remote graph or dataset) are added to the Graph Store, either in the
default graph or in a named graph, if specified.

Copy link
Contributor Author

@afs afs Dec 10, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"slots" are described in section 2 and 4.2 Auxiliary Definitions.

The text "either in the default slot or in a named slot, if specified." in LOAD is unchanged from SPARQL 1.1 Update in the formal definition section.

A Graph Store is a mutable container of slots (one unnamed slot, and zero or more slots with name). Each slot holds an immutable graph. Update is "replace graph in slot by by another graph", preserving the container.

A dataset is strictly immutable, just like graphs aren't mutable.

The spec is a bit weak in places:

transforms a Graph Store GS to another Graph Store GS'
written
Op(GS, Args) = GS'

but it is the same Graph Store with different contents.

See the note in 4.2 Auxiliary Definitions that mentions to punning on "Graph Store" and "RDF Dataset".

This could be cleared up (but not this PR!).

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

My bad. I should have looked to the pr-preview where it's much clearer why "slots" are being discussed.

</p>

<p>OpLoad ( GS, <em>documentIRI</em>) = dataset-merge ( GS, dataset ( <em>documentIRI</em> ) } )</p>

<p>OpLoad ( GS, <em>documentIRI</em>, <em>iri</em> ) = dataset-merge(GS, { {}, ( <em>iri</em>, graph ( <em>documentIRI</em> ) ) } )</p>

<p>where</p>
<ul>
<li>The operation <code>dataset ( <em>documentIRI</em> )</code> is a function
returning the RDF dataset serialized by the RDF document</li>
<li>The operation <code>graph ( <em>documentIRI</em> )</code> is a function
returning the RDF graph serialized by the RDF document</li>
<li>
The operation `dataset-merge` combines the Graph Store GS with the given
dataset using the
<a data-cite="RDF12-SEMANTICS#dfn-rdf-dataset-merge">dataset merge operation</a>
</li>
</ul>
<p>
Blank nodes present in the retrieved graph or dataset are
"standardized apart"; i.e., blank nodes from a loaded graph or
dataset are disjoint from the blank nodes already present in the
Graph Store GS.
</p>
</div>
</section>
<section id="def_clearOperation">
Expand Down Expand Up @@ -1842,6 +1904,7 @@ <h2>Changes between SPARQL 1.1 Update and SPARQL 1.2 Update</h2>
<li>Add reifying triples examples in <a href="#insertData" class="sectionRef"></a>, <a href="#deleteData" class="sectionRef"></a>, and <a href="#delete" class="sectionRef"></a></li>

<li>Use PREFIX instead of @prefix in all Turtle examples</li>
<li>Revise `LOAD` description and definition for handling RDF documents which contain a dataset</li>
</ul>
</section>

Expand Down
Loading