Field Lookups¶

The API is built with Django. Django uses field lookups to specify the SQL WHERE clause. So, for example, the simplest field lookup contains no extra keyword, just the field name and the value. Django converts it into a simple WHERE clause where the value must exactly match the queried value.

For example, the query parameter label=myanalysis would translate into:

SELECT * FROM analysis_table WHERE label = 'myanalysis';

What if we want to check if the field's value starts with a certain word, or to make a case insensitive search? This is where field lookups come into play.

For a case insensitive search, use the iexact keyword. Lookups are built by linking the field name and the keyword with two underscores: label__iexact. So Django would translate label__iexact=myanalysis into:

SELECT * FROM analysis_table WHERE label ILIKE 'myanalysis';

For a case sensitive containment search use label__contains=myanalysis:

SELECT * FROM analysis_table WHERE label LIKE '%myanalysis%';

Examples¶

Problem: Filter records from a given day.

Solution: The model's field is a datetime field, but there is a lookup keyword for this specific task: date.

curl -X GET \
  'https://api.biolanglobal.com/biolan/data/api/analysis?label=myanalysis&local_timestamp__date=2022-01-01' \
  -H 'Authorization: Bearer {token}' \
  -H 'accept: application/json'

Problem: Filter records from a date on.

Solution: use the gt lookup expression.

curl -X GET \
  'https://api.biolanglobal.com/biolan/data/api/analysis?label=myanalysis&local_timestamp__gt=2022-01-01' \
  -H 'Authorization: Bearer {token}' \
  -H 'accept: application/json'

Problem: Filter by a field named batch stored in the extra document.

Solution: Use a double underscore to navigate the values of the JSON document.

curl -X GET \
  'https://api.biolanglobal.com/biolan/data/api/analysis?label=myanalysis&extra__batch=0001' \
  -H 'Authorization: Bearer {token}' \
  -H 'accept: application/json'