Query the data

Our GraphQL endpoint tool allows you to use GraphQL to directly query the data behind the Our Heritage, Our Stories community collections.

If you're not familiar with GraphQL we recommend you use our search instead, or read on to learn more about how it works.

GraphQL is a query language that can be used to request specific data from a database. Users can form requests using the GraphQL language via a GraphQL server, which carries out the request and returns the data in a response.

GraphQL gives you the power to ask for exactly what you need and nothing more. For example, a user might make a request to only see data from a database containing a specific location label. Once the request is successfully made, the response will show only data relating to that location.

Our in-browser GraphQL endpoint allows you to query the Our Heritage, Our Stories database using current GraphQL query language. You can ask for the specific data you require using available fields and query parameters, which are outlined on the endpoint.

Take a look at the examples below, or you can learn more about structuring a query on graphql.org.

Let's start with a basic query and progressively add more elements to explore its capabilities.

Querying by field

Our endpoint uses the 'metadataByQuery' field to fetch data. Here's a simple query:

{
  metadataByQuery(field: "format:Glass Negative") {
    admin_ID
    format
  }
}

This query searches for items with the format "Glass Negative" and returns their 'admin_ID' and 'format'. The 'field' argument specifies your search criteria, while the fields inside the curly braces '{ }' determine what data you'll receive.

Customising fields

You can add or remove fields from the query to get exactly the information you need. For example, if you only need the title and date:

{
  metadataByQuery(field: "format:Glass Negative") {
    title
    date
  }
}

More information about the fields in our schema is available in the documents section of the GraphiQL interface, which can be accessed by clicking the book icon in the top left of the page. Some fields might be empty for certain items, so it's okay to request more fields than might be available.

Number of results returned

As standard, our endpoint will show up to 15 results for your query and list the number of results at the end of the response like so:

"stats": {
      "total": 1,
      "results": 1,
      "errors": 0,
      "providers": 1,
      "latency": 16
}

To increase the number of results shown you can add an argument such as '(size:50)' to your query as below:

{
  metadataByQuery(size:50 field: "location_named_entity:*Wycombe") {
    admin_ID
    date
    location_named_entity {
      value
      url
    }
  }
}

Adding filters

To refine your search, you can add filters. Let's modify our field query above to include only items dated before 1950:

{
  metadataByQuery(field: "format:Glass Negative" filter: "date: <1950") {
    admin_ID
    date
  }
}

The 'filter' argument allows you to apply additional conditions to your search. In this case, we're filtering for items with a date earlier than 1950.

Another useful filter is to refine your search to items from a single community archive. In this query we're filtering for items from the Sharing Wycombe’s Old Photographs which includes format information:

{
  metadataByQuery(filter:"community_archive_ID:Sharing Wycombe's Old Photographs" field:"format:*") {
    admin_ID 
    format
    community_archive_ID{
      title
    }
  }
}

The possible community archives to filter by are: CAIN Archive - Conflict and Politics in Northern Ireland, People's Collection Wales, Milton Keynes City Discovery Centre, Morrab Photo Archive, Sharing Wycombe's Old Photographs, and Surrey History Centre.

Working with named entities

Our system supports named entities, which are structured data fields. Let's query for items tagged with Edinburgh:

{
  metadataByQuery(field: "location_named_entity:Edinburgh" filter: "date: <1950") {
    admin_ID
    date
    location_named_entity {
      value
      url
    }
  }
}

Here, we're searching for items with Edinburgh in the 'location_named_entity' field. Notice how we can request nested data for named entities, such as 'value' and 'url'.

The OHOS project has named entities in the categories person, location, and organisation. By swapping out the word in the query field you can query the data on each of these, or look for items tagged with the location Edinburgh but that also have the person 'Elizabeth II':

{
  metadataByQuery(filter: "location_named_entity:Edinburgh;person_named_entity:Elizabeth II") {
		admin_ID
    location_named_entity {
      value
      url
    }
    person_named_entity {
      value
      url
    }
  }
}

Querying by item ID

When you know the specific ID of an item you're interested in, you can use the 'metadataByQuery(ids: ...)' structure. This allows for direct, efficient retrieval of item details.

The below query fetches all possible fields in the OHOS project for the item with ID "pcw-32257":

{
  metadataByQuery(ids: "pcw-32257") {
    title
    place_of_deposit
    level
    rights
    community_archive
    location
    date
    colour
    condition
    latitude
    longitude
    copies
    publisher
    rights_holder
    licence
    location_hierarchy
    provenance
  }
}

Multiple IDs:

You can query multiple items by providing an array of IDs. You will need to structure this argument like this:

metadataByQuery(ids: ["pcw-32257", "pcw-32258"])

• Start simple and gradually add complexity.
• Use the 'field' argument for your primary search criteria.
• Refine results with the 'filter' argument.
• For structured data like named entities, specify the subfields you want.
• Remember, GraphQL is flexible. Experiment with different combinations of fields and filters to get exactly the data you require.

Missing curly braces or errors

If you encounter syntax errors, check for missing or mismatched curly braces '{}' and parentheses '()'. Ensure that all fields and arguments are correctly spelled and formatted.

No results returned

Double-check your 'field' and 'filter' values to make sure they match the data in your database. Adjust the 'size' parameter if you're not seeing as many results as expected.

Unexpected data

If the data returned isn't what you expected, review the fields requested and ensure they align with your needs. Use the GraphiQL interface to explore available fields and their structures.