Wikidata:Wikibase GraphQL
|
Wikidata For Developers |
Overview
[edit]Wikibase GraphQL is a GraphQL API for Wikidata. It is a flexible alternative to a few simple Wikidata Query Service (WDQS) use cases, with a strong focus on developer experience, flexibility, and efficient data retrieval.
 | Warning:
The Wikibase GraphQL API is not yet stable. It is under active development, and the schema, functionality, and performance characteristics may change. We are actively collecting feedback and plan to add more functionality throughout the year. |
For development progress and upcoming features, see the Wikibase GraphQL Phabricator workboard
Background
[edit]The Wikibase GraphQL API was developed following an investigation into alternative ways of accessing Wikidata and Wikibase content that reduce load on the Wikidata Query Service (WDQS), improve the developer experience for common read use cases and allow more flexible data retrieval in a single request.
As part of this investigation, a Wikibase GraphQL prototype was built to explore what is technically possible and whether GraphQL would be a good fit for Wikibase data, with promising results and supportive feedback.
The GraphQL API has the following functionality for now:
- Labels of linked entities
- Bulk GET (batch reading Items)
- Search items by statement property and value
Why should I use the Wikibase GraphQL API?
[edit]- One-stop shop: Multiple data needs can be fulfilled from a single API endpoint, such as searching for entities, retrieving statements, and fetching labels or descriptions of linked entities.
- Flexible and expressive: Clients can decide which fields they want, reducing over-fetching and under-fetching of data.
- Excellent tooling: GraphQL comes with mature tooling such as interactive documentation via GraphiQL, strong client libraries (e.g. Apollo Client), and built-in schema introspection.
- Well-suited for linked data: Traversing direct relationships and requesting labels of linked entities is a core strength of GraphQL.
How to use the GraphQL API
[edit]Web-based interactive clients
[edit]The easiest way to explore the Wikibase GraphQL API is from your web browser via interactive GraphQL clients, which provide schema documentation, auto-completion, and immediate feedback.
- GraphiQL: An interactive GraphiQL client is available on doc.wikimedia.org.
- Apollo Sandbox Explorer: A web-based GraphQL explorer provided by Apollo.
Other clients
[edit]The GraphQL API can also be accessed using generic HTTP or GraphQL clients, including Altair, Bruno. Insomnia or Postman. These tools are useful for testing, scripting, and integration into non-JavaScript environments.
You can access the API on Wikidata using the base URL: https://www.wikidata.org/w/api.php?action=wbgraphql&format=json
Refer to the User-Agent policy and global rate limits when using the API.
GraphQL Schema
[edit]The GraphQL type system describes what data can be queried from the API. The collection of those capabilities is referred to as the service’s schema and can be expressed using the Schema Definition Language (SDL). You can find the Wikibase GraphQL schema file in the wikibase code repository or generate it from the GraphQL endpoint using tools such as get-graphql-schema.
Functionality
[edit]Fetching labels of linked entities
[edit]Request labels and/or descriptions of:
- statement properties,
- entities used as statement values.
This allows clients to retrieve human-readable data without issuing many follow-up requests.
Example
[edit]Fetch the English label for Item Q64 (Berlin) and all its statement values for the properties P31 instance of (ItemValue), P18 image (Commons Media File) and P571 inception (Point in time).
| Query | Response |
|---|---|
query exampleQuery_item {
item(id: "Q64") {
label(languageCode: "en")
instance_of: statements(propertyId: "P31") {
value {
... on ItemValue {
id
label(languageCode: "en")
}
}
}
image: statements(propertyId: "P18") {
value {
... on StringValue { content }
}
}
inception: statements(propertyId: "P571") {
value {
... on TimeValue { time }
}
}
}
}
|
{
"data": {
"item": {
"label": "Berlin",
"instance_of": [
{
"value": {
"id": "Q1901835",
"label": "seat of government"
}
},
{
"value": {
"id": "Q200250",
"label": "metropolis"
}
},
...
],
"image": [
{
"value": {
"content": "Cityscape Berlin.jpg"
}
}
],
"inception": [
{
"value": {
"time": "+1244-00-00T00:00:00Z"
}
}
]
}
}
}
|
This example shows the use of aliases to query three different statement fields (instance_of, image and inception) and the use of inline fragments with the spread operator (... on <ValueType>) to access data on the various underlying statement value types.
Retrieving multiple Items at once
[edit]Fetch up to 50 Items in a single request. This is useful for applications that already know a set of Item IDs and want to fetch their data efficiently.
Example
[edit]Fetch Items Q64 (Berlin), Q84 (London) and Q90 (Paris) with their English labels, statement values for the Property P2046 area (Quantity) and their ranks.
| Query | Response |
|---|---|
query itemsById {
itemsById(ids: ["Q64", "Q84", "Q90"]) {
label(languageCode: "en")
area: statements(propertyId: "P2046") {
value {
... on QuantityValue { amount }
}
rank
}
}
}
|
{
"data": {
"itemsById": [
{
"label": "Berlin",
"area": [
{
"value": { "amount": "+891.12" },
"rank": "PREFERRED"
},
{
"value": { "amount": "+891.69" },
"rank": "NORMAL"
}
]
},
{
"label": "London",
"area": [
{
"value": { "amount": "+1572" },
"rank": "NORMAL"
}
]
},
{
"label": "Paris",
"area": [
{
"value": { "amount": "+105" },
"rank": "NORMAL"
}
]
}
]
}
}
|
Searching items by statement property and value
[edit]Find Items that match specific statement property–value pairs, such as:
- “instance of: cat” (Q146)
- “occupation: art model” (Q1630100)
- combinations of multiple conditions using logical AND.
Example
[edit]Find Items with their IDs and English labels, that have property P31 (instance of) with value Q146 (cat) and property P106 (occupation) with value Q1630100 (art model).
| Query | Response |
|---|---|
query searchItems {
searchItems(
query: {
and: [
{ property: "P31", value: "Q146" },
{ property: "P106", value: "Q1630100" }
]
}
) {
edges {
node {
id
label(languageCode: "en")
}
}
}
}
|
{
"data": {
"searchItems": {
"edges": [
{
"node": {
"id": "Q131468628",
"label": "Brünnhilde"
}
}
]
}
}
}
|
Feedback and development
[edit]The Wikibase GraphQL API is under active development, and community feedback is highly encouraged.
We are interested to learn:
- Is the GraphQL API useful for you? Would you use it instead of existing options, like the Wikidata Query Service?
- Is the API easy to understand and use?
- Is any documentation missing?
- Are there any additional features you would find useful?
We provide a range of ways to submit feedback. Feel free to address any of the above questions, bring up other topics or submit bug reports. In order of time commitment from least to most, these include:
- Answer the embedded, single question survey at the top of the page.
- Leave a comment on this page’s discussion page, or +1 someone else’s comment.
- Create a Phabricator ticket with the tag: Wikibase GraphQL
- Sign-up for usability testing: do a short, predefined task using the API while we observe and then ask follow-up questions. No preparation needed and compensation is offered because it’s a researcher directed activity. If you’re interested, sign-up here.