Post search

This route allows you to make some custom queries for a specific couple (game / discr).

Thanks to this route you can request on both standard columns (such as score, platform …) and statistic fields.

In order to perform these kind of custom queries, the route defines a query language - close to mango queries - that is defined in this page.

Query language

For the purpose of this route, we define a custom query language that is described in this section.

It relies on JSON format and has four type of keys which are

Key	Required	Description
`selector`	No	The array of fields you want to select
`query`	No	The main query
`limit`	No	The maximum number of results
`offset`	No	The offset for the results

Selector

The selector field is an array of the field you want to select. It can be both a column or a statistic field.

If the selector field is missing or its array is empty, the request will select all columns except the extra one.

For specific statistic field, you have to prefix the stats field by stats.

The authorized values for column fields are :

Key	Description
`platform`	The player’s platform (e.g. _steam_, _octopod_ …)
`user`	The user identifier
`score`
`session`	The session identifier
`pseudo`
`extra`	The extra field
`discr`	The string array which contains discriminants
`country`
`launcher`	The launcher identifier if any
`stats`	A key / value structure that contains statistics

Query

The query field describes the query you want to perform.

It has a tree structure where the leaf nodes are target values and intermediate nodes are the operator to perform.

There are three types of operators: the composite operators (deal with several intermediate nodes), the decorator operators (deal with one intermediate node) and the atomic operators (deal with a leaf node).

Composite operators

A composite operation query has a composite operator and an array of query objects. The syntax is :

"query": {
    "operator": <composite operator>,
    "queries": [ <array of query objects> ]
}

List of composite operators

Operator

Example

and

"query": {
    "operator": "and",
    "queries": [
        {"operator": "eq", "query": {"field": "platform", "value": "steam"}},
        {"operator": "gt", "query": {"field": "score", "value": 1200}},
    ]
}

All rows of steam with a score greater than 1200

or

"query": {
    "operator": "or",
    "queries": [
        {"operator": "lt", "query": {"field": "score", "value": 1000}},
        {"operator": "gt", "query": {"field": "stats.foo", "value": 2000}},
    ]
}

All rows with score not in range [1000, 2000]

Decorator operators

A decorator operation query has a decorator operator and a single intermediate query objects(it cannot be a leaf node). The syntax is :

"query": {
    "operator": <decorator operator>,
    "query": <single intermediate query object>
}

List of decorator operators

Operator	Example
`not`	"query": { "operator": "not", "query": {"operator": "eq", "query": {"field": "platform", "value": "steam"}}, } All rows where platform is different to steam

Atomic operators

An atomic operation query has an atomic operator and a single leaf node query object (which contains the target value).

The syntax is :

"query": {
    "operator": <atomic operator>,
    "query": {
        "field": <selector name>,
        "value": <target value>
    }
}

List of atomic operators

Operator	Example
`eq`	"query": { "operator": "eq", "query": {"field": "platform", "value": "steam"} } All rows where platform is set to steam All kind of values is accepted
`lt`	"query": { "operator": "lt", "query": {"field": "score", "value": 1000} } All rows with score less than 1000 Only numeric values are allowed for stats selection
`lte`	"query": { "operator": "lte", "query": {"field": "score", "value": 1000} } All rows with score less or equal than 1000 Only numeric values are allowed for stats selection
`gt`	"query": { "operator": "gt", "query": {"field": "score", "value": 1000} } All rows with score greater than 1000 Only numeric values are allowed for stats selection
`gte`	"query": { "operator": "gte", "query": {"field": "score", "value": 1000} } All rows with score greater or equal than 1000 Only numeric values are allowed for stats selection
`in`	"query": { "operator": "in", "query": {"field": "platform", "value": ["octopod", "steam"]} } All rows where platform is either steam or octopod Only string array values are allowed

Limit

The system expects a strictly positive integer. By default, it limits the number of results to 25.

Offset

The system expects a positive integer (0 by default).

Route specifications

POST  /v2/:game/:discr/search

Route parameters

Key	Description
`:game`	the game name
`:discr`	the major discriminant (a discriminant is a criteria that identify the board where the score has to be put. Note that a game can have several independent leaderboard which are identified by a distinct discriminant)

Request body

The request body must be send with the application/json format.

The content of the body corresponds to the query, written in the custom query language.

Example :

{
    "selector": ["user", "platform", "score"],
    "query": {
        "operator": "and",
        "queries": [
            {
                "operator": "gte",
                "query": {"field": "score", "value": 1000}
            },
            {
                "operator": "eq",
                "query": {"field": "platform", "value": "octopod"}
            }
        ]
    },
    "limit": 3
}

Response

Code	Remarks
200	The query has been executed successfully and results have been sent
400	`(game/discr)` does not exist or there are some syntax errors in the posted query (see the error message)
500	Internal error

The response is sent in the JSON format. Results are sorted according to the ranking rules (i.e DESC score, ASC createdAt).

{
    "results": [
        {
            "platform": "octopod",
            "user": "toto",
            "score": 1600,
            "rank": 1
        },
        {
            "platform": "octopod",
            "user": "zar",
            "score": 1500,
            "rank": 2
        },
        {
            "platform": "octopod",
            "user": "baz",
            "score": 1100,
            "rank": 3
        }
    ]
}