Filter and facet
Browse without searching
You get pagination.total and every facet bucket, and items comes back empty. Nothing is fetched or hydrated, so it is the cheap query to run on page load, before the user has typed anything, to populate a filter UI.
{
creativeWorks(perPage: 0) {
# 0 is deliberate: it asks for total count and facets without the documents
pagination {
total
}
facets {
material {
buckets {
value
label {
value
}
count
}
totalValues
}
associatedMedia {
thumbnailUrl {
exists {
value
count
}
}
}
}
}
} Run queryEach bucket carries the value to filter on and the count to show beside it. totalValues says how many values the facet holds in all, so the interface can show “10 of 195”. A facet returns its 50 highest counts; ask for fewer or more with limit, from 1 to 100: material(limit: 10) for a short sidebar list, material(limit: 100) to fold it out. A larger limit returns the same buckets plus more, so a “show more” button sends the query again with perPage: 0 and only that facet. label is resolved only where the field points at another collection – material here, whose labels come from terms – so a facet over a plain keyword field such as type returns label: null, and the interface falls back to the value itself.
Search within a facet
A facet shows its largest values, so a material on three works hides behind the fifty most common ones. Let the user type instead, and send what they type as the facet’s query:
{
creativeWorks(perPage: 0) {
facets {
material(query: "zij", limit: 10) {
buckets {
value
label {
value
}
count
}
totalValues
}
}
}
} Run queryThe buckets are the materials whose label matches “zij” – “Zijde” and “zijdefluweel”, and “moiré zijde” too, because any word of a label counts – counted over the same works as without the query, highest count first. Only the label the works carry for each material is matched, not the alternate names a search of terms also finds.
- Three characters or more. A shorter query is ignored, and the facet comes back as without one: one or two letters match next to nothing or nearly everything.
- A selected value that doesn’t match is left out. The ticked checkbox disappears from the typeahead list. The same facet without a query still returns it, so keep the sidebar’s own request for undoing a selection.
totalValuescounts the matches among the current works. For a facet onpersons,termsor another collection it isnullwhen more than 50 labels match the text, because only the 50 most frequent are counted; ask the user to type more.- A facet on a plain value (
type) matches the values themselves, by prefix. dataset,publisher,isPartOfandcontributoroncreativeWorks, anddatasetonoccupations, match differently: the works carry no labels for them, so the query searches the referenced type itself, alternate names included. That search picks the 50 most relevant values across the whole collection, so a common name can come back empty when none of those 50 occur among the current works.- A reference whose values have no label, a yes/no facet and a range facet have no
queryargument. - A query on a reference facet costs one more under the query cost limit of 100 per request: the search for its matching values.
Filter
Keys inside where are combined with AND, and each takes a list that is itself an OR. Ask for banners that are made of silk or velvet, and have an image:
{
creativeWorks(
perPage: 10
where: {
associatedMedia: { where: { thumbnailUrl: { exists: true } } }
material: {
in: [
"https://id.drapo.nl/2d744075-7952-5e8a-ad0e-0cd664102d6c"
"https://id.drapo.nl/a472ec0b-957c-57a9-8178-b70fdab1c902"
]
}
}
) {
pagination {
total
}
items {
name {
value
}
}
}
} Run querySome fields filter on whether a value is there at all:
associatedMedia: { where: { thumbnailUrl: { exists: true } } }keeps works with a displayable image;contentLocation: { where: { latitude: { exists: true } } }(orlocationCreated) keeps works with a place that has coordinates – the ones a map can show; “either place” is anorof the two;dateCreated: { exists: true }keeps the dated works a timeline can place. A date no reader can parse counts as undated.existsstands alone in its filter: aminormaxalready matches dated works only, andexistsbeside one is refused.
Each is counted by the matching exists facet, such as facets { dateCreated { exists { value count } } }.
A facet ignores its own filter. Ask the query above for facets, and material still counts every material that has an image, so a filter UI can offer the alternatives to tick; associatedMedia { thumbnailUrl { exists } } counts every material-matching work, with or without one. A value you filter on always stays among its facet’s buckets – at count 0 when the other filters leave it no works – so its checkbox never disappears. An or across fields, below, belongs to no single facet and narrows them all.
Combine fields with or
To OR across different fields, list the alternatives under or. Each entry is a criterion: the same field names as where, without further nesting. This asks for banners that either depict a coat of arms or are made of silk:
{
creativeWorks(
perPage: 10
where: {
or: [
{
about: {
in: ["https://id.drapo.nl/a005b7a1-562a-5d71-83c2-b26dd96dfae6"]
}
}
{
material: {
in: ["https://id.drapo.nl/2d744075-7952-5e8a-ad0e-0cd664102d6c"]
}
}
]
}
) {
pagination {
total
}
}
} Run query253 works carry that subject and 123 that material; the union is 341, because 35 have both. or sits alongside ordinary keys, so adding associatedMedia: { where: { thumbnailUrl: { exists: true } } } next to it narrows the union rather than joining it, to 340.
To ask “what refers to this object, through any field?”, generate that list of criteria instead of writing it out: What refers to an object reads every field that can hold an IRI out of the schema itself.
Group with and
Most combinations need no grouping. Ordinary keys already AND, and each field's in already ORs, so “(silk or velvet) and depicting a coat of arms” is just two keys. Reach for and only when both sides of the AND are themselves cross-field ORs, which nothing else can express.
and takes whole where objects rather than criteria, so each entry may carry its own or:
{
creativeWorks(
perPage: 0
where: {
and: [
{
or: [
{
about: {
in: ["https://id.drapo.nl/a005b7a1-562a-5d71-83c2-b26dd96dfae6"]
}
}
{
material: {
in: ["https://id.drapo.nl/2d744075-7952-5e8a-ad0e-0cd664102d6c"]
}
}
]
}
{
or: [
{
about: {
in: ["https://id.drapo.nl/f5ca916a-fab2-5cdd-a0c7-e7105856fcd5"]
}
}
{
material: {
in: ["https://id.drapo.nl/a472ec0b-957c-57a9-8178-b70fdab1c902"]
}
}
]
}
]
}
) {
pagination {
total
}
}
} Run queryThe first group matches 341 works and the second 554; their intersection is 221.
Find works you may reuse
A licence belongs to a reproduction, not to the work: each associatedMedia entry carries its own. Filter on it through associatedMedia, and read the counts from the facet of the same name. This asks for works with a reproduction in the public domain:
{
creativeWorks(
perPage: 0
where: {
associatedMedia: {
where: {
license: {
in: ["https://creativecommons.org/publicdomain/zero/1.0/"]
}
}
}
}
) {
pagination {
total
}
facets {
associatedMedia {
license {
buckets {
value
count
}
}
}
}
}
} Run queryA bucket counts works, not reproductions: a work with two public-domain images counts once.