Sparnatural icon indicating copy to clipboard operation
Sparnatural copied to clipboard
Published 1 week ago • verified publisher icon sparna-git

User Story : parameterized queries

Open tfrancart opened this issue 1 year ago • 4 comments

The goal is to create query templates, and indicate which variables in this query template could be choosed by a user. Then users can be proposed with very simple forms containing only these variables to select, without having to redesign the entire query. This opens the possibility to offer multiple simple forms to end-users, using the same value selection widgets as in Sparnatural.

The story is the following:

  1. An administrator creates a Sparnatural query and store it somewhere, probably on a server (see #591). For example "All museums that are located in Any Country, with photo and geo coordinates"
  2. The administrator associates it with "variable bindings" to mark the variables that can be assigned by a user. For example the variable "Museum_2" in our example
  3. This parameterized query is saved somewhere, with a name a description. For example "List museums in a country".
  4. An end-user can select this parameterized query. He is presented with a very simple form containing only one field : "Country".
  5. The end-user selects a Country in the same widget as the original widget in Sparnatural
  6. He runs the query, and gets a list of musuem with photo and geo coordinates.

VocBench actually has this functionnality:

  1. Store query:

image

  1. Create variable binding:

image

  1. Store parametrized query

image

  1. End-user loads the query:

image

  1. End-user is presented with a simple form with only the variable binding to enter:

image

end-user selects a value:

image

  1. End-user runs the query:

image

@antoine37120

tfrancart avatar May 14 '24 14:05 tfrancart

Metaphacts also have something like this when saving queries:

image

tfrancart avatar Jun 24 '24 16:06 tfrancart

I. A new webcomponent

<spar-natural-form
	src="config.ttl"
	query="query.json"
	form="form.json"
/>

II. The form configuration file

form.json :

{
	"bindings": [
		{
			"variable" : "Country_4",
			"node" : {
				"type" : "UserPrompt",
				"name" : {
					"en" : "Country",
					"fr" : "Pays"
				}
			}
		},
		{
			"variable" : "Person_10",
			"node" : {
				"type" : "UserPrompt",
				"name" : {
					"en" : "Author",
					"fr" : "Auteur"
				}
			}
		}
	]	
}

III. The query json file (saved from Sparnatural)

image

query.json:

{
  "distinct": true,
  "variables": [
    {
      "termType": "Variable",
      "value": "Artwork_1"
    },
    {
      "termType": "Variable",
      "value": "Country_4"
    },
    {
      "termType": "Variable",
      "value": "Image_6"
    }
  ],
  "order": null,
  "branches": [
    {
      "line": {
        "s": "Artwork_1",
        "p": "http://ontologies.sparna.fr/sparnatural-demo-dbpedia#displayedAt",
        "o": "Museum_2",
        "sType": "http://ontologies.sparna.fr/sparnatural-demo-dbpedia#Artwork",
        "oType": "http://ontologies.sparna.fr/sparnatural-demo-dbpedia#Museum",
        "values": []
      },
      "children": [
        {
          "line": {
            "s": "Museum_2",
            "p": "http://ontologies.sparna.fr/sparnatural-demo-dbpedia#country",
            "o": "Country_4",
            "sType": "http://ontologies.sparna.fr/sparnatural-demo-dbpedia#Museum",
            "oType": "http://ontologies.sparna.fr/sparnatural-demo-dbpedia#Country",
            "values": []
          },
          "children": []
        }
      ]
    },
    {
      "line": {
        "s": "Artwork_1",
        "p": "http://ontologies.sparna.fr/sparnatural-demo-dbpedia#thumbnail",
        "o": "Image_6",
        "sType": "http://ontologies.sparna.fr/sparnatural-demo-dbpedia#Artwork",
        "oType": "http://ontologies.sparna.fr/sparnatural-demo-dbpedia#Image",
        "values": []
      },
      "children": [],
      "optional": true
    },
    {
      "line": {
        "s": "Artwork_1",
        "p": "http://ontologies.sparna.fr/sparnatural-demo-dbpedia#description",
        "o": "Text_8",
        "sType": "http://ontologies.sparna.fr/sparnatural-demo-dbpedia#Artwork",
        "oType": "http://ontologies.sparna.fr/sparnatural-demo-dbpedia#Text",
        "values": []
      },
      "children": [],
      "optional": true
    },
    {
      "line": {
        "s": "Artwork_1",
        "p": "http://ontologies.sparna.fr/sparnatural-demo-dbpedia#author",
        "o": "Person_10",
        "sType": "http://ontologies.sparna.fr/sparnatural-demo-dbpedia#Artwork",
        "oType": "http://ontologies.sparna.fr/sparnatural-demo-dbpedia#Person",
        "values": []
      },
      "children": [],
      "optional": true
    }
  ]
}

IV The generated form

image

IV The final query

Si l'utilisateur saisi seulement le pays mais pas l'auteur, alors:

  • la valeur du pays est injecté dans la requête
  • le critère d'auteur de la requête est supprimé car :
    • il est mis en optional
    • il n'est pas dans les variables sélectionnées de la requête
    • aucune valeur n'a été positionné pour lui

Requête JSON finale:

{
  "distinct": true,
  "variables": [
    {
      "termType": "Variable",
      "value": "Artwork_1"
    },
    {
      "termType": "Variable",
      "value": "Country_4"
    },
    {
      "termType": "Variable",
      "value": "Image_6"
    }
  ],
  "order": null,
  "branches": [
    {
      "line": {
        "s": "Artwork_1",
        "p": "http://ontologies.sparna.fr/sparnatural-demo-dbpedia#displayedAt",
        "o": "Museum_2",
        "sType": "http://ontologies.sparna.fr/sparnatural-demo-dbpedia#Artwork",
        "oType": "http://ontologies.sparna.fr/sparnatural-demo-dbpedia#Museum",
        "values": []
      },
      "children": [
        {
          "line": {
            "s": "Museum_2",
            "p": "http://ontologies.sparna.fr/sparnatural-demo-dbpedia#country",
            "o": "Country_4",
            "sType": "http://ontologies.sparna.fr/sparnatural-demo-dbpedia#Museum",
            "oType": "http://ontologies.sparna.fr/sparnatural-demo-dbpedia#Country",
            "values": [
            	{
                "label": "France (3987)",
                "rdfTerm": {
                  "type": "uri",
                  "value": "http://fr.dbpedia.org/resource/France"
                }
               }
            ]
          },
          "children": []
        }
      ]
    },
    {
      "line": {
        "s": "Artwork_1",
        "p": "http://ontologies.sparna.fr/sparnatural-demo-dbpedia#thumbnail",
        "o": "Image_6",
        "sType": "http://ontologies.sparna.fr/sparnatural-demo-dbpedia#Artwork",
        "oType": "http://ontologies.sparna.fr/sparnatural-demo-dbpedia#Image",
        "values": []
      },
      "children": [],
      "optional": true
    },
    {
      "line": {
        "s": "Artwork_1",
        "p": "http://ontologies.sparna.fr/sparnatural-demo-dbpedia#description",
        "o": "Text_8",
        "sType": "http://ontologies.sparna.fr/sparnatural-demo-dbpedia#Artwork",
        "oType": "http://ontologies.sparna.fr/sparnatural-demo-dbpedia#Text",
        "values": []
      },
      "children": [],
      "optional": true
    }
  ]
}

V We could use other inputs than user forms

Par exemple pour positionner une variable à la date du jour, ou par un bout de script:

{
	"bindings": [
		{
			"variable" : "Country_1",
			"node" : {
				"type" : "UserPrompt",
				"name" : {
					"en" : "Select a country",
					"fr" : "Sélectionner un pays"
				}
			}
		},
		{
			"variable" : "Date_2",
			"node" : {
				"type" : "DynamicValueProvider",
				"valueProvider" : "TypescriptClassNameOfTheValueProvider"
			}
		}
	]	
}

tfrancart avatar Jul 03 '24 12:07 tfrancart

This would greatly fit our use of sparnatural for the GRACEFUL17 project!

ch-sander avatar Aug 06 '24 16:08 ch-sander

Hopefully this development could be done end of 2024.

tfrancart avatar Aug 07 '24 07:08 tfrancart

@ch-sander this component is now developed, with a facet-like search panel reusing the Sparnatural widgets:

Image

It embeds a hardcoded Sparnatural query in which the selected values are injected (so that e.g. the selected columns are always the same). The user don't see the underlying graph structure.

Documentation here : https://docs.sparnatural.eu/#sparnatural-form

Repository here (but still needs a bit of cleanup in the next few weeks : https://github.com/sparna-git/Sparnatural-form

tfrancart avatar Apr 12 '25 21:04 tfrancart

Great work!

Questions

  • is there a live demo already?
  • the widgets for the form are defined by the SHACL configuration exactly like for the query builder?
  • There's also a multi select to render a VALUES statement?
  • there will be a separate release in the dedicated GitHub repository?

Ideas

  • [ ] maybe predefined filters (or other bindings) that are toggled by a check box in the form
  • [ ] a way to load different form configuration JSON like import for the query builder (maybe exists already)

ch-sander avatar Apr 13 '25 09:04 ch-sander

is there a live demo already?

Not yet, but we will build one

the widgets for the form are defined by the SHACL configuration exactly like for the query builder?

The possible widgets are the same as in Sparnatural. But the form fields are specified in another configuration file. Basically the form takes 3 inputs:

  • the SHACL spec (same as Sparnatural)
  • a query template in the Sparnatural JSON query format
  • the list of fields in the form : each field has a label and is associated to a variable name in the query (see above https://github.com/sparna-git/Sparnatural/issues/592#issuecomment-2206011836, form.json)

There's also a multi select to render a VALUES statement?

Same widgets as in Sparnatural. So, yes.

there will be a separate release in the dedicated GitHub repository?

Separate repo : https://github.com/sparna-git/Sparnatural-form

maybe predefined filters (or other bindings) that are toggled by a check box in the form

Yes. But the query you pass as parameters can contain already fixed values for some criterias

a way to load different form configuration JSON like import for the query builder (maybe exists already)

Hmmm.... what we did is that we configrued multiple forms in the page, each with a different config, and split into different tabs (see previous screenshot)

tfrancart avatar Apr 13 '25 17:04 tfrancart