Extension:VisualData/Queries

Queries edit

VisualData is able to query the data inserted through forms/schemas and to display them in various display formats using the parser functions visualdataquery and visualdataprint. The first is used to display data from multiple articles, and the second the data from a single article, also different from the article where the parser function is placed.

Here is an example of the use of the parser function visualdataqueryquery for displaying name, latitude and longitude of all cities of the state Badakhshan in Afghanistan. (of course the related data have to be inserted in the wiki beforehand, see section Maintenance scripts for more information)

{{#visualdataquery:[[name::Afghanistan]] [[states/name::Badakhshan]]
|schema=Country 
|?states/cities/name
|?states/cities/latitude
|?states/cities/longitude
|format=datatable 
}}

The query uses a Extension:Semantic MediaWiki-like syntax and prints the results using datatables: see here for more information about result formats and templates.

Although VisualData' query engine is currently less extensive than SMW query language it offers two important additional features:

it allows to query hierarchical data, according to the intrinsic recursive nature of json-schema
it allows to have namespaced properties, since each set of properties depends by a specific schema and does not conflict with the names of other schemas

This way it is possible to store also a large amount of data in a single article, using a deeply nested schema (here for instance are stored all states and cities information of the country Afghanistan) and to query your data using the desired depth level (for instance latitude and longitude of each city, or the names of all states).

Conditions edit

The query is the first argument of the parser function visualdataquery and looks as follows:

[[name::Afghanistan]] [[states/name::Badakhshan]]

Each string surrounded by double square brackets represents a query condition, where the string before the double colon represents the property path (called "printout" in the dialect of Visual Data), and the string on the right is the value to be matched.

The following search operators are currently supported:

symbol	meaning
`>`	greater than
`>=`	greater or equal than
`<`	less than
`<=`	less or equal than
`!`	not
`~`	like
`+`	not null

This allows to safely perform standard SQL queries on your set of data. For instance the following condition

[[name::Afghanistan]] [[states/cities/name::B~]]

matches all json data (in our case with schema "contry") with property "name" with value "Afghanistan" and (within such schema) all cities with name starting with "B".

Currently the OR operator between conditions is not supported (except when querying categories) although it may be supported in future versions of the extension.

Specific pages or categories can be inserted in the query in the following way:

[[My Article]][[Category:Category a]][[Category:Category b]]

where the query will search for a page with title "My article" with category "Category a" or "Category b". (note that the logical operator for categories is OR by contrast to AND for other kind of conditions)

Related schema edit

A query is always performed among the properties/values of a given schema, simply using the following parameter:

|schema=[my schema]

Printouts edit

In the specific dialect of VisualData (of course inherited from Semantic MediaWiki), a "printout" is a property path, therefore (technically) a json-pointer without array indexes and json-schema keywords. This way it is possible to easily reference nested property omitting technical details.

The printouts are indicated pre-pending a question mark to the parameter value:

|?states/cities/name
|?states/cities/latitude
|?states/cities/longitude

If no printouts are declared, the query will return all properties (including nested properties) of a given schema.

Playing with printouts and printout templates edit

Both parser functions support the use of non existing printouts that will be rendered as empty columns for the table or datatables format. This is useful when used in conjunction with printout templates in order to render custom content within such columns, like action buttons based on VisualData's forms.

In addition the pagetitle column can be hidden using |pagetitle=false.

(Find out more here)

Format edit

Both the visualdataquery (and the visualdataprint) parser functions expect a format through which print the result. Find out more here.

Parameters edit

Here are the available parameters for the visualdataquery parser function and their default values.

parameter	description	default
`(unnamed parameter)`	one or more conditions
`schema`	the schema to be queried
`separator`	items separator
`values-separator`	values-seperator	`,`
`limit`	limit of the query as in SQL	`100`
`order`	equivalent to 'ORDER BY' in SQL language	e.g. `\|order=population desc`
`offset`	offset of the query as in SQL	`0`
`format`	result printer format	`json`
`template`	template name
`template?[printout]`	template applied to a specific printout, or subitem
`pagetitle`	value of the field containing the article holding the related data. If set to empty (using `pagetitle=`) the entire field will be omitted	`pagetitle`
`pagetitle-name`	name of the field containing the article holding the related data	`pagetitle`
`articleid-name`	name of the field containing the article id holding the related data	`articleid`