Skip to main content

Query Parameters Reference

Common query parameters for filtering, sorting, and paginating DreamFactory API responses.

filter​

Filter records using SQL-like expressions.

Syntax: filter={field}{operator}{value}

Operators​

OperatorDescriptionExample
=Equalfilter=status='active'
!=Not equalfilter=status!='deleted'
>Greater thanfilter=age>21
>=Greater or equalfilter=created_at>='2024-01-01'
<Less thanfilter=price<100
<=Less or equalfilter=quantity<=10
likePattern matchfilter=name like 'John%'
inValue in listfilter=status in ('active','pending')
is nullNull checkfilter=deleted_at is null
is not nullNot null checkfilter=email is not null

Combining Filters​

Use and / or for compound conditions:

filter=(status='active') and (created_at>='2024-01-01')
filter=(type='admin') or (type='superuser')
filter=((status='active') and (age>=18)) or (verified=true)

Examples​

Find active users:

curl "https://example.com/api/v2/db/_table/users?filter=status%3D'active'"

Find orders over $100 from 2024:

curl "https://example.com/api/v2/db/_table/orders?filter=(total>100)%20and%20(order_date>%3D'2024-01-01')"

Search by name pattern:

curl "https://example.com/api/v2/db/_table/contacts?filter=name%20like%20'%25smith%25'"

Note: URL-encode special characters (= as %3D, space as %20, % as %25).

limit​

Maximum number of records to return.

Syntax: limit={integer}

Default: Configured per-service (typically 1000)

Examples:

# Get first 10 records
curl "https://example.com/api/v2/db/_table/products?limit=10"

# Get first 50 matching filter
curl "https://example.com/api/v2/db/_table/orders?filter=status='pending'&limit=50"

offset​

Number of records to skip before returning results.

Syntax: offset={integer}

Default: 0

Use with limit for pagination:

# Page 1 (records 1-10)
curl "https://example.com/api/v2/db/_table/products?limit=10&offset=0"

# Page 2 (records 11-20)
curl "https://example.com/api/v2/db/_table/products?limit=10&offset=10"

# Page 3 (records 21-30)
curl "https://example.com/api/v2/db/_table/products?limit=10&offset=20"

Pagination formula: offset = (page - 1) * limit

order​

Sort results by one or more fields.

Syntax: order={field} {direction} or order={field1} {dir},{field2} {dir}

Directions: ASC (ascending), DESC (descending)

Examples:

# Sort by name ascending
curl "https://example.com/api/v2/db/_table/contacts?order=name%20ASC"

# Sort by date descending (newest first)
curl "https://example.com/api/v2/db/_table/orders?order=created_at%20DESC"

# Multi-column sort
curl "https://example.com/api/v2/db/_table/products?order=category%20ASC,price%20DESC"

fields​

Select specific fields to return (reduces payload size).

Syntax: fields={field1},{field2},{field3}

Examples:

# Return only id, name, email
curl "https://example.com/api/v2/db/_table/users?fields=id,name,email"

# Combine with filter
curl "https://example.com/api/v2/db/_table/orders?filter=status='pending'&fields=id,total,customer_id"

Default: All fields returned if not specified.

Include related records from foreign key relationships.

Syntax: related={table_name} or related={table1},{table2}

Examples:

# Get orders with customer data
curl "https://example.com/api/v2/db/_table/orders?related=customers"

# Get products with category and supplier
curl "https://example.com/api/v2/db/_table/products?related=categories,suppliers"

Response includes nested related data:

{
  "resource": [
    {
      "id": 1,
      "product_name": "Widget",
      "category_id": 5,
      "categories_by_category_id": {
        "id": 5,
        "name": "Electronics"
      }
    }
  ]
}

Use dot notation to filter on related fields:

curl "https://example.com/api/v2/db/_table/orders?related=customers&filter=customers.country='USA'"

include_count​

Include total record count in response (useful for pagination UI).

Syntax: include_count=true

Response includes meta field:

{
  "resource": [...],
  "meta": {
    "count": 1523
  }
}

Example with pagination:

curl "https://example.com/api/v2/db/_table/products?limit=10&offset=0&include_count=true"

Note: May impact performance on large tables. Use sparingly.

ids​

Filter by primary key values (alternative to filter for simple lookups).

Syntax: ids={id1},{id2},{id3}

Examples:

# Get specific records by ID
curl "https://example.com/api/v2/db/_table/users?ids=1,5,10,15"

# Delete multiple records
curl -X DELETE "https://example.com/api/v2/db/_table/temp_data?ids=100,101,102"

id_field​

Specify which field to use as the identifier (when not using default primary key).

Syntax: id_field={field_name}

Example:

curl "https://example.com/api/v2/db/_table/products?ids=SKU001,SKU002&id_field=sku"

group​

Group results by field values (for aggregate queries).

Syntax: group={field} or group={field1},{field2}

Example:

curl "https://example.com/api/v2/db/_table/orders?group=status&fields=status,count(*)"

having​

Filter grouped results (use with group).

Syntax: having={condition}

Example:

curl "https://example.com/api/v2/db/_table/orders?group=customer_id&fields=customer_id,sum(total)&having=sum(total)>1000"

count_only​

Return only the total record count, not the records themselves.

Syntax: count_only=true

Example:

curl "https://example.com/api/v2/db/_table/users?filter=status='active'&count_only=true"

Response:

{
  "meta": {
    "count": 1523
  }
}

Parameter Aliases​

Some parameters have alternative names for convenience:

ParameterAliases
fieldsselect
filterwhere
limittop
offsetskip
ordersort, order_by
groupgroup_by

Complete Examples​

Paginated List with Count​

curl "https://example.com/api/v2/db/_table/products\
?limit=20\
&offset=40\
&order=name%20ASC\
&include_count=true\
&fields=id,name,price,stock"
curl "https://example.com/api/v2/db/_table/orders\
?filter=(status='pending')%20and%20(total>100)\
&related=customers\
&order=created_at%20DESC\
&limit=50"

Minimal Payload for Dropdown​

curl "https://example.com/api/v2/db/_table/categories\
?fields=id,name\
&order=name%20ASC\
&filter=active=true"

URL Encoding Reference​

CharacterEncoded
Space%20 or +
=%3D
'%27
%%25
&%26
(%28
)%29
,%2C

Tip: Use your HTTP client's built-in URL encoding rather than manual encoding.

See Also​