Query Parameters

Query parameters are used to search inside or aggregate values inside resource collections, e. g. GET /api/v2/Payment/Transactions?....

The values must be URL encoded.

Nested properties are addressed by joining the component names with dots, e. g. merchant.id.


Name

Type

Description

Sample

Response

count

integer

The maximum number of items to return

count=10


offset

integer

The position within the whole result set to start returning items (zero-based).

offset=80


fields

string

List of properties included in the result, all others will be filtered out.

fields=contact.surname

fields=id,contact.surname


q

string

A query string to restrict the returned items to given conditions. The query string must consist of any combination of single expressions in the form property:condition. A condition may contain:

  • wildcard * for any number of characters,

  • wildcard ? for one character,

  • ranges in the form [value TO value],

  • Single expressions may be combined by AND, OR, NOT operators and parenthesis (...) for grouping.

https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-query-string-query.html#query-string-syntax


For date fields it's also possible to use intervals with specific dates and dynamic date calculation.

images/s/t1byiy/9012/1ca6q62/_/images/icons/emoticons/warning.svg If you specify dates, f.e. 2022-12-31T23:59:59+01:00 you need to encode the + character as %2B, otherwise it will be interpreted as white space (https://www.w3schools.com/tags/ref_urlencode.ASP). If you are using UTC (+00:00) you could also use Z to avoid this: 2022-12-31T23:59:59Z (https://en.wikipedia.org/wiki/ISO_8601#Time_zone_designators)

https://www.elastic.co/guide/en/elasticsearch/reference/current/sql-functions-datetime.html

https://www.elastic.co/guide/en/elasticsearch/reference/current/common-options.html#date-math

q=contact.surname:Mustermann

q=contact.surname:Muster*

q=contact.surname:Muster|Mustermann

q=contact.forename:Max+AND+contact.surname:Muster*

q=contact.forename:/joh?n(ath[oa]n)/

q=(NOT merchantRef:DemoMerchantRef) AND basket_info.sum:[100 TO 10000]

q=_exists_:customer



q=created:[now-1M/d TO now]

q=created:[now-1M/M TO now-1M/M]

q=date:[2022-12-01T00:00:00%2B01:00 TO 2022-12-31T23:59:59%2B01:00]


sort

string

String with comma separated pairs of `field:order`.

Options for order:

  • ascending: asc

  • descending: desc

sort=created:desc

sort=currency:asc,amount:desc


validate

integer

Check syntax of a query string

validate=1

{
"result": true
}

meta

string

Return field definitions

meta=true

meta=only

{
"meta": {
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "cardprocessingtransactions",
"type": "object",
"properties": {
...
}
},
"count": null,
"data": []
}

scroll_expire

string

While a search request returns a single page of results, the scroll can be used to retrieve large numbers of results (or even all results) from a single search request, in much the same way as you would use a cursor on a traditional database.

This parameter enables this feature and defines how long it should keep the “search context” alive.

https://www.elastic.co/guide/en/elasticsearch/reference/current/scroll-api.html

scroll_expire=10m

{
"scroll_id": "DXF1ZXJ5QW5kRmV0Y2gBAAAAAAAAAD4WYm9laVYtZndUQlNsdDcwakFMNjU1QQ==",
"count": 1,
"data": []
}

scroll_id

string

Identifier of the previous search context

scroll_id=DXF1ZXJ5QW5kRmV0Y2gBAAAAAAAAAD4WYm9laVYtZndUQlNsdDcwakFMNjU1QQ==

expand

string

Expand fields (all or a specific one)

expand=true

expand=merchant

preset

string

Query presets

(only for specific endpoints)

preset=own

aggregate[timestamp_prop]

string

The name of the field on which to perform the date aggregation.

https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-bucket-datehistogram-aggregation.html

(see next line)

aggregate[interval]

string

The interval by which documents will be bucketed (calendar interval or fixed).

https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-bucket-datehistogram-aggregation.html

aggregate[timestamp_prop]=created&aggregate[interval]=1y

{
"type": "date",
"sum": false,
"data": [
{
"k": 1577836800000,
"ks": "2020-01-01T00:00:00Z",
"c": 132
},
{
"k": 1609459200000,
"ks": "2021-01-01T00:00:00Z",
"c": 85
},
{
"k": 1640995200000,
"ks": "2022-01-01T00:00:00Z",
"c": 17
}
]
}

aggregate[min]

integer

Enables extending the bounds of the histogram beyond the data itself.

https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-bucket-datehistogram-aggregation.html


aggregate[max]

integer

Enables extending the bounds of the histogram beyond the data itself.

https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-bucket-datehistogram-aggregation.html


aggregate[group_by_prop]

string

The name of the field on which to perform the group aggregation.

https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-bucket-terms-aggregation.html

aggregate[group_by_prop]=product_raw

{
"type": "term",
"sum": false,
"data": [
{
"l": 0,
"c": 6
},
{
"l": 1,
"c": 5
},
{
"l": 2,
"c": 5
},
{
"l": 3,
"c": 1
}
],
"lookup": [
"Vorkasse Demo",
"Kauf auf Rechnung",
"Zahlungsgarantie Kreditkarte",
"Kreditkarte Demo"
]
}

aggregate[sum_by_prop]

string

The name of the field on which to perform the sum aggregation.

https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-metrics-sum-aggregation.html

aggregate[group_by_prop]=product_raw&aggregate[sum_by_prop]=amount

{
"type": "term",
"sum": true,
"data": [
{
"l": 0,
"c": 6,
"s": 70033
},
{
"l": 1,
"c": 5,
"s": 17982
},
{
"l": 2,
"c": 5,
"s": 1237
},
{
"l": 3,
"c": 1,
"s": 309
}
],
"lookup": [
"Vorkasse Demo",
"Kauf auf Rechnung",
"Zahlungsgarantie Kreditkarte",
"Kreditkarte Demo"
]
}