Backlinks
Ask about the data in words, check the plan the assistant proposes, and run it
The assistant is optional and off by default. It is available on instances that enable the web-algebra service and give it a model key — see the setup instructions.
The assistant turns a question or an instruction into a Web-Algebra plan: the queries and writes that answer it, in the order they run. You see the plan before anything runs, and the plan runs as you, so it can read and change only what you can.
Open the assistant
Sign in with your WebID certificate and open a document you have append access to. Click Assistant in the creation bar. A conversation block opens above the bar, with a field to type into. Each click opens another conversation, and a conversation you have not asked anything in is closed with its button or with Escape.
Ask a question
Type a question about the data, or say what to change, and press Enter (Shift+Enter starts a new line). For example, on the Northwind Traders dashboard:
Which five customers ordered the most in 1997?
The assistant knows which document you are on, its dataspace's SPARQL endpoint and the dataspace's ontology, so a question can say "this order" or "these products". It also knows the last few questions in the same conversation and what they returned, so a follow-up such as "chart them by country" refers to the earlier rows.
The first question saves the conversation in the document as a block. A conversation where nothing was asked leaves nothing behind.
Check and run the plan
Screenshot: a plan card in the assistant, with its summary, its operations and the Execute button
The answer comes back as a card holding the plan: a sentence saying what it does, and its operations as rows, each marked as reading, writing, or able to remove content. Each row folds out the plan's XML, so you can read exactly what will run.
Click Execute to run the plan. The rows report as each operation runs, and when the plan is done the card shows what it returned (as a table, a chart or a map, when the plan says which suits the result) and links to the documents it changed. A sentence summing up the result appears at the top of the card, and the rows fold under it.
Screenshot: an answered card, with the answer summing up the result, the result as a table and the steps folded under their count
Two options above the question field change when plans run:
- Execute by default
- On by default. A plan that only reads runs as soon as it arrives. A plan that writes always waits for you to click Execute, whatever this option says, because a write cannot be undone from the card.
- Retry on empty result
- Off by default. When a plan returns nothing or fails, the assistant asks again by itself, telling the plan service what did not work, up to three times. Every attempt is its own card, and turning the option off stops it.
When a plan returns nothing
A query that matches nothing usually means the plan guessed a class or a property wrong. The card offers two ways on:
- Revise asks the same question again, telling the plan service that this plan returned nothing, so it does not propose it again.
- Retry runs the same plan once more, which helps when the failure was temporary.
Rephrasing the question with the names the data uses (the class and property labels shown in the document) also helps.
Come back to a conversation
Every question is saved when its answer has landed, with the plan, what running it reported (the first hundred rows or resources of the result) and how it went. When you open the document again, the conversation is there as you left it, and you can keep asking. Readers who are not signed in, or who do not have append access, see the conversation without a question field.
A conversation is a block like any other: it is deleted the way any block is, and it can be placed in another document as an object block, where it continues in the document it is stored in.
Read more about how the assistant works and how to set it up.