Parameters

This section covers query and body parameters which can be used to manipulate and filter data during certain requests.

Query Parameters

Query parameters can be used with

GET

and

SEARCH

requests to implement selection limits and querying.

Parameter	Name	Type	Description
hidesystemflags	Hide System Flags	Boolean	Removes system properties (e.g. _hash) from the returned documents. Default false.
foreignkeys	Foreign Keys	Boolean	Include foreign key data in the returned documents. Default false.
countonly	Count Only	Boolean	Only return total number of documents which match the given criteria. Returns the number in the data property. Default false.
l	Limit	Integer	Limits the number of documents that can be returned from the request. Can be used with o to implement pagination. Default 1000.
o	Offset	Integer	Offsets the documents returned from the database result. Can be used with l to implement pagination. Default 0.
q	Query	String	Perform a document scanning regex query on every property in the collection's text index.
search	Search	String	Perform a full-text search, implementing MongoDB's text search.
timezone	Time Zone	String	API will preprocess date/time data from standard UTC to a specified time zone. Accepts UTC offsets in format +00:00/-00:00. Or Olson Timezone Identifier such as Europe/London. If no timezone is given, UTC is returned.

Body Parameters

GET

'technically' supports the inclusion of a request body, but it isn't fully supported in most scenarios (including JavaScript's fetch API, for example).

SEARCH

has been implemented as an alternative to this, in order to support more complex request parameters and functionality. These parameters also partially apply to

PUT

and

DELETE

requests.

info

For systems where the

SEARCH

method is not supported, an equivalent

POST

endpoint is available: documents/query.

The request body must be a JSON object, and may contain any of these properties.

Parameter	Name	Type	Description
sort	Sort	Object	Sets the sort order for the resulting documents. Follows MongoDB's $sort syntax rules.
filter	Filter	Object	Filters the resulting documents and only returns data that matches the given conditions. Follows a limited subset of MongoDB's $match syntax. See below for more.
projection	Projection	Object	Allows fields to be individually removed, or exclusively shown. Follows a limited subset of MongoDB's $project syntax. See below for more.
update	Update	Object	Contains the document or partial document when running a replace or update operation ( PUT and PATCH ). Does not apply to getting operations ( SEARCH ).
group	Group	Object	Allows grouping and aggregation functions on data, such as $sum and $avg, on either all data on or a given set of fields. See below for more.

note

The

SEARCH

method will be replaced if an official standard is accepted,

QUERY

is the current contender.

Filtering

Data requests with

SEARCH

can include the filter property. The API supports a limited implementation of MongoDB's filter querying system. The primary difference is that conditions must use the explicit operator syntax. Implicit equality queries are not allowed:

Not allowed

{ "name": "Test 123" }

Allowed

{ "name": { "$eq": "Test 123" } }

Condition groups ($and, $or, $nor) are fully supported and nestable.

The following comparison operators are available to use:

• $eq
• $gt
• $gte
• $lt
• $lte
• $ne
• $in
• $nin
• $not
• $exists
• $mod
• $all
• $elemMatch
• $size
• $type

note

The $expr operator is currently unavailable.
Filtering may be changed to support the $expr syntax for more comprehensive filtering.

Special Types

The API implements MongoDB Extended JSON v2 in filters. This allows the use of special data types like ObjectId to be used in filters. Both relaxed and canonical modes are supported.

{
    "_id": {
        "$eq": { "$oid": "6437abf411885a3f1b78a469" }
    },
    "timestamp": {
        "$gt": { "$date": "2023-04-13T08:15:22.000Z" }
    }
}

warning

The following types are not supported in the API:

• Timestamp ($timestamp)
• Binary ($binary) with JavaScript Code subtypes (\x0D and \x0F)

Projection

Data requests with

SEARCH

can include the projection property. The API only supports single-string paths and numeric 1/0 syntax.

// Mixing inclusions & exclusions is only allowed with _id because it is always implicitly included
{
    "_id": 0,
    "name": 1,
    "company.contact.name": 1
}

Normal restrictions with this syntax apply as expected, such as mixing included & excluded projections in the same query. The projection object must not be empty, but can be null/undefined.

Not allowed

// Can't mix exclusions and inclusions
{
    "company": 1,
    "block": 0
}

// Inclusion of company collides with inclusion of a child of the same object
{
    "company": 1,
    "company.contact": 1
}

// Nested syntax is not allowed by the API.
{
    "company": {
        "contact": 1
    }
}

Grouping

Data requests with

SEARCH

can include the group property. This allows the client to request data be grouped and have a given aggregation function applied to all fields. Optionally, the client can provide a string array of fields to be grouped on. If no fields are provided, the aggregation function is applied against the entire dataset.

These functions are available:

• count *
• sum
• min
• max
• avg

* count is not MongoDB's native implementation of $count. This implementation counts all non-null values of each field using $sum and $ifNull.

Example

{
    "group": {
        "function": "sum",
        "by": ["customer.name"]
    }
}

Response:

{
    "timestamp": "2024-01-03T13:09:38.722Z",
    "data": [
        {
            "customer": {
                "name": "Customer 1"
            },
            "gross": {
                "weight": 60909873,
                "timestamp": 0,
                "sequenceNo": 2581469287710,
                "operator": 0,
                "scale": 0
            },
            "ticket": {
                "ticketNo": 11477364,
                "status": 0,
                "originalTicketNo": 11477364
            },
            "net": 48779660
        },
        {
            "customer": {
                "name": "Customer 2"
            },
            "gross": {
                "weight": 59413033,
                "timestamp": 0,
                "sequenceNo": 2462974817270,
                "operator": 0,
                "scale": 0
            },
            "ticket": {
                "ticketNo": 11305233,
                "status": 0,
                "originalTicketNo": 11305233
            },
            "net": 47589517
        }
    ]
}

Examples

Get all documents for January 2023 using weight2.timestamp.

{
    "filter": {
        "$and": [
            {
                "weight2.timestamp": {
                    "$gte": { "$date": "2023-01-01" }
                }
            },
            {
                "weight2.timestamp": {
                    "$lt": { "$date": "2023-02-01" }
                }
            }
        ]
    }
}

Only show the ticketNo, weight2, and product data, sorted by ticketNo in ascending order.

{
    "projection": {
        "ticketNo": 1,
        "weight2": 1,
        "product": 1
    },
    "sort": {
        "ticketNo": 1
    }
}

Group by product name and customer name, only show the sum of the netWeight, ordered from highest to lowest weight.

{
    "projection": {
        "netWeight": 1
    },
    "sort": {
        "netWeight": -1
    },
    "group": {
        "function": "sum",
        "by": ["product.name", "customer.name"]
    }
}