The reference catches up with LinkedDataHub 6.2.3

docs/reference/command-line-interface.ttl

@@ -408,6 +408,22 @@ ldh add file \\
   --title "Masala Chai" \\
   --slug 78 \\
   --primary-topic '#this'</pre>
+        <h3 id="children-view">A container's children view</h3>
+        <p>A container's first content block shows its children, as the <code>dh:Container</code> <a href="../administration/ontologies/#constructors">constructor</a> makes it. <code>--no-children-view</code> leaves it out, and the content is then appended like any other document's: a container whose children are laid out in another mode embeds a view of its own.</p>
+        <pre>container=$(ldh create container \\
+  --parent "$LDH_BASE" \\
+  --title "Products" \\
+  --slug products \\
+  --no-children-view)
+
+ldh add view \\
+  --uri '#children' \\
+  --query https://w3id.org/atomgraph/linkeddatahub#SelectChildren \\
+  --mode https://w3id.org/atomgraph/client#GridMode \\
+  --title "Products" \\
+  "$container"
+
+ldh add object-block --value "${container}#children" "$container"</pre>
         <h3 id="push">Pushing a directory</h3>
         <p><samp>ldh push</samp> replays a directory into the document tree it maps to — the <a href="../../tutorial/app-as-repository/">app as a repository</a> convention: one RDF file per document, a folder beside it for the files that document holds, and subfolders for its children.</p>
         <pre>ldh push "$LDH_BASE"                              # the current directory

docs/reference/configuration.ttl

@@ -196,6 +196,8 @@ HOST=ec2-54-235-229-141.compute-1.amazonaws.com</pre>
                     Defaults to <samp>true</samp>.</dd>
                 <dt><samp>MAX_CONTENT_LENGTH</samp></dt>
                 <dd>Maximum allowed request body size (<samp>nginx</samp> has a separate setting for this). Defaults to <samp>2097152</samp>.</dd>
+                <dt><samp>MAX_QUERY_RESPONSE_LENGTH</samp></dt>
+                <dd>The longest query result, in bytes, that the <a href="../http-api/sparql/"><samp>/sparql</samp> endpoint</a> answers a query with; a longer one is refused with <samp>502 Bad Gateway</samp>. Counted on the triplestore's response to the platform, not on what the caller receives. Defaults to <samp>5242880</samp> (5 MiB).</dd>
                 <dt><samp>HTTP_MAX_THREADS</samp></dt>
                 <dd>Maximum request threads on Tomcat's plain HTTP connector, the one the proxy forwards to. Defaults to Tomcat's own <samp>200</samp>. Beyond capacity it bounds how many server-side renders can be in flight against each other: a render calls back into this same connector through the proxy for the page's labels, so it holds one thread while it waits for another to answer — see the <a href="#http-client-pool">HTTP client pool</a>.</dd>
             </dl>
@@ -269,6 +271,12 @@ HOST=ec2-54-235-229-141.compute-1.amazonaws.com</pre>
             <dt><samp>VARNISH_END_USER_BACKEND_PORT</samp></dt>
             <dd>Port for end-user Varnish backend. Defaults to <samp>3030</samp>.</dd>
         </dl>
+        <p>The <samp>varnish-admin</samp> and <samp>varnish-end-user</samp> services keep SPARQL results in a store of their own, apart from the main one:</p>
+        <dl>
+            <dt><samp>VARNISH_SPARQL_STORAGE</samp></dt>
+            <dd>Size of the store SPARQL results are kept in, in Varnish's size syntax. A result too large for it ends the fetch, and the triplestore abandons the query, so it also bounds what one runaway query costs. Defaults to <samp>64M</samp>.</dd>
+        </dl>
+        <p><samp>varnish-frontend</samp> also <a href="../http-api/sparql/#caching">caches anonymous SPARQL queries</a> on their body, so the same query from different visitors reaches the platform once.</p>
     </div>
     <div>
         <h2 id="fuseki"><samp>fuseki</samp> service</h2>

docs/reference/data-model/documents.ttl

@@ -58,7 +58,7 @@
 <https://localhost:4443/categories/#select-children>
     a       ldh:Object ;
     rdf:value ldh:ChildrenView .</pre>
-            <p>The <code>&lt;#select-children&gt;</code> resource is an <code>ldh:Object</code> <a href="../blocks/">content block</a> whose <code>rdf:value</code> <code>ldh:ChildrenView</code> renders the container's children listing.</p>
+            <p>The <code>&lt;#select-children&gt;</code> resource is an <code>ldh:Object</code> <a href="../blocks/">content block</a> whose <code>rdf:value</code> <code>ldh:ChildrenView</code> renders the container's children listing. The container constructor and <samp>ldh create container</samp> write it as the first block; the command's <code>--no-children-view</code> <a href="../../command-line-interface/#children-view">leaves it out</a>.</p>
             <p class="exhibit-links">Live: <a href="https://northwind-traders.demo.linkeddatahub.com/categories/" target="_blank">/categories/</a> (the demo's version composes <a href="https://github.com/AtomGraph/LinkedDataHub-Apps/blob/master/demo/northwind-traders/categories.ttl" target="_blank">further blocks</a> on top of this shape)</p>
         </div>
     </div>

docs/reference/data-model/resources.ttl

@@ -211,7 +211,7 @@ ORDER BY DESC(?revenue)''' .
     dct:title "Revenue by category" ;
     rdf:value &lt;#category-revenue&gt; .</pre>
         <p class="exhibit-links">Source: <a href="https://github.com/AtomGraph/LinkedDataHub-Apps/blob/master/demo/northwind-traders/categories.ttl" target="_blank">categories.ttl</a> · Live: <a href="https://northwind-traders.demo.linkeddatahub.com/categories/" target="_blank">/categories/</a></p>
-        <p>Multiple <code>ldh:seriesVarName</code> values plot one series per named result variable — see the
+        <p>Multiple <code>ldh:seriesVarName</code> values (<samp>ldh add result-set-chart</samp> takes <code>--series-var-name</code> once per series) plot one series per named result variable, in the order the query's <code>SELECT</code> projects them — see the
             <a href="https://github.com/AtomGraph/LinkedDataHub-Apps/blob/master/demo/northwind-traders/orders.ttl" target="_blank">demo's revenue-by-carrier chart</a>,
             which pivots three carriers into three series with conditional aggregation.</p>
     </div>

docs/reference/http-api.ttl

@@ -166,7 +166,8 @@ ETag: "1e635b4-ntriples"
     <div>
         <h2 id="caching">Caching</h2>
         <p><code>GET</code> and <code>HEAD</code> RDF responses from the backend triplestores (<em>not LinkedDataHub responses</em>) are cached automatically by LinkedDataHub using <a href="https://varnish-cache.org" target="_blank">Varnish</a>
-            as an HTTP proxy cache. You can check the age of the response by inspecting the <code>Age</code> response header (the value is in seconds).</p>
+            as an HTTP proxy cache. You can check the age of the response by inspecting the <code>Age</code> response header (the value is in seconds).
+            Anonymous <a href="sparql/#caching">SPARQL queries</a> are cached too, on their body.</p>
         <p>LinkedDataHub sends <code>ETag</code> response headers derived from a digest of the document's URL and its RDF content. Every representation (HTML, RDF/XML, Turtle, etc.) gets a distinct <code>ETag</code> value, and language-negotiated HTML representations factor the accepted languages into the tag. Treat the value as opaque: it is a validator to quote back in a <a href="documents/#preconditions">conditional request</a>, and nothing about the document can be read from it.</p>
         <p>HTML responses carry a <code>Content-Language</code> negotiated against the languages the UI ships with, and advertise <code>Vary: Accept-Language</code> so shared caches keep the renderings apart.</p>
         <p>Caching of LinkedDataHub responses can be enabled on the nginx HTTP proxy server by uncommenting the <code>add_header Cache-Control</code> directives in the <samp>platform/nginx.conf.template</samp> file.

docs/reference/http-api/sparql.ttl

@@ -22,6 +22,10 @@
             documents are written through the <a href="../documents/">Graph Store Protocol</a>, not SPARQL Update.</p>
         <p>External clients are limited in how many queries they may have in flight and how often they may send them; a query beyond the
             <a href="../../configuration/#sparql-limits">limits</a> is answered with <code>429 Too Many Requests</code>.</p>
+        <p>A query result is bounded by <a href="../../configuration/#http"><samp>MAX_QUERY_RESPONSE_LENGTH</samp></a> (5 MiB by default). A longer one is refused, not truncated:
+            the response is <code>502 Bad Gateway</code> with a body typed <code>ldh:ResponseTooLarge</code>, and a client that needs the whole result pages through it with
+            <code>LIMIT</code>/<code>OFFSET</code>. Behind the platform, the triplestore abandons such a query once its result outgrows the
+            <a href="../../configuration/#varnish">Varnish store kept for SPARQL results</a>.</p>
         <p>The protocol's dataset parameters can be used to scope a query to a single document's graph: passing <code>default-graph-uri=&lt;document-uri&gt;</code>
             makes that document's named graph the query's default graph. The dataset specified this way overrides any <code>FROM</code>/<code>FROM NAMED</code>
             clauses in the query, and <code>GRAPH</code> patterns match nothing since no named graphs are part of the dataset. This is the read-side counterpart
@@ -31,6 +35,13 @@
   --data-urlencode 'query=PREFIX schema: &lt;https://schema.org/&gt; SELECT ?name WHERE { ?product a schema:Product ; schema:name ?name }' \\
   --data-urlencode 'default-graph-uri=https://localhost:4443/products/1/'</pre>
     </div>
+    <div>
+        <h2 id="caching">Caching</h2>
+        <p>An anonymous query — one sent without a WebID certificate or an authenticated session — is cached by the front Varnish on its body as well as its URL, whether it arrives as
+            <code>GET</code> or as the protocol's <code>POST</code> forms, so the views of a public dataspace reach the platform once per query rather than once per visitor.
+            A result is kept for an hour at most, and any write through the platform drops every cached result. Authenticated queries are not cached, since their results
+            depend on the agent's access.</p>
+    </div>
 </div>"""^^rdf:XMLLiteral ;
         rdfs:seeAlso <https://www.w3.org/TR/sparql11-protocol/> .