Difference between revisions of "SPQL: SPecies Query Language"
Lucio.lelii (Talk | contribs) m (→Grammar) |
Lucio.lelii (Talk | contribs) (→Examples) |
||
(32 intermediate revisions by 5 users not shown) | |||
Line 1: | Line 1: | ||
+ | ''SPQL'' is a language used to query the [[Biodiversity_Access | Species Product Discovery Service]] | ||
− | + | == SPQL 1.0 == | |
− | + | ||
− | == | + | |
<source lang="java"> | <source lang="java"> | ||
Line 31: | Line 30: | ||
coordinate: FLOAT ',' FLOAT | coordinate: FLOAT ',' FLOAT | ||
− | returnExpression: '*' | 'Occurrence' | 'Taxon' | + | returnExpression: '*' (havingExpression)? | 'Occurrence' | 'Taxon' |
havingExpression: HAVING 'Occurrence' | 'Taxon' | havingExpression: HAVING 'Occurrence' | 'Taxon' | ||
</source> | </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'' [, ...] [UNFOLD WITH '''''datasource''''' ] [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 UNFOLD clause is specified all the specified ''scientific name''s are expanded using their descendants provided by the specified datasource (only one) | ||
+ | #** 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 === | ||
+ | |||
+ | * Search all the products about the scientific name 'sarda sarda' in all available datasources. | ||
+ | |||
+ | <code> | ||
+ | SEARCH BY SN 'sarda sarda' | ||
+ | </code> | ||
+ | |||
+ | * Search all the products about 'sarda sarda' and his synonyms in OBIS, in all available datasources. | ||
+ | |||
+ | <code> | ||
+ | SEARCH BY SN 'sarda sarda' EXPAND WITH OBIS | ||
+ | </code> | ||
+ | |||
+ | * Search all the products about 'sarda sarda' and his synonyms found in OBIS, in ITIS datasource. | ||
+ | |||
+ | <code> | ||
+ | SEARCH BY SN 'sarda sarda' EXPAND WITH OBIS IN ITIS | ||
+ | </code> | ||
+ | |||
+ | * Search all the Taxa about 'sarda sarda' and his synonyms found in OBIS, in ITIS datasource. | ||
+ | |||
+ | <code> | ||
+ | SEARCH BY SN 'sarda sarda' EXPAND WITH OBIS IN ITIS RETURN TAXON | ||
+ | </code> | ||
+ | |||
+ | * Search all the products about the scientific names retrieved searching the common 'shark' in the datasource OBIS and mapping it into a scientific name using ITIS. Accept only the results with coordinate less or equals to (15.12, 16.12). | ||
+ | <code> | ||
+ | SEARCH BY CN 'shark' RESOLVE WITH OBIS EXPAND WITH ITIS WHERE coordinate <= 15.12, 16.12 RETURN Product | ||
+ | </code> | ||
+ | |||
+ | * Search all the occurrence points about the scientific names 'sarda sarda' and 'Carcharodon carcharias' expanded with synonyms from datasource OBIS, found in ITIS and with an event date between 2000 and 2005. | ||
+ | |||
+ | <code> | ||
+ | SEARCH BY SN 'sarda sarda', 'Carcharodon carcharias' EXPAND WITH OBIS IN ITIS WHERE eventDate >= '2000' AND eventDate <= '2005' RETURN Occurrence | ||
+ | </code> | ||
+ | |||
+ | * Search all the products about the scientific names retrieved searching the common 'shark' in the datasource OBIS and mapping it into a scientific name using ITIS. Accept only the results with coordinate less or equals to (15.12, 16.12). Results are post filtered using the xpath expression "//product[type='TAXON' and counter>0]". | ||
+ | |||
+ | <code> | ||
+ | SEARCH BY CN 'shark' RESOLVE WITH OBIS EXPAND WITH ITIS WHERE coordinate <= 15.12, 16.12 RETURN Product HAVING xpath("//product[type='TAXON' and counter>0]") | ||
+ | </code> | ||
+ | |||
+ | * Search all the Taxa about the scientific names retrieved unfolding (the tree below) using the datasource CatalogueOfLife in OBIS. | ||
+ | |||
+ | <code> | ||
+ | SEARCH BY SN 'cervidae' UNFOLD WITH CatalogueOfLife IN OBIS RETURN Taxon | ||
+ | </code> |
Latest revision as of 10:42, 16 December 2014
SPQL is a language used to query the Species Product Discovery Service
Contents
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 [, ...] [UNFOLD WITH datasource ] [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:
- 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 UNFOLD clause is specified all the specified scientific names are expanded using their descendants provided by the specified datasource (only one)
- 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
- CN case:
- 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).
- 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
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 |
Product
Property name | Value Type |
---|---|
author | String |
citation | String |
commonNames | List of CommonName |
credits | String |
dataSet | DataSet |
id | String |
lsid | String |
parent | Taxon |
products | List of Product |
properties | List of ElementProperty |
provider | String |
rank | String |
scientificName | String |
CommonName
Property name | Value Type |
---|---|
language | String |
locality | String |
name | String |
Product
Property name | Value Type |
---|---|
count | int |
key | String |
type | enumeration {Classification, NamesMapping, Occurences, Synonims} |
ElementProperty
Property name | Value Type |
---|---|
name | String |
value | String |
Functions
Currently the supported functions are:
- xpath: a XPath expression returning a boolean value;
- exl: a JExl expression returning a boolean value.
Examples
- Search all the products about the scientific name 'sarda sarda' in all available datasources.
SEARCH BY SN 'sarda sarda'
- Search all the products about 'sarda sarda' and his synonyms in OBIS, in all available datasources.
SEARCH BY SN 'sarda sarda' EXPAND WITH OBIS
- Search all the products about 'sarda sarda' and his synonyms found in OBIS, in ITIS datasource.
SEARCH BY SN 'sarda sarda' EXPAND WITH OBIS IN ITIS
- Search all the Taxa about 'sarda sarda' and his synonyms found in OBIS, in ITIS datasource.
SEARCH BY SN 'sarda sarda' EXPAND WITH OBIS IN ITIS RETURN TAXON
- Search all the products about the scientific names retrieved searching the common 'shark' in the datasource OBIS and mapping it into a scientific name using ITIS. Accept only the results with coordinate less or equals to (15.12, 16.12).
SEARCH BY CN 'shark' RESOLVE WITH OBIS EXPAND WITH ITIS WHERE coordinate <= 15.12, 16.12 RETURN Product
- Search all the occurrence points about the scientific names 'sarda sarda' and 'Carcharodon carcharias' expanded with synonyms from datasource OBIS, found in ITIS and with an event date between 2000 and 2005.
SEARCH BY SN 'sarda sarda', 'Carcharodon carcharias' EXPAND WITH OBIS IN ITIS WHERE eventDate >= '2000' AND eventDate <= '2005' RETURN Occurrence
- Search all the products about the scientific names retrieved searching the common 'shark' in the datasource OBIS and mapping it into a scientific name using ITIS. Accept only the results with coordinate less or equals to (15.12, 16.12). Results are post filtered using the xpath expression "//product[type='TAXON' and counter>0]".
SEARCH BY CN 'shark' RESOLVE WITH OBIS EXPAND WITH ITIS WHERE coordinate <= 15.12, 16.12 RETURN Product HAVING xpath("//product[type='TAXON' and counter>0]")
- Search all the Taxa about the scientific names retrieved unfolding (the tree below) using the datasource CatalogueOfLife in OBIS.
SEARCH BY SN 'cervidae' UNFOLD WITH CatalogueOfLife IN OBIS RETURN Taxon