Named Queries

A named query is a URI pattern that generates a projection of an asset query. This can generate IIIF Manifests, PDFs, zip files 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 this public facing URL:

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

This query is an instance of the following pattern:

https://dlcs.io/{output-type}/{customer}/{named-query}/{space}/{string1}

This pattern has two parts:

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

The first three elements are fixed:

path part
output-type	The format the query will be projected into. Permitted values are `iiif-resource`, `pdf`, `zip`.
customer	Either name or integer id of the customer
name	The name of the named query 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.io/customers/2/namedQueries/3ff5512a-8be8-4638-a0f0-b7af65acbc4c",
    "@type": "vocab:NamedQuery",
    "name": "manifest",
    "template": "manifest=s1&canvas=n1&space=p1&s1=p2"
}

This customer (acme-corp) has a named query called "manifest" that makes use of two parameters p1 and p2 - in this case the space and the string1 metadata field. These are used to SELECT the assets. The query is internally defined to use an additional asset metadata field - number1 - and to generate a manifest with each canvas having one asset. The assets selected by the query must all have string1=ae678999 in this case, and are ordered by number1.

selection: manifest=s1, spacename=p1 assignment: s1=p2 ordering: canvas=n1

Therefore:

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

plus

"template": "manifest=s1&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 iiif-resource.

An asset query against the platform API returns a collection of vocab:Image objects.
A Named Query uses an asset query but then projects these assets and constructs (in this case) a IIIF resource from them, using the parameters provided.

/customers/{customer}/namedQueries/{named-query}

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

You can't have two named queries with the same name. You cannot update the name with a PUT, only the template. The named query must be deleted if you want to change the name.

Named Query template syntax

Property Name	Description	Example
space	Matches a space by Id (by default named queries will search all images for customer)	`&space=p1`
spacename	Matches a space by name (by default named queries will search all images for customer)	`&spacename=p1`
manifest	How to group images	`&manifest=s1`
sequence	How to filter images in manifest	`&sequence=n1`
canvas	Ordering to apply to each image on canvas	`&canvas=n2`
s1	String1 metadata field	`&manifest=s1`
s2	String2 metadata field	`&s1=p1`
s3	String3 metadata field	`&manifest=s3`
n1	Number 1 metadata field	`&sequence=n1`
n2	Number 2 metadata field	`&canvas=n2`
n3	Number 3 metadata field	`&n1=p2`
p*	Identifies url parameters. Anything after `iiif-resource/{customer}/{query-name}` (/1/2/3)	`&n1=p2`
#*	When used in template adds the value to end of URL, effectively hardcoding a parameter	`todo`

Examples

(todo)

manifest=s1&sequence=n1&canvas=n2&spacename=p1s1=p2

manifest=s1&sequence=n1&canvas=n2&s1=p1&n1=p2

manifest=s1&sequence=n1&canvas=n2&s1=p1&n1=p2&space=p3&#=5&objectname={s1}_{n1}.pdf&coverpage=http://wellcomelibrary.org/service/pdfcoverpageaspdf/{s1}/0&roles=https://api.dlcs.io/customers/2/roles/clickthrough&redactedmessage=This page is restricted and is not available in PDF downloads

manifest=s3&canvas=n2&space=p1&s3=p2

manifest=s3&sequence=n1&canvas=n2&s3=p1&objectname={s3}&coverpage=http://wellcomelibrary.org/service/pdfcoverpage/{s3}/0&roles=https://api.dlcs.io/customers/4/roles/clickthrough

manifest=s3&canvas=n2&space=p1&s3=p2&objectname={s3}_{n2}.pdf&coverpage=https://iiif.wellcomecollection.org/pdf-cover/{s3}&roles=https://api.dlcs.io/customers/2/roles/clickthrough&redactedmessage=This page is restricted and is not available in PDF downloads

manifest=s1&sequence=n1&canvas=n1&s1=p1

touched 2025-09-23T12:04:54

Using Identifiers Single Asset Manifest