Domain Queries

All base root endpoints can be queried the domain using a query parameter s. There are five keywords that are in use for the criteria, $query, $take, $skip, $takeLast, $skipLast

Queryable fields

Not all fields can be specified in the query criteria Queryable fields should be denoted in the domain model specification

Query Criteria Syntax

Search criteria will be passed in a json with $query keyword Note that quotes around the json keys are optional.
/games?s={"$query" : {"season" : 2014}}

URL Encoding

Any special characters will have to be encoded. So the actual request would look like /games?s=%7B%22%24query%22%20%3A%20%7B%22season%22%20%3A%202014%7D%7D For the duration of the documentation, examples are displayed without the encoding

Logical Operators

Logical operators can be passed in using one of the following operators $or Joins query clauses with a logical OR returns all results that match the conditions of either clause.

Comparison Operators

Comparison queries can be passed in using one of the following operator

$gt    Matches values that are greater than the value specified in the query.
$gte  Matches values that are greater than or equal to the value specified in the query.
$in    Matches any of the values that exist in an array specified in the query.
$lt    Matches values that are less than the value specified in the query.
$lte  Matches values that are less than or equal to the value specified in the query.
$ne    Matches all values that are not equal to the value specified in the query.
$nin  Matches values that do not exist in an array specified to the query.

Using $or with comparison operator

{
    "$query" : {
        "season" : 2014, 
        "seasonType" : "REG", 
        "$or" : [ 
            {"week" : {"$gt" : 5}}, 
            {"week" : {"$lt": 10}}
        ]
    }
}

Using $in operator

{
    "$query" : {
        "season": 2014, 
        "seasonType" : "REG", 
        "week" : {
            "$in" : [5,6,7]
        }
    }
}

Querying using Embedded Objects

You can perform queries using any embedded objects by using the dot notations. As always, the embedded object must be queryable field.

To query on games that is played by team 'DEN' either as homeTeam or visitorTeam in 2014 REG season. (homeTeam and visitorTeam objects are searchable fields within Game object)

{
    "$query" : {
        "season": 2014, 
        "seasonType":" "REG", 
        "$or" : [ 
            {"homeTeam.abbr" : "DEN"}, 
            {"visitorTeam.abbr" : "DEN"}
        ] 
    }
}

You can also use the same dot notation when the embedded object is a collection object.

To query on games that had any drives that had more than 7 first downs and more than 90 total yards.

{
    "$query" : {
        "drives.firstDowns" : {"$gt" : 7}, 
        "drives.yards": {"$gt" : 90}
    }
}

To query on games that had any drives that had more than 7 first downs or any drive that had more than 90 total yards.

{
    "$query" : {
        "$or" : [
            {"drives.firstDowns" : {"$gt" : 7}}, 
            {"drives.yards" : {"$gt" : 90}}
        ]
    }
}

Querying on Embedded Collections

You can also perform queries on embedded collections themselves.
Note that this is different from the above topic in that, the query is performed on (not based on) embedded collections. For instance, you only need 2014 Season of playerGameStats of persons that are currently playing for Denver, you need to query 1) persons that are currently playing for Denver, 2) Within those persons, you only would like to 2014 playerGameStats as an embedded collection of the persons.

Games in 2014 Reg season week 1. Within those games, return only the drives that had more than 10 plays.

{
    "$query" : {
        "season": 2014, 
        "seasonType": "REG", 
        "week": 1
    }, 
    "drives" : {
        "$query" : {"playCount" : 10}
    }
}

Here note that drives has its own $query keyword that will filter each game's drive according the $query parameter.

Sorting

You can sort the objects on any of its attribute as well as attributes of its embedded objects, but not embedded collection objects. You can use the dot notation to represent any attribute of embedded objects. Value of 1 is ascending order and -1 is descending order.

{
    "$query" : {
        "season": 2014, 
        "seasonType": "REG", 
        "week": 1
    }, 
    "$sort" : {
        "gameTime" : 1,
        "homeTeam.abbr" : -1
    }
}

You can also perform sorting on the embedded collection themselves, independent of the sort of the root objects.

Example

Games in 2014 Reg season week 1 ordered by gameTime. Within those games, return only the drives that had more than 10 plays ordered by longest drives first.

Query

{
    "$query" : {
        "id": "862bc634-5daf-4c07-b557-a88d03d973ec",
        "seasonType": "REG", 
        "week": 1
    },
    "$sort" : {
        "gameTime" : 1,
    },
    "drives" : {
        "$query" : {"playCount" : 10},
        "$sort" : {
            "yards" : -1
        }
    }
}

Field Selector:

{
    id, 
    season, 
    seasonType, 
    gameTime, 
    homeTeam, 
    visitorTeam, 
    drives {
        yards, 
        plays
    }
}

Request:

/games?s=&fs={"$query" : {"id": "2014", "seasonType": "REG", "week": 1 }, "$sort" : {"gameTime" : 1, }, "drives" : {"$query" : {"playCount" : 10}, "$sort" : {"yards" : -1 } } }&s={id, season, seasonType, gameTime, homeTeam, visitorTeam, drives{yards, plays}}

Pagination

All queried result set is returned as an object of type pageable (See Pager.md) You can perform pagination on both the root domain as well as embedded collection using $take, $skip, $takeLast, $skipLast keywords. $take or $takeLast becomes the page size for the pager object.

Get 2014 REG season games between week 5 and 10. Only display 16 games and skip 32.

{
    "$query" : {"season": 2014, 
        "seasonType": "REG",  
        "week": {"$gte" : 5}, 
        "week" : {"$lte": 10}
    }, 
    "$take" : 16, 
    "$skip" : 32
}

You can also perform pagination on the embedded objects.

Get 2014 REG season games between week 5 and 10. Within each of these games, only get the last drive that has more than 50 yards.

{
    "$query" : {
        "season": 2014, 
        "seasonType": "REG", 
        "week": {"$gte" : 5}, 
        "week" : {"$lte": 10} 
    },
    "$take" : 2,
    "$skip" : 3,
    "drives" : {
        "$query" : {"yards" : {"$gt" : 50}},
        "$takeLast" : 1
    }
}