Documentation Center

GraphQL requests to search for facets

Perform a facets query within your search query to perform a search for facets, possibly across taxonomy providers.

In a facets query, you can specify:
  • the connector ID to indicate the taxonomy provider to connect to
  • the scheme title to identify the actual content scheme you are querying

For each of these, use the first parameter to specify the maximum number of results to show, and the language parameter to specify in which language you are querying.

For example, the following query retrieves the first 3 facets in any concept scheme that contains the string "sports":
{
  search(
    facets: {
      concepts: [
        {
          schemeTitle: "sports", 
          first: 3, 
          language: "english"
        }
      ]
    }
  ) 
  {
    facets(language: "english") {
      __typename
      ... on ConceptFacet {
        connectorId
        uri
        title
        concepts {
          label
          id
          count
        }
      }
    }
  }
}
Here's a possible response to this query: facets are found in three different concept schemes:
{
  "data": {
    "search": {
      "facets": [
        {
          "__typename": "ConceptFacet",
          "connectorId": "events",
          "uri": "localhost_udpautotests_31",
          "title": "sports events",
          "concepts": [
            {
              "label": "Formula 1 Zandvoort",
              "id": "localhost_udpautotests_32",
              "count": 1
            },
            {
              "label": "Wimbledon Grand Slam",
              "id": "localhost_udpautotests_33",
              "count": 1
            }
          ]
        },
        {
          "__typename": "ConceptFacet",
          "connectorId": "organizations",
          "uri": "localhost_udpautotests_21",
          "title": "sports associations",
          "concepts": [
            {
              "label": "UEFA",
              "id": "localhost_udpautotests_42",
              "count": 1
            },
            {
              "label": "WNBA",
              "id": "localhost_udpautotests_53",
              "count": 1
            }
          ]
        },
        {
          "__typename": "ConceptFacet",
          "connectorId": "people",
          "uri": "localhost_udpautotests_10",
          "title": "sports people",
          "concepts": [
            {
              "label": "Martina Navratilova",
              "id": "localhost_udpautotests_11",
              "count": 4
            },
            {
              "label": "Diego Maradona",
              "id": "localhost_udpautotests_15",
              "count": 3
            },
            {
              "label": "Simone Biles",
              "id": "localhost_udpautotests_17",
              "count": 1
            }
          ]
        }
      ]
    }
  }
}
This second example shows how including a results section in your facets query will yield an error, as this kind of query only returns facets, not actual content items:
{
  search(
    facets: {
      concepts: [
        {
          connectorId: "cars", 
          first: 4, 
          language: "english"
        },
        {
          schemeTitle: "teams", 
          first: 3, 
          language: "french"
        }
      ]
    }
  )
  {
    facets(language: "english") {
      __typename
      ... on ConceptFacet {
        connectorId
        uri
        title
        concepts {
          label
          id
          count
        }
      }
    }
    results {
      edges {
        node {
          search {
            id
            rawLanguageTitle
            locale
          }
        }
      }
    }
  }
}
The response to this query has results set to null and includes an error message:
{
  "data": {
    "search": {
      "facets": [
        {
          "__typename": "ConceptFacet",
          "connectorId": "teams",
          "uri": "localhost_udpautotests_31",
          "title": "Formula 1 Teams",
          "concepts": [
            {
              "label": "UK",
              "id": "localhost_udpautotests_32",
              "count": 1
            },
            {
              "label": "Manchester",
              "id": "localhost_udpautotests_33",
              "count": 1
            }
          ]
        },
        {
          "__typename": "ConceptFacet",
          "connectorId": "cars",
          "uri": "localhost_udpautotests_10",
          "title": "Compact Cars",
          "concepts": [
            {
              "label": "Morris",
              "id": "localhost_udpautotests_11",
              "count": 4
            },
            {
              "label": "Minor",
              "id": "localhost_udpautotests_15",
              "count": 3
            },
            {
              "label": "Golf",
              "id": "localhost_udpautotests_67",
              "count": 2
            },
            {
              "label": "Ibiza",
              "id": "localhost_udpautotests_68",
              "count": 2
            }
          ]
        }
      ],
      "results": null
    }
  },
  "errors": [
    {
      "message": "Exception while fetching data (/search/results) : java.lang.UnsupportedOperationException: Search query must have 'criteria' or 'rawCriteria'.",
      "path": [
        "search",
        "results"
      ],
      "locations": [
        {
          "line": 17,
          "column": 9,
          "sourceName": null
        }
      ],
      "extensions": null,
      "errorType": "DataFetchingException"
    }
  ]
}