Introduction
Eqlat puts a visual query builder on top of the projects you deploy from Agrafe. Pick concepts and the relations between them; Eqlat writes the SPARQL, runs it against the deployment and shows the answers in a table.
You can query your own deployments with their token, and the deployments of public projects with no account at all.
The Dolfin language has its own documentation at www.dolfin.fr/docs. Nothing here repeats it.
What is covered
- Signing in with your Agrafe account.
- Projects: your deployments, and public projects.
- Connecting to a deployment: the deployment token.
- Building a query: the visual query builder.
- The SPARQL editor: read and edit the generated query.
- Results: the results table.
- The demo: try the builder on DBpedia.
- Working alongside Agrafe: deployments, tokens and the other apps.
First steps
- Deploy your project in Agrafe and copy its token.
- Press Continue with Agrafe. See Signing in.
- Pick a deployment under Your Deployments and enter its token.
- Choose a concept in the builder, add a relation, and press the play button.
Conventions
- Deployment: a published version of an Agrafe project, with its own id, tokens and data.
- Token: the bearer token Agrafe issues for a deployment (it starts with
dlf_live_). - Menu and button names are written exactly as they appear in the app.
Signing in
Eqlat has no accounts of its own: press Continue with Agrafe and sign in with your Agrafe account. No account? Follow Create one. Just looking? Browse public projects needs no account (see Public projects).
Once signed in you land on the home page, with the Connect to a Deployment form and Your Deployments. It is the only page that needs a sign-in: opening it signed out sends you to the sign-in page.
Your session lasts 30 days from your last visit and renews on its own. Sign out, in the top bar, ends the Eqlat session only, not your Agrafe one, and brings you back to the sign-in page.
Signing in is not enough to query
Signing in lets Eqlat list your deployments. Querying one also needs its deployment token, which you get from Agrafe. See Connecting to a deployment. Public projects need neither.
Sign-in errors
| Message | What it means |
|---|---|
| Sign-in with Agrafe failed. Please try again. | The sign-in did not complete. Retry. |
| Could not reach Agrafe. Please try again in a moment. | Agrafe is down or restarting. |
| Your sign-in session expired. Please try again. | You took too long on the Agrafe approval screen. |
| Sign-in error: … | Another error reported by Agrafe. |
Projects
Your Deployments
Your Deployments, on the home page, lists your Agrafe deployments, grouped by project. Each group is headed by the project’s name and lists its deployments newest first. A card shows the project name, the number of schema and data triples, and the date of the deployment. Click a card to open its query page; Eqlat asks for the deployment’s token the first time (see Connecting to a deployment).
Deployments whose project is not one of yours, or that Agrafe does not tie to a project, are listed last under Other deployments.
The Sort control orders the groups: Manual (your Agrafe order), Recently opened or Recently modified. The choice lasts until you leave the page.
Eqlat cannot deploy a project: do that in Agrafe. No deployments found in Agrafe. Deploy a dolfin file first. means there is nothing to show yet.
Public projects
Browse public projects, on the sign-in page, opens Public Projects: the projects their owners made public in Agrafe, each with its owner (by …). No sign-in is needed.
Click a project to see its Deployments, one card per deployment with its version (v2), its schema and data triple counts and its date. Click a card to open the query builder on it straight away: a public project needs no token.
← Public projects, in the top bar, goes back to the list. No public projects yet. and This project has no deployments. mean there is nothing to show.
Connecting to a deployment
A deployment’s data is protected by its token, issued by Agrafe when you deploy (see Deployments in the Agrafe docs). Eqlat asks for it before showing the query builder.
From the home page
Connect to a Deployment, at the top of the home page, takes a Deployment ID and a Token. Fill both and press Connect to open the deployment’s query page. Use it for a deployment that is not in Your Deployments, for example one someone gave you the id and token of.
On the query page
Opening a deployment from Your Deployments shows Enter your deployment token to query this dataset. Paste the token and press Connect. The button reads Verifying… while Eqlat checks the token against the deployment.
If the token is accepted, the query builder appears. If not, you stay on the form with one of these messages:
| Message | What it means |
|---|---|
| Invalid or unauthorized token for this deployment. | The token is wrong, revoked, or belongs to another deployment. |
| Could not reach the endpoint: … | Agrafe did not answer. |
Remembered tokens
An accepted token is kept in your browser, for that deployment only. Next time, the query page checks it again and opens the builder directly. A token that no longer works is forgotten and the form comes back.
The bar above the builder shows Deployment: and the deployment id. Disconnect forgets the token in this browser and reloads the page, back to the token form.
Public projects have no token form and no Disconnect bar: see Public projects.
Building a query
Once connected, the query page shows three areas, top to bottom: the visual query builder, the SPARQL editor and the results.
The builder is Sparnatural. Its choices come from the deployment itself: Agrafe describes the deployed schema, its concepts and the properties between them, and Eqlat hands that description to the builder. What you can pick is exactly what the project declares.
Writing a query by clicking
Start from a concept: the builder lists the concepts of the deployment. Then pick a relation leaving it, and the concept at the other end. Keep chaining to follow the graph further. Labels are shown in English.
Every change rewrites the query in the SPARQL editor below, so you can see what the builder means. Queries are generated with a limit of 100 results.
Running it
Press the builder’s play button. It is disabled while the query runs and comes back when the answer arrives, in the results table. The query only sees the data of this deployment.
The play button runs what is in the SPARQL editor, so a query you edited by hand runs as edited.
Starting over
The builder’s reset button empties the query, the SPARQL editor and the results.
Not covered here
Eqlat does not change how the builder itself behaves. For its finer points, filters and options, see the Sparnatural documentation.
The SPARQL editor
Under the builder, the SPARQL editor shows the query the builder wrote. It updates on every change in the builder.
The builder works on its own names for concepts and relations; before the query reaches the editor, Eqlat replaces them with the real IRIs of the ontology. What you read is the query that is sent.
Editing by hand
The editor is a full SPARQL editor: you can change the query, or write one from scratch. Its own play button runs it, as does the builder’s play button. Either way, the results appear below.
A change in the builder replaces the editor’s content, hand edits included.
Queries are sent to the deployment’s SPARQL endpoint in Agrafe, with your token when the deployment needs one. Agrafe answers SELECT and ASK queries; see SPARQL in the Agrafe docs for what the endpoint sees.
An empty editor runs nothing.
Results
Answers appear in the table under the SPARQL editor, one row per answer and one column per variable. Each new run replaces the table; the builder’s reset button empties it. An error from the endpoint is shown in the same place.
Short names
IRIs in the table are written short, as prefix:name, using, from weakest to strongest:
- common prefixes:
rdf,rdfs,owl,xsd,skos,dcterms,foafandsh; - the prefixes of the deployment: one for each namespace the deployed project names its concepts and properties in;
- the
PREFIXlines of the query itself.
When two of them use the same name, the stronger one wins. An IRI is shortened with the longest matching namespace, and only when what is left is a valid local name; otherwise it is shown in full, in angle brackets.
Hover a short name to see the full IRI; it is also the link target.
Shortening is for display only: sorting, filtering and downloading the table use the full values.
The demo
The Sparnatural Demo page, at /demo, lets you try the query builder without an account, a deployment or a token.
It queries the public DBpedia SPARQL endpoint, with a small fixed choice of concepts: Person, Place and Country. Everything else works as on a real deployment: the SPARQL editor shows the generated query, and the results table shows the answers, shortened with the common prefixes only.
The demo does not touch your Agrafe projects. To query your own data, deploy a project in Agrafe and connect to it.
Working alongside Agrafe
Eqlat reads deployments from Agrafe; Agrafe stays the place where projects are written and deployed.
Deployments and tokens
Everything Eqlat queries is a deployment. In Agrafe:
- Deploy creates a new deployment, with a new id and new tokens. It shows up in Your Deployments, under its project.
- Update recompiles a deployment from the current files. The id, the tokens and the data are kept, so Eqlat keeps working with the token you already gave it.
- Tokens lists a deployment’s tokens; + Token issues a new one, Revoke disables one. A revoked token is refused the next time Eqlat checks it, and the token form comes back.
The query builder’s choices follow the deployed schema: after an Update, reload the query page to see new concepts and properties.
Public projects
A project switched to Public in Agrafe is listed on Eqlat’s Public Projects page, and its deployments can be queried without a token. See Public projects.
Prefixes
The short names in the results use the namespaces of the deployed project, as Agrafe compiled it. After changing them in Agrafe, Update the deployment.
Other apps
The Apps menu in the top bar switches to the other Dolfin apps, including Owlograf, which draws a project as a graph, and Pangloss, which shows it as a glossary.
Feedback and updates
The Feedback tab on the left edge sends a message to the Dolfin team with a screenshot you can crop. When Eqlat is updated while you have it open, a banner offers Reload.