Introspecting the schema
Describe one collection
Everything a search UI needs to know about one collection – which fields it can filter on and with what input, which keys it can sort by, and which facets it serves in which bucket shape – comes back from one introspection request, without walking the schema. The type is the unit of declaration, so ask for the type: <Type>Where for the filters, <Type>SortField for the sort keys and <Type>Facets for the facets.
{
where: __type(name: "CreativeWorkWhere") {
inputFields {
name
type {
...Ref
}
}
}
dateRange: __type(name: "DateRange") {
inputFields {
name
type {
...Ref
}
}
}
dateRangeOrExists: __type(name: "DateRangeOrExists") {
inputFields {
name
type {
...Ref
}
}
}
placeFilter: __type(name: "CreativeWorkContentLocationFilter") {
inputFields {
name
type {
...Ref
}
}
}
sortFields: __type(name: "CreativeWorkSortField") {
enumValues {
name
}
}
facets: __type(name: "CreativeWorkFacets") {
fields {
name
type {
...Ref
ofType {
fields {
name
type {
...Ref
}
}
ofType {
ofType {
fields {
name
type {
...Ref
}
}
}
}
}
}
}
}
}
fragment Ref on __Type {
kind
name
ofType {
kind
name
ofType {
kind
name
ofType {
kind
name
}
}
}
} Run queryFor creativeWorks today this yields:
- 19 filter keys:
idandtype;- references, each by its target’s filter:
datasetandisPartOfaDatasetFilter,publisheraPublisherFilter,creatoraPersonOrOrganizationFilter, andadditionalType,about,materialandgenreaTermFilter; contentLocationandlocationCreated: aCreativeWorkContentLocationFilterandCreativeWorkLocationCreatedFilter, whoseinis[IRI!]and whosewheretakeslatitude: { exists };contributor, a filter on one entry, andassociatedMedia, whosewherealso takesthumbnailUrl: { exists };temporalCoverageandsdDatePublished: aDateRangewithminandmax;dateCreated: aDateRangeOrExists, which addsexists;orandand.
- Four sort keys:
RELEVANCE,NAME,SD_DATE_PUBLISHED,DATE_CREATED. - 14 facet fields:
- an
IRIFacetfor each reference field that counts only its own values, whosebucketsareIRIBuckets (value: IRI!,count,label) beside itstotalValues; - a
ValueFacetofValueBuckets (value: String!) fortype; - an object for each field that counts more –
contentLocationandlocationCreated(buckets,totalValuesandlatitude { exists }),dateCreated { exists }andassociatedMedia { license thumbnailUrl { exists } }, whoseexistslists areBooleanBuckets. Substitute another collection’s type name –PersonWhere,PersonSortField,PersonFacets– for the rest.
- an
Enum values and fields live on the named type, not on its wrappers: IRIFacet! arrives as NON_NULL → OBJECT and [BooleanBucket!]! as NON_NULL → LIST → NON_NULL → OBJECT, which is why the facets block asks for fields one ofType down and again three down, and why enumValues is asked of the enum type directly. Asked on a wrapper, both come back empty rather than failing.
What refers to an object
To answer “what refers to the object I am looking at, through any field?” – click “ink” as a term, get every work that has it as material, subject or genre – you need the list of fields that can hold an IRI at all. Don’t write that list down: ask the API, and it stays right when the schema moves.
The IRI scalar makes it decidable. A filter input takes one in list, and its element type says what the field holds:
input TermFilter {
in: [IRI!] # material, about, genre – identity
}
input KeywordFilter {
in: [String!] # type – literals
}A field references IRIs when its filter input’s in takes IRI. Nothing keys on a field name, so this works on any LDE schema, including one you changed.
Ask the schema
Two halves: which filter inputs take IRIs (asked once for the whole schema), and which filter input each collection’s where fields use.
{
filters: __schema {
types {
name
inputFields {
name
type {
kind
name
ofType {
kind
name
ofType {
kind
name
}
}
}
}
}
}
collections: __schema {
queryType {
fields {
name
args {
name
type {
name
inputFields {
name
type {
name
}
}
}
}
}
}
}
} Run queryJoin the halves on the filter type name:
const namedType = (type) => (type.ofType ? namedType(type.ofType) : type);
// { TermFilter, PersonFilter, PlaceFilter, … } – the inputs that take IRIs
const iriFilters = new Set(
data.filters.types
.filter((type) =>
type.inputFields?.some(
(field) => field.name === 'in' && namedType(field.type).name === 'IRI',
),
)
.map((type) => type.name),
);
// { creativeWorks: ['id', 'dataset', 'creator', 'about', 'material', …], … }
const iriFields = Object.fromEntries(
data.collections.queryType.fields
.map((collection) => [
collection.name,
collection.args
.find((argument) => argument.name === 'where')
?.type.inputFields.filter((field) => iriFilters.has(field.type.name))
.map((field) => field.name),
])
.filter(([, fields]) => fields),
);or and and drop out on their own: they hold criteria, not filters, so they have no in. The collection list comes out of the same query, so a ninth collection needs no code change. Run this at boot and cache it – the surface only moves when the API is redeployed.
Why the shape: introspection has no string form for a type, so [IRI!] arrives as a wrapper chain (LIST → NON_NULL → SCALAR IRI) that you unwrap to the named type. And a query may nest at most two fields/inputFields lists – a third is rejected with Maximum introspection depth exceeded – which is why the IRI filter inputs are collected from __schema.types rather than walked per collection. type, ofType and args are free.
The query it builds
One or criterion per field, all carrying the same IRI. Drop id: that matches the object itself rather than what refers to it.
{
creativeWorks(
perPage: 10
where: {
or: [
{
about: {
in: ["https://id.drapo.nl/a005b7a1-562a-5d71-83c2-b26dd96dfae6"]
}
}
{
material: {
in: ["https://id.drapo.nl/a005b7a1-562a-5d71-83c2-b26dd96dfae6"]
}
}
{
creator: {
in: ["https://id.drapo.nl/a005b7a1-562a-5d71-83c2-b26dd96dfae6"]
}
}
]
}
) {
pagination {
total
}
items {
id
name {
value
}
about {
id
}
material {
id
}
}
}
} Run queryYou need not know what kind of thing the IRI names. Every filter takes [IRI!], so a term IRI under creator is a valid criterion that matches nothing – a wrong guess costs recall of zero, not an error. Repeat per collection, aliased into one request, to cover objects of every type.
To show through which field the match ran, either ask for the reference fields on the items and compare them to the IRI you filtered on (as above), or give each field its own aliased sub-query with perPage: 0 – then the field is the response key and you get a count per relation.
Caveats
- Which collection a field points at is a naming convention.
material: TermFilterholds term IRIs, but nothing in the schema linksTermFilterto thetermscollection – you need that only to click through to the referenced object’s own record, since a reference already carries itslabel. Strip theFiltersuffix and look the rest up among the collections’ item types –Term→terms, and that half is introspected – which resolves all eight today. Assert it at boot, so a rename fails loudly instead of pointing a click-through at nothing. - Introspection must stay enabled. It is on the published image – the playground runs on it – and there is no other route to the field list.
inis the whole vocabulary for IRIs: set membership, no negation; the disjunction isor.