RelFinder: how to use it

RelFinder answers one question: how are these things connected? Choose two or more things, such as people, companies, places or pieces of land, and say how many links may lie between them. RelFinder then finds every path that joins them in a knowledge graph and draws the paths as a picture you can explore. You can then filter the picture by the kind of link, the kind of thing, the length of the path and where the facts came from.

It searches up to five public SPARQL endpoints, such as DBpedia and Wikidata, and data of your own that you load into the page, all at once and in one picture. Your own data is searched inside your browser by HOLOS, a triplestore compiled to WebAssembly, so it never leaves your machine.

Contents

1. Getting started
2. Choosing what to relate
3. How far to look
4. Reading the picture
5. Filtering
6. Sources: endpoints and your own data
7. Keeping, sharing and repeating a search
8. Speed
9. Where your data goes
10. Credits and references

1. Getting started

The quickest way in is an example. Open Examples on the Find tab and choose Who owns Stone Court?. It loads a small dataset drawn from George Eliot's novel Middlemarch and asks how Will Ladislaw, Mary Garth and the Stone Court estate are connected. The answer runs through two wills, a sale, a banker's first marriage and a blackmailer. It needs no network: everything happens in your browser, and it takes a fraction of a second.

The Bookshop Trail example runs a search over the knowledge graph shared by the Semantechs SPARQL, SHACL and Ontology courses: invented bookshops in real British towns, with their authors, books, events and stock. The example fetches the data from the course repository on GitHub and asks how two authors, Ines Calloway and Agnes Varden, connect to the Ex Libris bookshop. The search itself runs in your browser.

What you're looking at

• The left panel has three tabs:
  • Find: the things to relate, the search settings, the filters and details of whatever you've clicked;
  • Sources: where RelFinder looks;
  • Log: every query sent, and how it went.
  Drag the bar between the panel and the picture to make the panel wider or narrower.
• The picture fills the rest. The things you asked about are the blue boxes, and everything RelFinder found between them grows around them as answers arrive.
• The status box, top right, says what is happening: Searching for relations, Fetching labels and classes or Idle. It also shows how many paths were found and how long the search took. Click it to open the log.

2. Choosing what to relate

Type a name into the first box. After two letters and a short pause, suggestions arrive from every source that is switched on. A coloured dot shows which source each one came from. Pick one with the mouse, or with the arrow keys and Enter. Under the box you'll see the identifier (IRI) of the thing you chose.

• Already know the identifier? Paste it: a full IRI such as http://dbpedia.org/resource/Berlin, or a short form such as dbr:Berlin, wd:Q42 or mm:StoneCourt.
• More than two. + Add input adds another box, up to ten. RelFinder searches between every pair, so three inputs mean three searches. The Connectivity filter (section 5) then tells you which resources link all of them.
• The same thing twice: its ego network. Give one thing in two boxes and RelFinder shows its ego network, and a note under the second box says so. That is everything the thing is the subject of: every resource it links to, and its values, such as dates, numbers and names in your language. It also shows the links among those neighbours, and from them back to it. Its name isn't repeated as a separate box, because it's already on the thing's own box. With other inputs alongside, say Ines Calloway twice and Ex Libris once, you get the paths between the different inputs as well. Neighbours in an ego network, under Search settings, sets how many neighbours are fetched from each source; 100 by default. You can also double-click any thing in the picture to add its ego network (section 4).
• Typed a name but didn't pick? When you press Find relations, a name that exactly matches one suggestion is taken. Otherwise the box turns red and asks you to choose.

Where the suggestions come from depends on the source. For DBpedia they come from Wikipedia's title search, because DBpedia's resources are named after Wikipedia articles. For Wikidata they come from Wikidata's own search. For your own data, RelFinder searches an index of names it builds when the data is loaded.

3. How far to look

Maximum links between inputs is the slider under the boxes. One link means "directly connected". Three means up to two things in between. The line beneath the slider says how many queries the search will send. Each extra link adds more, and long paths can be slow on busy public endpoints, so start short and lengthen if you need to.

Search settings

• Path shapes. Links have a direction: Fred is assistant to Caleb, not the other way round. The original RelFinder only looked for paths whose direction changes at most once. For example, both people point at the same company, or one points along a chain to the other. That is the default here. Every direction pattern also finds paths that double back more than once. The Middlemarch example needs it: Will Ladislaw is the child of Sarah, who is the child of Mrs Dunkirk, whom Bulstrode married, and Bulstrode owns Stone Court. With that switched off, the money trail never appears. It costs more queries from three links up.
• Results per query is the most paths of one shape to fetch from one source; 20 by default. The original used 10.
• Avoid cycles stops a path passing through the same thing twice, or back through one of your inputs. Leave it on.
• Let paths meet at a shared value lets two things connect through a shared date, number or name. That is usually a coincidence, so it is off by default.
• Hide new link types after … paths. This is the original's guard against clutter. Once the picture holds this many paths, any link type or length that turns up for the first time starts hidden. A notice under the status box offers to show them all. Set it to 0 to switch it off.
• Use cached answers. Answers from endpoints are kept in your browser for a week, so a repeated search returns almost at once (section 8).
• Never follow. This lists link types left out of every search, on every source. It fills from exclude on the Link tab, from a link's ignore= (section 7), and from the Bookshop Trail example, which leaves out geometry and vocabulary links. Click × to follow a link type again.
• Never pass through. This lists anything you've excluded from searches (section 4). Click × to allow it again.

Press Find relations to start, or Enter in any box. While a search runs, the button becomes Stop.

4. Reading the picture

• Your inputs are the blue boxes, pinned round an oval as in the original.
• Things found are the grey boxes. A name in grey text is a first guess taken from the identifier; it darkens when the real label arrives.
• Values, such as a date, a number or a yes/no, appear in an ego network as pale boxes with dashed borders. They are facts about a thing rather than things themselves.
• Links are the lines, each with its own small label box, and the arrow points the way the fact is stated. "Mary Garth → refused to burn → Featherstone's last will" reads along the arrows.
• Coloured dots inside a box, shown when more than one source is in use, say which sources found it, in the colours set on the Sources tab.
• New things fade in beside what they connect to, so the picture grows rather than jumps. Once everything has settled, the view fits itself to the window, unless you have moved it yourself.

Getting around

• Click a found thing to select it. Every path through it turns red, and its details appear at the bottom of the Find tab. Click it again, or press Esc, to clear the selection.
• Click a link label to see every link between those two things.
• Double-click a thing to add its ego network to the picture: everything it links to, and the links among those (section 2). What is already there stays. It works for things found along the way as well as for your inputs, and the info panel's Show its neighbours button does the same.
• Drag a box to move it. It then stays where you put it, marked by a small dot in its corner. Press P to let it go, or Re-layout to let everything go.
• Scroll to zoom, and drag the background to move around. When you zoom far out, labels shrink to dots.
• Keys, once you've clicked in the picture:
  • F fits the picture to the window;
  • Delete or H hides the selected thing;
  • P pins or unpins it.

The toolbar

• Fit and Re-layout. Re-layout lets go of everything you've pinned and arranges the picture afresh.
• Labels shows or hides the link labels.
• Group parallel links shows one label per pair of things, such as "child of +1", where there are several links between them. The original did the same.
• PNG saves the picture. Triples saves the links you can see as N-Triples, which the Turtle Editor Viewer can open.

Details of a selected thing

The panel shows:

• its name;
• its identifier, which links to the page it names;
• its class;
• how many of your inputs it connects, and how many paths pass through it;
• which sources found it;
• any equivalent identifiers in other sources.

RelFinder then fetches a description, a picture and other values where the source has them. Three buttons act on it:

• Hide removes it and every path through it from the picture.
• Add as input makes it one of the things to relate. Tick add to the graph before searching again to keep what you already have.
• Exclude from search hides it, and tells later searches never to pass through it. Use this for "hub" things that connect everything to everything, such as a country or a very general category.

5. Filtering

Once a search has found something, the Filter by tables appear. They are the original's four tabs plus one new one:

• Length: how many links a path has. Ego networks have a row of their own, ego network (neighbours), so they can be shown or hidden in one go.
• Class: what kind of thing was found, such as Person, Estate or Will. Where a source says something is a Banker, a Person and an Agent, only the most specific is used.
• Link: the kinds of link, such as "owns" or "child of". Two link types with the same name from different vocabularies show their prefix, as in "city (dbo)" and "city (dbp)".
• Connectivity: how many of your inputs a found thing is connected to. With three inputs, the things that connect all three are often the interesting ones. Things added by double-clicking a found thing connect to no input, and are counted under no input.
• Source: which endpoint, or your own data, a path was found in.

Each row works the same way:

• The checkbox shows or hides everything that depends on that row. Untick "located in" and every path that uses "located in" disappears. Things left with no visible path go with it.
• num shows how many are visible against how many were found. It counts paths for Length and Source, links for Link, and things for Class and Connectivity.
• Click the row to tint the matching parts of the picture pale green. Click again to clear the tint.
• only, which appears as you move over a row, shows that row alone.
• exclude, on the Link tab, also leaves that link type out of future searches.
• Show all / Hide all works on the whole tab. A tab with hidden rows carries an orange dot.

A path is shown only when its length, every link on it and every thing along it are all shown. For connectivity, it is judged by the best-connected thing on it: a path is hidden if the highest connectivity level among its things is hidden. Both rules are the original's.

6. Sources: endpoints and your own data

Your own data (the local store)

On the Sources tab you can load your own RDF in three ways: choose files or drop them on the box; give the address of a file; or paste Turtle.

• Formats: Turtle, N-Triples, N-Quads, TriG, RDF/XML and N3, also gzipped (.gz).
• Files on GitHub: paste the address of the file's page, such as https://github.com/pwin/SPARQL_Course/blob/main/data/bookshop-trail-1.1.ttl. It is fetched from GitHub's raw-file server, which allows it. A file from any other server loads only if that server allows requests from other web pages (CORS).
• Where it's searched: inside your browser, by HOLOS compiled to WebAssembly. Loading a few hundred thousand triples takes about a second. Searching them is usually quicker than a single request to a public endpoint.
• What's indexed: the names it can suggest when you type are indexed as part of the load.
• Losing it: the store lives in the page, so reloading or closing the page empties it. Empty the store does the same on purpose.

SPARQL endpoints

Up to five, each with:

• a tick box to switch it on or off;
• a colour;
• a Test button, which sends one small query and reports how long the answer took, or why it failed.

Add endpoint starts from a preset:

• DBpedia. It leaves out links that join almost everything, such as Wikipedia's page links, categories and types.
• Wikidata. It follows direct statements only, and leaves out "instance of" and "subclass of".
• Any SPARQL endpoint.

Settings on each endpoint controls:

• how requests are sent, how many at once, and how long to wait;
• which label language to prefer;
• how names are suggested;
• which link types to ignore, or to keep to;
• which properties hold names, types and subclasses;
• which namespaces count as classes.

Several sources in one search

Every switched-on source is searched, and the results are merged into one picture: a path found twice is kept once. If you chose an input from DBpedia, Wikidata knows it by a different identifier. RelFinder asks both sources for an owl:sameAs link and searches Wikidata for the matching item. The two then show as one box. If no match is found, that source is skipped for that input, and a note says so.

If an endpoint won't answer

RelFinder asks endpoints directly from your browser, so an endpoint has to allow requests from other web pages (CORS). DBpedia and Wikidata do. If the Test button reports that the request failed, that is the usual reason. A server administrator can fix it with a reverse proxy in front of the endpoint. Busy endpoints sometimes fail or time out. RelFinder asks again a couple of times before giving up, and the Log tab shows anything that still failed, with the query it sent and a button to copy it.

7. Keeping, sharing and repeating a search

• Add to the graph. Tick this before Find relations and the new results join the picture rather than replacing it, as the original did when you declined to clear.
• Copy link copies an address that repeats the search: the inputs, the endpoints, any data loaded from a web address, the maximum links, the path shapes and the link types left out. Anyone who opens it gets the same search, even in a browser that has never used RelFinder. Data loaded from files on your own computer can't travel in a link, and RelFinder says so when you copy.
• Save what you found with the PNG and Triples buttons (section 4).

Links that load data and start a search

You can write the address yourself, to hand someone a dataset and a question in one link. Add these to the page address:

• ?data=<url>: load an RDF file into the local store. You can repeat it to load several files. dot= works too, as in the Turtle Editor Viewer, and so do ttl=, rdf= and file=. A GitHub page address is turned into the raw file's address.
• &format=turtle: the file's format, if its name doesn't make it clear. The others are ntriples, nquads, trig, rdfxml and n3.
• &t=<iri>: an input; repeat it for each. A short form such as mm:StoneCourt or dbr:Berlin works. To give a name, write <iri>~<name>; without one, RelFinder takes the name from the data. input= works too.
• &endpoint=<url>: a SPARQL endpoint to search; repeatable, up to five. Add ~<name> to name it. DBpedia and Wikidata get their usual settings.
• &len=3: the most links between inputs, 1 to 6.
• &mode=all: every direction pattern. The default is relfinder, the original's shapes.
• &limit=50: results per query.
• &ignore=<iri>: a link type never to follow; repeatable.
• &ego=<iri>: show that thing's ego network. It is the same as giving it twice with t=. &egolimit=50 sets how many neighbours to fetch.
• &run=0: set everything up but don't search yet. With two or more inputs, the search otherwise starts as soon as the data has loaded.
• ?example=bookshop-trail or ?example=middlemarch: run a built-in example.

When a link names data or endpoints, only those are searched. Your other sources stay set up, but are switched off for that search. Remember to URL-encode addresses inside the link, especially their # and & characters.

For example, this link loads the SPARQL course's graph from GitHub and asks how the authors Rhona Blackwood and Iolo Vaughan connect to The Inkwell bookshop, within four links:

?data=https://raw.githubusercontent.com/pwin/SPARQL_Course/main/data/bookshop-trail-1.1.ttl&t=…author-rhona-blackwood&t=…author-iolo-vaughan&t=…shop-inkwell&len=4&mode=all&ignore=…

Any public RDF file works the same way. A file the Turtle Editor Viewer can open with ?dot= can be opened here by the same address.

8. Speed

Searching your own data is fast. In tests, 90 path queries over the Middlemarch example took a fifth of a second. A graph of 300,000 triples answered 42 path queries in a quarter of a second.

Public endpoints are slower, and they vary. The same query to DBpedia took under a second one minute and many seconds the next. RelFinder makes the most of them:

• it sends the shortest paths first, so the first answers appear early;
• it asks each endpoint a few things at a time, so one slow source holds up only itself;
• it fetches names in batches;
• it remembers answers, so the same search repeated in the same browser finishes in a moment.

If a search drags:

• lower the maximum links;
• leave every direction pattern off;
• exclude hub things and link types that connect everything;
• press Stop; everything found so far stays.

9. Where your data goes

• Your own data never leaves the browser. Files, addresses and pasted text are read and searched inside the page.
• A link can name a file to load. ?data=https://… makes your browser fetch whatever address the link names, and endpoint= makes it query that endpoint. That is the point of such links, but treat one like any other link from someone you don't know.
• Searches go to the endpoints you switch on, and nowhere else. The queries contain the identifiers of your inputs and of what was found.
• Typing into an input box sends what you've typed to the suggestion service of each switched-on source: Wikipedia's search for DBpedia, Wikidata's search for Wikidata, or the endpoint itself.
• Clicking a thing asks its source for a description, and may load a picture from wherever the source says it lives, such as Wikimedia Commons.
• Stored in your browser, and only there: your sources and settings, and a week of cached answers. Clear the cache on the Sources tab empties the cache. There are no cookies and no account, and nothing is sent to Semantechs.

10. Credits and references

RelFinder was conceived and built by Philipp Heim, Sebastian Hellmann, Jens Lehmann, Steffen Lohmann and Timo Stegemann. Its interface was described by Steffen Lohmann, Philipp Heim, Timo Stegemann and Jürgen Ziegler, and its way of searching for connections comes from the DBpedia Relationship Finder of Jens Lehmann, Jörg Schüppel and Sören Auer. The original source code is published by the Visual Data Web group at github.com/VisualDataWeb/RelFinder, under the GNU GPL version 3.

This version was written anew for the web by Semantechs. It reuses the authors' ideas and design, but none of their code, which was ActionScript for Adobe Flash. Any faults in it are ours, not theirs. If you use RelFinder in your work, please cite the original papers:

1. Lehmann, J., Schüppel, J. and Auer, S. (2007). Discovering Unknown Connections – the DBpedia Relationship Finder. In Proceedings of the 1st Conference on Social Semantic Web (CSSW 2007), Lecture Notes in Informatics P-113, pp. 99–109. GI Digital Library.
2. Heim, P., Hellmann, S., Lehmann, J., Lohmann, S. and Stegemann, T. (2009). RelFinder: Revealing Relationships in RDF Knowledge Bases. In Semantic Multimedia: 4th International Conference on Semantic and Digital Media Technologies (SAMT 2009), Lecture Notes in Computer Science 5887, pp. 182–187. Springer. doi:10.1007/978-3-642-10543-2_21.
3. Lohmann, S., Heim, P., Stegemann, T. and Ziegler, J. (2010). The RelFinder User Interface: Interactive Exploration of Relationships between Objects of Interest. In Proceedings of the 15th International Conference on Intelligent User Interfaces (IUI '10), pp. 421–422. ACM. doi:10.1145/1719970.1720052; also on ResearchGate.
4. Heim, P., Lohmann, S. and Stegemann, T. (2010). Interactive Relationship Discovery via the Semantic Web. In The Semantic Web: Research and Applications (ESWC 2010), Lecture Notes in Computer Science 6088, pp. 303–317. Springer. doi:10.1007/978-3-642-13486-9_21.

Also built on

• HOLOS, a triplestore and SPARQL 1.2 engine, here as its WebAssembly build holos-wasm. It also runs the Turtle Editor Viewer.
• d3-force for the layout, and React and Vite for the page.
• Middlemarch by George Eliot (1871–72), the public-domain novel behind the example data. The facts are the plot's, simplified.