SPQL: SPecies Query Language

SPQL is a language used to query the Species Product Discovery Service

SPQL 1.0

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'

SPQL 2.0

Synopsis

SEARCH BY term [, ...]
      [ IN datasource [, ...] ]
      [ WHERE condition [AND condition] ]
      [ RETURN {PRODUCT | OCCURRENCE | TAXON} ]
      [ HAVING having expression ]

Where term can be one of:

CN common name [, ...] RESOLVE [ WITH datasource [, ...] ] [EXPAND [ WITH datasource [, ...] ] ]
SN scientific name [, ...] [EXPAND [ WITH datasource [, ...] ] ]

Where condition can be one of:

coordinate {< | <= | == | => | >} LAT, LONG
eventDate {< | <= | == | => | >} DATE

Where having condition is a boolean expression composed by those elements:

item expression : item property {< | <= | == | != | => | >} value
function call: xpath(xpath expression) | exl(exl expression)

Description

The Search by query retrieves all the available elements from the species service. The general processing of Search by is as follows:

1. All the term are elaborated depending on the specified type:
   • CN case:
     • all the specified common names are mapped into scientific names using the specified datasources or all the available datasources if no one as been specified
     • if the EXPAND clause is specified the scientific names 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 names are expanded using the synonyms provided by the specified datasources or using all the available datasources if no one as been specified
2. The scientific names 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).
3. 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).
4. 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

Property name	Value Type
author	String
citation	String
credits	String
id	String
lsid	String
parent	Taxon
rank	String
scientificName	String

Occurrence

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	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

Property name	Value Type
citation	String
dataProvider	DataProvider
id	String
name	String

DataProvider

Property name	Value Type
id	String
name	String

Functions

Currently the supported functions are:

• xpath: a XPath expression returning a boolean value;
• exl: a JExl expression returning a boolean value.