View source for SPQL: SPecies Query Language

''SPQL'' is a language used to query the [[Biodiversity_Access | Species Product Discovery Service]]

== SPQL 1.0 ==

<source lang="java">
query: terms (IN identifiers)? (WHERE expressions)? (RETURN returnExpression)?
 
terms: term  (',' term)*

term: words AS (('ScientificName'|'SN') | ('CommonName'|'CN'))

words: word (',' word)*
	
word : STRING

identifiers:  identifier (',' identifier)*
			
identifier: ID
			
expressions: expression (AND expression)*

expression:	(bc=boundCondition | dateCondition)

boundCondition: ('lowerBound' | 'upperBound') IS coordinate
		
dateCondition: ('fromDate' | 'toDate') IS date
		
date: INT '/' INT '/' INT

coordinate: FLOAT ',' FLOAT

returnExpression: '*' (havingExpression)? | 'Occurrence' | 'Taxon'

havingExpression: HAVING 'Occurrence' | 'Taxon'
</source>

== SPQL 2.0 ==

=== Synopsis ===
<code>
 SEARCH BY '''''term''''' [, ...]
       [ IN '''''datasource''''' [, ...] ]
       [ WHERE '''''condition''''' [AND '''''condition'''''] ]
       [ RETURN {PRODUCT | OCCURRENCE | TAXON} ]
       [ HAVING '''''having expression''''' ]
</code>

Where '''''term''''' can be one of:
<code>
 CN ''common name'' [, ...] RESOLVE [ WITH '''''datasource''''' [, ...] ] [EXPAND [ WITH '''''datasource''''' [, ...] ] ]
 SN ''scientific name'' [, ...] [EXPAND [ WITH '''''datasource''''' [, ...] ] ]
</code>

Where '''''condition''''' can be one of:
<code>
 coordinate {< | <= | == | => | >} LAT, LONG
 eventDate {< | <= | == | => | >} DATE
</code>

Where '''''having condition''''' is a boolean expression composed by those elements:
<code>
 item expression : '''''item property''''' {< | <= | == | != | => | >} value
 function call: xpath('''''xpath expression''''') | exl('''''exl expression''''')
</code>

===Description===
The ''Search by'' query retrieves all the available elements from the species service.
The general processing of ''Search by'' is as follows:
# All the '''''term''''' are elaborated depending on the specified type:
#* '''CN''' case:
#** all the specified ''common name''s are mapped into ''scientific name''s using the specified datasources or all the available datasources if no one as been specified
#** if the EXPAND clause is specified the ''scientific name''s are expanded using the synonyms provided by the specified datasources or using all the available datasources if no one as been specified
#* '''SN''' case: 
#** if the EXPAND clause is specified all the specified ''scientific name''s  are expanded using the synonyms provided by the specified datasources or using all the available datasources if no one as been specified
# The ''scientific name''s retrieved from the '''''term''''' elaboration are used for the retrieving of the specified elements in the RETURN clause (if no element is specified PRODUCT are returned).
# If the WHERE clause is specified, all the elements that do not satisfy the condition are eliminated from the output (filtering made inside the Datasource).
# If the HAVING clause is specified, all the elements that do not satisfy the '''''having expression''''' are eliminated from the output (the filtering is made outside the Datasource).

==== Date format ====
Accepted DATE formats are:
* "yyyy"
* "MM-yyyy"
* "MM/yyyy"
* "yyyyMMdd"
* "dd-MM-yyyy"
* "yyyy-MM-dd"
* "MM/dd/yyyy"
* "yyyy/MM/dd"
* "dd MMM yyyy"
* "dd MMMM yyyy"
* "yyyyMMddHHmm"
* "yyyyMMdd HHmm"
* "dd-MM-yyyy HH:mm"
* "yyyy-MM-dd HH:mm"
* "MM/dd/yyyy HH:mm"
* "yyyy/MM/dd HH:mm"
* "dd MMM yyyy HH:mm"
* "dd MMMM yyyy HH:mm"
* "yyyyMMddHHmmss"
* "yyyyMMdd HHmmss"
* "dd-MM-yyyy HH:mm:ss"
* "yyyy-MM-dd HH:mm:ss"
* "MM/dd/yyyy HH:mm:ss"
* "yyyy/MM/dd HH:mm:ss"
* "dd MMM yyyy HH:mm:ss"
* "dd MMMM yyyy HH:mm:ss"

==== Item properties ====
Based on query returns type the post-filtering expression can access single item properties.

===== Taxon =====
{| border="1" style="border-collapse:collapse;width:500px;"
|-
! Property name !! Value Type
|-
| author || String
|-
| citation || String
|-
| credits || String
|-
| id || String
|-
| lsid || String
|-
| parent || [[SPQL:_SPecies_Query_Language#Taxon|Taxon]]
|-
| rank || String
|-
| scientificName || String
|}

===== Occurrence =====
{| border="1" style="border-collapse:collapse;width:1000px;"
|-
! Property name !! Value Type
|-
| author || String
|-
| basisOfRecord || enumeration {PreservedSpecimen, FossilSpecimen, LivingSpecimen, HumanObservation, MachineObservation}
|-
| catalogueNumber || String
|-
| citation || String
|-
| collectionCode || String
|-
| coordinateUncertaintyInMeters || String
|-
| country || String
|-
| credits || String
|-
| dataSet || [[SPQL:_SPecies_Query_Language#DataSet|DataSet]]
|-
| decimalLatitude || double
|-
| decimalLongitude || double
|-
| eventDate || Calendar
|-
| family || String
|-
| id || String
|-
| institutionCode || String
|-
| kingdom || String
|-
| locality || String
|-
| maxDepth || double
|-
| minDepth || double
|-
| modified || Calendar
|-
| properties || List
|-
| provider || String
|-
| recordedBy || String
|-
| scientificName || String
|}

====== DataSet ======
{| border="1" style="border-collapse:collapse;width:300px;"
|-
! Property name !! Value Type
|-
| citation || String
|-
| dataProvider || [[SPQL:_SPecies_Query_Language#DataProvider|DataProvider]]
|-
| id || String
|-
| name || String
|}

====== DataProvider ======
{| border="1" style="border-collapse:collapse;width:300px;"
|-
! Property name !! Value Type
|-
| id || String
|-
| name || String
|}


===== Product =====
{| border="1" style="border-collapse:collapse;width:300px;"
|-
! Property name !! Value Type
|-
| author || String
|-
| citation || String
|-
| commonNames || List of [[SPQL:_SPecies_Query_Language#CommonName|CommonName]]
|-
| credits || String
|-
| dataSet || [[SPQL:_SPecies_Query_Language#DataSet|DataSet]]
|-
| id || String
|-
| lsid || String
|-
| parent || [[SPQL:_SPecies_Query_Language#Taxon|Taxon]]
|-
| products || List of [[SPQL:_SPecies_Query_Language#Product|Product]]
|-
| properties || List of [[SPQL:_SPecies_Query_Language#ElementProperty|ElementProperty]]
|-
| provider || String
|-
| rank || String
|-
| scientificName || String
|}

====== CommonName ======
{| border="1" style="border-collapse:collapse;width:300px;"
|-
! Property name !! Value Type
|-
| language || String
|-
| locality || String
|-
| name || String
|}

====== Product ======
{| border="1" style="border-collapse:collapse;width:700px;"
|-
! Property name !! Value Type
|-
| count || int
|-
| key || String
|-
| type || enumeration {Classification, NamesMapping, Occurences, Synonims}
|}


====== ElementProperty ======
{| border="1" style="border-collapse:collapse;width:300px;"
|-
! Property name !! Value Type
|-
| name || String
|-
| value || String
|}

==== Functions ====
Currently the supported functions are:
* '''xpath''': a XPath expression returning a boolean value;
* '''exl''': a [http://commons.apache.org/proper/commons-jexl/reference/syntax.html JExl] expression returning a boolean value.

=== Examples ===