From 7e02bc18c31a0cad5a0f50cfad12c1848267c6fb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Martynas=20Jusevi=C4=8Dius?= Date: Wed, 21 Oct 2026 16:49:59 +0200 Subject: [PATCH] The reference catches up with LinkedDataHub 6.2.3. The CLI page says the bin/ HTTP API scripts are removed, not deprecated, and points at the migration table; it documents the children view a container is created with and the --no-children-view option that replaces create container's --block and --mode, with the add view and add object-block steps that build a view of the children in another mode. The configuration page adds MAX_QUERY_RESPONSE_LENGTH, the bound on a /sparql result, and VARNISH_SPARQL_STORAGE, the store the admin and end-user Varnish services keep SPARQL results in. The SPARQL endpoint page says an oversize result is refused with 502 and ldh:ResponseTooLarge rather than truncated, and that the front Varnish caches anonymous queries on their body for an hour at most, dropped by any write; the HTTP API caching section links to it. The documents page notes which commands write the children view, and the charts section says the CLI takes --series-var-name once per series and the series follow the SELECT projection order. Co-Authored-By: Claude Fable 5.1 --- docs/reference/command-line-interface.ttl | 22 +++++++++++++++++++--- docs/reference/configuration.ttl | 8 ++++++++ docs/reference/data-model/documents.ttl | 2 +- docs/reference/data-model/resources.ttl | 2 +- docs/reference/http-api.ttl | 3 ++- docs/reference/http-api/sparql.ttl | 11 +++++++++++ 6 files changed, 42 insertions(+), 6 deletions(-) diff --git a/docs/reference/command-line-interface.ttl b/docs/reference/command-line-interface.ttl index f632d31..288c6fb 100644 --- a/docs/reference/command-line-interface.ttl +++ b/docs/reference/command-line-interface.ttl @@ -36,14 +36,14 @@ ldh --help
-

The CLI talks to the HTTP API directly and embeds Apache Jena. Unlike the shell scripts it replaces, it needs no curl, python or Jena command line tools on $PATH.

+

The CLI talks to the HTTP API directly and embeds Apache Jena. Unlike the shell scripts it replaced, it needs no curl, python or Jena command line tools on $PATH.

- Deprecated shell scripts -

The HTTP API shell scripts in the bin folder that ldh replaces are deprecated. The certificate and WebID tooling (webid-keygen.sh, webid-keygen-pem.sh, webid-uri.sh, webid-modulus.sh, server-cert-gen.sh) talks to no API and is not deprecated.

+ Removed shell scripts +

The HTTP API shell scripts in the bin folder that ldh replaces were deprecated in 5.10.0 and are removed as of 6.2.3; the migration table maps each script to its command. The certificate and WebID tooling (webid-keygen.sh, webid-keygen-pem.sh, webid-uri.sh, webid-modulus.sh, server-cert-gen.sh) talks to no API and stays in bin.

Migrating from a script to its command means dropping the .sh suffix, prefixing the invocation with ldh (the hyphenated name becomes a verb-object pair, e.g. admin/acl/create-group.sh becomes ldh admin create group), and passing the .p12 keystore to -f instead of the .pem certificate.

@@ -408,6 +408,22 @@ ldh add file \\ --title "Masala Chai" \\ --slug 78 \\ --primary-topic '#this' +

A container's children view

+

A container's first content block shows its children, as the dh:Container constructor makes it. --no-children-view 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.

+ 
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"

Pushing a directory

ldh push replays a directory into the document tree it maps to — the app as a repository convention: one RDF file per document, a folder beside it for the files that document holds, and subfolders for its children.

ldh push "$LDH_BASE"                              # the current directory
diff --git a/docs/reference/configuration.ttl b/docs/reference/configuration.ttl
index 7a6a1e7..7b6b76d 100644
--- a/docs/reference/configuration.ttl
+++ b/docs/reference/configuration.ttl
@@ -196,6 +196,8 @@ HOST=ec2-54-235-229-141.compute-1.amazonaws.com
Defaults to true.
MAX_CONTENT_LENGTH
Maximum allowed request body size (nginx has a separate setting for this). Defaults to 2097152.
+
MAX_QUERY_RESPONSE_LENGTH
+
The longest query result, in bytes, that the /sparql endpoint answers a query with; a longer one is refused with 502 Bad Gateway. Counted on the triplestore's response to the platform, not on what the caller receives. Defaults to 5242880 (5 MiB).
HTTP_MAX_THREADS
Maximum request threads on Tomcat's plain HTTP connector, the one the proxy forwards to. Defaults to Tomcat's own 200. 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 HTTP client pool.
@@ -269,6 +271,12 @@ HOST=ec2-54-235-229-141.compute-1.amazonaws.com
VARNISH_END_USER_BACKEND_PORT
Port for end-user Varnish backend. Defaults to 3030.
+

The varnish-admin and varnish-end-user services keep SPARQL results in a store of their own, apart from the main one:

+
+
VARNISH_SPARQL_STORAGE
+
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 64M.
+
+

varnish-frontend also caches anonymous SPARQL queries on their body, so the same query from different visitors reaches the platform once.

fuseki service

diff --git a/docs/reference/data-model/documents.ttl b/docs/reference/data-model/documents.ttl index d3e60c3..52b5613 100644 --- a/docs/reference/data-model/documents.ttl +++ b/docs/reference/data-model/documents.ttl @@ -58,7 +58,7 @@ <https://localhost:4443/categories/#select-children> a ldh:Object ; rdf:value ldh:ChildrenView . -

The <#select-children> resource is an ldh:Object content block whose rdf:value ldh:ChildrenView renders the container's children listing.

+

The <#select-children> resource is an ldh:Object content block whose rdf:value ldh:ChildrenView renders the container's children listing. The container constructor and ldh create container write it as the first block; the command's --no-children-view leaves it out.

Live: /categories/ (the demo's version composes further blocks on top of this shape)

diff --git a/docs/reference/data-model/resources.ttl b/docs/reference/data-model/resources.ttl index 386a8d4..f0b853d 100644 --- a/docs/reference/data-model/resources.ttl +++ b/docs/reference/data-model/resources.ttl @@ -211,7 +211,7 @@ ORDER BY DESC(?revenue)''' . dct:title "Revenue by category" ; rdf:value <#category-revenue> .

Source: categories.ttl · Live: /categories/

-

Multiple ldh:seriesVarName values plot one series per named result variable — see the +

Multiple ldh:seriesVarName values (ldh add result-set-chart takes --series-var-name once per series) plot one series per named result variable, in the order the query's SELECT projects them — see the demo's revenue-by-carrier chart, which pivots three carriers into three series with conditional aggregation.

diff --git a/docs/reference/http-api.ttl b/docs/reference/http-api.ttl index 7f1993d..d981b39 100644 --- a/docs/reference/http-api.ttl +++ b/docs/reference/http-api.ttl @@ -166,7 +166,8 @@ ETag: "1e635b4-ntriples"

Caching

GET and HEAD RDF responses from the backend triplestores (not LinkedDataHub responses) are cached automatically by LinkedDataHub using Varnish - as an HTTP proxy cache. You can check the age of the response by inspecting the Age response header (the value is in seconds).

+ as an HTTP proxy cache. You can check the age of the response by inspecting the Age response header (the value is in seconds). + Anonymous SPARQL queries are cached too, on their body.

LinkedDataHub sends ETag 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 ETag 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 conditional request, and nothing about the document can be read from it.

HTML responses carry a Content-Language negotiated against the languages the UI ships with, and advertise Vary: Accept-Language so shared caches keep the renderings apart.

Caching of LinkedDataHub responses can be enabled on the nginx HTTP proxy server by uncommenting the add_header Cache-Control directives in the platform/nginx.conf.template file. diff --git a/docs/reference/http-api/sparql.ttl b/docs/reference/http-api/sparql.ttl index 0a970f7..eaadff1 100644 --- a/docs/reference/http-api/sparql.ttl +++ b/docs/reference/http-api/sparql.ttl @@ -22,6 +22,10 @@ documents are written through the Graph Store Protocol, not SPARQL Update.

External clients are limited in how many queries they may have in flight and how often they may send them; a query beyond the limits is answered with 429 Too Many Requests.

+

A query result is bounded by MAX_QUERY_RESPONSE_LENGTH (5 MiB by default). A longer one is refused, not truncated: + the response is 502 Bad Gateway with a body typed ldh:ResponseTooLarge, and a client that needs the whole result pages through it with + LIMIT/OFFSET. Behind the platform, the triplestore abandons such a query once its result outgrows the + Varnish store kept for SPARQL results.

The protocol's dataset parameters can be used to scope a query to a single document's graph: passing default-graph-uri=<document-uri> makes that document's named graph the query's default graph. The dataset specified this way overrides any FROM/FROM NAMED clauses in the query, and GRAPH 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: <https://schema.org/> SELECT ?name WHERE { ?product a schema:Product ; schema:name ?name }' \\ --data-urlencode 'default-graph-uri=https://localhost:4443/products/1/'

+
+

Caching

+

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 + GET or as the protocol's POST 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.

+
"""^^rdf:XMLLiteral ; rdfs:seeAlso .