Skip to content

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.

graphql
{
  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 query

For creativeWorks today this yields:

  • 19 filter keys:
    • id and type;
    • references, each by its target’s filter: dataset and isPartOf a DatasetFilter, publisher a PublisherFilter, creator a PersonOrOrganizationFilter, and additionalType, about, material and genre a TermFilter;
    • contentLocation and locationCreated: a CreativeWorkContentLocationFilter and CreativeWorkLocationCreatedFilter, whose in is [IRI!] and whose where takes latitude: { exists };
    • contributor, a filter on one entry, and associatedMedia, whose where also takes thumbnailUrl: { exists };
    • temporalCoverage and sdDatePublished: a DateRange with min and max; dateCreated: a DateRangeOrExists, which adds exists;
    • or and and.
  • Four sort keys: RELEVANCE, NAME, SD_DATE_PUBLISHED, DATE_CREATED.
  • 14 facet fields:
    • an IRIFacet for each reference field that counts only its own values, whose buckets are IRIBuckets (value: IRI!, count, label) beside its totalValues;
    • a ValueFacet of ValueBuckets (value: String!) for type;
    • an object for each field that counts more – contentLocation and locationCreated (buckets, totalValues and latitude { exists }), dateCreated { exists } and associatedMedia { license thumbnailUrl { exists } }, whose exists lists are BooleanBuckets. Substitute another collection’s type name – PersonWhere, PersonSortField, PersonFacets – for the rest.

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:

graphql
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.

graphql
{
  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 query

Join the halves on the filter type name:

js
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.

graphql
{
  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 query

You 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: TermFilter holds term IRIs, but nothing in the schema links TermFilter to the terms collection – you need that only to click through to the referenced object’s own record, since a reference already carries its label. Strip the Filter suffix 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.
  • in is the whole vocabulary for IRIs: set membership, no negation; the disjunction is or.