Queries

Queries join multiple collections through lookup references, creating read-only datasets with selected properties from each.

URL Structure

Queries share the same namespace as collections:

https://<region>.restapi.com/<api-name>/<query-name>

Fetching a Single Item

To fetch a single item from a query, append the ID to the URL:

https://<region>.restapi.com/<api-name>/<query-name>/<id>

The ID refers to the primary (root) collection's item ID. This returns the query result for that specific item with all joined data included.

Creating Queries

Use the Query Builder in the Developer Portal:

1. Navigate to your API's schema
2. Create a new query
3. Select collections to join
4. Choose properties to include
5. Test with the Query Explorer

Property Aliasing

Properties must have unique aliases within the query. This is necessary because multiple collections may have properties with the same name.

customers.name → customerName
orders.name → orderName

Simple Query Example

Join orders with customer information:

Query: orders-with-customers

orders
  └── customer (lookup) → customers
        └── name, state

Selected properties:

• orders.orderDate → orderDate
• orders.total → total
• customers.name → customerName
• customers.state → customerState

Result:

{
  "data": [
    {
      "orderDate": "2024-01-15",
      "total": 299.99,
      "customerName": "Acme Corp",
      "customerState": "California"
    }
  ]
}

Property Behaviour

Each property in a query can have a behaviour that determines how it's processed:

Behaviour	Description
None	Include the property value as-is (default)
SUM	Total of numeric values
AVG	Average of numeric values
MIN	Minimum value
MAX	Maximum value
COUNT	Number of items
FILTER	Use for filtering only, not included in results

None (Default)

Properties with no behaviour are included directly in results. When joining collections, this creates a flat result set.

Aggregation Functions

Use SUM, AVG, MIN, MAX, or COUNT to aggregate values. When using aggregation, non-aggregated properties become grouping columns.

Filter Only

The FILTER behaviour lets you use a property in the query's filter without including it in the results. Useful for filtering on fields you don't need to display.

Aggregation Example

Query: Customer Order Totals

customers
  └── orders (via customer lookup)
        └── orderLines (via order lookup)
              └── lineTotal

Property configuration:

• customers.name → behaviour: None (grouping column)
• orderLines.lineTotal → behaviour: SUM

Result:

{
  "data": [
    { "customerName": "Acme Corp", "totalOrders": 15420.50 },
    { "customerName": "Tech Inc", "totalOrders": 8750.00 }
  ]
}

Sorting Query Results

Use the sortBy parameter:

?sortBy=totalOrders-    # Descending
?sortBy=customerName    # Ascending

Filtering Queries

Apply filters to query results:

?filter=totalOrders gt 10000

Query vs View

Feature	Query	View
Joins collections	Yes	No
Aggregation	Yes	No
Write operations	No (read-only)	Configurable
Filter built-in	Optional	Optional
Performance	Computed on request	Computed on request

Best Practices

• Alias clearly — Use descriptive names for aliased properties
• Limit joins — Complex queries with many joins may be slower
• Add filters — Reduce result size with built-in filters
• Use pagination — For large datasets, use pageNo and pageSize