UsefulQueries

Code for usefulQueries

Documentation: https://www.wikidata.org/wiki/User:Kristbaum/usefulQueries

Adding your own queries

Queries that would be useful to general users can be added as suggestions on GitHub or on Wikidata.

You can add your own query templates to the project by reusing the existing JSON templates in templates/queries.

Steps:

1. Download this repo

2. Install npm

3. Copy one of the existing files from templates/queries and rename it for your new query (keep the .json extension).

4. Edit the file following the template structure described below.

5. Optionally add a link template in templates/links if your query integrates with an external viewer.

6. Rebuild the project assets so the new template becomes available in the UI:

   npm install
   npm run build

7. Copy minified_version.js and upload it to a location like: https://www.wikidata.org/wiki/Special:MyPage/myUsefulQueries.js

8. Replace the link in https://www.wikidata.org/wiki/Special:MyPage/common.js with your version.

Query template structure (templates/queries/*.json)

A query template is a JSON file that describes when a button should appear and what SPARQL query it runs. There are three trigger modes controlled by scope:

scope: "entity" — button appears on every item:

{
  "id": "entityGraph",
  "scope": "entity",
  "template": [
    "#defaultView:Graph",
    "SELECT ?node ?nodeLabel ?childNode ?childNodeLabel WHERE {",
    "  BIND(wd:{itemQid} AS ?node)",
    "  ...",
    "}"
  ],
  "emoji": "🔗",
  "title": "Connections of {itemLabel}"
}

scope: "property" — button appears when the item has a specific property (e.g. P2124 member count):

{
  "id": "membersCount",
  "scope": "property",
  "propertyId": ["P2124"],
  "template": [
    "#defaultView:LineChart",
    "SELECT ?pit ?s_count WHERE {",
    "  wd:{itemQid} p:P2124 ?statement.",
    "  ?statement ps:P2124 ?s_count.",
    "  OPTIONAL { ?statement pq:P585 ?pit. }",
    "}"
  ],
  "emoji": "📊",
  "title": "Members count of {itemLabel} over time"
}

scope: "value" — button appears when the item has a specific property set to a specific value (e.g. occupation = painter):

{
  "id": "artworks",
  "scope": "value",
  "propertyId": ["P106"],
  "valueId": ["Q1028181"],
  "template": [
    "#defaultView:ImageGrid",
    "SELECT ?item ?image WHERE {",
    "  ?item wdt:P170 wd:{itemQid}.",
    "  OPTIONAL { ?item wdt:P18 ?image. }",
    "}",
    "LIMIT 100"
  ],
  "emoji": "🖼️",
  "title": "Artworks by {itemLabel}"
}

The placeholders {itemQid}, {itemLabel}, {valueQid}, and {valueLabel} are replaced at runtime with the current item's data. On value-scope templates, {valueLat} and {valueLon} additionally expose the coordinates of a globe-coordinate value such as P625.

Link template structure (templates/links/*.json)

A link template adds a button that opens an external URL instead of running a SPARQL query. The URL is built from a pattern using the current item's QID.

scope: "property" — link appears when the item has any of the listed properties:

{
  "id": "entitree_family",
  "scope": "property",
  "propertyId": ["P22", "P25", "P26", "P40", "P3373", "P1038", "P3448", "P8810"],
  "urlTemplate": "https://www.entitree.com/en/family_tree/{itemQid}",
  "emoji": "🌳",
  "title": "Family tree on Entitree"
}

scope: "value" — link appears when the item has a specific property set to a specific value:

{
  "id": "scholia",
  "scope": "value",
  "propertyId": ["P106"],
  "valueId": ["Q1650915"],
  "urlTemplate": "https://scholia.toolforge.org/author/{itemQid}",
  "emoji": "📚",
  "title": "Page on Scholia"
}

The {itemQid} placeholder is replaced at runtime with the current item's QID.

Run on another Wikibase

Adapt the settings in settings.json and rebuild using:

npm install
npm run build

Wikibase Cloud / MediaWiki version compatibility: The popup feature relies on CdxPopover from the Codex design system, which is not available on every Wikibase Version. The script detects this at runtime and automatically falls back to opening the query as a plain link in a new tab instead of showing an inline popup.

Custom builds with --custom

For a self-contained variant (e.g. targeting a different Wikibase), you can keep all configuration, templates and output inside a named subfolder using the --custom <Name> flag.

Expected folder layout for a custom build named MyQueries:

MyQueries/
├── settings.json          # Same format as src/settings.json
└── templates/
    ├── queries/           # Query template JSON files
    └── links/             # Link template JSON files

Build command:

node scripts/assemble.mjs --custom MyQueries

The build will read MyQueries/settings.json, load templates from MyQueries/templates/queries/ and MyQueries/templates/links/, and write the output files into the same subfolder:

• MyQueries/usefulMyQueriesQueries.js — readable output
• MyQueries/minified_MyQueries_version.js — minified output for upload

Missing queries/ or links/ subdirectories are silently ignored (treated as empty). The shared source files in src/ are always used, so only settings and templates need to be provided per variant.

Development

sudo apt install npm
npm install # For linting tools
npm run build

# Optional
npm run lint

Todo

• Make it Wikibase agnostic

Example Items

• Artus Wolffort
• University of Marburg