JQL Fundamentals
Filters and queries
Filtering, exclusion, Q expressions, generic search, ordering, and aggregate query options.
JQL filters are JSON objects converted to Django ORM filters. Dotted paths such as category.alias become relation traversals, and camelCase field names are normalized before the queryset is built.
Basic filters
filter accepts either one object or a list of objects. Each object may include __meta__.glue set to and or or.
1{
2 "__meta__": {
3 "schema": "model",
4 "namespace": "tickets.Ticket",
5 "intent": "retrieve",
6 "authenticationClass": "jwt",
7 "filter": {
8 "__meta__": {
9 "glue": "and"
10 },
11 "status": "open",
12 "category.alias": "support"
13 },
14 "ordering": "-created",
15 "limit": 25
16 },
17 "id": null,
18 "title": null,
19 "status": null,
20 "created": null
21}Use Django lookup suffixes when needed: created__gte, name__icontains, amount__gt, or category.name__iexact. Dot notation is translated to __ traversal.
Exclude
exclude has the same shape as filter and removes matching rows before pagination.
1{
2 "__meta__": {
3 "schema": "model",
4 "namespace": "tasks.Task",
5 "intent": "retrieve",
6 "authenticationClass": "jwt",
7 "filter": {
8 "status": "pending"
9 },
10 "exclude": {
11 "priority": "low"
12 }
13 },
14 "id": null,
15 "title": null,
16 "priority": null
17}Q expressions
q supports nested logical conditions using a Mongo-style shape. The processor converts it to Django Q objects and also transforms dynamic object fields for objects.<Namespace> calls.
1{
2 "__meta__": {
3 "schema": "model",
4 "namespace": "objects.Customer",
5 "intent": "retrieve",
6 "authenticationClass": "jwt",
7 "q": {
8 "logicalOperator": "$and",
9 "conditions": [
10 {
11 "field": "status",
12 "operator": "$eq",
13 "value": "active"
14 },
15 {
16 "logicalOperator": "$or",
17 "conditions": [
18 {
19 "field": "city",
20 "operator": "$eq",
21 "value": "London"
22 },
23 {
24 "field": "city",
25 "operator": "$eq",
26 "value": "Lagos"
27 }
28 ]
29 }
30 ]
31 }
32 },
33 "id": null,
34 "additionalInformation": null
35}Search and ordering
search performs generic text search over a model's declared searchable fields. It combines basic contains filters, weighted full-text search, trigram similarity where available, and stable ordering. ordering accepts a string or list; prefix a field with - for descending order.
Time helpers
Filters are interpolated with helper values such as today, tomorrow, yesterday, and now. Date-range helpers can be used in model filters that support range lookups.
See field selection, pagination, and /guides/records.