Named Queries

A named query is a URI pattern that generates a projection of an asset query. This can generate IIIF Manifests and other multi-asset results.

A typical scenario is to select a set of assets based on one metadata field, order them by another metadata field, and generate a IIIF Manifest from the results. The named query projection (the query result) is public-facing (in the same way that an info.json is public-facing), and you manage the named queries through the platform API.

Consider these public-facing URLs:

• https://dlcs.example/iiif-resource/acme-corp/manifest/43/ae67899
• https://dlcs.example/iiif-resource/acme-corp/manifest/43/bc5b6a8
• https://dlcs.example/iiif-resource/acme-corp/manifest/43/pph839a
• https://dlcs.example/iiif-resource/acme-corp/manifest/43/mm97c3k
• https://dlcs.example/iiif-resource/acme-corp/manifest/999/test

All these queries are instances of the following pattern:

https://dlcs.example/{output-type}/{customer}/{named-query}/{p1}/{p2}/.../{pn}

This pattern has two parts:

https://dlcs.example/{output-type}/{customer}/{named-query}...................
https://dlcs.example/....................................../{p1}/{p2}/.../{pn}

The first three elements are fixed:

path part
output-type	The format the query will be projected into. Currently iiif-resource is supported.
customer	Either name or integer id of the customer (both are valid).
name	The path-element-safe name of the named query within the customer.

The remaining elements /{p1}/{p2}/.../{pn} are a sequence of parameter values. Some named query templates do not need any parameters, but others require one, or two, or more parameters.

The customer whose name field is "acme-corp" has a named query whose name field is "manifest":

{
    "@id": "https://api.dlcs.example/customers/2/namedQueries/3ff5512a-8be8-4638-a0f0-b7af65acbc4c",
    "@type": "vocab:NamedQuery",
    "name": "manifest",
    "template": "canvas=n1&space=p1&s1=p2"
}

This named query uses two URL parameters, p1 and p2 — in this case the space and the string1 metadata field value. The template can be broken down as:

• selection: space=p1&s1=p2 selects all assets where asset.space equals the first parameter and asset.string1 equals the second parameter
• ordering: canvas=n1 orders the canvases within the manifest by number1

Therefore:

https://dlcs.example/iiif-resource/acme-corp/manifest/43/ae67899

plus

"template": "canvas=n1&space=p1&s1=p2"

means:

SELECT the assets belonging to customer acme-corp in space 43 with string1=ae67899. ORDER by number1. PROJECT into a IIIF manifest.

An asset query against the platform API returns a collection of vocab:Image objects. A named query uses an asset query but then projects those assets and constructs a IIIF resource from them using the parameters provided.

/customers/{customer}/namedQueries/{name}

Method	Label	Expects	Returns	Status
GET	Retrieve a Named Query	-	vocab:NamedQuery	200 OK, 404 Not Found
PUT	Update a Named Query (but not create one)	vocab:NamedQuery	vocab:NamedQuery	200 OK, 404 Not Found
DELETE	Delete a Named Query	-	owl:Nothing	204 No Content

You cannot have two named queries with the same name. You cannot update the name with a PUT — only the template can be updated this way. Delete and re-create the named query if you need to change its name.

You create a named query with a POST to the parent collection /customers/{customer}/namedQueries.

💻 GET, PUT and DELETE a NamedQuery Create, retrieve, update and delete a named query, and construct the public-facing URL

name

The identifier for the named query within the customer. This value appears as a path element in the public-facing URL and must be unique within the customer. It is required when creating a named query via POST to the parent collection; the platform will not mint a value if one is not supplied. It cannot be updated via PUT — delete and re-create the named query if you need to change it.

domain	range	readonly	writeonly
vocab:NamedQuery	xsd:string	False	False

template

The query string that defines how assets are selected, grouped and ordered to produce the named query output (the projection). See Named Query template syntax below for the full syntax.

domain	range	readonly	writeonly
vocab:NamedQuery	xsd:string	False	False

Named Query template syntax

The template property is a query string of key=value pairs that defines how assets are selected, grouped and ordered.

Property name	Description	Example
space	Restricts to a space by numeric id	&space=p1
spacename	Restricts to a space by name	&spacename=p1
canvas	The metadata field used to order canvases in the projection	&canvas=n2
assetOrder	Alias for canvases, more generic when the project is not a IIIF manifest	&assetOrder=n2
batch	Restrict to assets created in a particular batch (useful for reporting)	&batch=656721
manifest	Select assets that are part of a stored IIIF Manifest	&manifest=xxxx
s1	Alias for the string1 metadata field	&s1=p2
s2	Alias for the string2 metadata field	&s2=p1
s3	Alias for the string3 metadata field	&manifest=s3
n1	Alias for the number1 metadata field	&canvas=n1
n2	Alias for the number2 metadata field	&canvas=n2
n3	Alias for the number3 metadata field	&canvas=n3
p1, p2, …	URL parameter values — the path elements after the named query name in the public URL	&s1=p2
#	Hardcodes a parameter value in the template, so no URL parameter is needed	&#=my-string

Examples

canvas=n2&s1=p1&n1=p2

Select assets where string1 equals the first URL parameter and number1 equals the second parameter; group into one projection, ordered within that projection by number2. Because both string1 and number1 must match, this typically returns a single canvas.

canvas=n2&spacename=p1&s1=p2

Select assets where string1 equals the second URL parameter, restricting to only those assets in the Space with name equal to the first parameter. Group into one projection, ordered within that projection by number2.

canvas=n2&space=p1&s3=p2

Select assets in the space given by the first parameter where string3 equals the second parameter; order canvases by number2.

canvas=n1&s1=p1

Select assets where string1 equals the first URL parameter; order canvases by number1. This will select assets from across all spaces.

canvas=n1&s1=p1&#=my-string

As above, but the value of p1 is hardcoded to "my-string" in the template using &#=my-string. No URL parameter is needed — the public URL is just /{nq-name} with no further path elements.

The following table shows the examples with sample parameter values and the number of canvases each produces, given a space named docs-nq-space containing assets with string1, string3, number1 and number2 metadata:

Template	URL parameters	Canvases returned
canvas=n1&s1=p1	autumn-1985	3 (all assets where string1=autumn-1985, ordered by number1)
canvas=n2&spacename=p1&s1=p2	docs-nq-space/autumn-1985	3 (same assets, restricted to the named space, ordered by number2)
canvas=n2&space=p1&s3=p2	314160/prints	3 (assets in space 314160 where string3=prints, ordered by number2)
canvas=n2&s1=p1&n1=p2	autumn-1985/2	1 (the single asset where string1=autumn-1985 and number1=2)
canvas=n1&s1=p1&#=my-string	(none)	2 (assets where string1=my-string, p1 hardcoded — no URL parameter needed)

💻 Named query template examples Set up assets with varied metadata and demonstrate four named query templates

More on assetOrder

The assetOrder property in the template also supports asc and desc modifiers, and can take multiple values, split by ;:

assetOrder=n1;n2 asc;s3 desc