Data search
Introduction
Anis-server provides a single entrypoint to search into a dataset. For a search in a dataset, the user can specify:
- Attributes to be displayed
- Search criteria
- Sort order
- Pagination
- An output format
Entrypoint example to search into observations
dataset:
/search/observations
The search parameters must be added after the ?
.
We will see in the following documentation what parameters are availables and how to add them.
/search/observations?[PARAMETERS]
Warning
: the parameter a
is mandatory to perform a search.
Attributes (param a)
The user can select output attributes by their metamodel ID. When the dataset is created and the attributes are added, the metamodel assigns an identification number starting from 1. The user can list the attributes available for a dataset.
curl "http://localhost:8080/dataset/observations/attribute"
To add a list of attributes in a dataset search the user must add the query parameter a
.
It must specify a list of ID separated by a semicolon.
If the user wants attributes 1, 2 and 3:
a=1;2;3
Example:
curl "http://localhost:8080/search/observations?a=1;2;3"
The user can choose the output order of the attributes. Example if the user wants to see attribute 3 before 2:
curl "http://localhost:8080/search/observations?a=1;3;2"
Count
The user can replace the list of attributes with the special keyword count
.
This will return the number of records found for a search.
For example, if the user wants to retrieve the number of records in the observations dataset:
curl "http://localhost:8080/search/observations?a=count"
if the user wants to retrieve the number of records in the observations dataset when the ID observations is greater than 424:
curl "http://localhost:8080/search/observations?a=count&c=1::gt::424"
All
The user can replace the list of attributes with the special keyword all
.
This will return all attributes available for the dataset.
For example, if the user wants to retrieve all columns for this dataset observations search:
curl "http://localhost:8080/search/observations?a=all&c=1::gt::424"
Criteria (param c)
The user can apply one or more search criteria to filter the search result.
The search criteria are added on the parameter c
and each criterion is separated by a ;
.
c=c1;c2;c3....
Each search criterion is composed of 3 parts:
- The attribute on which the filter will be performed
- The operator
- 0 or n values
Each part must be separated by ::
Example
1::eq::10
This filter will search for all values where the attribute 1 is 10.
We will now see the list of available operators.
Equal
The user can add an equal search criterion using the eq
operator.
With the eq
operator the user must specify a single value.
For example if the user wants to search for the observation with the number 418:
1::eq::418
Complete example with observations dataset:
curl "http://localhost:8080/search/observations?a=1;2;3&c=1::eq::418"
Not equal
The user can add a not equal search criterion using the neq
operator.
With the neq
operator the user must specify a single value.
For example if the user wants to search all observations except 418:
1::neq::418
Complete example with observations dataset:
curl "http://localhost:8080/search/observations?a=1;2;3&c=1::neq::418"
Between
The user can add a between search criterion using the bw
operator.
With the bw
operator the user must specify two values separated by |
.
For example if the user wants to search all observations between 418 and 420:
1::bw::418|420
Complete example with observations dataset:
curl "http://localhost:8080/search/observations?a=1;2;3&c=1::bw::418|420"
Greater than
The user can add a greater than search criterion using the gt
operator.
With the gt
operator the user must specify a single value.
For example if the user wants to search all observations with ID greater than 424:
1::gt::424
Complete example with observations dataset:
curl "http://localhost:8080/search/observations?a=1;2;3&c=1::gt::424"
Greater than equal
The user can add a greater than equal search criterion using the gte
operator.
With the gte
operator the user must specify a single value.
For example if the user wants to search all observations with ID greater than or equal to 424:
1::gte::424
Complete example with observations dataset:
curl "http://localhost:8080/search/observations?a=1;2;3&c=1::gte::424"
Less than
The user can add a less than search criterion using the lt
operator.
With the lt
operator the user must specify a single value.
For example if the user wants to search all observations with ID less than 424:
1::lt::424
Complete example with observations dataset:
curl "http://localhost:8080/search/observations?a=1;2;3&c=1::lt::424"
Less than equal
The user can add a less than equal search criterion using the lte
operator.
With the lte
operator the user must specify a single value.
For example if the user wants to search all observations with ID less than or equal to 424:
1::lte::424
Complete example with observations dataset:
curl "http://localhost:8080/search/observations?a=1;2;3&c=1::lte::424"
Like
The user can add a like search criterion using the lk
operator.
With the lk
operator the user must specify a single value.
For example if the user wants to search observations object name (M 15) which contains the string 15:
7::lk::15
Complete example with observations dataset:
curl "http://localhost:8080/search/observations?a=1;2;3;7&c=7::lk::15"
Not like
The user can add a like search criterion using the nlk
operator.
With the nlk
operator the user must specify a single value.
For example if the user wants to search observations object name which not contains the string 15:
7::nlk::15
Complete example with observations dataset:
curl "http://localhost:8080/search/observations?a=1;2;3;7&c=7::nlk::15"
In
The user can add a in search criterion using the in
operator.
With the in
operator the user must specify multiple values separated by |
.
For example if the user wants to search observations number 418 and 419 and 420:
1::in::418|419|420
Complete example with observations dataset:
curl "http://localhost:8080/search/observations?a=1;2;3&c=1::in::418|419|420"
Not in
The user can add a not in search criterion using the nin
operator.
With the nin
operator the user must specify multiple values separated by |
.
For example if the user wants to search observations which do not have the number 418 and 419 and 420:
1::nin::418|419|420
Complete example with observations dataset:
curl "http://localhost:8080/search/observations?a=1;2;3&c=1::nin::418|419|420"
Null
The user can add a null criterion using nl
operator.
With the nl
operator the user must not specify any value.
For example if the user wants to search cards whose type is null:
6::nl
Complete example with sp_cards dataset:
curl "http://localhost:8080/search/sp_cards?a=1;2;3;4;5;6&c=6::nl"
Not null
The user can add a not null criterion using nnl
operator.
With the nnl
operator the user must not specify any value.
For example if the user wants to search cards whose type is not null:
6::nnl
Complete example with sp_cards dataset:
curl "http://localhost:8080/search/sp_cards?a=1;2;3;4;5;6&c=6::nnl"
Json
The user can add a json criterion using js
operator.
This operator is a special operator allows you to search in a json column for PostgreSQL databases only.
For example if the user wants to search cards when the json_schema contains the key name
equal to MXT-EVT-CAL
:
7::js::name|eq|MXT-EVT-CAL
Complete example with sp_cards dataset:
curl "http://localhost:8080/search/sp_cards?a=1;2;3;4;5;6;7&c=7::js::name|eq|MXT-EVT-CAL"
Cone-search (param cs)
The user has the possibility to perform a cone-search on a dataset to filter the results. The user must specify a spatial position in degrees and a search radius in arc seconds.
The parameter cs
requires 3 values separated by :
:
- Right ascension in degrees
- Declination in degrees
- Search radius in arc seconds
For example if the user wants all observations around of the position 322.5 +12.167 (100 arc seconds):
cs=322.5:12.167:100
Complete example with observations dataset:
curl "http://localhost:8080/search/observations?a=1;2;3&cs=322.5:12.167:100"
Warning: For searching via a cone-search in a dataset the dataset config must contains cone-search parameters
and flag cone-search enabled must be to true.
Example see config->cone-search
for dataset observations:
curl "http://localhost:8080/dataset/observations"
Order (param o)
The user has the possibility to sort the results by attributes and in ascending or descending order. The user can perform several sortings. For example, sort by date and then for each date by alphabetical order.
Each order o
must contain:
- The attribute ID on which the sorting is performed
- The meaning
a
for ascending andd
for descending
If there are several orders, each sort must be separated by ;
For example if the user wants to sort all observations by date and for each date by object name descending:
o=4:a;7:d
Complete example with observations dataset:
curl "http://localhost:8080/search/observations?a=1;2;3;4;5;6;7&o=4:a;7:d"
Pagination (param p)
The user has the possibility to return the result using a pagination. This is very useful when the result is too large. The user can choose the number of results per page and the page to be displayed.
The parameter p
requires 2 values:
- The number of results per page
- The page to be displayed
For example if the user wants to see the first page with 2 results per page:
p=2:1
Pagination requires ordering the result for example by observations ID. Complete example with observations dataset:
curl "http://localhost:8080/search/observations?a=1;2;3&o=1:a&p=2:1"
Result format
The user can choose the format of the search result with the parameter f
.
By default the result is returned in a json format.
The user can choose between 4 formats:
json
csv
ascii
(values separated by one space)votable
For example if the user wants all observations in csv format:
curl "http://localhost:8080/search/observations?a=1;2;3&f=csv"
Search trajectory parameter (param s: not of use for a search)
There is, for the client, an optional parameter s
. The latter is used to check
on which step, the user is passed on criteria
, output
or result
during a search through a dataset (1 if
passed, 0 if not).
For instance, if the user passed through all of them while searching a dataset, you will see in the search bar something like:
"http://localhost:4200/instance/default/search/result/observed_spectra?s=111&a=1;3;4;5;7;8;9;11"
If you stopped at the result table, you will see:
"http://localhost:4200/instance/default/search/result/observed_spectra?s=110&a=1;3;4;5;7;8;9;11"
This parameter is not of use for a search, and can be omitted safely while performing a query. We mention it here, for the sake of completeness and clarity.